mocktp 0.0.1-security → 3.15.3

package/src/rules/websockets/websocket-rule-builder.ts

@@ -0,0 +1,275 @@
+import { MockedEndpoint, Headers } from "../../types";
+import type { WebSocketRuleData } from "./websocket-rule";
+
+import {
+    PassThroughWebSocketHandlerDefinition,
+    TimeoutHandlerDefinition,
+    CloseConnectionHandlerDefinition,
+    ResetConnectionHandlerDefinition,
+    PassThroughWebSocketHandlerOptions,
+    RejectWebSocketHandlerDefinition,
+    EchoWebSocketHandlerDefinition,
+    ListenWebSocketHandlerDefinition
+} from './websocket-handler-definitions';
+
+import { BaseRuleBuilder } from "../base-rule-builder";
+import { WildcardMatcher } from "../matchers";
+
+/**
+ * @class WebSocketRuleBuilder
+
+ * A builder for defining websocket mock rules. Create one using
+ * `.forAnyWebSocket(path)` on a Mockttp instance, then call whatever
+ * methods you'd like here to define more precise matching behaviour,
+ * control how the connection is handled, and how many times this
+ * rule should be applied.
+ *
+ * When you're done, call a `.thenX()` method to register the configured rule
+ * with the server. These return a promise for a MockedEndpoint, which can be
+ * used to verify the details of the requests matched by the rule.
+ *
+ * This returns a promise because rule registration can be asynchronous,
+ * either when using a remote server or testing in the browser. Wait for the
+ * promise returned by `.thenX()` methods to guarantee that the rule has taken
+ * effect before sending requests to it.
+ */
+export class WebSocketRuleBuilder extends BaseRuleBuilder {
+
+    /**
+     * Mock rule builders should be constructed through the Mockttp instance you're
+     * using, not directly. You shouldn't ever need to call this constructor.
+     */
+    constructor(
+        private addRule: (rule: WebSocketRuleData) => Promise<MockedEndpoint>
+    ) {
+        super();
+
+        // By default, websockets just match everything:
+        this.matchers.push(new WildcardMatcher());
+    }
+
+    /**
+     * Pass matched websockets through to their real destination. This works
+     * for proxied requests only, and direct requests will be rejected with
+     * an error.
+     *
+     * This method takes options to configure how the request is passed
+     * through. See {@link PassThroughWebSocketHandlerOptions} for the full
+     * details of the options available.
+     *
+     * Calling this method registers the rule with the server, so it
+     * starts to handle requests.
+     *
+     * This method returns a promise that resolves with a mocked endpoint.
+     * Wait for the promise to confirm that the rule has taken effect
+     * before sending requests to be matched. The mocked endpoint
+     * can be used to assert on the requests matched by this rule.
+     *
+     * @category Responses
+     */
+    thenPassThrough(options: PassThroughWebSocketHandlerOptions = {}): Promise<MockedEndpoint> {
+        const rule: WebSocketRuleData = {
+            ...this.buildBaseRuleData(),
+            handler: new PassThroughWebSocketHandlerDefinition(options)
+        };
+
+        return this.addRule(rule);
+    }
+
+    /**
+     * Forward matched websockets on to the specified forwardToUrl. The url
+     * specified must not include a path or an error will be thrown.
+     * The path portion of the original request url is used instead.
+     *
+     * The url may optionally contain a protocol. If it does, it will override
+     * the protocol (and potentially the port, if unspecified) of the request.
+     * If no protocol is specified, the protocol (and potentially the port)
+     * of the original request URL will be used instead.
+     *
+     * This method takes options to configure how the request is passed
+     * through. See {@link PassThroughWebSocketHandlerOptions} for the full
+     * details of the options available.
+     *
+     * Calling this method registers the rule with the server, so it
+     * starts to handle requests.
+     *
+     * This method returns a promise that resolves with a mocked endpoint.
+     * Wait for the promise to confirm that the rule has taken effect
+     * before sending requests to be matched. The mocked endpoint
+     * can be used to assert on the requests matched by this rule.
+     *
+     * @category Responses
+     */
+    async thenForwardTo(
+        forwardToLocation: string,
+        options: Omit<PassThroughWebSocketHandlerOptions, 'forwarding'> & {
+            forwarding?: Omit<PassThroughWebSocketHandlerOptions['forwarding'], 'targetHost'>
+        } = {}
+    ): Promise<MockedEndpoint> {
+        const rule: WebSocketRuleData = {
+            ...this.buildBaseRuleData(),
+            handler: new PassThroughWebSocketHandlerDefinition({
+                ...options,
+                forwarding: {
+                    ...options.forwarding,
+                    targetHost: forwardToLocation
+                }
+            })
+        };
+
+        return this.addRule(rule);
+    }
+
+    /**
+     * Accept incoming WebSocket connections, and echo every message
+     * received on the WebSocket back to the client.
+     *
+     * Calling this method registers the rule with the server, so it
+     * starts to handle requests.
+     *
+     * This method returns a promise that resolves with a mocked endpoint.
+     * Wait for the promise to confirm that the rule has taken effect
+     * before sending requests to be matched. The mocked endpoint
+     * can be used to assert on the requests matched by this rule.
+     *
+     * @category Responses
+     */
+    thenEcho(): Promise<MockedEndpoint> {
+        const rule: WebSocketRuleData = {
+            ...this.buildBaseRuleData(),
+            handler: new EchoWebSocketHandlerDefinition()
+        };
+
+        return this.addRule(rule);
+    }
+
+    /**
+     * Accept incoming WebSocket connections, and simply listen to
+     * incoming messages without ever sending anything in return.
+     *
+     * Calling this method registers the rule with the server, so it
+     * starts to handle requests.
+     *
+     * This method returns a promise that resolves with a mocked endpoint.
+     * Wait for the promise to confirm that the rule has taken effect
+     * before sending requests to be matched. The mocked endpoint
+     * can be used to assert on the requests matched by this rule.
+     *
+     * @category Responses
+     */
+    thenPassivelyListen(): Promise<MockedEndpoint> {
+        const rule: WebSocketRuleData = {
+            ...this.buildBaseRuleData(),
+            handler: new ListenWebSocketHandlerDefinition()
+        };
+
+        return this.addRule(rule);
+    }
+
+    /**
+     * Rejects connections, sending an HTTP response with the given
+     * status, message and body, to explicitly refuse the WebSocket
+     * handshake.
+     *
+     * Calling this method registers the rule with the server, so it
+     * starts to handle requests.
+     *
+     * This method returns a promise that resolves with a mocked endpoint.
+     * Wait for the promise to confirm that the rule has taken effect
+     * before sending requests to be matched. The mocked endpoint
+     * can be used to assert on the requests matched by this rule.
+     *
+     * @category Responses
+     */
+    thenRejectConnection(
+        statusCode: number,
+        statusMessage?: string,
+        headers?: Headers,
+        body?: Buffer | string
+    ): Promise<MockedEndpoint> {
+        const rule: WebSocketRuleData = {
+            ...this.buildBaseRuleData(),
+            handler: new RejectWebSocketHandlerDefinition(
+                statusCode,
+                statusMessage,
+                headers,
+                body
+            )
+        };
+
+        return this.addRule(rule);
+    }
+
+    /**
+     * Close connections that match this rule immediately, without accepting
+     * the socket or sending any other response.
+     *
+     * Calling this method registers the rule with the server, so it
+     * starts to handle requests.
+     *
+     * This method returns a promise that resolves with a mocked endpoint.
+     * Wait for the promise to confirm that the rule has taken effect
+     * before sending requests to be matched. The mocked endpoint
+     * can be used to assert on the requests matched by this rule.
+     *
+     * @category Responses
+     */
+    thenCloseConnection(): Promise<MockedEndpoint> {
+        const rule: WebSocketRuleData = {
+            ...this.buildBaseRuleData(),
+            handler: new CloseConnectionHandlerDefinition()
+        };
+
+        return this.addRule(rule);
+    }
+
+    /**
+     * Reset connections that match this rule immediately, sending a TCP
+     * RST packet directly, without accepting the socket or sending any
+     * other response, and without cleanly closing the TCP connection.
+     *
+     * This is only supported in Node.js versions (>=16.17, >=18.3.0, or
+     * later), where `net.Socket` includes the `resetAndDestroy` method.
+     *
+     * Calling this method registers the rule with the server, so it
+     * starts to handle requests.
+     *
+     * This method returns a promise that resolves with a mocked endpoint.
+     * Wait for the promise to confirm that the rule has taken effect
+     * before sending requests to be matched. The mocked endpoint
+     * can be used to assert on the requests matched by this rule.
+     *
+     * @category Responses
+     */
+    thenResetConnection(): Promise<MockedEndpoint> {
+        const rule: WebSocketRuleData = {
+            ...this.buildBaseRuleData(),
+            handler: new ResetConnectionHandlerDefinition()
+        };
+
+        return this.addRule(rule);
+    }
+
+    /**
+     * Hold open connections that match this rule, but never respond
+     * with anything at all, typically causing a timeout on the client side.
+     *
+     * Calling this method registers the rule with the server, so it
+     * starts to handle requests.
+     *
+     * This method returns a promise that resolves with a mocked endpoint.
+     * Wait for the promise to confirm that the rule has taken effect
+     * before sending requests to be matched. The mocked endpoint
+     * can be used to assert on the requests matched by this rule.
+     *
+     * @category Responses
+     */
+    thenTimeout(): Promise<MockedEndpoint> {
+        const rule: WebSocketRuleData = {
+            ...this.buildBaseRuleData(),
+            handler: new TimeoutHandlerDefinition()
+        };
+
+        return this.addRule(rule);
+    }
+}

