alepha/server/proxy.d.ts

Alepha is a convention-driven TypeScript framework for building robust, end-to-end type-safe applications, from serverless APIs to full-stack React apps.

import * as _alepha_core1 from "alepha";
import { Alepha, Async, Descriptor, KIND } from "alepha";
import { ServerHandler, ServerRequest, ServerRouterProvider } from "alepha/server";
import * as _alepha_logger0 from "alepha/logger";

//#region src/descriptors/$proxy.d.ts

/**
 * Creates a proxy descriptor to forward requests to another server.
 *
 * This descriptor enables you to create reverse proxy functionality, allowing your Alepha server
 * to forward requests to other services while maintaining a unified API surface. It's particularly
 * useful for microservice architectures, API gateways, or when you need to aggregate multiple
 * services behind a single endpoint.
 *
 * **Key Features**
 *
 * - **Path-based routing**: Match specific paths or patterns to proxy
 * - **Dynamic targets**: Support both static and dynamic target resolution
 * - **Request/Response hooks**: Modify requests before forwarding and responses after receiving
 * - **URL rewriting**: Transform URLs before forwarding to the target
 * - **Conditional proxying**: Enable/disable proxies based on environment or conditions
 *
 * @example
 * **Basic proxy setup:**
 * ```ts
 * import { $proxy } from "alepha/server-proxy";
 *
 * class ApiGateway {
 *   // Forward all /api/* requests to external service
 *   api = $proxy({
 *     path: "/api/*",
 *     target: "https://api.example.com"
 *   });
 * }
 * ```
 *
 * @example
 * **Dynamic target with environment-based routing:**
 * ```ts
 * class ApiGateway {
 *   // Route to different environments based on configuration
 *   api = $proxy({
 *     path: "/api/*",
 *     target: () => process.env.NODE_ENV === "production"
 *       ? "https://api.prod.example.com"
 *       : "https://api.dev.example.com"
 *   });
 * }
 * ```
 *
 * @example
 * **Advanced proxy with request/response modification:**
 * ```ts
 * class SecureProxy {
 *   secure = $proxy({
 *     path: "/secure/*",
 *     target: "https://secure-api.example.com",
 *     beforeRequest: async (request, proxyRequest) => {
 *       // Add authentication headers
 *       proxyRequest.headers = {
 *         ...proxyRequest.headers,
 *         'Authorization': `Bearer ${await getServiceToken()}`,
 *         'X-Forwarded-For': request.headers['x-forwarded-for'] || request.ip
 *       };
 *     },
 *     afterResponse: async (request, proxyResponse) => {
 *       // Log response for monitoring
 *       console.log(`Proxied ${request.url} -> ${proxyResponse.status}`);
 *     },
 *     rewrite: (url) => {
 *       // Remove /secure prefix when forwarding
 *       url.pathname = url.pathname.replace('/secure', '');
 *     }
 *   });
 * }
 * ```
 *
 * @example
 * **Conditional proxy based on feature flags:**
 * ```ts
 * class FeatureProxy {
 *   newApi = $proxy({
 *     path: "/v2/*",
 *     target: "https://new-api.example.com",
 *     disabled: !process.env.ENABLE_V2_API // Disable if feature flag is off
 *   });
 * }
 * ```
 */
