@salesforce/mrt-utilities 0.0.1 → 0.1.0

package/dist/esm/utils/ssr-proxying.d.ts

@@ -0,0 +1,300 @@
+import type { IncomingHttpHeaders } from 'http';
+declare const HEADER_FORMATS: readonly ["http", "aws"];
+export declare const X_PROXY_REQUEST_URL = "x-proxy-request-url";
+export declare const X_MOBIFY_REQUEST_CLASS = "x-mobify-request-class";
+export declare const MAX_URL_LENGTH_BYTES = 8192;
+type HeaderFormat = (typeof HEADER_FORMATS)[number];
+/**
+ * Represents a parsed cookie object from set-cookie-parser
+ */
+interface ParsedCookie {
+    name: string;
+    value: string;
+    path?: string;
+    expires?: Date;
+    domain?: string;
+    maxAge?: number;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: string;
+}
+/**
+ * Represents a parsed host with its components
+ */
+export interface ParsedHost {
+    /** The host (10.10.10.10:port), which includes the port (if any) */
+    host: string;
+    /** The hostname (10.10.10.10), which excludes the port */
+    hostname: string;
+    /** The host's port */
+    port?: string;
+    /** Whether the hostname is an IP or localhost */
+    isIPOrLocalhost: boolean;
+}
+/**
+ * Represents AWS Lambda Event headers format
+ */
+interface AWSHeaderValue {
+    key: string;
+    value: string;
+}
+export type AWSHeaders = Record<string, AWSHeaderValue[]>;
+/**
+ * Represents HTTP IncomingMessage headers format
+ */
+export type HTTPHeaders = Record<string, string | string[]>;
+/**
+ * This class provides a representation of HTTP request or response
+ * headers, that operates in the same way in multiple contexts
+ * (i.e. within the Express app as well as the request-processor).
+ *
+ * Within a Headers instance, headers are referenced using lower-case
+ * names. Use getHeader to access the value for a header. If there
+ * are multiple values, this will return the first value. This class
+ * internally supports round-trip preservation of multi-value headers,
+ * but does not yet provide a way to access them.
+ */
+export declare class Headers {
+    private httpFormat;
+    private headers;
+    private _modified;
+    /**
+     * Construct a Headers object from either an AWS Lambda Event headers
+     * object, or an http.IncomingMessage headers object.
+     *
+     * Project code should never need to call this constructor.
+     *
+     * @private
+     * @param headers the input headers
+     * @param format either 'http' or 'aws'
+     */
+    constructor(headers: AWSHeaders | HTTPHeaders | IncomingHttpHeaders, format: HeaderFormat);
+    /**
+     * Return true if and only if any set or delete methods were called on
+     * this instance after construction. This does not actually test if
+     * the headers values have been changed, just whether any mutating
+     * methods have been called.
+     * @returns {Boolean}
+     */
+    get modified(): boolean;
+    /**
+     * Return an array of the header keys (all lower-case)
+     */
+    keys(): string[];
+    /**
+     * Get the value of the set-cookie header(s), returning an array
+     * of strings. Always returns an array, even if it's empty.
+     */
+    getSetCookie(): string[];
+    /**
+     * Set the value of the set-cookie header(s)
+     * @param values Array of set-cookie header values
+     */
+    setSetCookie(values: string[]): void;
+    /**
+     * Return the FIRST value of the header with the given key.
+     * This is for single-value headers only: Location, Access-Control-*, etc
+     * If the header is not present, returns undefined.
+     * @param key header name
+     */
+    getHeader(key: string): string | undefined;
+    /**
+     * Set the value of the header with the given key. This is for single-
+     * value headers only (see getHeader). Setting the value removes ALL other
+     * values for the given key.
+     * @param key header name
+     * @param value header value
+     */
+    setHeader(key: string, value: string): void;
+    /**
+     * Remove any header with the given key
+     * @param key header name to remove
+     */
+    deleteHeader(key: string): void;
+    /**
+     * Return the headers in AWS (Lambda event) format.
+     *
+     * Project code should never need to use this method.
+     */
+    toAWSFormat(): AWSHeaders;
+    /**
+     * Return the headers in Express (http.IncomingMessage) format.
+     *
+     * RFC2616 allows some flexibility in how multiple values are
+     * combined into a single header value. We separate with ', '
+     * rather than just ',' to maintain previous behaviour.
+     *
+     * Project code should never need to use this method.
+     */
+    toHTTPFormat(): HTTPHeaders;
+    /**
+     * Return the headers in the same format (aws or http) that was
+     * used to construct them.
+     *
+     * Project code should never need to use this method.
+     */
+    toObject(): AWSHeaders | HTTPHeaders | IncomingHttpHeaders;
+}
+/**
+ * Return the given date as an RFC1123-format string, suitable for
+ * use in a Set-Cookie or Date header. The result is always in UTC.
+ * @function
+ * @param date Date object
+ * @returns RFC1123 formatted date string
+ */
+export declare const rfc1123: (date: Date) => string;
+/**
+ * Given a cookie object parsed by set-cookie-parser,
+ * return a set-cookie header value for it.
+ * @private
+ */
+export declare const cookieAsString: (cookie: ParsedCookie) => string;
+/**
+ * Given a hostname that may be a hostname or ip address optionally
+ * followed by a port, return an object with 'host' being the ip address,
+ * the hostname, a port (if there is one), and 'isIPOrLocalhost' true for an ip
+ * address or localhost, false for a hostname
+ * @private
+ * @param host Can be localhost, an IP or domain name
+ * @return ParsedHost object
+ */
+export declare const parseHost: (host: string) => ParsedHost;
+export declare const rewriteDomain: (domain: string, appHostname: string, targetHost: string) => string;
+/**
+ * Parameters for rewriteSetCookies function
+ */
+interface RewriteSetCookiesParams {
+    /** the hostname (host+port) under which the Express app is running (e.g. localhost:3443 for a local dev server) */
+    appHostname: string;
+    /** Array of set-cookie header values */
+    setCookies: string[];
+    /** the target hostname (host+port) */
+    targetHost: string;
+    /** true to log operations */
+    logging?: boolean;
+}
+/**
+ * Given a headers object, rewrite any set-cookie headers in it
+ * so that they apply to the app hostname rather than the target
+ * hostname.
+ *
+ * @private
+ * @param params Configuration object for rewriting set-cookies
+ * @returns string[] of rewritten set-cookie header values
+ */
+export declare const rewriteSetCookies: ({ appHostname, setCookies, targetHost, logging, }: RewriteSetCookiesParams) => string[];
+/**
+ * Parameters for rewriteProxyResponseHeaders function
+ */
+interface RewriteProxyResponseHeadersParams {
+    /** the hostname (host+port) under which the Express app is running (e.g. localhost:3443 for a local dev server) */
+    appHostname: string;
+    /** true for a caching proxy, false for a standard proxy */
+    caching: boolean;
+    /** the headers to be rewritten */
+    headers: AWSHeaders | HTTPHeaders | IncomingHttpHeaders;
+    /** 'aws' or 'http' - the format of the 'headers' parameter */
+    headerFormat?: HeaderFormat;
+    /** the path being proxied (e.g. /mobify/proxy/base/) */
+    proxyPath: string;
+    /** the URL from the request that prompted the response. If present, used to set the X-Proxy-Request-Url header. This should be the request URL sent to the target host, not containing any /mobify/proxy/... part. */
+    requestUrl?: string;
+    /** the protocol to use to make requests to the target ('http' or 'https') */
+    targetProtocol: string;
+    /** the target hostname (host+port) */
+    targetHost: string;
+    /** the protocol to use to make requests to the origin ('http' or 'https', defaults to 'https'), use of unencrypted protocol is only allowed in local development */
+    appProtocol?: string;
+    /** true to log operations */
+    logging?: boolean;
+    /** the response status code */
+    statusCode?: number;
+}
+/**
+ * Rewrite headers for a proxied response.
+ *
+ * 1. If the original domain appears in the
+ * Access-Control-Allow-Origin header, it's replaced with the
+ * appOrigin.
+ * 2. If the response is a 30x redirection and contains a Location
+ * header on the target host, that header is rewritten to use the
+ * app host and proxy path.
+ *
+ * For a caching proxy, we also remove any Set-Cookie headers - caching
+ * proxies don't pass Cookie headers for requests and don't allow Set-Cookie
+ * in responses, so that they may be cached independently of any cookie
+ * values.
+ *
+ * @private
+ * @param params Configuration object for rewriting proxy response headers
+ * @returns the modified response headers
+ */
+export declare const rewriteProxyResponseHeaders: ({ appHostname, caching, headers, headerFormat, proxyPath, requestUrl, statusCode, targetProtocol, targetHost, appProtocol, logging, }: RewriteProxyResponseHeadersParams) => AWSHeaders | HTTPHeaders | IncomingHttpHeaders;
+/**
+ * List of x- headers that are removed from proxied requests.
+ * @private
+ */
+export declare const X_HEADERS_TO_REMOVE_PROXY: string[];
+/**
+ * List of x- headers that are removed from origin requests.
+ * @private
+ */
+export declare const X_HEADERS_TO_REMOVE_ORIGIN: string[];
+/**
+ * X-header key and values to add to proxied requests
+ * @private
+ */
+export declare const X_HEADERS_TO_ADD: Record<string, string>;
+/**
+ * List of headers that are allowed for a caching proxy request.
+ * This must match the allowlist that CloudFront uses for a
+ * CacheBehavior that does not pass cookies and is not configured
+ * to cache based on headers.
+ *
+ * This is a map from lower-case header name to 'true' - we use an object
+ * to make lookups fast, since this mapping might be used for many requests.
+ *
+ * Also see what is configured in the SSR Manager (ssr-infrastructure repo),
+ * in the CloudFront configuration. This list is a superset of that list,
+ * since the proxying code must also allow headers that it adds, such as
+ * Host, Origin, etc.
+ *
+ * See https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/header-caching.html
+ * See https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Cookies.html
+ *
+ * @private
+ */
+export declare const ALLOWED_CACHING_PROXY_REQUEST_HEADERS: Record<string, boolean>;
+/**
+ * Parameters for rewriteProxyRequestHeaders function
+ */
+interface RewriteProxyRequestHeadersParams {
+    /** true for a caching proxy, false for a standard proxy */
+    caching?: boolean;
+    /** the headers to be rewritten */
+    headers?: AWSHeaders | HTTPHeaders | IncomingHttpHeaders;
+    /** 'aws' or 'http' - the format of the 'headers' parameter */
+    headerFormat?: HeaderFormat;
+    /** the protocol to use to make requests to the target ('http' or 'https') */
+    targetProtocol: string;
+    /** the target hostname (host+port) */
+    targetHost: string;
+    /** true to log operations */
+    logging?: boolean;
+}
+/**
+ * Rewrite headers for a request that is being proxied.
+ *
+ * 1. If the request contains a Host header, rewrite it so that the
+ * value is the target host.
+ * 2. If the request contains an Origin header, rewrite it so that the
+ * value is the target host.
+ * 3. ALL other header values are left unchanged. If they are multi-value
+ * headers whose values are stored as arrays, the values are left as arrays.
+ *
+ * @private
+ * @param params Configuration object for rewriting proxy request headers
+ * @returns the modified request headers
+ */
+export declare const rewriteProxyRequestHeaders: ({ caching, headers, headerFormat, targetProtocol, targetHost, logging, }: RewriteProxyRequestHeadersParams) => AWSHeaders | HTTPHeaders | IncomingHttpHeaders;
+export {};