@jaredwray/mockhttp 1.2.0 → 1.4.0

package/README.md

@@ -25,6 +25,7 @@ A simple HTTP server that can be used to mock HTTP responses for testing purpose
 - [Deploy via Docker](#deploy-via-docker)
 - [Deploy via Docker Compose](#deploy-via-docker-compose)
 - [Deploy via NodeJS](#deploy-via-nodejs)
+- [HTTPS Support](#https-support)
 - [Response Injection (Tap Feature)](#response-injection-tap-feature)
 - [Rate Limiting](#rate-limiting)
 - [Logging](#logging)
@@ -69,13 +70,133 @@ npm install @jaredwray/mockhttp --save
 then run `mockhttp` in your code.
 
 ```javascript
-import { mockhttp } from '@jaredwray/mockhttp';
-await mockhttp.start(); // start the server
+import { MockHttp } from '@jaredwray/mockhttp';
+const mock = new MockHttp();
+await mock.start(); // start the server
 const response = await fetch('http://localhost:3000/get');
 console.log(response);
-await mockhttp.stop(); // stop the server
+await mock.close(); // stop the server
+```
+
+# HTTPS Support
+
+MockHttp supports HTTPS with auto-generated self-signed certificates or your own custom certificates. No external dependencies are required — certificate generation uses only Node.js built-in `crypto`.
+
+## Auto-Generated Certificate
+
+The simplest way to enable HTTPS is to pass `https: true`. A self-signed certificate for `localhost` is generated automatically:
+
+```javascript
+import { MockHttp } from '@jaredwray/mockhttp';
+
+const mock = new MockHttp({ https: true });
+await mock.start();
+
+console.log(mock.isHttps); // true
+
+// Use Fastify's built-in inject() for testing (no TLS setup needed)
+const response = await mock.server.inject({ method: 'GET', url: '/get' });
+console.log(response.statusCode); // 200
+
+await mock.close();
+```
+
+> **Note:** Self-signed certificates are not trusted by default. When making real HTTPS requests (e.g. with `fetch`), set `NODE_TLS_REJECT_UNAUTHORIZED=0` in your test environment or use a custom HTTPS agent.
+
+## Custom Certificate Options
+
+You can customize the auto-generated certificate by passing `certificateOptions`:
+
+```javascript
+const mock = new MockHttp({
+  https: {
+    certificateOptions: {
+      commonName: 'my-test-server',
+      validityDays: 30,
+      keySize: 4096,
+      altNames: [
+        { type: 'dns', value: 'example.local' },
+        { type: 'dns', value: '*.example.local' },
+        { type: 'ip', value: '192.168.1.100' },
+      ],
+    },
+  },
+});
+
+await mock.start();
+// Make requests...
+await mock.close();
+```
+
+## Provide Your Own Certificate
+
+You can supply your own PEM-encoded certificate and key, either as strings or file paths:
+
+```javascript
+// Using PEM strings
+const mock = new MockHttp({
+  https: {
+    cert: '-----BEGIN CERTIFICATE-----\n...',
+    key: '-----BEGIN PRIVATE KEY-----\n...',
+  },
+});
+await mock.start();
+// Make requests...
+await mock.close();
+```
+
+```javascript
+// Using file paths
+const mock = new MockHttp({
+  https: {
+    cert: '/path/to/cert.pem',
+    key: '/path/to/key.pem',
+  },
+});
+await mock.start();
+// Make requests...
+await mock.close();
+```
+
+## Standalone Certificate Generation
+
+You can also generate certificates independently using the exported utility functions:
+
+```javascript
+import { generateCertificate, generateCertificateFiles } from '@jaredwray/mockhttp';
+
+// Generate in-memory PEM strings
+const { cert, key } = generateCertificate({
+  commonName: 'my-app',
+  validityDays: 90,
+});
+
+// Generate and write to disk
+const result = await generateCertificateFiles({
+  certPath: './certs/cert.pem',
+  keyPath: './certs/key.pem',
+  commonName: 'my-app',
+});
 ```
 
+## HTTPS Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `cert` | string | — | PEM-encoded certificate string or file path |
+| `key` | string | — | PEM-encoded private key string or file path |
+| `autoGenerate` | boolean | `true` | Auto-generate a self-signed certificate when cert/key are not provided |
+| `certificateOptions` | CertificateOptions | — | Options for the auto-generated certificate |
+
+### Certificate Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `commonName` | string | `'localhost'` | Certificate subject Common Name (CN) |
+| `altNames` | Array\<{ type, value }\> | `[dns:localhost, ip:127.0.0.1, ip:::1]` | Subject Alternative Names with type `'dns'` or `'ip'` |
+| `validityDays` | number | `365` | Certificate validity period in days |
+| `keySize` | number | `2048` | RSA key size in bits |
+
 # 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:
@@ -467,6 +588,7 @@ new MockHttp(options?)
     - `anything?`: boolean - Enable anything routes (default: true)
     - `auth?`: boolean - Enable authentication routes (default: true)
     - `images?`: boolean - Enable image routes (default: true)
+  - `https?`: boolean | HttpsOptions - Enable HTTPS with auto-generated or custom certificates (default: undefined/disabled)
   - `hookOptions?`: HookifiedOptions - Hookified options
 
 ### Properties
@@ -479,6 +601,8 @@ new MockHttp(options?)
 - `logging`: boolean - Get/set logging enabled state
 - `rateLimit`: RateLimitPluginOptions | undefined - Get/set rate limiting options
 - `httpBin`: HttpBinOptions - Get/set httpbin route options
+- `https`: HttpsOptions | undefined - Get/set HTTPS configuration
+- `isHttps`: boolean - Whether the server is running with HTTPS
 - `server`: FastifyInstance - Get/set the Fastify server instance
 - `taps`: TapManager - Get/set the TapManager instance
 

package/dist/index.d.ts

@@ -2,6 +2,61 @@ import { RateLimitPluginOptions } from '@fastify/rate-limit';
 import { FastifyRequest, FastifyInstance } from 'fastify';
 import { Hookified, HookifiedOptions } from 'hookified';
 
+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>;
+
 /**
  * Configuration for the injected response
  */
@@ -132,6 +187,25 @@ type HttpBinOptions = {
     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 = {
     /**
@@ -172,6 +246,11 @@ type MockHttpOptions = {
      * 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;
 };
 declare class MockHttp extends Hookified {
     private _port;
@@ -182,6 +261,8 @@ declare class MockHttp extends Hookified {
     private _logging;
     private _httpBin;
     private _rateLimit?;
+    private _https;
+    private _httpsCredentials;
     private _server;
     private _taps;
     constructor(options?: MockHttpOptions);
@@ -245,6 +326,20 @@ declare class MockHttp extends Hookified {
      * @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;
     /**
      * HTTP Bin options. Defaults to all enabled.
      */
@@ -347,8 +442,15 @@ declare class MockHttp extends Hookified {
      * @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;
 }
 
 declare const start: () => Promise<MockHttp>;
 
-export { type InjectionMatcher, type InjectionResponse, type InjectionTap, MockHttp as default, MockHttp as mockhttp, start };
+export { type CertificateFileOptions, type CertificateOptions, type CertificateResult, type HttpsOptions, type InjectionMatcher, type InjectionResponse, type InjectionTap, MockHttp as default, generateCertificate, generateCertificateFiles, MockHttp as mockhttp, start };