@bilal-fazlani/mock-server 0.2.1 → 0.3.0

package/.next/standalone/tests/router/dynamic.e2e.test.ts

@@ -0,0 +1,147 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { loadCatalog } from '../../src/lib/catalog/load'
+import { loadFixture } from '../../src/lib/mock-engine/fixtures'
+import { compileResolver, resolverFilePath, type CompiledResolver } from '../../src/lib/mock-engine/resolver'
+import type { MockProfile } from '../../src/lib/profiles/store'
+import { createMockHandler } from '../../src/lib/router/handler'
+import type { RouterDeps } from '../../src/lib/router/route-request'
+
+const NOW = new Date('2026-07-02T00:00:00.000Z')
+
+const tmpDirs: string[] = []
+
+function tmpCatalogDir(files: Record<string, unknown>): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mock-dynamic-e2e-'))
+  tmpDirs.push(dir)
+  for (const [rel, content] of Object.entries(files)) {
+    const full = path.join(dir, rel)
+    fs.mkdirSync(path.dirname(full), { recursive: true })
+    fs.writeFileSync(full, typeof content === 'string' ? content : JSON.stringify(content))
+  }
+  return dir
+}
+
+afterEach(() => {
+  while (tmpDirs.length) fs.rmSync(tmpDirs.pop()!, { recursive: true, force: true })
+})
+
+const SYSTEM_META = { name: 'Test System', baseUrlEnv: 'TEST_URL' }
+const ENDPOINT_META = {
+  displayName: 'Customer Status',
+  method: 'GET',
+  path: '/customers/{customerId}/status',
+  profileIdSelector: 'path:customerId',
+}
+const DEFAULT_FIXTURE = { status: 200, body: { status: 'ACTIVE' } }
+const FAILURE_FIXTURE = { status: 503, body: { status: 'DOWN' } }
+// Stateful pure function: serves "failure" until the history already contains
+// one entry, then flips to "default". This proves the resolver actually
+// receives the accumulated history from a real (non-faked) history store.
+const DYNAMIC_SOURCE = `export default (i) => i.history.length < 1 ? 'failure' : 'default'`
+
+// Keyed by `${ownerType}|${ownerKey}|${endpointName}|${scenario}`, mirroring
+// the real history-store's compound key, but backed by a plain in-memory
+// array instead of Mongo -- this is the "real" collaborator under test here,
+// not a fake that always returns a canned value.
+function makeHistoryStore() {
+  const store = new Map<string, string[]>()
+  const key = (ownerType: string, ownerKey: string, endpointName: string, scenario: string) =>
+    `${ownerType}|${ownerKey}|${endpointName}|${scenario}`
+  return {
+    store,
+    getDynamicHistory: async (
+      ownerType: string,
+      ownerKey: string,
+      endpointName: string,
+      scenario: string,
+    ) => store.get(key(ownerType, ownerKey, endpointName, scenario)) ?? [],
+    appendDynamicHistory: async (
+      ownerType: string,
+      ownerKey: string,
+      endpointName: string,
+      scenario: string,
+      slug: string,
+    ) => {
+      const k = key(ownerType, ownerKey, endpointName, scenario)
+      const existing = store.get(k) ?? []
+      store.set(k, [...existing, slug])
+    },
+  }
+}
+
+function statusRequest(customerId: string): Request {
+  return new Request(`http://localhost:3000/customers/${customerId}/status`, { method: 'GET' })
+}
+
+function statusRoute(customerId: string): string[] {
+  return ['customers', customerId, 'status']
+}
+
+describe('dynamic resolver end-to-end (real compileResolver + real history store)', () => {
+  it('serves failure then default as the real history accumulates across calls', async () => {
+    const dir = tmpCatalogDir({
+      'sys/_system.json': SYSTEM_META,
+      'sys/ep/_endpoint.json': ENDPOINT_META,
+      'sys/ep/default.json': DEFAULT_FIXTURE,
+      'sys/ep/failure.json': FAILURE_FIXTURE,
+      'sys/ep/dynamic.ts': DYNAMIC_SOURCE,
+    })
+    const catalog = loadCatalog(dir)
+
+    // Compile once via the real compileResolver, exactly as the runtime does.
+    const source = fs.readFileSync(resolverFilePath(dir, 'sys', 'ep', 'dynamic'), 'utf8')
+    const resolver: CompiledResolver = compileResolver(source, 'sys/ep/dynamic.ts')
+
+    const history = makeHistoryStore()
+
+    const profiles: Record<string, MockProfile> = {
+      'customer-123': {
+        profileId: 'customer-123',
+        endpointScenarios: { ep: 'dynamic' },
+        createdAt: NOW,
+        modifiedAt: NOW,
+      },
+    }
+
+    const deps: RouterDeps = {
+      catalog,
+      passthroughAsDefault: false,
+      unmockedUsers: 'ERROR',
+      timeoutMs: 1000,
+      env: {},
+      getProfile: async (id) => profiles[id] ?? null,
+      getProfileKeyMapping: async () => null,
+      getGlobalMockScenario: async () => null,
+      captureProfileKeyMapping: async () => {},
+      advanceScenarioProgress: async () => 1,
+      getCompiledResolver: () => resolver,
+      getDynamicHistory: history.getDynamicHistory,
+      appendDynamicHistory: history.appendDynamicHistory,
+      passthrough: async () => ({
+        status: 299,
+        headers: { 'x-proxied': '1' },
+        bodyBytes: Buffer.from('proxied'),
+      }),
+      loadFixture: (systemSlug, endpointName, scenario) =>
+        loadFixture(dir, systemSlug, endpointName, scenario),
+      now: () => NOW,
+    }
+    const handle = createMockHandler(deps)
+
+    // 1st request: history is empty, so the resolver picks "failure".
+    const res1 = await handle(statusRequest('customer-123'), statusRoute('customer-123'))
+    expect(res1.status).toBe(503)
+    expect(await res1.json()).toEqual({ status: 'DOWN' })
+
+    // 2nd request: history now has one entry, so the resolver flips to "default".
+    const res2 = await handle(statusRequest('customer-123'), statusRoute('customer-123'))
+    expect(res2.status).toBe(200)
+    expect(await res2.json()).toEqual({ status: 'ACTIVE' })
+
+    // The real in-memory store actually accumulated both appended slugs, in order.
+    expect(history.store.get('profile|customer-123|ep|dynamic')).toEqual(['failure', 'default'])
+  })
+})

