@jaredwray/mockhttp 1.5.0 → 1.6.0

package/README.md

@@ -8,11 +8,11 @@
 [![Docker Pulls](https://img.shields.io/docker/pulls/jaredwray/mockhttp)](https://hub.docker.com/r/jaredwray/mockhttp)
 [![mockhttp.org](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fjaredwray.com%2Fapi%2Fmockhttp-traffic&query=%24.message&label=mockhttp.org)](https://mockhttp.org)
 
-A simple HTTP server that can be used to mock HTTP responses for testing purposes. Inspired by [httpbin](https://httpbin.org/) and built using `nodejs` and `fastify` with the idea of running it via https://mockhttp.org, via docker `jaredwray/mockhttp`, or nodejs `npm install jaredwray/mockhttp`.
+A simple HTTP server that can be used to mock HTTP responses for testing purposes. Inspired by [httpbin](https://httpbin.org/) and built using `nodejs` and `fastify` with the idea of running it via https://mockhttp.org, via docker `jaredwray/mockhttp`, or nodejs `npm install @jaredwray/mockhttp`.
 
 # Features
 * All the features of [httpbin](https://httpbin.org/)
-* Taps - Inject custom responses for testing and develepment
+* Taps - Inject custom responses for testing and development
 * `@fastify/helmet` built in by default
 * Built with `nodejs`, `typescript`, and `fastify`
 * Deploy via `docker` or `nodejs`
@@ -30,6 +30,7 @@ A simple HTTP server that can be used to mock HTTP responses for testing purpose
 - [Response Injection (Tap Feature)](#response-injection-tap-feature)
 - [Rate Limiting](#rate-limiting)
 - [Logging](#logging)
+- [Flexible URL Matching](#flexible-url-matching)
 - [API Reference](#api-reference)
 - [About mockhttp.org](#about-mockhttporg)
 - [Contributing](#contributing)
@@ -608,6 +609,21 @@ You can also disable logging via the `LOGGING` environment variable:
 LOGGING=false node your-app.js
 ```
 
+# Flexible URL Matching
+
+MockHttp ignores trailing path segments that come after the parsable portion of a URL. This is useful when a client appends extra data to a known endpoint — instead of returning 404, MockHttp serves the closest matching route.
+
+For example, all of these are served by `/status/:code`:
+
+```
+GET /status/429
+GET /status/429/
+GET /status/429/foo
+GET /status/429/foo/bar
+```
+
+The rewrite preserves the query string and only triggers when a more specific route exists; URLs whose first path segment doesn't correspond to a registered route still return 404.
+
 # API Reference
 
 ## MockHttp Class

package/dist/index.d.mts

@@ -0,0 +1,494 @@
+import { RateLimitPluginOptions } from "@fastify/rate-limit";
+import { FastifyInstance, FastifyRequest } from "fastify";
+import { Hookified, HookifiedOptions } from "hookified";
+
+//#region src/certificate.d.ts
+type CertificateOptions = {
+  /**
+   * Common Name for the certificate subject. Defaults to 'localhost'.
+   */
+  commonName?: string;
+  /**
+   * Subject Alternative Names. Defaults to [dns:localhost, ip:127.0.0.1, ip:::1].
+   */
+  altNames?: Array<{
+    type: "dns";
+    value: string;
+  } | {
+    type: "ip";
+    value: string;
+  }>;
+  /**
+   * Number of days the certificate is valid. Defaults to 365.
+   */
+  validityDays?: number;
+  /**
+   * RSA key size in bits. Defaults to 2048.
+   */
+  keySize?: number;
+};
+type CertificateResult = {
+  /**
+   * PEM-encoded X.509 certificate.
+   */
+  cert: string;
+  /**
+   * PEM-encoded PKCS#8 private key.
+   */
+  key: string;
+};
+type CertificateFileOptions = CertificateOptions & {
+  /**
+   * File path to write the certificate PEM.
+   */
+  certPath: string;
+  /**
+   * File path to write the private key PEM.
+   */
+  keyPath: string;
+};
+/**
+ * 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;
+/**
+ * Generate a self-signed certificate and write PEM files to disk.
+ * Returns the same CertificateResult as generateCertificate().
+ */
+declare function generateCertificateFiles(options: CertificateFileOptions): Promise<CertificateResult>;
+//#endregion
+//#region src/tap-manager.d.ts
+/**
+ * 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;
+}
+//#endregion
+//#region src/mock-http.d.ts
+type HttpBinOptions = {
+  httpMethods?: boolean;
+  redirects?: boolean;
+  requestInspection?: boolean;
+  responseInspection?: boolean;
+  statusCodes?: boolean;
+  responseFormats?: boolean;
+  cookies?: boolean;
+  anything?: boolean;
+  auth?: boolean;
+  images?: boolean;
+  dynamicData?: boolean;
+};
+type HttpsOptions = {
+  /**
+   * PEM-encoded certificate string, or file path to a certificate PEM file.
+   */
+  cert?: string;
+  /**
+   * PEM-encoded private key string, or file path to a private key PEM file.
+   */
+  key?: string;
+  /**
+   * If true, auto-generate a self-signed certificate. Defaults to true when no cert/key provided.
+   */
+  autoGenerate?: boolean;
+  /**
+   * Options for auto-generating a self-signed certificate. Only used when auto-generating.
+   */
+  certificateOptions?: CertificateOptions;
+};
+type MockHttpOptions = {
+  /**
+   * The port to listen on. If not provided, defaults to 3000 and detects the next available port if in use.
+   */
+  port?: number;
+  /**
+   * The host to listen on. If not provided, defaults to '0.0.0.0'.
+   */
+  host?: string;
+  /**
+   * Whether to automatically detect the next available port if the provided port is in use. Defaults
+   * to true.
+   */
+  autoDetectPort?: boolean;
+  /**
+   * Whether to use Helmet for security headers. Defaults to true.
+   */
+  helmet?: boolean;
+  /**
+   * Whether to use Swagger for API documentation. Defaults to true.
+   */
+  apiDocs?: boolean;
+  /**
+   * Whether to use Swagger UI. Defaults to true.
+   */
+  httpBin?: HttpBinOptions;
+  /**
+   * Rate limiting options. Defaults to 1000 requests per minute (localhost excluded).
+   * Set to undefined to disable rate limiting, or provide custom options to configure.
+   */
+  rateLimit?: boolean | RateLimitPluginOptions;
+  /**
+   * Hookified options.
+   */
+  hookOptions?: HookifiedOptions;
+  /**
+   * Whether to enable logging. Defaults to true.
+   */
+  logging?: 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.
+   */
+  https?: boolean | HttpsOptions;
+  /**
+   * Whether to enable HTTP/2 support. When used with `https`, enables h2 (HTTP/2 over TLS).
+   * When used without `https`, enables h2c (HTTP/2 cleartext).
+   * Defaults to false.
+   */
+  http2?: boolean;
+  /**
+   * Whether to allow HTTP/1.1 fallback when using HTTP/2 with HTTPS (ALPN negotiation).
+   * Only applies when both `http2` and `https` are enabled.
+   * Defaults to true.
+   */
+  http1?: boolean;
+};
+declare class MockHttp extends Hookified {
+  private _port;
+  private _host;
+  private _autoDetectPort;
+  private _helmet;
+  private _apiDocs;
+  private _logging;
+  private _httpBin;
+  private _rateLimit?;
+  private _http2;
+  private _http1;
+  private _https;
+  private _httpsCredentials;
+  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.
+   * @default 3000
+   */
+  get port(): number;
+  /**
+   * The port to listen on. If not provided, defaults to 3000 and detects the next available port if in use.
+   * @default 3000
+   */
+  set port(port: number);
+  /**
+   * The host to listen on. If not provided, defaults to 'localhost'.
+   * @default 'localhost'
+   */
+  get host(): string;
+  /**
+   * The host to listen on. If not provided, defaults to 'localhost'.
+   * @default 'localhost'
+   */
+  set host(host: string);
+  /**
+   * Whether to automatically detect the next available port if the provided port is in use. Defaults to true.
+   * @default true
+   */
+  get autoDetectPort(): boolean;
+  /**
+   * Whether to automatically detect the next available port if the provided port is in use. Defaults to true.
+   * @default true
+   */
+  set autoDetectPort(autoDetectPort: boolean);
+  /**
+   * Whether to use Helmet for security headers. Defaults to true.
+   * @default true
+   */
+  get helmet(): boolean;
+  /**
+   * Whether to use Helmet for security headers. Defaults to true.
+   * @default true
+   */
+  set helmet(helmet: boolean);
+  /**
+   * Whether to use Swagger for API documentation. Defaults to true.
+   * @default true
+   */
+  get apiDocs(): boolean;
+  /**
+   * Whether to use Swagger for API documentation. Defaults to true.
+   * @default true
+   */
+  set apiDocs(apiDocs: boolean);
+  /**
+   * Whether to enable logging. Defaults to true.
+   * @default true
+   */
+  get logging(): boolean;
+  /**
+   * Whether to enable logging. Defaults to true.
+   * @default true
+   */
+  set logging(logging: 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.
+   */
+  get https(): HttpsOptions | undefined;
+  /**
+   * HTTPS configuration. Set to true to auto-generate a self-signed certificate,
+   * or provide an HttpsOptions object with cert/key or auto-generation options.
+   */
+  set https(value: boolean | HttpsOptions | undefined);
+  /**
+   * Whether the server is running in HTTPS mode.
+   */
+  get isHttps(): boolean;
+  /**
+   * Whether HTTP/2 support is enabled.
+   * @default false
+   */
+  get http2(): boolean;
+  /**
+   * Whether HTTP/2 support is enabled.
+   * @default false
+   */
+  set http2(http2: boolean);
+  /**
+   * Whether to allow HTTP/1.1 fallback when using HTTP/2 with HTTPS.
+   * @default true
+   */
+  get http1(): boolean;
+  /**
+   * Whether to allow HTTP/1.1 fallback when using HTTP/2 with HTTPS.
+   * @default true
+   */
+  set http1(http1: boolean);
+  /**
+   * HTTP Bin options. Defaults to all enabled.
+   */
+  get httpBin(): HttpBinOptions;
+  /**
+   * HTTP Bin options. Defaults to all enabled.
+   */
+  set httpBin(httpBinary: HttpBinOptions);
+  /**
+   * Rate limiting options. Defaults to 1000 requests per minute (localhost excluded).
+   * Set to undefined to disable rate limiting, or provide custom options to configure.
+   * @default { max: 1000, timeWindow: "1 minute", allowList: ["127.0.0.1", "::1"] }
+   */
+  get rateLimit(): RateLimitPluginOptions | undefined;
+  /**
+   * Rate limiting options. Defaults to 1000 requests per minute (localhost excluded).
+   * Set to undefined to disable rate limiting, or provide custom options to configure.
+   *
+   * Note: Changing this property requires restarting the server (close() then start()) for changes to take effect.
+   * @default { max: 1000, timeWindow: "1 minute", allowList: ["127.0.0.1", "::1"] }
+   */
+  set rateLimit(rateLimit: RateLimitPluginOptions | undefined);
+  /**
+   * The Fastify server instance.
+   */
+  get server(): FastifyInstance;
+  /**
+   * 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.
+   */
+  start(): Promise<void>;
+  /**
+   * Close the Fastify server.
+   */
+  close(): Promise<void>;
+  /**
+   * Detect the next available port to run on.
+   * @returns The port that is available to run on
+   */
+  detectPort(): Promise<number>;
+  /**
+   * This will register the API documentation routes including openapi and swagger ui.
+   * @param fastifyInstance - the server instance to register the routes on.
+   */
+  registerApiDocs(fastifyInstance?: FastifyInstance): Promise<void>;
+  /**
+   * Register the HTTP methods routes.
+   * @param fastifyInstance - the server instance to register the routes on.
+   */
+  registerHttpMethods(fastifyInstance?: FastifyInstance): Promise<void>;
+  /**
+   * Register the status code routes.
+   * @param fastifyInstance - the server instance to register the routes on.
+   */
+  registerStatusCodeRoutes(fastifyInstance?: FastifyInstance): Promise<void>;
+  /**
+   * Register the request inspection routes.
+   * @param fastifyInstance - the server instance to register the routes on.
+   */
+  registerRequestInspectionRoutes(fastifyInstance?: FastifyInstance): Promise<void>;
+  /**
+   * Register the response inspection routes.
+   * @param fastifyInstance - the server instance to register the routes on.
+   */
+  registerResponseInspectionRoutes(fastifyInstance?: FastifyInstance): Promise<void>;
+  registerResponseFormatRoutes(fastifyInstance?: FastifyInstance): Promise<void>;
+  /**
+   * Register the redirect routes.
+   * @param fastifyInstance - the server instance to register the routes on.
+   */
+  registerRedirectRoutes(fastifyInstance?: FastifyInstance): Promise<void>;
+  /**
+   * Register the cookie routes.
+   * @param fastifyInstance - the server instance to register the routes on.
+   */
+  registerCookieRoutes(fastifyInstance?: FastifyInstance): Promise<void>;
+  /**
+   * Register the anything routes.
+   * @param fastifyInstance - the server instance to register the routes on.
+   */
+  registerAnythingRoutes(fastifyInstance?: FastifyInstance): Promise<void>;
+  /**
+   * Register the auth routes.
+   * @param fastifyInstance - the server instance to register the routes on.
+   */
+  registerAuthRoutes(fastifyInstance?: FastifyInstance): Promise<void>;
+  /**
+   * Register the image routes.
+   * @param fastifyInstance - the server instance to register the routes on.
+   */
+  registerImageRoutes(fastifyInstance?: FastifyInstance): Promise<void>;
+  /**
+   * Register the dynamic data routes.
+   * @param fastifyInstance - the server instance to register the routes on.
+   */
+  registerDynamicDataRoutes(fastifyInstance?: FastifyInstance): Promise<void>;
+  private resolveHttpsCredentials;
+  private loadPemValue;
+}
+//#endregion
+//#region src/index.d.ts
+declare const start: () => Promise<MockHttp>;
+//#endregion
+export { type CertificateFileOptions, type CertificateOptions, type CertificateResult, type HttpsOptions, type InjectionMatcher, type InjectionResponse, type InjectionTap, MockHttp as default, MockHttp as mockhttp, generateCertificate, generateCertificateFiles, start };