package/src/rules/websockets/websocket-rule.ts

@@ -0,0 +1,136 @@
+import * as _ from 'lodash';
+import { v4 as uuid } from "uuid";
+import * as net from 'net';
+import * as http from 'http';
+
+import {
+    OngoingRequest,
+    CompletedRequest,
+    Explainable,
+    RulePriority
+} from "../../types";
+import { waitForCompletedRequest } from '../../util/request-utils';
+import { MaybePromise } from '../../util/type-utils';
+
+import { validateMockRuleData } from '../rule-serialization';
+
+import * as matchers from "../matchers";
+import * as completionCheckers from "../completion-checkers";
+import { WebSocketHandler, WsHandlerLookup } from "./websocket-handlers";
+import type { WebSocketHandlerDefinition } from "./websocket-handler-definitions";
+
+// The internal representation of a mocked endpoint
+export interface WebSocketRule extends Explainable {
+    id: string;
+    requests: Promise<CompletedRequest>[];
+
+    // We don't extend the main interfaces for these, because MockRules are not Serializable
+    matches(request: OngoingRequest): MaybePromise<boolean>;
+    handle(request: OngoingRequest, response: net.Socket, head: Buffer, record: boolean): Promise<void>;
+    isComplete(): boolean | null;
+}
+
+export interface WebSocketRuleData {
+    id?: string;
+    priority?: number; // Higher is higher, by default 0 is fallback, 1 is normal, must be positive
+    matchers: matchers.RequestMatcher[];
+    handler: WebSocketHandler | WebSocketHandlerDefinition;
+    completionChecker?: completionCheckers.RuleCompletionChecker;
+}
+
+export class WebSocketRule implements WebSocketRule {
+    private matchers: matchers.RequestMatcher[];
+    private handler: WebSocketHandler;
+    private completionChecker?: completionCheckers.RuleCompletionChecker;
+
+    public id: string;
+    public readonly priority: number;
+    public requests: Promise<CompletedRequest>[] = [];
+    public requestCount = 0;
+
+    constructor(data: WebSocketRuleData) {
+        validateMockRuleData(data);
+
+        this.id = data.id || uuid();
+        this.priority = data.priority ?? RulePriority.DEFAULT;
+        this.matchers = data.matchers;
+        if ('handle' in data.handler) {
+            this.handler = data.handler;
+        } else {
+            // We transform the definition into a real handler, by creating an raw instance of the handler (which is
+            // a subtype of the definition with the same constructor) and copying the fields across.
+            this.handler = Object.assign(
+                Object.create(WsHandlerLookup[data.handler.type].prototype),
+                data.handler
+            );
+        }
+        this.completionChecker = data.completionChecker;
+    }
+
+    matches(request: OngoingRequest) {
+        return matchers.matchesAll(request, this.matchers);
+    }
+
+    handle(req: OngoingRequest, res: net.Socket, head: Buffer, record: boolean): Promise<void> {
+        let handlerPromise = (async () => { // Catch (a)sync errors
+            return this.handler.handle(req as OngoingRequest & http.IncomingMessage, res, head);
+        })();
+
+        // Requests are added to rule.requests as soon as they start being handled,
+        // as promises, which resolve only when the response & request body is complete.
+        if (record) {
+            this.requests.push(
+                Promise.race([
+                    // When the handler resolves, the request is completed:
+                    handlerPromise,
+                    // If the response is closed before the handler completes (due to aborts, handler
+                    // timeouts, whatever) then that also counts as the request being completed:
+                    new Promise((resolve) => res.on('close', resolve))
+                ])
+                .catch(() => {}) // Ignore handler errors here - we're only tracking the request
+                .then(() => waitForCompletedRequest(req))
+            );
+        }
+
+        // Even if traffic recording is disabled, the number of matched
+        // requests is still tracked
+        this.requestCount += 1;
+
+        return handlerPromise as Promise<any>;
+    }
+
+    isComplete(): boolean | null {
+        if (this.completionChecker) {
+            // If we have a specific rule, use that
+            return this.completionChecker.isComplete(this.requestCount);
+        } else if (this.requestCount === 0) {
+            // Otherwise, by default we're definitely incomplete if we've seen no requests
+            return false;
+        } else {
+            // And we're _maybe_ complete if we've seen at least one request. In reality, we're incomplete
+            // but we should be used anyway if we're at any point we're the last matching rule for a request.
+            return null;
+        }
+    }
+
+    explain(withoutExactCompletion = false): string {
+        let explanation = `Match websockets ${matchers.explainMatchers(this.matchers)}, ` +
+        `and then ${this.handler.explain()}`;
+
+        if (this.completionChecker) {
+            explanation += `, ${this.completionChecker.explain(
+                withoutExactCompletion ? undefined : this.requestCount
+            )}.`;
+        } else {
+            explanation += '.';
+        }
+
+        return explanation;
+    }
+
+    dispose() {
+        this.handler.dispose();
+        this.matchers.forEach(m => m.dispose());
+        if (this.completionChecker) this.completionChecker.dispose();
+    }
+}