package/.next/standalone/tests/router/handler.e2e.test.ts

@@ -0,0 +1,97 @@
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { loadCatalog } from '../../src/lib/catalog/load'
+import { loadFixture } from '../../src/lib/mock-engine/fixtures'
+import type { MockProfile } from '../../src/lib/profiles/store'
+import { createMockHandler } from '../../src/lib/router/handler'
+import type { RouterDeps } from '../../src/lib/router/route-request'
+
+const NOW = new Date('2026-07-02T00:00:00.000Z')
+const CATALOG_DIR = path.join(__dirname, '../../catalog')
+
+function handlerWith(profiles: Record<string, Partial<MockProfile>>, overrides: Partial<RouterDeps> = {}) {
+  const deps: RouterDeps = {
+    catalog: loadCatalog(CATALOG_DIR),
+    passthroughAsDefault: false,
+    unmockedUsers: 'ERROR',
+    timeoutMs: 1000,
+    env: { HELLO_SYSTEM_URL: 'http://real.example' },
+    getProfile: async (id) =>
+      profiles[id]
+        ? { profileId: id, endpointScenarios: {}, createdAt: NOW, modifiedAt: NOW, ...profiles[id] }
+        : null,
+    getProfileKeyMapping: async () => null,
+    getGlobalMockScenario: async () => null,
+    captureProfileKeyMapping: async () => {},
+    advanceScenarioProgress: async () => 1,
+    getCompiledResolver: () => null,
+    getDynamicHistory: async () => [],
+    appendDynamicHistory: async () => {},
+    passthrough: async () => ({
+      status: 299,
+      headers: { 'x-proxied': '1' },
+      bodyBytes: Buffer.from('proxied'),
+    }),
+    loadFixture: (systemSlug, endpointName, scenario) =>
+      loadFixture(CATALOG_DIR, systemSlug, endpointName, scenario),
+    now: () => NOW,
+    ...overrides,
+  }
+  return createMockHandler(deps)
+}
+
+function statusRequest(customerId: string): Request {
+  return new Request(`http://localhost:3000/customers/${customerId}/status`, {
+    method: 'GET',
+  })
+}
+
+function statusRoute(customerId: string): string[] {
+  return ['customers', customerId, 'status']
+}
+
+describe('customer-status end to end', () => {
+  it('gap-fill (no pick) returns the default fixture with the echoed customerId', async () => {
+    const handle = handlerWith({ 'customer-123': { endpointScenarios: {} } })
+    const res = await handle(statusRequest('customer-123'), statusRoute('customer-123'))
+    expect(res.status).toBe(200)
+    expect(await res.json()).toMatchObject({
+      customerId: 'customer-123',
+      status: 'ACTIVE',
+    })
+  })
+
+  it('frozen scenario returns the frozen fixture with the echoed customerId', async () => {
+    const handle = handlerWith({ 'customer-123': { endpointScenarios: { customer_status: 'frozen' } } })
+    const res = await handle(statusRequest('customer-123'), statusRoute('customer-123'))
+    expect(res.status).toBe(200)
+    expect(await res.json()).toMatchObject({
+      customerId: 'customer-123',
+      status: 'FROZEN',
+    })
+  })
+
+  it('real scenario proxies to the passthrough', async () => {
+    const handle = handlerWith({ 'customer-123': { endpointScenarios: { customer_status: 'real' } } })
+    const res = await handle(statusRequest('customer-123'), statusRoute('customer-123'))
+    expect(res.status).toBe(299)
+    expect(res.headers.get('x-proxied')).toBe('1')
+    expect(await res.text()).toBe('proxied')
+  })
+
+  it('a profile pinning real 500s when the base URL is missing', async () => {
+    const handle = handlerWith(
+      { 'customer-123': { endpointScenarios: { customer_status: 'real' } } },
+      { env: {} },
+    )
+    const res = await handle(statusRequest('customer-123'), statusRoute('customer-123'))
+    expect(res.status).toBe(500)
+  })
+
+  it('unknown profile under UNMOCKED_USERS=ERROR is a 404 with the extracted ID', async () => {
+    const handle = handlerWith({})
+    const res = await handle(statusRequest('ghost'), statusRoute('ghost'))
+    expect(res.status).toBe(404)
+    expect(((await res.json()) as { error: string }).error).toMatch(/ghost/)
+  })
+})

