Refactor passthrough HTTP+WS conn options into a shared type

Author: pimterry

src/main.ts

@@ -56,6 +56,11 @@ export type {
     ProxySettingCallback,
     ProxySettingCallbackParams
 } from './rules/proxy-config';
+export type {
+    ForwardingOptions,
+    PassThroughLookupOptions,
+    PassThroughHandlerConnectionOptions
+} from './rules/passthrough-handling-definitions';
 
 export type { RequestRuleBuilder } from "./rules/requests/request-rule-builder";
 export type { WebSocketRuleBuilder } from "./rules/websockets/websocket-rule-builder";

src/rules/passthrough-handling-definitions.ts

@@ -0,0 +1,100 @@
+import { ProxyConfig } from "./proxy-config";
+
+export interface ForwardingOptions {
+    targetHost: string,
+    // Should the host (H1) or :authority (H2) header be updated to match?
+    updateHostHeader?: true | false | string // Change automatically/ignore/change to custom value
+}
+
+export interface PassThroughLookupOptions {
+    /**
+     * The maximum time to cache a DNS response. Up to this limit,
+     * responses will be cached according to their own TTL. Defaults
+     * to Infinity.
+     */
+    maxTtl?: number;
+    /**
+     * How long to cache a DNS ENODATA or ENOTFOUND response. Defaults
+     * to 0.15.
+     */
+    errorTtl?: number;
+    /**
+     * The primary servers to use. DNS queries will be resolved against
+     * these servers first. If no data is available, queries will fall
+     * back to dns.lookup, and use the OS's default DNS servers.
+     *
+     * This defaults to dns.getServers().
+     */
+    servers?: string[];
+}
+
+/**
+ * This defines the upstream connection parameters. These passthrough parameters
+ * are shared between both WebSocket & Request passthrough rules.
+ */
+export interface PassThroughHandlerConnectionOptions {
+    /**
+     * The forwarding configuration for the passthrough rule.
+     * This generally shouldn't be used explicitly unless you're
+     * building rule data by hand. Instead, call `thenPassThrough`
+     * to send data directly or `thenForwardTo` with options to
+     * configure traffic forwarding.
+     */
+    forwarding?: ForwardingOptions,
+
+    /**
+     * A list of hostnames for which server certificate and TLS version errors
+     * should be ignored (none, by default).
+     *
+     * If set to 'true', HTTPS errors will be ignored for all hosts. WARNING:
+     * Use this at your own risk. Setting this to `true` can open your
+     * application to MITM attacks and should never be used over any network
+     * that is not completed trusted end-to-end.
+     */
+    ignoreHostHttpsErrors?: string[] | boolean;
+
+    /**
+     * An array of additional certificates, which should be trusted as certificate
+     * authorities for upstream hosts, in addition to Node.js's built-in certificate
+     * authorities.
+     *
+     * Each certificate should be an object with either a `cert` key and a string
+     * or buffer value containing the PEM certificate, or a `certPath` key and a
+     * string value containing the local path to the PEM certificate.
+     */
+    trustAdditionalCAs?: Array<{ cert: string | Buffer } | { certPath: string }>;
+
+    /**
+     * A mapping of hosts to client certificates to use, in the form of
+     * `{ key, cert }` objects (none, by default)
+     */
+    clientCertificateHostMap?: {
+        [host: string]: { pfx: Buffer, passphrase?: string }
+    };
+
+    /**
+     * Upstream proxy configuration: pass through requests via this proxy.
+     *
+     * If this is undefined, no proxy will be used. To configure a proxy
+     * provide either:
+     * - a ProxySettings object
+     * - a callback which will be called with an object containing the
+     *   hostname, and must return a ProxySettings object or undefined.
+     * - an array of ProxySettings or callbacks. The array will be
+     *   processed in order, and the first not-undefined ProxySettings
+     *   found will be used.
+     *
+     * When using a remote client, this parameter or individual array
+     * values may be passed by reference, using the name of a rule
+     * parameter configured in the admin server.
+     */
+    proxyConfig?: ProxyConfig;
+
+    /**
+     * Custom DNS options, to allow configuration of the resolver used
+     * when forwarding requests upstream. Passing any option switches
+     * from using node's default dns.lookup function to using the
+     * cacheable-lookup module, which will cache responses.
+     */
+    lookupOptions?: PassThroughLookupOptions;
+}

src/rules/passthrough-handling.ts

