Scaffold support for multistep rules & rename all 'handlers' to 'steps'

This is a breaking change for the manual rule building APIs
(server.addRule({ handler: new XYZ })) but not for the most common &
standard chaining (server.forX().thenY()) rule definition APIs.

Internally this includes backward compatibility on both client & server
side, so should be safe to deploy either side independently, as long as
only one-step rules are used.

As yet there are no multi-step rules in place, so this is just
scaffolding & future planning for now (watch this space...)

Author: pimterry

src/admin/mockttp-schema.ts

@@ -48,15 +48,17 @@ export const MockttpSchema = gql`
         id: String
         priority: Int
         matchers: [Raw!]!
-        handler: Raw!
+        handler: Raw # Backward compat, deprecated
+        steps: [Raw!] # Can only be unset if handler is set
         completionChecker: Raw
     }
 
     input WebSocketMockRule {
         id: String
         priority: Int
         matchers: [Raw!]!
-        handler: Raw!
+        handler: Raw # Backward compat, deprecated
+        steps: [Raw!] # Can only be unset if handler is set
         completionChecker: Raw
     }
 

src/client/mockttp-admin-request-builder.ts

@@ -17,6 +17,7 @@ import { MockedEndpointClient } from "./mocked-endpoint-client";
 import { AdminClient } from './admin-client';
 import { serializeRuleData } from '../rules/rule-serialization';
 import { deserializeBodyReader } from '../serialization/body-serialization';
+import { unreachableCheck } from '@httptoolkit/util';
 
 function normalizeHttpMessage(message: any, event?: SubscribableEvent) {
     if (message.timingEvents) {
@@ -95,67 +96,30 @@ export class MockttpAdminRequestBuilder {
         this.messageBodyDecoding = options.messageBodyDecoding;
     }
 
-    buildAddRequestRulesQuery(
-        rules: Array<RequestRuleData>,
+    buildAddRulesQuery(
+        type: 'http' | 'ws',
+        rules: Array<RequestRuleData | WebSocketRuleData>,
         reset: boolean,
         adminStream: stream.Duplex
     ): AdminQuery<
         { endpoints: Array<{ id: string, explanation?: string }> },
         MockedEndpoint[]
     > {
-        const requestName = (reset ? 'Set' : 'Add') + 'Rules';
-        const mutationName = (reset ? 'set' : 'add') + 'Rules';
-
-        const serializedRules = rules.map((rule) => {
-            const serializedRule = serializeRuleData(rule, adminStream)
-            if (!this.schema.typeHasInputField('MockRule', 'id')) {
-                delete serializedRule.id;
-            }
-            return serializedRule;
-        });
-
-        return {
-            query: gql`
-                mutation ${requestName}($newRules: [MockRule!]!) {
-                    endpoints: ${mutationName}(input: $newRules) {
-                        id,
-                        ${this.schema.asOptionalField('MockedEndpoint', 'explanation')}
-                    }
-                }
-            `,
-            variables: {
-                newRules: serializedRules
-            },
-            transformResponse: (response, { adminClient }) => {
-                return response.endpoints.map(({ id, explanation }) =>
-                    new MockedEndpointClient(
-                        id,
-                        explanation,
-                        this.getEndpointDataGetter(adminClient, id)
-                    )
-                )
-            }
-        };
-    }
-
-    buildAddWebSocketRulesQuery(
-        rules: Array<WebSocketRuleData>,
-        reset: boolean,
-        adminStream: stream.Duplex
-    ): AdminQuery<
-        { endpoints: Array<{ id: string, explanation?: string }> },
-        MockedEndpoint[]
-    > {
-        // Seperate and simpler than buildAddRequestRulesQuery, because it doesn't have to
-        // deal with backward compatibility.
-        const requestName = (reset ? 'Set' : 'Add') + 'WebSocketRules';
-        const mutationName = (reset ? 'set' : 'add') + 'WebSocketRules';
-
-        const serializedRules = rules.map((rule) => serializeRuleData(rule, adminStream));
+        const ruleTypeName = type === 'http'
+                ? ''
+            : type === 'ws'
+                ? 'WebSocket'
+            : unreachableCheck(type);
+        const requestName = (reset ? 'Set' : 'Add') + ruleTypeName + 'Rules';
+        const mutationName = (reset ? 'set' : 'add') + ruleTypeName + 'Rules';
+
+        // Backward compatibility for old servers that don't support steps:
+        const supportsSteps = this.schema.typeHasInputField('MockRule', 'steps');
+        const serializedRules = rules.map((rule) => serializeRuleData(rule, adminStream, { supportsSteps }));
 
         return {
             query: gql`