package/.next/standalone/tests/router/handler.test.ts

@@ -0,0 +1,344 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { Catalog } from '../../src/lib/catalog/types'
+import type { LogEntry } from '../../src/lib/logs/store'
+import type { MockProfile } from '../../src/lib/profiles/store'
+import { createMockHandler, type MockHandlerDeps } from '../../src/lib/router/handler'
+
+const NOW = new Date('2026-07-02T00:00:00.000Z')
+
+const CATALOG: Catalog = {
+  systems: [
+    {
+      name: 'Test System',
+      slug: 'test-system',
+      baseUrlEnv: 'TEST_SYSTEM_URL',
+      endpoints: [
+        {
+          name: 'hello',
+          displayName: 'Hello',
+          method: 'POST',
+          path: '/hello',
+          profileIdSelector: '$.customerId',
+          scenarios: { default: { label: 'Success' } },
+          resolverScenarios: [],
+        },
+      ],
+    },
+  ],
+}
+
+const profile: MockProfile = {
+  profileId: 'c1',
+  endpointScenarios: {},
+  createdAt: NOW,
+  modifiedAt: NOW,
+}
+
+function handlerWith(
+  overrides: Partial<MockHandlerDeps> = {},
+  fixtureBody: unknown = { ok: true },
+) {
+  const written: LogEntry[] = []
+  const deps: MockHandlerDeps = {
+    catalog: CATALOG,
+    passthroughAsDefault: false,
+    unmockedUsers: 'ERROR',
+    timeoutMs: 1000,
+    env: {},
+    getProfile: async (id) => (id === 'c1' ? profile : null),
+    getGlobalMockScenario: async () => null,
+    getProfileKeyMapping: async () => null,
+    captureProfileKeyMapping: async () => {},
+    advanceScenarioProgress: async () => 1,
+    getCompiledResolver: () => null,
+    getDynamicHistory: async () => [],
+    appendDynamicHistory: async () => {},
+    passthrough: async () => {
+      throw new Error('not used')
+    },
+    loadFixture: () => ({ status: 200, headers: {}, body: fixtureBody }),
+    now: () => NOW,
+    writeLog: async (entry) => {
+      written.push(entry)
+    },
+    ...overrides,
+  }
+  return { handle: createMockHandler(deps), written }
+}
+
+function helloRequest(body: unknown = { customerId: 'c1' }): Request {
+  return new Request('http://localhost:3000/hello', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+}
+
+const settle = () => new Promise((r) => setTimeout(r, 0))
+
+function spyConsole() {
+  const info = vi.spyOn(console, 'info').mockImplementation(() => {})
+  const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+  return {
+    info,
+    warn,
+    error,
+    restore: () => {
+      info.mockRestore()
+      warn.mockRestore()
+      error.mockRestore()
+    },
+  }
+}
+
+describe('mock handler logging', () => {
+  it('prints a compact info line for routed fixture responses regardless of fixture status', async () => {
+    const consoleSpy = spyConsole()
+    const { handle } = handlerWith({
+      consoleLogLevel: 'info',
+      loadFixture: () => ({ status: 404, headers: {}, body: { expected: 'missing' } }),
+    })
+
+    const res = await handle(helloRequest(), ['hello'])
+
+    expect(res.status).toBe(404)
+    expect(consoleSpy.info).toHaveBeenCalledTimes(1)
+    expect(consoleSpy.info.mock.calls[0][0]).toMatch(
+      /^\[mock\] POST \/hello -> 404 \d+ms test-system\/hello profile=c1 scenario=default outcome=fixture$/,
+    )
+    expect(consoleSpy.warn).not.toHaveBeenCalled()
+    expect(consoleSpy.error).not.toHaveBeenCalled()
+    consoleSpy.restore()
+  })
+
+  it('treats unmatched requests as warnings and honors the warn threshold', async () => {
+    const consoleSpy = spyConsole()
+    const { handle } = handlerWith({ consoleLogLevel: 'warn' })
+
+    await handle(helloRequest(), ['hello'])
+    await handle(new Request('http://localhost:3000/nope?x=1', { method: 'GET' }), ['nope'])
+
+    expect(consoleSpy.info).not.toHaveBeenCalled()
+    expect(consoleSpy.warn).toHaveBeenCalledTimes(1)
+    expect(consoleSpy.warn.mock.calls[0][0]).toMatch(
+      /^\[mock\] GET \/nope\?x=1 -> 404 \d+ms outcome=error error=no_match$/,
+    )
+    expect(consoleSpy.error).not.toHaveBeenCalled()
+    consoleSpy.restore()
+  })
+
+  it('logs unmocked-user fallback as a warning when the response succeeds', async () => {
+    const consoleSpy = spyConsole()
+    const { handle } = handlerWith({
+      consoleLogLevel: 'warn',
+      unmockedUsers: 'DEFAULT_MOCK',
+      getProfile: async () => null,
+    })
+
+    const res = await handle(helloRequest({ customerId: 'ghost' }), ['hello'])
+
+    expect(res.status).toBe(200)
+    expect(consoleSpy.info).not.toHaveBeenCalled()
+    expect(consoleSpy.warn).toHaveBeenCalledTimes(1)
+    expect(consoleSpy.warn.mock.calls[0][0]).toMatch(
+      /^\[mock\] POST \/hello -> 200 \d+ms test-system\/hello profile=ghost scenario=default source=unmocked_policy outcome=fixture$/,
+    )
+    expect(consoleSpy.error).not.toHaveBeenCalled()
+    consoleSpy.restore()
+  })
+
+  it('logs profile-not-found under UNMOCKED_USERS=ERROR as an error', async () => {
+    const consoleSpy = spyConsole()
+    const { handle } = handlerWith({
+      consoleLogLevel: 'error',
+      getProfile: async () => null,
+    })
+
+    const res = await handle(helloRequest({ customerId: 'ghost' }), ['hello'])
+
+    expect(res.status).toBe(404)
+    expect(consoleSpy.info).not.toHaveBeenCalled()
+    expect(consoleSpy.warn).not.toHaveBeenCalled()
+    expect(consoleSpy.error).toHaveBeenCalledTimes(1)
+    expect(consoleSpy.error.mock.calls[0][0]).toMatch(
+      /^\[mock\] POST \/hello -> 404 \d+ms test-system\/hello profile=ghost outcome=error error=profile_not_found$/,
+    )
+    consoleSpy.restore()
+  })
+
+  it('logs failed request-log writes as warnings through the configured threshold', async () => {
+    const consoleSpy = spyConsole()
+    const { handle } = handlerWith({
+      consoleLogLevel: 'warn',
+      writeLog: async () => {
+        throw new Error('mongo down')
+      },
+    })
+
+    const res = await handle(helloRequest(), ['hello'])
+    await settle()
+
+    expect(res.status).toBe(200)
+    expect(consoleSpy.info).not.toHaveBeenCalled()
+    expect(consoleSpy.warn).toHaveBeenCalledWith(
+      '[mock-log] failed to write log entry: mongo down',
+    )
+    expect(consoleSpy.error).not.toHaveBeenCalled()
+    consoleSpy.restore()
+  })
+
+  it('echoes a log id header and writes a matching entry', async () => {
+    const { handle, written } = handlerWith()
+
+    const res = await handle(helloRequest(), ['hello'])
+    await settle()
+
+    const logId = res.headers.get('x-mock-log-id')
+    expect(logId).toMatch(/^lg_/)
+    expect(written).toHaveLength(1)
+    const entry = written[0]
+    expect(entry.logId).toBe(logId)
+    expect(entry.kind).toBe('request')
+    expect(entry.method).toBe('POST')
+    expect(entry.path).toBe('/hello')
+    expect(entry.profileId).toBe('c1')
+    expect(entry.system).toBe('test-system')
+    expect(entry.endpoint).toBe('hello')
+    expect(entry.outcome).toBe('fixture')
+    expect(entry.request?.body).toEqual({ customerId: 'c1' })
+    expect(entry.request?.truncated).toBe(false)
+    expect(entry.response?.status).toBe(200)
+    expect(entry.response?.body).toEqual({ ok: true })
+    expect(entry.response?.headers['x-mock-log-id']).toBe(logId)
+    expect(typeof entry.durationMs).toBe('number')
+    expect(entry.ts).toBeInstanceOf(Date)
+    expect(entry.trace.scenario).toBe('default')
+    expect(entry.trace.scenarioSource).toBe('implicit')
+    expect(entry.trace.profileResolution).toEqual({
+      selector: '$.customerId',
+      value: 'c1',
+      via: 'direct',
+    })
+  })
+
+  it('redacts authorization headers from persisted request logs', async () => {
+    const { handle, written } = handlerWith()
+    const request = new Request('http://localhost:3000/hello', {
+      method: 'POST',
+      headers: {
+        authorization: 'Bearer secret-token',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ customerId: 'c1' }),
+    })
+
+    await handle(request, ['hello'])
+    await settle()
+
+    expect(written).toHaveLength(1)
+    expect(written[0].request?.headers.authorization).toBe('[REDACTED]')
+    expect(written[0].request?.headers['content-type']).toBe('application/json')
+  })
+
+  it('records error entries for unmatched requests', async () => {
+    const { handle, written } = handlerWith()
+
+    const res = await handle(
+      new Request('http://localhost:3000/nope', { method: 'GET' }),
+      ['nope'],
+    )
+    await settle()
+
+    expect(res.status).toBe(404)
+    expect(written).toHaveLength(1)
+    expect(written[0].outcome).toBe('error')
+    expect(written[0].error?.code).toBe('no_match')
+    expect(written[0].profileId).toBeUndefined()
+  })
+
+  it('does not write request logs for Next.js internal asset paths', async () => {
+    const { handle, written } = handlerWith()
+
+    const res = await handle(
+      new Request('http://localhost:3000/_next/static/chunks/app.js', { method: 'GET' }),
+      ['_next', 'static', 'chunks', 'app.js'],
+    )
+    await settle()
+
+    expect(res.status).toBe(404)
+    expect(res.headers.get('x-mock-log-id')).toBeNull()
+    expect(written).toHaveLength(0)
+  })
+
+  it('records an error entry when passthrough throws before receiving a response', async () => {
+    const { handle, written } = handlerWith({
+      env: { TEST_SYSTEM_URL: 'http://127.0.0.1:1' },
+      getProfile: async (id) =>
+        id === 'c1'
+          ? {
+              ...profile,
+              endpointScenarios: { hello: 'real' },
+            }
+          : null,
+      passthrough: async () => {
+        const err = new TypeError('fetch failed') as TypeError & { cause?: unknown }
+        err.cause = { code: 'ECONNREFUSED' }
+        throw err
+      },
+    })
+
+    const res = await handle(helloRequest(), ['hello'])
+    await settle()
+
+    expect(res.status).toBe(502)
+    expect(await res.json()).toEqual({
+      error: 'passthrough request failed',
+      endpoint: 'hello',
+      upstream: 'http://127.0.0.1:1/hello',
+      message: 'fetch failed (ECONNREFUSED)',
+    })
+    expect(written).toHaveLength(1)
+    expect(written[0].profileId).toBe('c1')
+    expect(written[0].outcome).toBe('error')
+    expect(written[0].error?.code).toBe('passthrough_failed')
+    expect(written[0].error?.message).toContain('ECONNREFUSED')
+    expect(written[0].trace.scenario).toBe('real')
+    expect(written[0].response?.status).toBe(502)
+  })
+
+  it('truncates oversized bodies and flags them', async () => {
+    const bigString = 'x'.repeat(20 * 1024)
+    const { handle, written } = handlerWith({}, { blob: bigString })
+
+    await handle(helloRequest({ customerId: 'c1', padding: bigString }), ['hello'])
+    await settle()
+
+    const entry = written[0]
+    expect(entry.request?.truncated).toBe(true)
+    expect(typeof entry.request?.body).toBe('string')
+    expect((entry.request?.body as string).length).toBeLessThanOrEqual(16 * 1024)
+    expect(entry.response?.truncated).toBe(true)
+    expect((entry.response?.body as string).length).toBeLessThanOrEqual(16 * 1024)
+  })
+
+  it('serves the response even when the log write fails', async () => {
+    const { handle } = handlerWith({
+      writeLog: async () => {
+        throw new Error('mongo down')
+      },
+    })
+
+    const res = await handle(helloRequest(), ['hello'])
+    await settle()
+
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ ok: true })
+  })
+
+  it('works without a writeLog dependency', async () => {
+    const { handle } = handlerWith({ writeLog: undefined })
+    const res = await handle(helloRequest(), ['hello'])
+    expect(res.status).toBe(200)
+  })
+})

