@jaredwray/mockhttp 1.8.1 → 2.0.0

package/README.md

@@ -17,8 +17,8 @@ A simple HTTP server that can be used to mock HTTP responses for testing purpose
 * `@fastify/helmet` built in by default
 * Built with `nodejs`, `typescript`, and `fastify`
 * Deploy via `docker` or `nodejs`
-* Global deployment via [mockhttp.org](https://mockhttp.org) (free service)
-* Better API documentation and examples
+* Free hosted service at [mockhttp.org](https://mockhttp.org), running on a Cloudflare Worker
+* Documentation site and interactive OpenAPI reference (Docula)
 * Auto detect the port that is not in use
 * Maintained and updated regularly!
 
@@ -998,9 +998,13 @@ new MockHttp(options?)
   - `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)
+  - `apiDocs?`: boolean - Serve the Docula documentation site and OpenAPI spec (default: true)
+  - `siteDistPath?`: string - Path to the built Docula site (default: the package `site/dist` directory)
   - `rateLimit?`: RateLimitPluginOptions - Configure rate limiting (default: 1000 req/min, localhost excluded)
   - `logging?`: boolean - Enable logging (default: true)
+  - `staticFiles?`: boolean - Serve files from the package `public/` directory (default: true)
+  - `pluginTimeout?`: number - Fastify plugin boot timeout in milliseconds; `0` disables it (default: Fastify's timeout)
+  - `startBins?`: boolean - Start the request-bin cleanup timer during `initialize()` (default: true)
   - `httpBin?`: HttpBinOptions - Configure which httpbin routes to enable
     - `httpMethods?`: boolean - Enable HTTP method routes (default: true)
     - `redirects?`: boolean - Enable redirect routes (default: true)
@@ -1024,8 +1028,12 @@ new MockHttp(options?)
 - `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
+- `apiDocs`: boolean - Get/set whether the documentation site and OpenAPI spec are served
+- `siteDistPath`: string - Get/set the path to the built Docula site
 - `logging`: boolean - Get/set logging enabled state
+- `staticFiles`: boolean - Get/set whether files from `public/` are served
+- `pluginTimeout`: number | undefined - Get/set Fastify plugin boot timeout
+- `startBins`: boolean - Get/set whether bin cleanup starts during `initialize()`
 - `rateLimit`: RateLimitPluginOptions | undefined - Get/set rate limiting options
 - `httpBin`: HttpBinOptions - Get/set httpbin route options
 - `https`: HttpsOptions | undefined - Get/set HTTPS configuration
@@ -1038,6 +1046,10 @@ new MockHttp(options?)
 
 ### Methods
 
+#### `async initialize()`
+
+Register plugins and routes without listening. Use `server.inject()` afterwards, or call `start()` to bind a port.
+
 #### `async start()`
 
 Start the Fastify server. If already running, it will be closed and restarted.
@@ -1054,7 +1066,15 @@ Detect the next available port.
 
 #### `async registerApiDocs(fastifyInstance?)`
 
-Register Swagger API documentation routes.
+Register OpenAPI generation and the Docula documentation site.
+
+#### `async registerSwagger(fastifyInstance?)`
+
+Register `@fastify/swagger` and the live `/openapi.json` spec route.
+
+#### `async registerSite(fastifyInstance?)`
+
+Serve the built Docula site from `siteDistPath` when the directory exists.
 
 #### `async registerHttpMethods(fastifyInstance?)`
 
@@ -1210,9 +1230,11 @@ A getter that returns whether there are any active injections.
 
 **Returns:** boolean - `true` if there are active injections, `false` otherwise
 
-# About mockhttp.org 
+# About mockhttp.org
+
+[mockhttp.org](https://mockhttp.org) is a free hosted instance of this codebase for testing. It runs on a [Cloudflare Worker](https://developers.cloudflare.com/workers/) (no containers): documentation is served from Workers Assets, and mock APIs such as `/get` and `/post` run in the Worker. The service is globally available and rate-limited (1000 requests per minute per IP) to prevent abuse.
 
-[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.
+Getting Started is served at `/` and `/docs`, other guides at `/docs/...`, and the interactive HTTP API reference at `/api`. Mock endpoints such as `/get` and `/post` are unchanged.
 
 # Contributing
 

package/dist/index.d.mts

@@ -1,34 +1,51 @@
 import { RateLimitPluginOptions } from "@fastify/rate-limit";
 import { FastifyInstance, FastifyRequest } from "fastify";
 import { Hookified, HookifiedOptions } from "hookified";
-
 //#region src/bin-store.d.ts
 /**
  * A request captured by a bin, including method, headers, body and metadata.
  */
 type CapturedRequest = {
-  /** Unique identifier for this captured request */id: string; /** Identifier of the bin that captured this request */
-  binId: string; /** HTTP method (GET, POST, etc.) */
-  method: string; /** Request URL path + query, relative to the bin (e.g. "/foo?x=1") */
-  url: string; /** Sub-path after the bin id ("/" if the request hit the bin root) */
-  path: string; /** Parsed query string parameters */
-  query: Record<string, string | string[]>; /** Request headers */
-  headers: Record<string, string | string[]>; /** Client IP address as reported by Fastify */
-  remoteAddress: string; /** Content-Type header value, if any */
-  contentType?: string; /** Original body length in bytes */
-  bodySize: number; /** Body payload as utf8 text, base64-encoded bytes, or null when empty */
-  body: string | null; /** Encoding used for the `body` field */
-  bodyEncoding: "utf8" | "base64" | "none"; /** True if the body was longer than the configured `maxBodySize` */
-  truncated: boolean; /** ISO timestamp of when the request was captured */
+  /** Unique identifier for this captured request */
+  id: string;
+  /** Identifier of the bin that captured this request */
+  binId: string;
+  /** HTTP method (GET, POST, etc.) */
+  method: string;
+  /** Request URL path + query, relative to the bin (e.g. "/foo?x=1") */
+  url: string;
+  /** Sub-path after the bin id ("/" if the request hit the bin root) */
+  path: string;
+  /** Parsed query string parameters */
+  query: Record<string, string | string[]>;
+  /** Request headers */
+  headers: Record<string, string | string[]>;
+  /** Client IP address as reported by Fastify */
+  remoteAddress: string;
+  /** Content-Type header value, if any */
+  contentType?: string;
+  /** Original body length in bytes */
+  bodySize: number;
+  /** Body payload as utf8 text, base64-encoded bytes, or null when empty */
+  body: string | null;
+  /** Encoding used for the `body` field */
+  bodyEncoding: "utf8" | "base64" | "none";
+  /** True if the body was longer than the configured `maxBodySize` */
+  truncated: boolean;
+  /** ISO timestamp of when the request was captured */
   capturedAt: string;
 };
 /**
  * Metadata for a bin (without its captured requests).
  */
 type Bin = {
-  /** Unique short identifier for the bin */id: string; /** ISO timestamp of bin creation */
-  createdAt: string; /** ISO timestamp at which the bin expires */
-  expiresAt: string; /** Number of requests currently stored in the bin */
+  /** Unique short identifier for the bin */
+  id: string;
+  /** ISO timestamp of bin creation */
+  createdAt: string;
+  /** ISO timestamp at which the bin expires */
+  expiresAt: string;
+  /** Number of requests currently stored in the bin */
   requestCount: number;
 };
 /**
@@ -66,7 +83,7 @@ interface BinStore {
  * In-memory implementation of {@link BinStore} backed by two Maps. State is
  * lost when the process exits.
  */
-declare class InMemoryBinStore implements BinStore {
+export declare class InMemoryBinStore implements BinStore {
   private readonly _bins;
   private readonly _requests;
   createBin(bin: Bin): void;
@@ -85,18 +102,24 @@ declare class InMemoryBinStore implements BinStore {
  * Configuration options for {@link BinManager}.
  */
 type BinManagerOptions = {
-  /** Storage backend. Defaults to a new {@link InMemoryBinStore}. */store?: BinStore; /** Bin lifetime in milliseconds. Defaults to 24 hours. */
-  defaultTtlMs?: number; /** Maximum number of requests retained per bin (FIFO). Defaults to 100. */
-  maxRequestsPerBin?: number; /** Maximum captured body size in bytes. Larger bodies are truncated. Defaults to 1 MiB. */
-  maxBodySize?: number; /** Length of generated bin and request ids. Defaults to 12. */
-  idLength?: number; /** Interval between cleanup sweeps in milliseconds. Defaults to 1 minute. */
+  /** Storage backend. Defaults to a new {@link InMemoryBinStore}. */
+  store?: BinStore;
+  /** Bin lifetime in milliseconds. Defaults to 24 hours. */
+  defaultTtlMs?: number;
+  /** Maximum number of requests retained per bin (FIFO). Defaults to 100. */
+  maxRequestsPerBin?: number;
+  /** Maximum captured body size in bytes. Larger bodies are truncated. Defaults to 1 MiB. */
+  maxBodySize?: number;
+  /** Length of generated bin and request ids. Defaults to 12. */
+  idLength?: number;
+  /** Interval between cleanup sweeps in milliseconds. Defaults to 1 minute. */
   cleanupIntervalMs?: number;
 };
 /**
  * Manages request bins: ephemeral URL endpoints that capture incoming HTTP
  * requests so they can be inspected later.
  */
-declare class BinManager {
+export declare class BinManager {
   private readonly _store;
   private readonly _defaultTtlMs;
   private readonly _maxRequestsPerBin;
@@ -192,12 +215,12 @@ type CertificateFileOptions = CertificateOptions & {
  * Generate a self-signed certificate using only Node.js built-in crypto.
  * Returns PEM-encoded certificate and private key strings.
  */
-declare function generateCertificate(options?: CertificateOptions): CertificateResult;
+export declare function generateCertificate(options?: CertificateOptions): CertificateResult;
 /**
  * Generate a self-signed certificate and write PEM files to disk.
  * Returns the same CertificateResult as generateCertificate().
  */
-declare function generateCertificateFiles(options: CertificateFileOptions): Promise<CertificateResult>;
+export declare function generateCertificateFiles(options: CertificateFileOptions): Promise<CertificateResult>;
 //#endregion
 //#region src/tap-manager.d.ts
 /**
@@ -371,11 +394,22 @@ type MockHttpOptions = {
    */
   helmet?: boolean;
   /**
-   * Whether to use Swagger for API documentation. Defaults to true.
+   * Whether to serve files from the package `public/` directory (favicon, logos).
+   * Defaults to true. Disable this when those files are served by another layer
+   * such as Cloudflare Workers Assets.
+   */
+  staticFiles?: boolean;
+  /**
+   * Whether to serve the Docula documentation site and OpenAPI spec. Defaults to true.
    */
   apiDocs?: boolean;
   /**
-   * Whether to use Swagger UI. Defaults to true.
+   * Path to the built Docula site (`site/dist`). Defaults to the package's
+   * `site/dist` directory. Explicit paths are resolved from the current working directory.
+   */
+  siteDistPath?: string;
+  /**
+   * Configure which httpbin-style mock routes to enable. Defaults to all enabled.
    */
   httpBin?: HttpBinOptions;
   /**
@@ -391,6 +425,17 @@ type MockHttpOptions = {
    * Whether to enable logging. Defaults to true.
    */
   logging?: boolean;
+  /**
+   * Fastify plugin boot timeout in milliseconds. Set to `0` to disable the
+   * timeout (needed on Cloudflare Workers, where avvio timers are unreliable).
+   */
+  pluginTimeout?: number;
+  /**
+   * Whether to start the request-bin cleanup timer during `initialize()`.
+   * Defaults to true. Disable this on Cloudflare Workers, where `setInterval`
+   * during startup can hang the isolate.
+   */
+  startBins?: boolean;
   /**
    * HTTPS configuration. Set to true to auto-generate a self-signed certificate,
    * or provide an object with cert/key strings/paths or auto-generation options.
@@ -414,8 +459,12 @@ declare class MockHttp extends Hookified {
   private _host;
   private _autoDetectPort;
   private _helmet;
+  private _staticFiles;
   private _apiDocs;
+  private _siteDistPath;
   private _logging;
+  private _pluginTimeout?;
+  private _startBins;
   private _httpBin;
   private _rateLimit?;
   private _http2;
@@ -467,15 +516,35 @@ declare class MockHttp extends Hookified {
    */
   set helmet(helmet: boolean);
   /**
-   * Whether to use Swagger for API documentation. Defaults to true.
+   * Whether to serve files from the package `public/` directory. Defaults to true.
+   * @default true
+   */
+  get staticFiles(): boolean;
+  /**
+   * Whether to serve files from the package `public/` directory. Defaults to true.
+   * @default true
+   */
+  set staticFiles(staticFiles: boolean);
+  /**
+   * Whether to serve the Docula documentation site and OpenAPI spec. Defaults to true.
    * @default true
    */
   get apiDocs(): boolean;
   /**
-   * Whether to use Swagger for API documentation. Defaults to true.
+   * Whether to serve the Docula documentation site and OpenAPI spec. Defaults to true.
    * @default true
    */
   set apiDocs(apiDocs: boolean);
+  /**
+   * Path to the built Docula site served when `apiDocs` is enabled.
+   * @default the package `site/dist` directory
+   */
+  get siteDistPath(): string;
+  /**
+   * Path to the built Docula site served when `apiDocs` is enabled.
+   * @default the package `site/dist` directory
+   */
+  set siteDistPath(siteDistPath: string);
   /**
    * Whether to enable logging. Defaults to true.
    * @default true
@@ -486,6 +555,24 @@ declare class MockHttp extends Hookified {
    * @default true
    */
   set logging(logging: boolean);
+  /**
+   * Fastify plugin boot timeout in milliseconds. `undefined` uses Fastify's default.
+   */
+  get pluginTimeout(): number | undefined;
+  /**
+   * Fastify plugin boot timeout in milliseconds. `undefined` uses Fastify's default.
+   */
+  set pluginTimeout(pluginTimeout: number | undefined);
+  /**
+   * Whether to start the request-bin cleanup timer during `initialize()`.
+   * @default true
+   */
+  get startBins(): boolean;
+  /**
+   * Whether to start the request-bin cleanup timer during `initialize()`.
+   * @default true
+   */
+  set startBins(startBins: boolean);
   /**
    * HTTPS configuration. Set to true to auto-generate a self-signed certificate,
    * or provide an HttpsOptions object with cert/key or auto-generation options.
@@ -566,6 +653,11 @@ declare class MockHttp extends Hookified {
    * The BinManager instance for managing request bins.
    */
   set bins(bins: BinManager);
+  /**
+   * Register plugins and routes without listening. Use `inject()` against
+   * `server`, or call `start()` to bind a port.
+   */
+  initialize(): Promise<void>;
   /**
    * Start the Fastify server. If the server is already running, it will be closed and restarted.
    */
@@ -580,10 +672,20 @@ declare class MockHttp extends Hookified {
    */
   detectPort(): Promise<number>;
   /**
-   * This will register the API documentation routes including openapi and swagger ui.
+   * Register OpenAPI generation and the Docula documentation site.
    * @param fastifyInstance - the server instance to register the routes on.
    */
   registerApiDocs(fastifyInstance?: FastifyInstance): Promise<void>;
+  /**
+   * Register `@fastify/swagger` and the live `/openapi.json` spec route.
+   * @param fastifyInstance - the server instance to register the routes on.
+   */
+  registerSwagger(fastifyInstance?: FastifyInstance): Promise<void>;
+  /**
+   * Serve the built Docula site from `siteDistPath` when the directory exists.
+   * @param fastifyInstance - the server instance to register the routes on.
+   */
+  registerSite(fastifyInstance?: FastifyInstance): Promise<void>;
   /**
    * Register the HTTP methods routes.
    * @param fastifyInstance - the server instance to register the routes on.
@@ -645,6 +747,6 @@ declare class MockHttp extends Hookified {
 }
 //#endregion
 //#region src/index.d.ts
-declare const start: () => Promise<MockHttp>;
+export declare const start: () => Promise<MockHttp>;
 //#endregion
-export { type Bin, BinManager, type BinManagerOptions, type BinStore, type CapturedRequest, type CertificateFileOptions, type CertificateOptions, type CertificateResult, type HttpsOptions, InMemoryBinStore, type InjectionMatcher, type InjectionResponse, type InjectionTap, MockHttp as default, MockHttp as mockhttp, generateCertificate, generateCertificateFiles, start };
+export { type Bin, type BinManagerOptions, type BinStore, type CapturedRequest, type CertificateFileOptions, type CertificateOptions, type CertificateResult, type HttpsOptions, type InjectionMatcher, type InjectionResponse, type InjectionTap, MockHttp as default, MockHttp as mockhttp };