mocktp 0.0.1-security → 3.15.3

package/src/client/mockttp-client.ts

@@ -0,0 +1,178 @@
+import _ = require('lodash');
+
+import { MockedEndpoint } from "../types";
+import { Mockttp, AbstractMockttp, MockttpOptions, PortRange, SubscribableEvent } from "../mockttp";
+
+import type { RequestRuleData } from "../rules/requests/request-rule";
+import type { WebSocketRuleData } from '../rules/websockets/websocket-rule';
+
+import { AdminClient, AdminClientEvent } from './admin-client';
+import { MockttpAdminPlugin } from '../admin/mockttp-admin-plugin';
+import { MockttpAdminRequestBuilder } from './mockttp-admin-request-builder';
+
+export interface MockttpClientOptions extends MockttpOptions {
+    /**
+     * The full URL to use to connect to a Mockttp admin server when using a
+     * remote (or local but browser) client.
+     *
+     * When using a local server, this option is ignored.
+     */
+    adminServerUrl?: string;
+
+    /**
+     * Options to include on all client requests, e.g. to add extra
+     * headers for authentication.
+     */
+    client?: {
+        headers?: { [key: string]: string };
+    }
+}
+
+export type MockttpClientEvent = `admin-client:${AdminClientEvent}`;
+
+/**
+ * A Mockttp implementation, controlling a remote Mockttp admin server.
+ *
+ * A MockttpClient supports the exact same Mockttp API as MockttpServer, but rather
+ * than directly using Node.js APIs to start a mock server and rewrite traffic, it
+ * makes calls to a remote admin server to start a mock server and rewrite traffic
+ * there. This is useful to allow proxy configuration from inside browser tests, and
+ * to allow creating mock proxies that run on remote machines.
+ */
+export class MockttpClient extends AbstractMockttp implements Mockttp {
+
+    private mockServerOptions: MockttpOptions;
+
+    private adminClient: AdminClient<{ http: MockttpAdminPlugin }>;
+    private requestBuilder: MockttpAdminRequestBuilder | undefined; // Set once server has started.
+
+    constructor(options: MockttpClientOptions = {}) {
+        super(_.defaults(options, {
+            // Browser clients generally want cors enabled. For other clients, it doesn't hurt.
+            // TODO: Maybe detect whether we're in a browser in future
+            cors: true,
+        }));
+
+        this.mockServerOptions = options;
+
+        this.adminClient = new AdminClient({
+            adminServerUrl: options.adminServerUrl,
+            requestOptions: options.client
+        });
+    }
+
+    enableDebug(): Promise<void> {
+        return this.adminClient.enableDebug();
+    }
+
+    reset = (): Promise<void> => {
+        return this.adminClient.reset();
+    }
+
+    get url(): string {
+        return this.adminClient.metadata!.http.mockRoot;
+    }
+
+    get port(): number {
+        return this.adminClient.metadata!.http.port;
+    }
+
+    async start(port?: number | PortRange) {
+        await this.adminClient.start({
+            http: {
+                port,
+                options: this.mockServerOptions
+            }
+        });
+
+        this.requestBuilder = new MockttpAdminRequestBuilder(this.adminClient.schema);
+    }
+
+    stop() {
+        return this.adminClient.stop();
+    }
+
+    public addRequestRules = async (...rules: RequestRuleData[]): Promise<MockedEndpoint[]> => {
+        return this._addRequestRules(rules, false);
+    }
+
+    public setRequestRules = async (...rules: RequestRuleData[]): Promise<MockedEndpoint[]> => {
+        return this._addRequestRules(rules, true);
+    }
+
+    public addWebSocketRules = async (...rules: WebSocketRuleData[]): Promise<MockedEndpoint[]> => {
+        return this._addWsRules(rules, false);
+    }
+
+    public setWebSocketRules = async (...rules: WebSocketRuleData[]): Promise<MockedEndpoint[]> => {
+        return this._addWsRules(rules, true);
+    }
+
+    private _addRequestRules = async (
+        rules: Array<RequestRuleData>,
+        reset: boolean
+    ): Promise<MockedEndpoint[]> => {
+        if (!this.requestBuilder) throw new Error('Cannot add rules before the server is started');
+
+        const { adminStream } = this.adminClient;
+        return this.adminClient.sendQuery(
+            this.requestBuilder.buildAddRequestRulesQuery(rules, reset, adminStream)
+        );
+    }
+
+    private _addWsRules = async (
+        rules: Array<WebSocketRuleData>,
+        reset: boolean
+    ): Promise<MockedEndpoint[]> => {
+        if (!this.requestBuilder) throw new Error('Cannot add rules before the server is started');
+
+        const { adminStream } = this.adminClient;
+
+        return this.adminClient.sendQuery(
+            this.requestBuilder.buildAddWebSocketRulesQuery(rules, reset, adminStream)
+        );
+    }
+
+    public async getMockedEndpoints() {
+        if (!this.requestBuilder) throw new Error('Cannot query mocked endpoints before the server is started');
+
+        return this.adminClient.sendQuery(
+            this.requestBuilder.buildMockedEndpointsQuery()
+        );
+    }
+
+    public async getPendingEndpoints() {
+        if (!this.requestBuilder) throw new Error('Cannot query pending endpoints before the server is started');
+
+        return this.adminClient.sendQuery(
+            this.requestBuilder.buildPendingEndpointsQuery()
+        );
+    }
+
+    public async getRuleParameterKeys() {
+        return this.adminClient.getRuleParameterKeys();
+    }
+
+    public on(event: SubscribableEvent | MockttpClientEvent, callback: (data: any) => void): Promise<void> {
+        if (event.startsWith('admin-client:')) {
+            // All MockttpClient events come from the internal admin-client instance:
+            this.adminClient.on(event.slice('admin-client:'.length), callback);
+            return Promise.resolve();
+        }
+
+        if (!this.requestBuilder) throw new Error('Cannot subscribe to Mockttp events before the server is started');
+
+        const subRequest = this.requestBuilder.buildSubscriptionRequest(event as SubscribableEvent);
+
+        if (!subRequest) {
+            // We just return an immediately promise if we don't recognize the event, which will quietly
+            // succeed but never call the corresponding callback (the same as the server and most event
+            // sources in the same kind of situation). This is what happens when the *client* doesn't
+            // recognize the event. Subscribe() below handles the unknown-to-server case.
+            console.warn(`Ignoring subscription for event unrecognized by Mockttp client: ${event}`);
+            return Promise.resolve();
+        }
+
+        return this.adminClient.subscribe(subRequest, callback);
+    }
+}

