Interface MockttpClientOptions

interface MockttpClientOptions {
    adminServerUrl?: string;
    client?: {
        headers?: {
            [key: string]: string;
        };
    };
    cors?: boolean | CorsOptions;
    debug?: boolean;
    http2?: boolean | "fallback";
    https?: MockttpHttpsOptions;
    maxBodySize?: number;
    messageBodyDecoding?: "none" | "server-side";
    passthrough?: "unknown-protocol"[];
    recordTraffic?: boolean;
    socks?: boolean | SocksServerOptions;
    suggestChanges?: boolean;
}

Hierarchy (view full)

Properties

adminServerUrl?: string

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.

client?: {
    headers?: {
        [key: string]: string;
    };
}

Options to include on all client requests, e.g. to add extra headers for authentication.

cors?: boolean | CorsOptions

Should the server automatically respond to OPTIONS requests with a permissive response?

Defaults to true for remote clients (e.g. in the browser), and false otherwise. If this is set to false, browser requests will typically fail unless you stub OPTIONS responses by hand.

debug?: boolean

Should the server print extra debug information?

http2?: boolean | "fallback"

Should HTTP/2 be enabled? Can be true, false, or 'fallback'. If true, HTTP/2 is used for all clients supporting it. If false, HTTP/2 is never used. If 'fallback' HTTP/2 is used only for clients that do not advertise support for HTTP/1.1, but HTTP/1.1 is used by preference in all other cases.

Client HTTP/2 support is only advertised as part of the TLS options. When no HTTPS configuration is provided, 'fallback' is equivalent to false.

The HTTPS settings to be used. Optional, only HTTP interception will be enabled if omitted. This should be set to either a { key, cert } object containing the private key and certificate in PEM format, or a { keyPath, certPath } object containing the path to files containing that content.

maxBodySize?: number

The maximum body size to process, in bytes.

Bodies larger than this will be dropped, becoming empty, so they won't match body matchers, won't be available in .seenRequests, and won't be included in subscribed event data. Body data will still typically be included in passed through request & response data, in most cases, so this won't affect the external HTTP clients otherwise.

messageBodyDecoding?: "none" | "server-side"

Where should message body decoding happen? If set to 'server-side', (the default) then the request body will be pre-decoded on the server, and delivered to the client in decoded form (in addition to its encoded form), meaning that the client doesn't need to do any decoding itself (which can be awkward e.g. given encodings like zstd/Brotli with poor browser JS support).

If set to 'none', the request body will be delivered to the client in original encoded form. If so, any access to data that requires decoding (e.g. response.body.getText() on a gzipped response) will fail. Instead, you will need to read and decode body.buffer manually yourself.

This is only relevant for advanced use cases. In general, you should leave this as 'server-side' for convenient reliable behaviour, and set it only to 'none' if you are handling decoding yourself and want to actively optimize for that.

passthrough?: "unknown-protocol"[]

An array of rules for traffic that should be passed through the proxy immediately, without interception or modification.

This is subtly different to TLS passthrough/interceptOnly, which only apply to TLS connections, and only after the TLS client hello has been received and found to match a rule.

For now, the only rule here is 'unknown-protocol', which enables passthrough of all unknown protocols (i.e. traffic that is definitely not HTTP, HTTP/2, WebSocket, or SOCKS traffic) which are received on a proxy connection (a connection carrying end-destination information, such as SOCKS - direct connections of unknown data without any final destination information from a preceeding tunnel cannot be passed through).

Unknown protocol connections that cannot be passed through (because this rule is not enabled, or because they are not proxied with a destination specified) will be closed with a 400 Bad Request HTTP response like any other client HTTP error.

recordTraffic?: boolean

Record the requests & response for all traffic matched by each rule, and make it available via endpoint.getSeenRequests().

Defaults to true. It can be useful to set this to false if lots of data will be sent to/via the server, to avoid storing all traffic in memory unnecessarily, if getSeenRequests will not be used.

If this is set to false then getSeenRequests() will always return an empty array. This only disables the built-in persistence of request data, so traffic can still be captured live or stored elsewhere using .on('request') & .on('response').

socks?: boolean | SocksServerOptions

Should the server accept incoming SOCKS connections? Defaults to false.

If set to true or if detailed options are provided, the server will listen for incoming SOCKS connections on the same port as the HTTP server, unwrap received connections, and handle them like any other incoming TCP connection (intercepting HTTP(S) from within the SOCKS connection as normal).

The only supported option for now is authMethods.

suggestChanges?: boolean

By default, requests that match no rules will receive an explanation of the request & existing rules, followed by some suggested example Mockttp code which could be used to match the rule.

In some cases where the end client is unaware of Mockttp, these example suggestions are just confusing. Set suggestChanges to false to disable it.