package/src/serialization/body-serialization.ts

@@ -0,0 +1,84 @@
+import * as _ from 'lodash';
+import { encode as encodeBase64 } from 'base64-arraybuffer';
+
+import { CompletedBody, Headers } from "../types";
+import { asBuffer } from "../util/buffer-utils";
+import { buildBodyReader, isMockttpBody } from "../util/request-utils";
+import { Replace } from "../util/type-utils";
+
+import { deserializeBuffer, serializeBuffer } from "./serialization";
+
+export function withSerializedBodyReader<T extends {
+    body: CompletedBody
+}>(input: T): Replace<T, { body: string }> {
+    return {
+        ...input,
+        body: asBuffer(input.body.buffer).toString('base64')
+    };
+}
+
+export function withDeserializedBodyReader<T extends { headers: Headers, body: CompletedBody }>(
+    input: Replace<T, { body: string }>
+): T {
+    return {
+        ...input,
+        body: buildBodyReader(deserializeBuffer(input.body), input.headers)
+    } as T;
+}
+
+/**
+ * Serialize a callback result (callback handlers, BeforeRequest/Response etc)
+ * to transform all the many possible buffer formats into either base64-encoded
+ * buffer data, or undefined.
+ */
+export function withSerializedCallbackBuffers<T extends {
+    body?: CompletedBody | Buffer | Uint8Array | ArrayBuffer | string,
+    rawBody?: Buffer | Uint8Array
+}>(input: T): Replace<T, { body: string | undefined }> {
+    let serializedBody: string | undefined;
+
+    if (!input.body) {
+        serializedBody = undefined;
+    } else if (_.isString(input.body)) {
+        serializedBody = serializeBuffer(asBuffer(input.body));
+    } else if (_.isBuffer(input.body)) {
+        serializedBody = serializeBuffer(input.body as Buffer);
+    } else if (_.isArrayBuffer(input.body) || _.isTypedArray(input.body)) {
+        serializedBody = encodeBase64(input.body as ArrayBuffer);
+    } else if (isMockttpBody(input.body)) {
+        serializedBody = serializeBuffer(asBuffer(input.body.buffer));
+    }
+
+    return {
+        ...input,
+        body: serializedBody,
+        rawBody: input.rawBody
+            ? serializeBuffer(asBuffer(input.rawBody))
+            : undefined
+    };
+}
+
+export type WithSerializedCallbackBuffers<T extends { body?: any }> =
+    Replace<T, { body?: string, rawBody?: string }>;
+
+/**
+ * Deserialize a callback result (callback handlers, BeforeRequest/Response etc)
+ * to build buffer data (or undefined) from the base64-serialized data
+ * produced by withSerializedCallbackBuffers
+ */
+export function withDeserializedCallbackBuffers<T extends {
+    body?: Buffer | Uint8Array | string,
+    rawBody?: Buffer | Uint8Array
+}>(
+    input: Replace<T, { body?: string, rawBody?: string }>
+): T {
+    return {
+        ...input,
+        body: input.body !== undefined
+            ? Buffer.from(input.body, 'base64')
+            : undefined,
+        rawBody: input.rawBody !== undefined
+            ? Buffer.from(input.rawBody, 'base64')
+            : undefined
+    } as T;
+}