package/src/client/schema-introspection.ts

@@ -0,0 +1,131 @@
+import * as _ from 'lodash';
+
+export class SchemaIntrospector {
+
+    constructor(
+        private adminServerSchema: any
+    ) {}
+
+    public queryTypeDefined(queryType: string): boolean {
+        return this.typeHasField('Query', queryType);
+    }
+
+    public isTypeDefined(typeName: string): boolean {
+        return _.some(this.adminServerSchema.types, { name: typeName });
+    }
+
+    public typeHasField(typeName: string, fieldName: string): boolean {
+        const type: any = _.find(this.adminServerSchema.types, { name: typeName });
+        if (!type) return false;
+        return !!_.find(type.fields, { name: fieldName });
+    }
+
+    public asOptionalField(typeName: string | string[], fieldName: string): string {
+        const possibleNames = !Array.isArray(typeName) ? [typeName] : typeName;
+
+        const firstAvailableName = possibleNames.find((name) => this.isTypeDefined(name));
+        if (!firstAvailableName) return '';
+
+        return (this.typeHasField(firstAvailableName, fieldName))
+            ? fieldName
+            : '';
+    }
+
+    public typeHasInputField(typeName: string, fieldName: string): boolean {
+        const type: any = _.find(this.adminServerSchema.types, { name: typeName });
+        if (!type) return false;
+        return !!_.find(type.inputFields, { name: fieldName });
+    }
+
+}
+
+// Taken from src/utilities/introspectionQuery.js in GraphQL-js
+// Copied directly, to avoid bundling the whole thing into frontend code.
+export const introspectionQuery = `
+  query IntrospectionQuery {
+    __schema {
+      queryType { name }
+      mutationType { name }
+      subscriptionType { name }
+      types {
+        ...FullType
+      }
+      directives {
+        name
+        locations
+        args {
+          ...InputValue
+        }
+      }
+    }
+  }
+
+  fragment FullType on __Type {
+    kind
+    name
+    fields(includeDeprecated: true) {
+      name
+      args {
+        ...InputValue
+      }
+      type {
+        ...TypeRef
+      }
+      isDeprecated
+      deprecationReason
+    }
+    inputFields {
+      ...InputValue
+    }
+    interfaces {
+      ...TypeRef
+    }
+    enumValues(includeDeprecated: true) {
+      name
+      isDeprecated
+      deprecationReason
+    }
+    possibleTypes {
+      ...TypeRef
+    }
+  }
+
+  fragment InputValue on __InputValue {
+    name
+    type { ...TypeRef }
+    defaultValue
+  }
+
+  fragment TypeRef on __Type {
+    kind
+    name
+    ofType {
+      kind
+      name
+      ofType {
+        kind
+        name
+        ofType {
+          kind
+          name
+          ofType {
+            kind
+            name
+            ofType {
+              kind
+              name
+              ofType {
+                kind
+                name
+                ofType {
+                  kind
+                  name
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;

package/src/main.browser.ts

@@ -0,0 +1,60 @@
+import { MockttpClient } from "./client/mockttp-client";
+
+import { Mockttp, MockttpOptions } from "./mockttp";
+export { Method, RulePriority } from "./types";
+
+// Export rule data builders:
+import * as matchers from './rules/matchers';
+import * as requestHandlerDefinitions from './rules/requests/request-handler-definitions';
+import * as webSocketHandlerDefinitions from './rules/websockets/websocket-handler-definitions';
+import * as completionCheckers from './rules/completion-checkers';
+
+export {
+    matchers,
+    requestHandlerDefinitions,
+    webSocketHandlerDefinitions,
+    completionCheckers
+};
+
+// We re-export definitions to pretend they're real handlers in the browser. This should be safe
+// because the missing methods (i.e. handle()) were always unusable in non-Node environments anyway.
+// In practice though, new browser code using this should actively use requestHandlerDefinitions instead.
+// In future, we should probably expose definitions only for both browsers & node, but that's a
+// breaking change.
+export const requestHandlers = {
+    'SimpleHandler': requestHandlerDefinitions.SimpleHandlerDefinition,
+    'CallbackHandler': requestHandlerDefinitions.CallbackHandlerDefinition,
+    'StreamHandler': requestHandlerDefinitions.StreamHandlerDefinition,
+    'FileHandler': requestHandlerDefinitions.FileHandlerDefinition,
+    'PassThroughHandler': requestHandlerDefinitions.PassThroughHandlerDefinition,
+    'CloseConnectionHandler': requestHandlerDefinitions.CloseConnectionHandlerDefinition,
+    'TimeoutHandler': requestHandlerDefinitions.TimeoutHandlerDefinition,
+    'HandlerLookup': requestHandlerDefinitions.HandlerDefinitionLookup
+};
+
+export const webSocketHandlers = {
+    'PassThroughWebSocketHandler': webSocketHandlerDefinitions.PassThroughWebSocketHandlerDefinition,
+    'CloseConnectionHandler': webSocketHandlerDefinitions.CloseConnectionHandlerDefinition,
+    'TimeoutHandler': webSocketHandlerDefinitions.TimeoutHandlerDefinition,
+    'WsHandlerLookup': webSocketHandlerDefinitions.WsHandlerDefinitionLookup
+};
+
+export { MOCKTTP_PARAM_REF } from './rules/rule-parameters';
+
+// Export the core API:
+export function getLocal(options: MockttpOptions = {}): Mockttp {
+    return new MockttpClient(options);
+}
+
+export function getRemote(options: MockttpOptions = {}): Mockttp {
+    return new MockttpClient(options);
+}
+
+export function getAdminServer(): never {
+    throw new Error('Cannot set up an admin server within a browser');
+}
+
+export { resetAdminServer } from "./client/admin-client";
+
+export * as PluggableAdmin from './pluggable-admin-api/pluggable-admin';
+export * as MockttpPluggableAdmin from './pluggable-admin-api/mockttp-pluggable-admin';

package/src/main.ts

@@ -0,0 +1,160 @@
+import { Mockttp, MockttpOptions, MockttpHttpsOptions, SubscribableEvent, PortRange } from "./mockttp";
+import { MockttpServer } from "./server/mockttp-server";
+import {
+    MockttpClient,
+    MockttpClientOptions
+} from "./client/mockttp-client";
+import { MockttpAdminServer, MockttpAdminServerOptions } from "./admin/mockttp-admin-server";
+
+// Export the core type definitions:
+export * from "./types";
+export type {
+    Mockttp,
+    MockttpServer,
+    MockttpAdminServer,
+    MockttpOptions,
+    MockttpHttpsOptions,
+    MockttpClientOptions,
+    MockttpAdminServerOptions,
+    SubscribableEvent,
+    PortRange
+};
+
+// Export now-renamed types with the old aliases to provide backward compat and
+// avoid unnecessary type breakage:
+export type { TlsHandshakeFailure as TlsRequest } from './types';
+export type {
+    CertDataOptions as HttpsOptions,
+    CertPathOptions as HttpsPathOptions
+} from './util/tls';
+
+// Export rule data builders & type definitions:
+import * as matchers from './rules/matchers';
+import * as requestHandlers from './rules/requests/request-handlers';
+import * as requestHandlerDefinitions from './rules/requests/request-handler-definitions';
+import * as webSocketHandlers from './rules/websockets/websocket-handlers';
+import * as webSocketHandlerDefinitions from './rules/websockets/websocket-handler-definitions';
+import * as completionCheckers from './rules/completion-checkers';
+
+export {
+    matchers,
+    requestHandlers,
+    requestHandlerDefinitions,
+    webSocketHandlers,
+    webSocketHandlerDefinitions,
+    completionCheckers
+};
+
+import type { RequestRule, RequestRuleData } from './rules/requests/request-rule';
+import type { WebSocketRule, WebSocketRuleData } from './rules/websockets/websocket-rule';
+
+export type { RequestRule, RequestRuleData, WebSocketRule, WebSocketRuleData };
+export type {
+    ProxyConfig,
+    ProxySetting,
+    ProxySettingSource,
+    ProxySettingCallback,
+    ProxySettingCallbackParams
+} from './rules/proxy-config';
+export type {
+    CADefinition,
+    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";
+
+export {
+    MOCKTTP_PARAM_REF,
+    RuleParameterReference,
+    RuleParameters
+} from './rules/rule-parameters';
+export type { ServerMockedEndpoint } from "./server/mocked-endpoint";
+
+// Export TLS utility methods:
+export {
+    generateCACertificate,
+    generateSPKIFingerprint
+} from './util/tls';
+
+// Export various referenced utility types:
+export type {
+    CAOptions,
+    PEM,
+    CertDataOptions,
+    CertPathOptions
+} from './util/tls';
+export type { CachedDns, DnsLookupFunction } from './util/dns';
+export type { Serialized, SerializedValue } from './serialization/serialization';
+export type { MaybePromise } from './util/type-utils';
+
+// Export the core API:
+
+/**
+ * Get a Mockttp instance on the local machine.
+ *
+ * In most simple environments, you can call this method directly and immediately
+ * get a Mockttp instance and start mocking servers.
+ *
+ * In node, the mocked servers will run in process and require no further setup.
+ *
+ * In browsers this is an alias for getRemote. You'll need to start a Mockttp admin server
+ * outside your tests before calling this, which will create and manage your fake servers
+ * outside the browser.
+ */
+export function getLocal(options: MockttpOptions = {}): Mockttp {
+    return new MockttpServer(options);
+}
+
+/**
+ * Get a Mockttp instance, controlled through a Mockttp admin server.
+ *
+ * This connects to a Mockttp admin server, and uses that to start
+ * and stop mock servers.
+ */
+export function getRemote(options: MockttpClientOptions = {}): Mockttp {
+    return new MockttpClient(options);
+}
+
+/**
+ * Get a Mockttp admin server, which can be used with a Mockttp remote client to create
+ * & manage Mockttp instances either from remote machines or from local environments
+ * that lack necessary capabilities, e.g. to use Mockttp from inside a browser.
+ *
+ * This function exists so you can set up these servers programmatically, but for most
+ * usage you can just run your tests via the `mockttp` binary, which will automatically
+ * start and stop an admin server for you:
+ *
+ * ```
+ * mockttp -c <your test command>
+ * ```
+ */
+export function getAdminServer(options: MockttpAdminServerOptions = {}): MockttpAdminServer {
+    return new MockttpAdminServer(options);
+}
+import { resetAdminServer } from "./client/admin-client";
+export { resetAdminServer };
+
+/**
+ * This API is not yet stable, and is intended for internal use only. It may change in future
+ * in minor versions without warning.
+ *
+ * These generic pluggable admin components allow composing an admin server and client that
+ * are capable of managing arbitrary mock protocols, including Mockttp but also others depending
+ * on the admin plugins used. To use Mockttp, combine this with the MockttpPluggableAdmin API.
+ * @category Internal
+ */
+export * as PluggableAdmin from './pluggable-admin-api/pluggable-admin';
+
+/**
+ * This API is not yet stable, and is intended for internal use only. It may change in future
+ * in minor versions without warning.
+ *
+ * These plugin components can be applied to the PluggableAdmin API to create a remotely
+ * controlable mock management server that can mock HTTP in addition to protocols from
+ * other plugins.
+ * @category Internal
+ */
+export * as MockttpPluggableAdmin from './pluggable-admin-api/mockttp-pluggable-admin';