feat: add headerTransform middleware

Author: gkoos

README.md

@@ -124,6 +124,7 @@ Chaos Proxy uses Koa Router for path matching, supporting named parameters (e.g.
 - `cors({ origin, methods, headers })` — enable and configure CORS headers. All options are strings.
 `throttle({ rate, chunkSize, burst, key })` — throttles bandwidth per request to a specified rate (bytes per second), with optional burst capacity and chunk size. The key option allows per-client throttling. (Implemented natively, not using koa-throttle.)
 - `bodyTransform({ request?, response? })` — parse and mutate request and/or response body with custom functions.
+- `headerTransform({ request?, response? })` — parse and mutate request and/or response headers with custom functions.
 
 ### Rate Limiting
 
@@ -238,6 +239,51 @@ startServer({
 });
 ```
 
+### Header Transform
+
+The `headerTransform` middleware allows you to parse and mutate both the request and response headers using custom transformation functions. You can specify a `request` and/or `response` transform, each as either a JavaScript function string (for YAML config) or a real function (for programmatic usage).
+
+How it works:
+- If a `request` transform is provided, it is called with a copy of the request headers and Koa context, and its return value replaces `ctx.request.headers`.
+- After downstream middleware and proxying, if a `response` transform is provided, it is called with a copy of the response headers and Koa context, and its return value replaces `ctx.response.headers`.
+- Both transforms can be used independently or together.
+
+**Example (YAML):**
+```yaml
+global:
+  - headerTransform:
+      request: "(headers, ctx) => { headers['x-added'] = 'foo'; return headers; }"
+      response: "(headers, ctx) => { headers['x-powered-by'] = 'chaos'; return headers; }"
+```
+
+This configuration adds an `x-added: foo` header to every request and an `x-powered-by: chaos` header to every response.
+
+**Note:**
+For maximum flexibility, the `request` and `response` options in `headerTransform` can be specified as JavaScript function strings in your YAML config. This allows you to define custom transformation logic directly in the config file. Be aware that evaluating JS from config can introduce security and syntax risks. Use with care and only in trusted environments.
+
+If you call `startServer` programmatically, you can also pass real functions instead of strings:
+
+```ts
+import { startServer, headerTransform } from 'chaos-proxy';
+
+startServer({
+  target: 'http://localhost:4000',
+  port: 5000,
+  global: [
+    headerTransform({
+      request: (headers, ctx) => {
+        headers['x-added'] = 'foo';
+        return headers;
+      },
+      response: (headers, ctx) => {
+        headers['x-powered-by'] = 'chaos';
+        return headers;
+      }
+    })
+  ]
+});
+```
+
 ---
 
 ## Extensibility

src/middlewares/headerTransform.ts

@@ -0,0 +1,69 @@
+import type { Context } from 'koa';
+
+export type HeaderTransformFn = (headers: Record<string, string | string[] | undefined>, ctx: Context) => Record<string, string | string[] | undefined>;
+
+export interface HeaderTransformConfig {
+  request?: string | { transform: HeaderTransformFn };
+  response?: string | { transform: HeaderTransformFn };
+}
+
+function parseTransform(fnOrString: string | { transform: HeaderTransformFn } | undefined): HeaderTransformFn | undefined {
+  if (!fnOrString) return undefined;
+  if (typeof fnOrString === 'string') {
+    // Try to parse as arrow function or function body
+    try {
+      if (fnOrString.trim().startsWith('(') || fnOrString.includes('=>')) {
+        return eval(fnOrString);
+      } else {
+        return new Function('headers', 'ctx', fnOrString) as HeaderTransformFn;
+      }
+    } catch (e) {
+      throw new Error('Invalid headerTransform function string: ' + e);
+    }
+  }
+  if (typeof fnOrString === 'object' && typeof fnOrString.transform === 'function') {
+    return fnOrString.transform;
+  }
+  throw new Error('Invalid headerTransform config');
+}
+
+export function headerTransform(config: HeaderTransformConfig) {
+  const requestTransform = parseTransform(config.request);
+  const responseTransform = parseTransform(config.response);
+
+  return async function headerTransformMiddleware(ctx: Context, next: () => Promise<void>) {
+    // Request headers
+    if (requestTransform) {
+      // Only pass string or string[] values to the transform
+      const reqHeaders: Record<string, string | string[] | undefined> = {};
+      for (const [k, v] of Object.entries(ctx.request.headers)) {
+        if (typeof v === 'string' || Array.isArray(v)) {
+          reqHeaders[k] = v;
+        } else if (typeof v === 'number') {
+          reqHeaders[k] = String(v);
+        } else if (v != null) {
+          reqHeaders[k] = String(v);
+        }
+      }
+      const newHeaders = requestTransform(reqHeaders, ctx);
+      ctx.request.headers = { ...newHeaders };
+    }
+    await next();
+    // Response headers
+    if (responseTransform) {
+      // Only pass string or string[] values to the transform
+      const resHeaders: Record<string, string | string[] | undefined> = {};
+      for (const [k, v] of Object.entries(ctx.response.headers)) {
+        if (typeof v === 'string' || Array.isArray(v)) {
+          resHeaders[k] = v;
+        } else if (typeof v === 'number') {
+          resHeaders[k] = String(v);
+        } else if (v != null) {
+          resHeaders[k] = String(v);
+        }
+      }
+      const newHeaders = responseTransform(resHeaders, ctx);
+      ctx.response.headers = { ...newHeaders };
+    }
+  };
+}

src/registry/builtin.ts

@@ -1,11 +1,11 @@
-import { cors } from '../middlewares/cors';
 import { registerMiddleware } from './middleware';
-// ...existing code...
-import { latency } from '../middlewares/latency';
-import { latencyRange } from '../middlewares/latencyRange';
-import { failRandomly } from '../middlewares/failRandomly';
+import { cors } from '../middlewares/cors';
 import { dropConnection } from '../middlewares/dropConnection';
+import { headerTransform } from '../middlewares/headerTransform';
 import { fail } from '../middlewares/fail';
+import { failRandomly } from '../middlewares/failRandomly';
+import { latency } from '../middlewares/latency';
+import { latencyRange } from '../middlewares/latencyRange';
 import { rateLimit } from '../middlewares/rateLimit';
 import type { RateLimitOptions } from '../middlewares/rateLimit';
 import { throttle } from '../middlewares/throttle';
@@ -27,4 +27,5 @@ export function registerBuiltins() {
   );
   registerMiddleware('rateLimit', (opts) => rateLimit(opts as unknown as RateLimitOptions));
   registerMiddleware('throttle', (opts) => throttle(opts as unknown as ThrottleOptions));
+  registerMiddleware('headerTransform', (opts) => headerTransform(opts));
 }

test/middlewares/headerTransform.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+import { headerTransform } from '../../src/middlewares/headerTransform';
+import type { Context } from 'koa';
+
+function createMockCtx(headers: Record<string, string | string[] | undefined> = {}, responseHeaders: Record<string, string | string[] | undefined> = {}): Context {
+  return {
+    request: {
+      headers: { ...headers },
+    },
+    response: {
+      headers: { ...responseHeaders },
+    },
+    set: () => {},
+    method: 'GET',
+  } as unknown as Context;
+}
+
+describe('headerTransform middleware', () => {
+  it('mutates request headers', async () => {
+    const mw = headerTransform({
+      request: {
+        transform: (headers) => {
+          headers['x-mutated'] = 'yes';
+          return headers;
+        },
+      },
+    });
+    const ctx = createMockCtx({ foo: 'bar' });
+    await mw(ctx, async () => {});
+    expect(ctx.request.headers['x-mutated']).toBe('yes');
+  });
+
+  it('mutates response headers', async () => {
+    const mw = headerTransform({
+      response: {
+        transform: (headers) => {
+          headers['x-res'] = 'done';
+          return headers;
+        },
+      },
+    });
+    const ctx = createMockCtx({}, { foo: 'bar' });
+    await mw(ctx, async () => {});
+    expect(ctx.response.headers['x-res']).toBe('done');
+  });
+
+  it('can use both request and response transforms', async () => {
+    const mw = headerTransform({
+      request: {
+        transform: (headers) => {
+          headers['x-req'] = '1';
+          return headers;
+        },
+      },
+      response: {
+        transform: (headers) => {
+          headers['x-res'] = '2';
+          return headers;
+        },
+      },
+    });
+    const ctx = createMockCtx({ foo: 'bar' }, { bar: 'baz' });
+    await mw(ctx, async () => {});
+    expect(ctx.request.headers['x-req']).toBe('1');
+    expect(ctx.response.headers['x-res']).toBe('2');
+  });
+
+  it('accepts a string arrow function for request transform', async () => {
+    const mw = headerTransform({ request: '(headers, ctx) => { headers["x-added"] = "abc"; return headers; }' });
+    const ctx = createMockCtx({ foo: 'bar' });
+    await mw(ctx, async () => {});
+    expect(ctx.request.headers['x-added']).toBe('abc');
+  });
+
+  it('accepts a string function body for response transform', async () => {
+    const mw = headerTransform({ response: 'headers["x-func"] = "body"; return headers;' });
+    const ctx = createMockCtx({}, { foo: 'bar' });
+    await mw(ctx, async () => {});
+    expect(ctx.response.headers['x-func']).toBe('body');
+  });
+
+  it('throws for invalid function string in request', async () => {
+    expect(() => headerTransform({ request: 'not valid js' })).toThrow();
+  });
+
+  it('throws for invalid function string in response', async () => {
+    expect(() => headerTransform({ response: 'not valid js' })).toThrow();
+  });
+});