declare const $proxy: {
  (options: ProxyDescriptorOptions): ProxyDescriptor;
  [KIND]: typeof ProxyDescriptor;
};
type ProxyDescriptorOptions = {
  /**
   * Path pattern to match for proxying requests.
   *
   * Supports wildcards and path parameters:
   * - `/api/*` - Matches all paths starting with `/api/`
   * - `/api/v1/*` - Matches all paths starting with `/api/v1/`
   * - `/users/:id` - Matches `/users/123`, `/users/abc`, etc.
   *
   * @example "/api/*"
   * @example "/secure/admin/*"
   * @example "/users/:id/posts"
   */
  path: string;
  /**
   * Target URL to which matching requests should be forwarded.
   *
   * Can be either:
   * - **Static string**: A fixed URL like `"https://api.example.com"`
   * - **Dynamic function**: A function that returns the URL, enabling runtime target resolution
   *
   * The target URL will be combined with the remaining path from the original request.
   *
   * @example "https://api.example.com"
   * @example () => process.env.API_URL || "http://localhost:3001"
   */
  target: string | (() => string);
  /**
   * Whether this proxy is disabled.
   *
   * When `true`, requests matching the path will not be proxied and will be handled
   * by other routes or return 404. Useful for feature toggles or conditional proxying.
   *
   * @default false
   * @example !process.env.ENABLE_PROXY
   */
  disabled?: boolean;
  /**
   * Hook called before forwarding the request to the target server.
   *
   * Use this to:
   * - Add authentication headers
   * - Modify request headers or body
   * - Add request tracking/logging
   * - Transform the request before forwarding
   *
   * @param request - The original incoming server request
   * @param proxyRequest - The request that will be sent to the target (modifiable)
   *
   * @example
   * ```ts
   * beforeRequest: async (request, proxyRequest) => {
   *   proxyRequest.headers = {
   *     ...proxyRequest.headers,
   *     'Authorization': `Bearer ${await getToken()}`,
   *     'X-Request-ID': generateRequestId()
   *   };
   * }
   * ```
   */
  beforeRequest?: (request: ServerRequest, proxyRequest: RequestInit) => Async<void>;
  /**
   * Hook called after receiving the response from the target server.
   *
   * Use this to:
   * - Log response details for monitoring
   * - Add custom headers to the response
   * - Transform response data
   * - Handle error responses
   *
   * @param request - The original incoming server request
   * @param proxyResponse - The response received from the target server
   *
   * @example
   * ```ts
   * afterResponse: async (request, proxyResponse) => {
   *   console.log(`Proxy ${request.method} ${request.url} -> ${proxyResponse.status}`);
   *
   *   if (!proxyResponse.ok) {
   *     await logError(`Proxy error: ${proxyResponse.status}`, { request, response: proxyResponse });
   *   }
   * }
   * ```
   */
  afterResponse?: (request: ServerRequest, proxyResponse: Response) => Async<void>;
  /**
   * Function to rewrite the URL before sending to the target server.
   *
   * Use this to:
   * - Remove or add path prefixes
   * - Transform path parameters
   * - Modify query parameters
   * - Change the URL structure entirely
   *
   * The function receives a mutable URL object and should modify it in-place.
   *
   * @param url - The URL object to modify (mutable)
   *
   * @example
   * ```ts
   * // Remove /api prefix when forwarding
   * rewrite: (url) => {
   *   url.pathname = url.pathname.replace('/api', '');
   * }
   * ```
   *
   * @example
   * ```ts
   * // Add version prefix
   * rewrite: (url) => {
   *   url.pathname = `/v2${url.pathname}`;
   * }
   * ```
   */
  rewrite?: (url: URL) => void;
};
declare class ProxyDescriptor extends Descriptor<ProxyDescriptorOptions> {}
//#endregion
//#region src/providers/ServerProxyProvider.d.ts
declare class ServerProxyProvider {
  protected readonly log: _alepha_logger0.Logger;
  protected readonly routerProvider: ServerRouterProvider;
  protected readonly alepha: Alepha;
  protected readonly configure: _alepha_core1.HookDescriptor<"configure">;
  createProxy(options: ProxyDescriptorOptions): void;
  createProxyHandler(target: string, options: Omit<ProxyDescriptorOptions, "path">): ServerHandler;
  private getRawRequestBody;
}
//#endregion
//#region src/index.d.ts
/**
 * Plugin for Alepha that provides a proxy server functionality.
 *
 * @see {@link $proxy}
 * @module alepha.server.proxy
 */
declare const AlephaServerProxy: _alepha_core1.Service<_alepha_core1.Module>;
//#endregion
export { $proxy, AlephaServerProxy, ProxyDescriptor, ProxyDescriptorOptions, ServerProxyProvider };
//# sourceMappingURL=index.d.ts.map