@@ -14,9 +14,11 @@ import { areFFDHECurvesSupported } from '../util/openssl-compat';
 
 import {
     CallbackRequestResult,
-    CallbackResponseMessageResult,
-    PassThroughLookupOptions
+    CallbackResponseMessageResult
 } from './requests/request-handler-definitions';
+import {
+    PassThroughLookupOptions
+} from './passthrough-handling-definitions';
 
 // TLS settings for proxied connections, intended to avoid TLS fingerprint blocking
 // issues so far as possible, by closely emulating a Firefox Client Hello:

src/rules/requests/request-handler-definitions.ts

@@ -28,6 +28,11 @@ import {
     withSerializedCallbackBuffers
 } from '../../serialization/body-serialization';
 import { ProxyConfig } from '../proxy-config';
+import {
+    ForwardingOptions,
+    PassThroughHandlerConnectionOptions,
+    PassThroughLookupOptions
+} from '../passthrough-handling-definitions';
 
 /*
 This file defines request handler *definitions*, which includes everything necessary to define
@@ -446,100 +451,7 @@ export interface PassThroughResponse {
     body: CompletedBody;
 }
 
-export interface ForwardingOptions {
-    targetHost: string,
-    // Should the host (H1) or :authority (H2) header be updated to match?
-    updateHostHeader?: true | false | string // Change automatically/ignore/change to custom value
-}
-
-export interface PassThroughLookupOptions {
-    /**
-     * The maximum time to cache a DNS response. Up to this limit,
-     * responses will be cached according to their own TTL. Defaults
-     * to Infinity.
-     */
-    maxTtl?: number;
-    /**
-     * How long to cache a DNS ENODATA or ENOTFOUND response. Defaults
-     * to 0.15.
-     */
-    errorTtl?: number;
-    /**
-     * The primary servers to use. DNS queries will be resolved against
-     * these servers first. If no data is available, queries will fall
-     * back to dns.lookup, and use the OS's default DNS servers.
-     *
-     * This defaults to dns.getServers().
-     */
-    servers?: string[];
-}
-
-export interface PassThroughHandlerOptions {
-    /**
-     * The forwarding configuration for the passthrough rule.
-     * This generally shouldn't be used explicitly unless you're
-     * building rule data by hand. Instead, call `thenPassThrough`
-     * to send data directly or `thenForwardTo` with options to
-     * configure traffic forwarding.
-     */
-    forwarding?: ForwardingOptions,
-
-    /**
-     * A list of hostnames for which server certificate and TLS version errors
-     * should be ignored (none, by default).
-     *
-     * If set to 'true', HTTPS errors will be ignored for all hosts. WARNING:
-     * Use this at your own risk. Setting this to `true` can open your
-     * application to MITM attacks and should never be used over any network
-     * that is not completed trusted end-to-end.
-     */
-    ignoreHostHttpsErrors?: string[] | boolean;
-
-    /**
-     * An array of additional certificates, which should be trusted as certificate
-     * authorities for upstream hosts, in addition to Node.js's built-in certificate
-     * authorities.
-     *
-     * Each certificate should be an object with either a `cert` key and a string
-     * or buffer value containing the PEM certificate, or a `certPath` key and a
-     * string value containing the local path to the PEM certificate.
-     */
-    trustAdditionalCAs?: Array<{ cert: string | Buffer } | { certPath: string }>;
-
-    /**
-     * A mapping of hosts to client certificates to use, in the form of
-     * `{ key, cert }` objects (none, by default)
-     */
-    clientCertificateHostMap?: {
-        [host: string]: { pfx: Buffer, passphrase?: string }
-    };
-
-    /**
-     * Upstream proxy configuration: pass through requests via this proxy.
-     *
-     * If this is undefined, no proxy will be used. To configure a proxy
-     * provide either:
-     * - a ProxySettings object
-     * - a callback which will be called with an object containing the
-     *   hostname, and must return a ProxySettings object or undefined.
-     * - an array of ProxySettings or callbacks. The array will be
-     *   processed in order, and the first not-undefined ProxySettings
-     *   found will be used.
-     *
-     * When using a remote client, this parameter or individual array
-     * values may be passed by reference, using the name of a rule
-     * parameter configured in the admin server.
-     */
-    proxyConfig?: ProxyConfig;
-
-    /**
-     * Custom DNS options, to allow configuration of the resolver used
-     * when forwarding requests upstream. Passing any option switches
-     * from using node's default dns.lookup function to using the
-     * cacheable-lookup module, which will cache responses.
-     */
-    lookupOptions?: PassThroughLookupOptions;
-
+export interface PassThroughHandlerOptions extends PassThroughHandlerConnectionOptions {
     /**
      * Whether to simulate connection errors back to the client.
      *

src/rules/requests/request-handlers.ts

@@ -67,6 +67,10 @@ import { assertParamDereferenced, RuleParameters } from '../rule-parameters';
 
 import { getAgent } from '../http-agents';
 import { ProxySettingSource } from '../proxy-config';
+import {
+    ForwardingOptions,
+    PassThroughLookupOptions,
+} from '../passthrough-handling-definitions';
 import {
     getContentLengthAfterModification,
     getHostAfterModification,
@@ -89,12 +93,10 @@ import {
     CallbackResponseResult,
     CloseConnectionHandlerDefinition,
     FileHandlerDefinition,
-    ForwardingOptions,
     HandlerDefinitionLookup,
     JsonRpcResponseHandlerDefinition,
     PassThroughHandlerDefinition,
     PassThroughHandlerOptions,
-    PassThroughLookupOptions,
     PassThroughResponse,
     RequestHandlerDefinition,
     RequestTransform,

src/rules/websockets/websocket-handler-definitions.ts

@@ -11,14 +11,17 @@ import {
 
 import { Explainable, Headers } from "../../types";
 
+import { ProxyConfig } from '../proxy-config';
 import {
-    CloseConnectionHandlerDefinition,
-    ResetConnectionHandlerDefinition,
-    TimeoutHandlerDefinition,
+    PassThroughHandlerConnectionOptions,
     ForwardingOptions,
     PassThroughLookupOptions
+} from '../passthrough-handling-definitions';
+import {
+    CloseConnectionHandlerDefinition,
+    ResetConnectionHandlerDefinition,
+    TimeoutHandlerDefinition
 } from '../requests/request-handler-definitions';
-import { ProxyConfig } from '../proxy-config';
 
 /*
 This file defines websocket handler *definitions*, which includes everything necessary to define
@@ -37,64 +40,7 @@ export interface WebSocketHandlerDefinition extends Explainable, Serializable {
     type: keyof typeof WsHandlerDefinitionLookup;
 }
 
-export interface PassThroughWebSocketHandlerOptions {
-    /**
-     * The forwarding configuration for the passthrough rule.
-     * This generally shouldn't be used explicitly unless you're
-     * building rule data by hand. Instead, call `thenPassThrough`
-     * to send data directly or `thenForwardTo` with options to
-     * configure traffic forwarding.
-     */
-    forwarding?: ForwardingOptions,
-
-    /**
-     * A list of hostnames for which server certificate and TLS version errors
-     * should be ignored (none, by default).
-     *
-     * If set to 'true', HTTPS errors will be ignored for all hosts. WARNING:
-     * Use this at your own risk. Setting this to `true` can open your
-     * application to MITM attacks and should never be used over any network
-     * that is not completed trusted end-to-end.
-     */
-    ignoreHostHttpsErrors?: string[] | boolean;
-
-    /**
-     * An array of additional certificates, which should be trusted as certificate
-     * authorities for upstream hosts, in addition to Node.js's built-in certificate
-     * authorities.
-     *
-     * Each certificate should be an object with either a `cert` key and a string
-     * or buffer value containing the PEM certificate, or a `certPath` key and a
-     * string value containing the local path to the PEM certificate.
-     */
-    trustAdditionalCAs?: Array<{ cert: string | Buffer } | { certPath: string }>;
-
-    /**
-     * Upstream proxy configuration: pass through websockets via this proxy.
-     *
-     * If this is undefined, no proxy will be used. To configure a proxy
-     * provide either:
-     * - a ProxySettings object
-     * - a callback which will be called with an object containing the
-     *   hostname, and must return a ProxySettings object or undefined.
-     * - an array of ProxySettings or callbacks. The array will be
-     *   processed in order, and the first not-undefined ProxySettings
-     *   found will be used.
-     *
-     * When using a remote client, this parameter or individual array
-     * values may be passed by reference, using the name of a rule
-     * parameter configured in the admin server.
-     */
-    proxyConfig?: ProxyConfig;
-
-    /**
-     * Custom DNS options, to allow configuration of the resolver used
-     * when forwarding requests upstream. Passing any option switches
-     * from using node's default dns.lookup function to using the
-     * cacheable-lookup module, which will cache responses.
-     */
-    lookupOptions?: PassThroughLookupOptions;
-}
+export type PassThroughWebSocketHandlerOptions = PassThroughHandlerConnectionOptions;
 
 /**
  * @internal