-                mutation ${requestName}($newRules: [WebSocketMockRule!]!) {
+                mutation ${requestName}($newRules: [${ruleTypeName}MockRule!]!) {
                     endpoints: ${mutationName}(input: $newRules) {
                         id,
                         explanation

src/client/mockttp-client.ts

@@ -143,7 +143,7 @@ export class MockttpClient extends AbstractMockttp implements Mockttp {
 
         const { adminStream } = this.adminClient;
         return this.adminClient.sendQuery(
-            this.requestBuilder.buildAddRequestRulesQuery(rules, reset, adminStream)
+            this.requestBuilder.buildAddRulesQuery('http', rules, reset, adminStream)
         );
     }
 
@@ -156,7 +156,7 @@ export class MockttpClient extends AbstractMockttp implements Mockttp {
         const { adminStream } = this.adminClient;
 
         return this.adminClient.sendQuery(
-            this.requestBuilder.buildAddWebSocketRulesQuery(rules, reset, adminStream)
+            this.requestBuilder.buildAddRulesQuery('ws', rules, reset, adminStream)
         );
     }
 

src/main.browser.ts

@@ -5,14 +5,14 @@ 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 requestStepDefinitions from './rules/requests/request-step-definitions';
+import * as webSocketStepDefinitions from './rules/websockets/websocket-step-definitions';
 import * as completionCheckers from './rules/completion-checkers';
 
 export {
     matchers,
-    requestHandlerDefinitions as requestHandlers,
-    webSocketHandlerDefinitions as webSocketHandlers,
+    requestStepDefinitions as requestSteps,
+    webSocketStepDefinitions as webSocketSteps,
     completionCheckers
 };
 

src/main.ts

@@ -26,19 +26,19 @@ export type {
 
 // Export rule data builders & type definitions:
 import * as matchers from './rules/matchers';
-import type { RequestHandler, RequestHandlerOptions } from './rules/requests/request-handlers';
-import * as requestHandlerDefinitions from './rules/requests/request-handler-definitions';
-import type { WebSocketHandler } from './rules/websockets/websocket-handlers';
-import * as webSocketHandlerDefinitions from './rules/websockets/websocket-handler-definitions';
+import type { RequestStep, RequestStepOptions } from './rules/requests/request-steps';
+import * as requestStepDefinitions from './rules/requests/request-step-definitions';
+import type { WebSocketStep } from './rules/websockets/websocket-steps';
+import * as webSocketStepDefinitions from './rules/websockets/websocket-step-definitions';
 import * as completionCheckers from './rules/completion-checkers';
 
 export {
     matchers,
-    RequestHandler,
-    RequestHandlerOptions,
-    requestHandlerDefinitions as requestHandlers,
-    WebSocketHandler,
-    webSocketHandlerDefinitions as webSocketHandlers,
+    RequestStep,
+    RequestStepOptions,
+    requestStepDefinitions as requestSteps,
+    WebSocketStep,
+    webSocketStepDefinitions as webSocketSteps,
     completionCheckers
 };
 
@@ -57,7 +57,7 @@ export type {
     CADefinition,
     ForwardingOptions,
     PassThroughLookupOptions,
-    PassThroughHandlerConnectionOptions
+    PassThroughStepConnectionOptions
 } from './rules/passthrough-handling-definitions';
 
 export type { RequestRuleBuilder } from "./rules/requests/request-rule-builder";

src/rules/base-rule-builder.ts

@@ -1,7 +1,7 @@
 import { isString } from "lodash";
 import { MaybePromise } from "../main";
 
-import { CompletedRequest, Method, RulePriority } from "../types";
+import { CompletedRequest, RulePriority } from "../types";
 
 import {
     RuleCompletionChecker,

src/rules/passthrough-handling-definitions.ts

@@ -36,7 +36,7 @@ export type CADefinition =
  * This defines the upstream connection parameters. These passthrough parameters
  * are shared between both WebSocket & Request passthrough rules.
  */
-export interface PassThroughHandlerConnectionOptions {
+export interface PassThroughStepConnectionOptions {
     /**
      * The forwarding configuration for the passthrough rule.
      * This generally shouldn't be used explicitly unless you're

src/rules/passthrough-handling.ts

@@ -19,8 +19,8 @@ import { getHeaderValue } from '../util/header-utils';
 import {
     CallbackRequestResult,
     CallbackResponseMessageResult
-} from './requests/request-handler-definitions';
-import { AbortError } from './requests/request-handlers';
+} from './requests/request-step-definitions';
+import { AbortError } from './requests/request-steps';
 import {
     CADefinition,
     PassThroughLookupOptions

src/rules/requests/request-rule-builder.ts

@@ -6,19 +6,19 @@ import { Headers, CompletedRequest, Method, MockedEndpoint, Trailers } from "../
 import type { RequestRuleData } from "./request-rule";
 
 import {
-    SimpleHandlerDefinition,
-    PassThroughHandlerDefinition,
-    CallbackHandlerDefinition,
+    SimpleStepDefinition,
+    PassThroughStepDefinition,
+    CallbackStepDefinition,
     CallbackResponseResult,
-    StreamHandlerDefinition,
-    CloseConnectionHandlerDefinition,
-    TimeoutHandlerDefinition,
-    PassThroughHandlerOptions,
-    FileHandlerDefinition,
-    JsonRpcResponseHandlerDefinition,
-    ResetConnectionHandlerDefinition,
+    StreamStepDefinition,
+    CloseConnectionStepDefinition,
+    TimeoutStepDefinition,
+    PassThroughStepOptions,
+    FileStepDefinition,
+    JsonRpcResponseStepDefinition,
+    ResetConnectionStepDefinition,
     CallbackResponseMessageResult
-} from "./request-handler-definitions";
+} from "./request-step-definitions";
 import { byteLength } from "../../util/util";
 import { BaseRuleBuilder } from "../base-rule-builder";
 import { MethodMatcher, RegexPathMatcher, SimplePathMatcher, WildcardMatcher } from "../matchers";
@@ -141,13 +141,13 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
 
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
-            handler: new SimpleHandlerDefinition(
+            steps: [new SimpleStepDefinition(
                 status,
                 statusMessage,
                 data,
                 headers,
                 trailers
-            )
+            )]
         };
 
         return this.addRule(rule);
@@ -184,7 +184,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
 
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
-            handler: new SimpleHandlerDefinition(status, undefined, jsonData, headers)
+            steps: [new SimpleStepDefinition(status, undefined, jsonData, headers)]
         };
 
         return this.addRule(rule);
@@ -218,7 +218,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
     ): Promise<MockedEndpoint> {
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
-            handler: new CallbackHandlerDefinition(callback)
+            steps: [new CallbackStepDefinition(callback)]
         }
 
         return this.addRule(rule);
@@ -247,7 +247,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
     thenStream(status: number, stream: Readable, headers?: Headers): Promise<MockedEndpoint> {
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
-            handler: new StreamHandlerDefinition(status, stream, headers)
+            steps: [new StreamStepDefinition(status, stream, headers)]
         }
 
         return this.addRule(rule);
@@ -296,7 +296,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
 
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
-            handler: new FileHandlerDefinition(status, statusMessage, path, headers)
+            steps: [new FileStepDefinition(status, statusMessage, path, headers)]
         };
 
         return this.addRule(rule);
@@ -308,7 +308,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
      * an error.
      *
      * This method takes options to configure how the request is passed
-     * through. See {@link PassThroughHandlerOptions} for the full details
+     * through. See {@link PassThroughStepOptions} for the full details
      * of the options available.
      *
      * Calling this method registers the rule with the server, so it
@@ -321,10 +321,10 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
      *
      * @category Responses
      */
-    thenPassThrough(options?: PassThroughHandlerOptions): Promise<MockedEndpoint> {
+    thenPassThrough(options?: PassThroughStepOptions): Promise<MockedEndpoint> {
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
-            handler: new PassThroughHandlerDefinition(options)
+            steps: [new PassThroughStepDefinition(options)]
         };
 
         return this.addRule(rule);
@@ -341,7 +341,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
      * of the original request URL will be used instead.
      *
      * This method takes options to configure how the request is passed
-     * through. See {@link PassThroughHandlerOptions} for the full details
+     * through. See {@link PassThroughStepOptions} for the full details
      * of the options available.
      *
      * Calling this method registers the rule with the server, so it
@@ -356,19 +356,19 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
      */
     async thenForwardTo(
         forwardToLocation: string,
-        options: Omit<PassThroughHandlerOptions, 'forwarding'> & {
-            forwarding?: Omit<PassThroughHandlerOptions['forwarding'], 'targetHost'>
+        options: Omit<PassThroughStepOptions, 'forwarding'> & {
+            forwarding?: Omit<PassThroughStepOptions['forwarding'], 'targetHost'>
         } = {}
     ): Promise<MockedEndpoint> {
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
-            handler: new PassThroughHandlerDefinition({
+            steps: [new PassThroughStepDefinition({
                 ...options,
                 forwarding: {
                     ...options.forwarding,
                     targetHost: forwardToLocation
                 }
-            })
+            })]
         };
 
         return this.addRule(rule);
@@ -391,7 +391,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
     thenCloseConnection(): Promise<MockedEndpoint> {
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
-            handler: new CloseConnectionHandlerDefinition()
+            steps: [new CloseConnectionStepDefinition()]
         };
 
         return this.addRule(rule);
@@ -418,7 +418,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
     thenResetConnection(): Promise<MockedEndpoint> {
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
-            handler: new ResetConnectionHandlerDefinition()
+            steps: [new ResetConnectionStepDefinition()]
         };
 
         return this.addRule(rule);
@@ -441,7 +441,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
     thenTimeout(): Promise<MockedEndpoint> {
         const rule: RequestRuleData = {
             ...this.buildBaseRuleData(),
-            handler: new TimeoutHandlerDefinition()
+            steps: [new TimeoutStepDefinition()]
         };
 
         return this.addRule(rule);
@@ -457,7 +457,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
     thenSendJsonRpcResult(result: any) {
         const rule = {
             ...this.buildBaseRuleData(),
-            handler: new JsonRpcResponseHandlerDefinition({ result })
+            steps: [new JsonRpcResponseStepDefinition({ result })]
         };
 
         return this.addRule(rule);
@@ -473,7 +473,7 @@ export class RequestRuleBuilder extends BaseRuleBuilder {
     thenSendJsonRpcError(error: any) {
         const rule = {
             ...this.buildBaseRuleData(),
-            handler: new JsonRpcResponseHandlerDefinition({ error })
+            steps: [new JsonRpcResponseStepDefinition({ error })]
         };
 
         return this.addRule(rule);