package/.next/standalone/tests/router/passthrough.test.ts

@@ -0,0 +1,100 @@
+import http from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { passthrough } from '../../src/lib/router/passthrough'
+
+let server: http.Server
+let baseUrl: string
+const BINARY = Buffer.from([0x89, 0x50, 0x00, 0xff, 0x01])
+
+beforeAll(async () => {
+  server = http.createServer((req, res) => {
+    if (req.url?.startsWith('/slow')) {
+      setTimeout(() => res.end('late'), 500)
+      return
+    }
+    if (req.url?.startsWith('/binary')) {
+      res.writeHead(200, { 'content-type': 'application/octet-stream' })
+      res.end(BINARY)
+      return
+    }
+    const chunks: Buffer[] = []
+    req.on('data', (c: Buffer) => chunks.push(c))
+    req.on('end', () => {
+      res.writeHead(201, { 'content-type': 'application/json', 'x-upstream': 'yes' })
+      res.end(
+        JSON.stringify({
+          method: req.method,
+          url: req.url,
+          host: req.headers.host,
+          proxyAuth: req.headers['proxy-authorization'] ?? null,
+          xKeep: req.headers['x-keep'] ?? null,
+          echo: Buffer.concat(chunks).toString('utf8'),
+        }),
+      )
+    })
+  })
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+  baseUrl = `http://127.0.0.1:${(server.address() as AddressInfo).port}`
+})
+
+afterAll(() => new Promise<void>((r) => server.close(() => r())))
+
+describe('passthrough', () => {
+  it('preserves method/path/query/body, strips hop-by-hop headers, rewrites Host', async () => {
+    const res = await passthrough({
+      baseUrl,
+      method: 'POST',
+      path: '/hello/world',
+      search: '?a=1&b=two',
+      headers: {
+        host: 'original.example.com',
+        'proxy-authorization': 'secret',
+        connection: 'keep-alive',
+        'x-keep': 'kept',
+        'content-type': 'application/json',
+      },
+      rawBody: Buffer.from('{"customerId":"c1"}'),
+      timeoutMs: 5000,
+    })
+    expect(res.status).toBe(201)
+    expect(res.headers['x-upstream']).toBe('yes')
+    const upstream = JSON.parse(res.bodyBytes.toString('utf8'))
+    expect(upstream.method).toBe('POST')
+    expect(upstream.url).toBe('/hello/world?a=1&b=two')
+    expect(upstream.host).toBe(new URL(baseUrl).host) // rewritten, not original.example.com
+    expect(upstream.proxyAuth).toBeNull() // hop-by-hop stripped
+    expect(upstream.xKeep).toBe('kept') // ordinary header preserved
+    expect(upstream.echo).toBe('{"customerId":"c1"}')
+  })
+
+  it('returns the upstream body as opaque bytes', async () => {
+    const res = await passthrough({
+      baseUrl,
+      method: 'GET',
+      path: '/binary',
+      search: '',
+      headers: {},
+      rawBody: null,
+      timeoutMs: 5000,
+    })
+    expect(res.status).toBe(200)
+    expect(Buffer.compare(res.bodyBytes, BINARY)).toBe(0)
+  })
+
+  it('returns 504 naming the upstream when the timeout elapses', async () => {
+    const res = await passthrough({
+      baseUrl,
+      method: 'GET',
+      path: '/slow',
+      search: '',
+      headers: {},
+      rawBody: null,
+      timeoutMs: 100,
+    })
+    expect(res.status).toBe(504)
+    const body = JSON.parse(res.bodyBytes.toString('utf8'))
+    expect(body.error).toMatch(/timeout/)
+    expect(body.upstream).toBe(baseUrl)
+  })
+})