@jaredwray/mockhttp 1.0.1 → 1.2.0

package/README.md

@@ -21,6 +21,18 @@ A simple HTTP server that can be used to mock HTTP responses for testing purpose
 * Auto detect the port that is not in use
 * Maintained and updated regularly!
 
+# Table of Contents
+- [Deploy via Docker](#deploy-via-docker)
+- [Deploy via Docker Compose](#deploy-via-docker-compose)
+- [Deploy via NodeJS](#deploy-via-nodejs)
+- [Response Injection (Tap Feature)](#response-injection-tap-feature)
+- [Rate Limiting](#rate-limiting)
+- [Logging](#logging)
+- [API Reference](#api-reference)
+- [About mockhttp.org](#about-mockhttporg)
+- [Contributing](#contributing)
+- [License](#license)
+
 # Deploy via Docker
 ```bash
 docker run -d -p 3000:3000 jaredwray/mockhttp
@@ -60,7 +72,7 @@ then run `mockhttp` in your code.
 import { mockhttp } from '@jaredwray/mockhttp';
 await mockhttp.start(); // start the server
 const response = await fetch('http://localhost:3000/get');
-console.log(reaponse);
+console.log(response);
 await mockhttp.stop(); // stop the server
 ```
 
@@ -247,6 +259,184 @@ const tap = mock.taps.inject(
 );
 ```
 
+# Rate Limiting
+
+MockHttp supports rate limiting using [@fastify/rate-limit](https://github.com/fastify/fastify-rate-limit). Rate limiting is **enabled by default** at **1000 requests per minute** with **localhost (127.0.0.1 and ::1) excluded** from rate limiting.
+
+## Default Rate Limiting
+
+By default, MockHttp applies the following rate limit:
+- **1000 requests per minute** per IP address
+- **Localhost is excluded** - requests from 127.0.0.1 and ::1 bypass rate limiting (ideal for local development and testing)
+
+```javascript
+import { MockHttp } from '@jaredwray/mockhttp';
+
+const mock = new MockHttp();
+await mock.start();
+// Rate limiting is active (1000 req/min) except for localhost
+```
+
+## Customizing Rate Limiting
+
+To customize rate limiting, pass a `rateLimit` configuration object when creating your MockHttp instance:
+
+```javascript
+import { MockHttp } from '@jaredwray/mockhttp';
+
+const mock = new MockHttp({
+  rateLimit: {
+    max: 100,              // Maximum 100 requests
+    timeWindow: '1 minute' // Per 1 minute window
+  }
+});
+
+await mock.start();
+```
+
+## Common Configuration Options
+
+The `rateLimit` option accepts all [@fastify/rate-limit options](https://github.com/fastify/fastify-rate-limit#options):
+
+### Basic Rate Limiting
+
+```javascript
+// Limit to 50 requests per minute
+const mock = new MockHttp({
+  rateLimit: {
+    max: 50,
+    timeWindow: '1 minute'
+  }
+});
+```
+
+### Stricter Limits with Custom Error Response
+
+```javascript
+const mock = new MockHttp({
+  rateLimit: {
+    max: 30,
+    timeWindow: 60000, // 1 minute in milliseconds
+    errorResponseBuilder: (req, context) => ({
+      statusCode: 429,
+      error: 'Too Many Requests',
+      message: `Rate limit exceeded. Try again in ${context.after}`
+    })
+  }
+});
+```
+
+### Allow List (Exclude Specific IPs)
+
+```javascript
+const mock = new MockHttp({
+  rateLimit: {
+    max: 100,
+    timeWindow: '1 minute',
+    allowList: ['127.0.0.1', '192.168.1.100'] // These IPs bypass rate limiting
+  }
+});
+```
+
+### Custom Key Generator (Rate Limit by Header)
+
+```javascript
+const mock = new MockHttp({
+  rateLimit: {
+    max: 100,
+    timeWindow: '1 minute',
+    keyGenerator: (request) => {
+      // Rate limit by API key instead of IP
+      return request.headers['x-api-key'] || request.ip;
+    }
+  }
+});
+```
+
+### Advanced Configuration
+
+```javascript
+const mock = new MockHttp({
+  rateLimit: {
+    global: true,                    // Apply to all routes
+    max: 100,                        // Max requests
+    timeWindow: '1 minute',          // Time window
+    cache: 10000,                    // Cache size for tracking clients
+    skipOnError: false,              // Don't skip on storage errors
+    ban: 10,                         // Ban after 10 rate limit violations
+    continueExceeding: false,        // Don't reset window on each request
+    enableDraftSpec: true,           // Use IETF draft spec headers
+    addHeaders: {                    // Customize rate limit headers
+      'x-ratelimit-limit': true,
+      'x-ratelimit-remaining': true,
+      'x-ratelimit-reset': true
+    }
+  }
+});
+```
+
+## Disabling Rate Limiting
+
+To disable rate limiting completely, set the `rateLimit` option to `false`:
+
+```javascript
+const mock = new MockHttp({
+  rateLimit: false // Completely disable rate limiting
+});
+
+await mock.start();
+// No rate limiting is applied to any requests
+```
+
+**Note:** To change rate limiting settings after the server has started, you must restart the server:
+
+```javascript
+const mock = new MockHttp();
+await mock.start(); // Starts with default rate limiting
+
+// To change or disable rate limiting:
+await mock.close();
+mock.rateLimit = undefined; // or set new options
+await mock.start(); // Restarts with new settings
+```
+
+## Available Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `max` | number \| function | `1000` | Maximum requests per time window |
+| `timeWindow` | number \| string | `60000` | Duration of rate limit window (milliseconds or string like '1 minute') |
+| `cache` | number | `5000` | LRU cache size for tracking clients |
+| `allowList` | array \| function | `[]` | IPs or function to exclude from rate limiting |
+| `keyGenerator` | function | IP-based | Function to generate unique client identifier |
+| `errorResponseBuilder` | function | Default 429 | Custom error response function |
+| `skipOnError` | boolean | `false` | Skip rate limiting if storage errors occur |
+| `ban` | number | `-1` | Ban client after N violations (disabled by default) |
+| `continueExceeding` | boolean | `false` | Renew time window on each request while limited |
+| `enableDraftSpec` | boolean | `false` | Use IETF draft specification headers |
+
+For the complete list of options, see the [@fastify/rate-limit documentation](https://github.com/fastify/fastify-rate-limit#options).
+
+# Logging
+
+MockHttp uses [Pino](https://github.com/pinojs/pino) for logging via Fastify's built-in logger. Logging is **enabled by default** but can be disabled when needed.
+
+## Disabling Logging
+
+```javascript
+import { MockHttp } from '@jaredwray/mockhttp';
+
+const mock = new MockHttp({ logging: false });
+await mock.start();
+// Server runs silently without any log output
+```
+
+You can also disable logging via the `LOGGING` environment variable:
+
+```bash
+LOGGING=false node your-app.js
+```
+
 # API Reference
 
 ## MockHttp Class
@@ -264,7 +454,19 @@ new MockHttp(options?)
   - `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)
+  - `rateLimit?`: RateLimitPluginOptions - Configure rate limiting (default: 1000 req/min, localhost excluded)
+  - `logging?`: boolean - Enable logging (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)
+    - `requestInspection?`: boolean - Enable request inspection routes (default: true)
+    - `responseInspection?`: boolean - Enable response inspection routes (default: true)
+    - `statusCodes?`: boolean - Enable status code routes (default: true)
+    - `responseFormats?`: boolean - Enable response format routes (default: true)
+    - `cookies?`: boolean - Enable cookie routes (default: true)
+    - `anything?`: boolean - Enable anything routes (default: true)
+    - `auth?`: boolean - Enable authentication routes (default: true)
+    - `images?`: boolean - Enable image routes (default: true)
   - `hookOptions?`: HookifiedOptions - Hookified options
 
 ### Properties
@@ -274,6 +476,8 @@ new MockHttp(options?)
 - `autoDetectPort`: boolean - Get/set auto-detect port behavior
 - `helmet`: boolean - Get/set Helmet security headers
 - `apiDocs`: boolean - Get/set API documentation
+- `logging`: boolean - Get/set logging enabled state
+- `rateLimit`: RateLimitPluginOptions | undefined - Get/set rate limiting options
 - `httpBin`: HttpBinOptions - Get/set httpbin route options
 - `server`: FastifyInstance - Get/set the Fastify server instance
 - `taps`: TapManager - Get/set the TapManager instance
@@ -334,6 +538,10 @@ Register "anything" catch-all routes.
 
 Register authentication routes (basic, bearer, digest, hidden-basic).
 
+#### `async registerImageRoutes(fastifyInstance?)`
+
+Register image routes (jpeg, png, svg, webp) with content negotiation support.
+
 ## Taps (Response Injection)
 
 Access the TapManager via `mockHttp.taps` to inject custom responses.

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { RateLimitPluginOptions } from '@fastify/rate-limit';
 import { FastifyRequest, FastifyInstance } from 'fastify';
 import { Hookified, HookifiedOptions } from 'hookified';
 
@@ -130,6 +131,7 @@ type HttpBinOptions = {
     cookies?: boolean;
     anything?: boolean;
     auth?: boolean;
+    images?: boolean;
 };
 type MockHttpOptions = {
     /**
@@ -157,10 +159,19 @@ type MockHttpOptions = {
      * 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;
 };
 declare class MockHttp extends Hookified {
     private _port;
@@ -168,7 +179,9 @@ declare class MockHttp extends Hookified {
     private _autoDetectPort;
     private _helmet;
     private _apiDocs;
+    private _logging;
     private _httpBin;
+    private _rateLimit?;
     private _server;
     private _taps;
     constructor(options?: MockHttpOptions);
@@ -222,6 +235,16 @@ declare class MockHttp extends Hookified {
      * @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);
     /**
      * HTTP Bin options. Defaults to all enabled.
      */
@@ -230,6 +253,20 @@ declare class MockHttp extends Hookified {
      * 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.
      */
@@ -305,6 +342,11 @@ declare class MockHttp extends Hookified {
      * @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>;
 }
 
 declare const start: () => Promise<MockHttp>;