@jaredwray/mockhttp 0.9.0 → 1.0.0

package/README.md

@@ -12,6 +12,7 @@ A simple HTTP server that can be used to mock HTTP responses for testing purpose
 
 # Features
 * All the features of [httpbin](https://httpbin.org/)
+* Taps - Inject custom responses for testing and develepment
 * `@fastify/helmet` built in by default
 * Built with `nodejs`, `typescript`, and `fastify`
 * Deploy via `docker` or `nodejs`
@@ -63,6 +64,328 @@ console.log(reaponse);
 await mockhttp.stop(); // stop the server
 ```
 
+# Response Injection (Tap Feature)
+
+The injection/tap feature allows you to "tap into" the request flow and inject custom responses for specific requests. This is particularly useful for:
+- **Offline testing** - Mock external API responses without network access
+- **Testing edge cases** - Simulate errors, timeouts, or specific response scenarios
+- **Development** - Work on your application without depending on external services
+
+## What is a "Tap"?
+
+A "tap" is a reference to an injected response, similar to "wiretapping" - you're intercepting requests and returning predefined responses. Each tap can be removed when you're done with it, restoring normal server behavior.
+
+## Basic Usage
+
+```javascript
+import { mockhttp } from '@jaredwray/mockhttp';
+
+const mock = new mockhttp();
+await mock.start();
+
+// Inject a simple response
+const tap = mock.taps.inject(
+  {
+    response: "Hello, World!",
+    statusCode: 200,
+    headers: { "Content-Type": "text/plain" }
+  },
+  {
+    url: "/api/greeting",
+    method: "GET"
+  }
+);
+
+// Make requests - they will get the injected response
+const response = await fetch('http://localhost:3000/api/greeting');
+console.log(await response.text()); // "Hello, World!"
+
+// Remove the injection when done
+mock.taps.removeInjection(tap);
+
+await mock.close();
+```
+
+## Advanced Examples
+
+### Inject JSON Response
+
+```javascript
+const tap = mock.taps.inject(
+  {
+    response: { message: "Success", data: { id: 123 } },
+    statusCode: 200
+  },
+  { url: "/api/users/123" }
+);
+```
+
+### Wildcard URL Matching
+
+```javascript
+// Match all requests under /api/
+const tap = mock.taps.inject(
+  {
+    response: "API is mocked",
+    statusCode: 503
+  },
+  { url: "/api/*" }
+);
+```
+
+### Multiple Injections
+
+```javascript
+const tap1 = mock.taps.inject(
+  { response: "Users data" },
+  { url: "/api/users" }
+);
+
+const tap2 = mock.taps.inject(
+  { response: "Posts data" },
+  { url: "/api/posts" }
+);
+
+// View all active injections
+console.log(mock.taps.injections); // Map of all active taps
+
+// Remove specific injections
+mock.taps.removeInjection(tap1);
+mock.taps.removeInjection(tap2);
+```
+
+### Match by HTTP Method
+
+```javascript
+// Only intercept POST requests
+const tap = mock.taps.inject(
+  { response: "Created", statusCode: 201 },
+  { url: "/api/users", method: "POST" }
+);
+```
+
+### Match by Headers
+
+```javascript
+const tap = mock.taps.inject(
+  { response: "Authenticated response" },
+  {
+    url: "/api/secure",
+    headers: {
+      "authorization": "Bearer token123"
+    }
+  }
+);
+```
+
+### Catch-All Injection
+
+```javascript
+// Match ALL requests (no matcher specified)
+const tap = mock.taps.inject({
+  response: "Server is in maintenance mode",
+  statusCode: 503
+});
+```
+
+### Dynamic Function Response
+
+You can provide a function that dynamically generates the response based on the incoming request:
+
+```javascript
+// Function response with access to the request object
+const tap = mock.taps.inject(
+  (request) => {
+    return {
+      response: {
+        message: `You requested ${request.url}`,
+        method: request.method,
+        timestamp: new Date().toISOString()
+      },
+      statusCode: 200,
+      headers: {
+        "X-Request-Path": request.url
+      }
+    };
+  },
+  { url: "/api/*" }
+);
+```
+
+```javascript
+// Conditional responses based on request
+const tap = mock.taps.inject((request) => {
+  // Return error for URLs containing 'error'
+  if (request.url.includes('error')) {
+    return {
+      response: { error: "Something went wrong" },
+      statusCode: 500
+    };
+  }
+
+  // Return success for everything else
+  return {
+    response: { status: "success" },
+    statusCode: 200
+  };
+});
+```
+
+```javascript
+// Dynamic headers based on request
+const tap = mock.taps.inject(
+  (request) => ({
+    response: "OK",
+    statusCode: 200,
+    headers: {
+      "X-Original-Method": request.method,
+      "X-Original-URL": request.url,
+      "X-Original-Host": request.hostname
+    }
+  }),
+  { url: "/api/mirror" }
+);
+```
+
+# API Reference
+
+## MockHttp Class
+
+### Constructor
+
+```javascript
+new MockHttp(options?)
+```
+
+**Parameters:**
+- `options?` (MockHttpOptions):
+  - `port?`: number - The port to listen on (default: 3000)
+  - `host?`: string - The host to listen on (default: '0.0.0.0')
+  - `autoDetectPort?`: boolean - Auto-detect next available port if in use (default: true)
+  - `helmet?`: boolean - Use Helmet for security headers (default: true)
+  - `apiDocs?`: boolean - Enable Swagger API documentation (default: true)
+  - `httpBin?`: HttpBinOptions - Configure which httpbin routes to enable
+  - `hookOptions?`: HookifiedOptions - Hookified options
+
+### Properties
+
+- `port`: number - Get/set the server port
+- `host`: string - Get/set the server host
+- `autoDetectPort`: boolean - Get/set auto-detect port behavior
+- `helmet`: boolean - Get/set Helmet security headers
+- `apiDocs`: boolean - Get/set API documentation
+- `httpBin`: HttpBinOptions - Get/set httpbin route options
+- `server`: FastifyInstance - Get/set the Fastify server instance
+- `taps`: TapManager - Get/set the TapManager instance
+
+### Methods
+
+#### `async start()`
+
+Start the Fastify server. If already running, it will be closed and restarted.
+
+#### `async close()`
+
+Stop the Fastify server.
+
+#### `async detectPort()`
+
+Detect the next available port.
+
+**Returns:** number - The available port
+
+#### `async registerApiDocs(fastifyInstance?)`
+
+Register Swagger API documentation routes.
+
+#### `async registerHttpMethods(fastifyInstance?)`
+
+Register HTTP method routes (GET, POST, PUT, PATCH, DELETE).
+
+#### `async registerStatusCodeRoutes(fastifyInstance?)`
+
+Register status code routes.
+
+#### `async registerRequestInspectionRoutes(fastifyInstance?)`
+
+Register request inspection routes (headers, ip, user-agent).
+
+#### `async registerResponseInspectionRoutes(fastifyInstance?)`
+
+Register response inspection routes (cache, etag, response-headers).
+
+#### `async registerResponseFormatRoutes(fastifyInstance?)`
+
+Register response format routes (json, xml, html, etc.).
+
+#### `async registerRedirectRoutes(fastifyInstance?)`
+
+Register redirect routes (absolute, relative, redirect-to).
+
+#### `async registerCookieRoutes(fastifyInstance?)`
+
+Register cookie routes (get, set, delete).
+
+#### `async registerAnythingRoutes(fastifyInstance?)`
+
+Register "anything" catch-all routes.
+
+#### `async registerAuthRoutes(fastifyInstance?)`
+
+Register authentication routes (basic, bearer, digest, hidden-basic).
+
+## Taps (Response Injection)
+
+Access the TapManager via `mockHttp.taps` to inject custom responses.
+
+### `taps.inject(response, matcher?)`
+
+Injects a custom response for requests matching the criteria.
+
+**Parameters:**
+- `response` (InjectionResponse | InjectionResponseFunction):
+  - **Static Response** (InjectionResponse):
+    - `response`: string | object | Buffer - The response body
+    - `statusCode?`: number - HTTP status code (default: 200)
+    - `headers?`: object - Response headers
+  - **Function Response** (InjectionResponseFunction):
+    - A function that receives the Fastify request object and returns an InjectionResponse
+    - `(request: FastifyRequest) => InjectionResponse`
+    - Allows dynamic response generation based on request properties (url, method, headers, etc.)
+
+- `matcher?` (InjectionMatcher) - Optional matching criteria:
+  - `url?`: string - URL path (supports wildcards with `*`)
+  - `method?`: string - HTTP method (GET, POST, etc.)
+  - `hostname?`: string - Hostname to match
+  - `headers?`: object - Headers that must be present
+
+**Returns:** `InjectionTap` - A tap object with a unique `id` that can be used to remove the injection
+
+## `taps.removeInjection(tapOrId)`
+
+Removes an injection.
+
+**Parameters:**
+- `tapOrId`: InjectionTap | string - The tap object or tap ID to remove
+
+**Returns:** boolean - `true` if removed, `false` if not found
+
+### `taps.injections`
+
+A getter that returns a Map of all active injection taps.
+
+**Returns:** `Map<string, InjectionTap>` - Map of all active injections with tap IDs as keys
+
+## `taps.clear()`
+
+Removes all injections.
+
+## `taps.hasInjections`
+
+A getter that returns whether there are any active injections.
+
+**Returns:** boolean - `true` if there are active injections, `false` otherwise
+
 # About mockhttp.org 
 
 [mockhttp.org](https://mockhttp.org) is a free service that runs this codebase and allows you to use it for testing purposes. It is a simple way to mock HTTP responses for testing purposes. It is globally available has some limitations on it to prevent abuse such as requests per second. It is ran via [Cloudflare](https://cloudflare.com) and [Google Cloud Run](https://cloud.google.com/run/) across 7 regions globally and can do millions of requests per second.

package/dist/index.d.ts

@@ -1,6 +1,125 @@
-import { FastifyInstance } from 'fastify';
+import { FastifyRequest, FastifyInstance } from 'fastify';
 import { Hookified, HookifiedOptions } from 'hookified';
 
+/**
+ * Configuration for the injected response
+ */
+type InjectionResponse = {
+    /**
+     * The response body (can be string, object, or buffer)
+     */
+    response: string | Record<string, unknown> | Buffer;
+    /**
+     * HTTP status code for the response
+     * @default 200
+     */
+    statusCode?: number;
+    /**
+     * Response headers
+     */
+    headers?: Record<string, string | string[]>;
+};
+/**
+ * Criteria for matching requests to inject responses
+ */
+type InjectionMatcher = {
+    /**
+     * URL path to match (supports wildcards with *)
+     * @example "/api/users" - exact match
+     * @example "/api/*" - wildcard match
+     */
+    url?: string;
+    /**
+     * Hostname to match
+     * @example "localhost"
+     * @example "api.example.com"
+     */
+    hostname?: string;
+    /**
+     * HTTP method to match
+     * @example "GET"
+     * @example "POST"
+     */
+    method?: string;
+    /**
+     * Request headers to match (all specified headers must match)
+     */
+    headers?: Record<string, string>;
+};
+/**
+ * Function that returns an injection response
+ */
+type InjectionResponseFunction = (request: FastifyRequest) => InjectionResponse;
+/**
+ * A tap represents an active injection that can be removed later
+ */
+type InjectionTap = {
+    /**
+     * Unique identifier for this injection
+     */
+    id: string;
+    /**
+     * The response configuration or a function that returns it
+     */
+    response: InjectionResponse | InjectionResponseFunction;
+    /**
+     * The request matcher configuration
+     */
+    matcher?: InjectionMatcher;
+};
+/**
+ * Manages HTTP response injections for testing and mocking
+ */
+declare class TapManager {
+    private _injections;
+    constructor();
+    /**
+     * Get all active injection taps
+     */
+    get injections(): Map<string, InjectionTap>;
+    /**
+     * Check if there are any active injections
+     */
+    get hasInjections(): boolean;
+    /**
+     * Inject a custom response for requests matching the given criteria
+     * @param response - The response configuration or a function that returns it
+     * @param matcher - Optional criteria to match requests
+     * @returns A tap object that can be used to remove the injection
+     */
+    inject(response: InjectionResponse | InjectionResponseFunction, matcher?: InjectionMatcher): InjectionTap;
+    /**
+     * Remove an injection by its tap object or ID
+     * @param tapOrId - The tap object or tap ID to remove
+     * @returns true if the injection was removed, false if it wasn't found
+     */
+    removeInjection(tapOrId: InjectionTap | string): boolean;
+    /**
+     * Find the first injection that matches the given request
+     * @param request - The Fastify request object
+     * @returns The matching injection tap, or undefined if no match
+     */
+    matchRequest(request: FastifyRequest): InjectionTap | undefined;
+    /**
+     * Clear all injections
+     */
+    clear(): void;
+    /**
+     * Check if a request matches the given matcher criteria
+     * @param request - The Fastify request object
+     * @param matcher - The matcher criteria (undefined matches all requests)
+     * @returns true if the request matches
+     */
+    private requestMatches;
+    /**
+     * Check if a URL matches a pattern (supports wildcards with *)
+     * @param url - The URL to test
+     * @param pattern - The pattern to match against
+     * @returns true if the URL matches the pattern
+     */
+    private urlMatches;
+}
+
 type HttpBinOptions = {
     httpMethods?: boolean;
     redirects?: boolean;
@@ -51,6 +170,7 @@ declare class MockHttp extends Hookified {
     private _apiDocs;
     private _httpBin;
     private _server;
+    private _taps;
     constructor(options?: MockHttpOptions);
     /**
      * The port to listen on. If not provided, defaults to 3000 and detects the next available port if in use.
@@ -118,6 +238,14 @@ declare class MockHttp extends Hookified {
      * The Fastify server instance.
      */
     set server(server: FastifyInstance);
+    /**
+     * The TapManager instance for managing injection taps.
+     */
+    get taps(): TapManager;
+    /**
+     * The TapManager instance for managing injection taps.
+     */
+    set taps(taps: TapManager);
     /**
      * Start the Fastify server. If the server is already running, it will be closed and restarted.
      */
@@ -181,4 +309,4 @@ declare class MockHttp extends Hookified {
 
 declare const start: () => Promise<MockHttp>;
 
-export { MockHttp as default, MockHttp as mockhttp, start };
+export { type InjectionMatcher, type InjectionResponse, type InjectionTap, MockHttp as default, MockHttp as mockhttp, start };