@fly/cdn/lib/proxy.d.ts

Fly's TypeScript CDN

/**
 * Library for proxying requests to origins. Use this to create `fetch` like functions
 *  for making requests to other services. For example:
 *
 * ```javascript
 * // sends all traffic to an Amazon ELB,
 * // `Host` header passes through from visitor request
 * const origin = proxy("https://elb1298.amazonaws.com")
 * ```
 *
 * By default, this function sends the `Host` header inferred from the origin URL. To forward
 * host headers sent by visitors, set `forwardHostHeader` to true.
 *
 * ```javascript
 * // sends all traffic to an Amazon ELB, include host header from original request.
 * const origin = proxy("https://elb1298.amazonaws.com", {
 *  forwardHostHeader: true
 * })
 * ```
 *
 * And then way more rare, no host header at all. Usually you'd strip out `x-forwarded-host`,
 * since some origins don't like that:
 * ```javascript
 * // sends all traffic to an Amazon ELB, never sends a host header
 * const origin = proxy("https://elb1298.amazonaws.com", {
 *  headers: { host: false}
 * })
 * ```
 *
 * @preferred
 * @module HTTP
 */
import { FetchFunction } from "./fetch";
/**
 * This generates a `fetch` like function for proxying requests to a given origin.
 * When this function makes origin requests, it adds standard proxy headers like
 * `X-Forwarded-Host` and `X-Forwarded-For`. It also passes headers from the original
 * request to the origin.
 * @param origin A URL to an origin, can include a path to rebase requests.
 * @param options Options and headers to control origin request.
 */
export declare function proxy(origin: string | URL, options?: ProxyOptions): ProxyFunction<ProxyOptions>;
/**
 * @protected
 * @hidden
 * @param origin
 * @param options
 * @param req
 * @param init
 */
export declare function buildProxyRequest(origin: string | URL, options: ProxyOptions, r: RequestInfo, init?: RequestInit): Request;
export declare function rewriteLocationHeader(url: URL | string, burl: URL | string, resp: Response): Response;
/**
 * Options for `proxy`.
 */
export interface ProxyOptions {
    /**
     * Replace this portion of URL path before making request to origin.
     *
     * For example, this makes a request to `https://fly.io/path1/to/document.html`:
     * ```javascript
     * const opts = { stripPath: "/path2/"}
     * const origin = proxy("https://fly.io/path1/", opts)
     * origin("https://somehostname.com/path2/to/document.html")
     * ```
     */
    stripPath?: string;
    /**
     * Forward `Host` header from original request. Without this options,
     * proxy requests infers a host header from the origin URL.
     * Defaults to `false`.
     */
    forwardHostHeader?: boolean;
    /**
     * Rewrite location headers (defaults to true) to match incoming request.
     *
     * Example:
     *  - Request url: http://test.com/blog/asdf
     *  - Proxy url: http://origin.com/asdf
     *  - Location http://origin.com/jklm bcomes http://test.com/blog/jklm
     */
    rewriteLocationHeaders?: boolean;
    /**
     * Headers to set on backend request. Each header accepts either a `boolean` or `string`.
     * * If set to `false`, strip header entirely before sending.
     * * `true` or `undefined` send the header through unmodified from the original request.
     * * `string` header values are sent as is
     */
    headers?: {
        [key: string]: string | boolean | undefined;
        /**
         * Host header to set before sending origin request. Some sites only respond to specific
         * host headers.
         */
        host?: string | boolean;
    };
    /** @private */
    origin?: string;
}
/**
 * A proxy `fetch` like function. These functions include their
 * original configuration information.
 */
export interface ProxyFunction<T = unknown> extends FetchFunction {
    proxyConfig: T;
}
export interface ProxyFactory<TOpts = any, TInput = any> {
    (options: TInput): ProxyFunction<TOpts>;
    normalizeOptions?: (input: any) => TOpts;
}