imposters 0.1.0

package/src/server/FiberManager.ts

@@ -0,0 +1,25 @@
+import { Context, Effect, FiberMap, Layer } from "effect"
+
+export interface FiberManagerShape {
+  readonly start: (id: string, effect: Effect.Effect<never, unknown>) => Effect.Effect<void>
+  readonly stop: (id: string) => Effect.Effect<void>
+  readonly isRunning: (id: string) => Effect.Effect<boolean>
+}
+
+export class FiberManager extends Context.Tag("FiberManager")<FiberManager, FiberManagerShape>() {}
+
+export const FiberManagerLive = Layer.scoped(
+  FiberManager,
+  Effect.gen(function*() {
+    const fiberMap = yield* FiberMap.make<string>()
+
+    const start = (id: string, effect: Effect.Effect<never, unknown>): Effect.Effect<void> =>
+      FiberMap.run(fiberMap, id, effect)
+
+    const stop = (id: string): Effect.Effect<void> => FiberMap.remove(fiberMap, id)
+
+    const isRunning = (id: string): Effect.Effect<boolean> => FiberMap.has(fiberMap, id)
+
+    return { start, stop, isRunning }
+  })
+)

package/src/server/ImposterServer.ts

@@ -0,0 +1,244 @@
+import { Context, Data, Effect, HashMap, Layer, Ref, Runtime } from "effect"
+import * as DateTime from "effect/DateTime"
+import { ImposterConfig, type ImposterNotFoundError, type ProxyConfigDomain } from "../domain/imposter"
+import { extractRequestContext, findMatchingStub } from "../matching/RequestMatcher"
+import { buildResponse, makeResponseState } from "../matching/ResponseGenerator"
+import { ImposterRepository } from "../repositories/ImposterRepository"
+import { NonEmptyString } from "../schemas/common"
+import type { RequestLogEntry } from "../schemas/RequestLogSchema"
+import type { Stub } from "../schemas/StubSchema"
+import { MetricsService } from "../services/MetricsService"
+import { ProxyService } from "../services/ProxyService"
+import { RequestLogger } from "../services/RequestLogger"
+import { makeUiRouter } from "../ui/UiRouter"
+import { ServerFactory } from "./BunServer"
+import { FiberManager } from "./FiberManager"
+
+export class ImposterServerError extends Data.TaggedError("ImposterServerError")<{
+  readonly imposterId: string
+  readonly reason: string
+}> {}
+
+export interface ImposterServerShape {
+  readonly start: (id: string) => Effect.Effect<void, ImposterServerError | ImposterNotFoundError>
+  readonly stop: (id: string) => Effect.Effect<void>
+  readonly updateStubs: (id: string) => Effect.Effect<void>
+  readonly updateProxyConfig: (id: string) => Effect.Effect<void>
+  readonly isRunning: (id: string) => Effect.Effect<boolean>
+}
+
+export class ImposterServer extends Context.Tag("ImposterServer")<ImposterServer, ImposterServerShape>() {}
+
+interface ImposterState {
+  readonly stubsRef: Ref.Ref<ReadonlyArray<Stub>>
+  readonly proxyConfigRef: Ref.Ref<ProxyConfigDomain | undefined>
+}
+
+export const ImposterServerLive = Layer.effect(
+  ImposterServer,
+  Effect.gen(function*() {
+    const repo = yield* ImposterRepository
+    const fiberManager = yield* FiberManager
+    const serverFactory = yield* ServerFactory
+    const requestLogger = yield* RequestLogger
+    const metricsService = yield* MetricsService
+    const proxyService = yield* ProxyService
+    const stateMapRef = yield* Ref.make<HashMap.HashMap<string, ImposterState>>(HashMap.empty())
+
+    const start = (id: string): Effect.Effect<void, ImposterServerError | ImposterNotFoundError> =>
+      Effect.gen(function*() {
+        const record = yield* repo.get(id)
+        const config = record.config
+
+        // Create per-imposter state
+        const stubsRef = yield* Ref.make<ReadonlyArray<Stub>>(record.stubs)
+        const proxyConfigRef = yield* Ref.make<ProxyConfigDomain | undefined>(config.proxy)
+        const responseState = yield* makeResponseState()
+
+        // Store state for hot-reload
+        yield* Ref.update(stateMapRef, HashMap.set(id, { stubsRef, proxyConfigRef } as ImposterState))
+
+        // Capture runtime for running effects inside fetch handler
+        const rt = yield* Effect.runtime<never>()
+        const runPromise = Runtime.runPromise(rt)
+
+        // UI router for /_admin pages
+        const uiRouter = makeUiRouter({ id, config, stubsRef, repo, requestLogger, runPromise })
+
+        const handler = async (request: Request): Promise<Response> => {
+          // Try UI router first (returns null if not a /_admin path)
+          const uiResponse = await uiRouter(request)
+          if (uiResponse !== null) return uiResponse
+
+          return runPromise(
+            Effect.gen(function*() {
+              const startTime = Date.now()
+              const stubs = yield* Ref.get(stubsRef)
+              const ctx = yield* Effect.promise(() => extractRequestContext(request))
+              const stub = findMatchingStub(ctx, stubs)
+
+              let response: Response
+              let proxied = false
+              if (!stub) {
+                const proxyConfig = yield* Ref.get(proxyConfigRef)
+                if (proxyConfig) {
+                  const url = new URL(request.url)
+                  response = yield* proxyService.forward(ctx, proxyConfig, url).pipe(
+                    Effect.catchTag("ProxyError", (err) =>
+                      Effect.succeed(
+                        new Response(
+                          JSON.stringify({ error: "Proxy failed", target: err.targetUrl, reason: err.reason }),
+                          { status: 502, headers: { "content-type": "application/json" } }
+                        )
+                      ))
+                  )
+                  proxied = true
+                  // Record mode: save as stub + update stubsRef
+                  if (proxyConfig.mode === "record" && response.status < 500) {
+                    const responseClone = response.clone()
+                    const newStub = yield* proxyService.recordAsStub(ctx, responseClone)
+                    yield* repo.addStub(id, newStub).pipe(Effect.catchAll(() => Effect.void))
+                    const freshStubs = yield* repo.getStubs(id).pipe(
+                      Effect.catchAll(() => Effect.succeed([] as ReadonlyArray<Stub>))
+                    )
+                    yield* Ref.set(stubsRef, freshStubs)
+                  }
+                } else {
+                  response = new Response(
+                    JSON.stringify({ error: "No matching stub found", method: ctx.method, path: ctx.path }),
+                    { status: 404, headers: { "content-type": "application/json" } }
+                  )
+                }
+              } else {
+                const responses = stub.responses
+                const index = yield* responseState.getNextIndex(id, stub.id, responses.length, stub.responseMode)
+                const responseConfig = responses[index]!
+                const delay = responseConfig.delay
+                if (delay !== undefined && delay > 0) {
+                  yield* Effect.sleep(`${delay} millis`)
+                }
+                response = yield* Effect.promise(() => buildResponse(responseConfig, ctx))
+              }
+
+              // Capture response for logging
+              const respText = yield* Effect.promise(() => response.text())
+              const respHeaders: Record<string, string> = {}
+              response.headers.forEach((val, key) => {
+                respHeaders[key] = val
+              })
+              // Reconstruct since .text() consumed body
+              response = new Response(respText, { status: response.status, headers: response.headers })
+
+              const logBody = respText.length > 10240 ? respText.slice(0, 10240) : (respText || undefined)
+
+              const duration = Date.now() - startTime
+              const logEntry: RequestLogEntry = {
+                id: NonEmptyString.make(crypto.randomUUID()),
+                imposterId: NonEmptyString.make(id),
+                timestamp: DateTime.unsafeMake(startTime),
+                request: {
+                  method: ctx.method,
+                  path: ctx.path,
+                  headers: ctx.headers,
+                  query: ctx.query,
+                  body: ctx.body
+                },
+                response: {
+                  status: response.status,
+                  headers: respHeaders,
+                  ...(logBody !== undefined ? { body: logBody } : {}),
+                  ...(stub ? { matchedStubId: NonEmptyString.make(stub.id) } : {}),
+                  proxied
+                },
+                duration
+              }
+              yield* requestLogger.log(logEntry).pipe(Effect.catchAll(() => Effect.void))
+              yield* metricsService.recordRequest(logEntry).pipe(Effect.catchAll(() => Effect.void))
+
+              return response
+            }).pipe(
+              Effect.catchAllCause((cause) =>
+                Effect.succeed(
+                  new Response(
+                    JSON.stringify({ error: "Internal server error", details: String(cause) }),
+                    { status: 500, headers: { "content-type": "application/json" } }
+                  )
+                )
+              )
+            )
+          )
+        }
+
+        // Build the long-running fiber effect with acquireRelease
+        const fiberEffect = Effect.acquireRelease(
+          Effect.try({
+            try: () => serverFactory.create({ port: config.port, fetch: handler }),
+            catch: (err) =>
+              new ImposterServerError({ imposterId: id, reason: `Failed to bind port ${config.port}: ${err}` })
+          }),
+          (server) => Effect.sync(() => server.stop(true))
+        ).pipe(
+          Effect.andThen(Effect.never),
+          Effect.scoped
+        )
+
+        // Wrap fiber in onError for crash supervision
+        const supervisedEffect = fiberEffect.pipe(
+          Effect.onError(() =>
+            Effect.gen(function*() {
+              yield* Ref.update(stateMapRef, HashMap.remove(id))
+              yield* repo.update(id, (r) => ({
+                ...r,
+                config: ImposterConfig({ ...r.config, status: "stopped" })
+              })).pipe(Effect.catchAll(() => Effect.void))
+              yield* responseState.reset(id)
+            })
+          )
+        ) as Effect.Effect<never, unknown>
+
+        yield* fiberManager.start(id, supervisedEffect)
+
+        // Update status to running
+        yield* repo.update(id, (r) => ({
+          ...r,
+          config: ImposterConfig({ ...r.config, status: "running" })
+        })).pipe(Effect.catchTag("ImposterNotFoundError", () => Effect.void))
+      })
+
+    const stop = (id: string): Effect.Effect<void> =>
+      Effect.gen(function*() {
+        yield* fiberManager.stop(id)
+        yield* Ref.update(stateMapRef, HashMap.remove(id))
+        yield* repo.update(id, (r) => ({
+          ...r,
+          config: ImposterConfig({ ...r.config, status: "stopped" })
+        })).pipe(Effect.catchAll(() => Effect.void))
+        yield* requestLogger.removeImposter(id)
+      })
+
+    const updateStubs = (id: string): Effect.Effect<void> =>
+      Effect.gen(function*() {
+        const stubs = yield* repo.getStubs(id).pipe(Effect.catchAll(() => Effect.succeed([] as ReadonlyArray<Stub>)))
+        const stateMap = yield* Ref.get(stateMapRef)
+        const state = HashMap.get(stateMap, id)
+        if (state._tag === "Some") {
+          yield* Ref.set(state.value.stubsRef, stubs)
+        }
+      })
+
+    const updateProxyConfig = (id: string): Effect.Effect<void> =>
+      Effect.gen(function*() {
+        const record = yield* repo.get(id).pipe(Effect.catchAll(() => Effect.succeed(null)))
+        if (record === null) return
+        const stateMap = yield* Ref.get(stateMapRef)
+        const state = HashMap.get(stateMap, id)
+        if (state._tag === "Some") {
+          yield* Ref.set(state.value.proxyConfigRef, record.config.proxy)
+        }
+      })
+
+    const isRunning = (id: string): Effect.Effect<boolean> => fiberManager.isRunning(id)
+
+    return { start, stop, updateStubs, updateProxyConfig, isRunning } satisfies ImposterServerShape
+  })
+)

package/src/services/AppConfig.ts

@@ -0,0 +1,22 @@
+import { Config, Context, Layer } from "effect"
+
+export interface AppConfigShape {
+  readonly adminPort: number
+  readonly portRangeMin: number
+  readonly portRangeMax: number
+  readonly maxImposters: number
+  readonly logLevel: "debug" | "info" | "warn" | "error"
+}
+
+export class AppConfig extends Context.Tag("AppConfig")<AppConfig, AppConfigShape>() {}
+
+const config = Config.all({
+  adminPort: Config.number("ADMIN_PORT").pipe(Config.withDefault(2525)),
+  portRangeMin: Config.number("PORT_RANGE_MIN").pipe(Config.withDefault(3000)),
+  portRangeMax: Config.number("PORT_RANGE_MAX").pipe(Config.withDefault(4000)),
+  maxImposters: Config.number("MAX_IMPOSTERS").pipe(Config.withDefault(100)),
+  logLevel: Config.literal("debug", "info", "warn", "error")("LOG_LEVEL")
+    .pipe(Config.withDefault("info" as const))
+})
+
+export const AppConfigLive = Layer.effect(AppConfig, config)

package/src/services/MetricsService.ts

@@ -0,0 +1,157 @@
+import { Context, Effect, HashMap, Layer, Ref } from "effect"
+import * as DateTime from "effect/DateTime"
+import type { RequestLogEntry } from "../schemas/RequestLogSchema"
+
+const BUFFER_SIZE = 1000
+
+interface ImposterMetrics {
+  totalRequests: number
+  requestsByMethod: Record<string, number>
+  requestsByStatusCode: Record<string, number>
+  responseTimes: Float64Array
+  responseTimeIndex: number
+  responseTimeCount: number
+  firstRequestAt: DateTime.Utc
+  lastRequestAt: DateTime.Utc
+  errorCount: number
+}
+
+export interface Statistics {
+  readonly totalRequests: number
+  readonly requestsPerMinute: number
+  readonly averageResponseTime: number
+  readonly errorRate: number
+  readonly requestsByMethod: Record<string, number>
+  readonly requestsByStatusCode: Record<string, number>
+  readonly lastRequestAt?: DateTime.Utc
+  readonly p50ResponseTime?: number
+  readonly p95ResponseTime?: number
+  readonly p99ResponseTime?: number
+}
+
+const makeEmptyMetrics = (now: DateTime.Utc): ImposterMetrics => ({
+  totalRequests: 0,
+  requestsByMethod: {},
+  requestsByStatusCode: {},
+  responseTimes: new Float64Array(BUFFER_SIZE),
+  responseTimeIndex: 0,
+  responseTimeCount: 0,
+  firstRequestAt: now,
+  lastRequestAt: now,
+  errorCount: 0
+})
+
+const computePercentile = (sorted: Array<number>, p: number): number => {
+  if (sorted.length === 0) return 0
+  const index = Math.ceil((p / 100) * sorted.length) - 1
+  return sorted[Math.max(0, index)]!
+}
+
+const computeStats = (metrics: ImposterMetrics): Statistics => {
+  const count = metrics.responseTimeCount
+  const total = metrics.totalRequests
+
+  // Compute average response time
+  let sumRT = 0
+  for (let i = 0; i < Math.min(count, BUFFER_SIZE); i++) {
+    sumRT += metrics.responseTimes[i]!
+  }
+  const avgRT = count > 0 ? sumRT / Math.min(count, BUFFER_SIZE) : 0
+
+  // Compute requests per minute
+  const elapsedMs = DateTime.toEpochMillis(metrics.lastRequestAt) - DateTime.toEpochMillis(metrics.firstRequestAt)
+  const elapsedMinutes = elapsedMs / 60000
+  const rpm = elapsedMinutes > 0 ? total / elapsedMinutes : total
+
+  // Compute error rate
+  const errorRate = total > 0 ? metrics.errorCount / total : 0
+
+  // Compute percentiles
+  const bufferLen = Math.min(count, BUFFER_SIZE)
+  const sorted = Array.from(metrics.responseTimes.subarray(0, bufferLen)).sort((a, b) => a - b)
+
+  return {
+    totalRequests: total,
+    requestsPerMinute: Math.round(rpm * 100) / 100,
+    averageResponseTime: Math.round(avgRT * 100) / 100,
+    errorRate: Math.round(errorRate * 10000) / 10000,
+    requestsByMethod: { ...metrics.requestsByMethod },
+    requestsByStatusCode: { ...metrics.requestsByStatusCode },
+    ...(total > 0 ? { lastRequestAt: metrics.lastRequestAt } : {}),
+    ...(bufferLen > 0
+      ? {
+        p50ResponseTime: computePercentile(sorted, 50),
+        p95ResponseTime: computePercentile(sorted, 95),
+        p99ResponseTime: computePercentile(sorted, 99)
+      }
+      : {})
+  }
+}
+
+export interface MetricsServiceShape {
+  readonly recordRequest: (entry: RequestLogEntry) => Effect.Effect<void>
+  readonly getStats: (imposterId: string) => Effect.Effect<Statistics>
+  readonly resetStats: (imposterId: string) => Effect.Effect<void>
+}
+
+export class MetricsService extends Context.Tag("MetricsService")<MetricsService, MetricsServiceShape>() {}
+
+export const MetricsServiceLive = Layer.effect(
+  MetricsService,
+  Effect.gen(function*() {
+    const storeRef = yield* Ref.make(HashMap.empty<string, ImposterMetrics>())
+
+    const recordRequest = (entry: RequestLogEntry): Effect.Effect<void> =>
+      Ref.update(storeRef, (store) => {
+        const existing = HashMap.get(store, entry.imposterId)
+        const now = entry.timestamp
+        const metrics = existing._tag === "Some" ? existing.value : makeEmptyMetrics(now)
+
+        metrics.totalRequests += 1
+
+        // Method counts
+        const method = entry.request.method.toUpperCase()
+        metrics.requestsByMethod[method] = (metrics.requestsByMethod[method] ?? 0) + 1
+
+        // Status code counts
+        const statusKey = String(entry.response.status)
+        metrics.requestsByStatusCode[statusKey] = (metrics.requestsByStatusCode[statusKey] ?? 0) + 1
+
+        // Response time circular buffer
+        metrics.responseTimes[metrics.responseTimeIndex % BUFFER_SIZE] = entry.duration
+        metrics.responseTimeIndex = (metrics.responseTimeIndex + 1) % BUFFER_SIZE
+        metrics.responseTimeCount += 1
+
+        // Error tracking (4xx + 5xx)
+        if (entry.response.status >= 400) {
+          metrics.errorCount += 1
+        }
+
+        metrics.lastRequestAt = now
+
+        return HashMap.set(store, entry.imposterId, metrics)
+      })
+
+    const getStats = (imposterId: string): Effect.Effect<Statistics> =>
+      Ref.get(storeRef).pipe(
+        Effect.map((store) => {
+          const existing = HashMap.get(store, imposterId)
+          if (existing._tag === "None") {
+            return {
+              totalRequests: 0,
+              requestsPerMinute: 0,
+              averageResponseTime: 0,
+              errorRate: 0,
+              requestsByMethod: {},
+              requestsByStatusCode: {}
+            }
+          }
+          return computeStats(existing.value)
+        })
+      )
+
+    const resetStats = (imposterId: string): Effect.Effect<void> => Ref.update(storeRef, HashMap.remove(imposterId))
+
+    return { recordRequest, getStats, resetStats } satisfies MetricsServiceShape
+  })
+)

package/src/services/PortAllocator.ts

@@ -0,0 +1,68 @@
+import { Context, Data, Effect, HashSet, Layer, Ref } from "effect"
+import { AppConfig } from "./AppConfig"
+
+export class PortAllocatorError extends Data.TaggedError("PortAllocatorError")<{
+  readonly reason: string
+  readonly port?: number
+}> {}
+
+export class PortExhaustedError extends Data.TaggedError("PortExhaustedError")<{
+  readonly rangeMin: number
+  readonly rangeMax: number
+}> {}
+
+export interface PortAllocatorShape {
+  readonly allocate: (preferred?: number) => Effect.Effect<number, PortAllocatorError | PortExhaustedError>
+  readonly release: (port: number) => Effect.Effect<void>
+  readonly isAvailable: (port: number) => Effect.Effect<boolean>
+}
+
+export class PortAllocator extends Context.Tag("PortAllocator")<PortAllocator, PortAllocatorShape>() {}
+
+export const PortAllocatorLive = Layer.effect(
+  PortAllocator,
+  Effect.gen(function*() {
+    const config = yield* AppConfig
+    const portsRef = yield* Ref.make(HashSet.empty<number>())
+
+    type AllocateResult = readonly [
+      Effect.Effect<number, PortAllocatorError | PortExhaustedError>,
+      HashSet.HashSet<number>
+    ]
+
+    const allocate = (preferred?: number): Effect.Effect<number, PortAllocatorError | PortExhaustedError> => {
+      if (preferred !== undefined) {
+        return Ref.modify(portsRef, (ports): AllocateResult => {
+          if (HashSet.has(ports, preferred)) {
+            return [
+              Effect.fail(
+                new PortAllocatorError({ reason: `Port ${preferred} is already allocated`, port: preferred })
+              ),
+              ports
+            ]
+          }
+          return [Effect.succeed(preferred), HashSet.add(ports, preferred)]
+        }).pipe(Effect.flatten)
+      }
+
+      return Ref.modify(portsRef, (ports): AllocateResult => {
+        for (let port = config.portRangeMin; port <= config.portRangeMax; port++) {
+          if (!HashSet.has(ports, port)) {
+            return [Effect.succeed(port), HashSet.add(ports, port)]
+          }
+        }
+        return [
+          Effect.fail(new PortExhaustedError({ rangeMin: config.portRangeMin, rangeMax: config.portRangeMax })),
+          ports
+        ]
+      }).pipe(Effect.flatten)
+    }
+
+    const release = (port: number): Effect.Effect<void> => Ref.update(portsRef, HashSet.remove(port))
+
+    const isAvailable = (port: number): Effect.Effect<boolean> =>
+      Ref.get(portsRef).pipe(Effect.map((ports) => !HashSet.has(ports, port)))
+
+    return { allocate, release, isAvailable }
+  })
+)

package/src/services/ProxyService.ts

@@ -0,0 +1,139 @@
+import { Context, Data, Effect, Layer } from "effect"
+import type { ProxyConfigDomain } from "../domain/imposter"
+import type { RequestContext } from "../matching/RequestMatcher"
+import { NonEmptyString } from "../schemas/common"
+import type { Stub } from "../schemas/StubSchema"
+import { Uuid } from "./Uuid"
+
+export class ProxyError extends Data.TaggedError("ProxyError")<{
+  readonly targetUrl: string
+  readonly reason: string
+  readonly cause?: unknown
+}> {}
+
+const HOP_BY_HOP_HEADERS = new Set([
+  "host",
+  "connection",
+  "keep-alive",
+  "transfer-encoding",
+  "upgrade",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailers"
+])
+
+export interface ProxyServiceShape {
+  readonly forward: (
+    ctx: RequestContext,
+    config: ProxyConfigDomain,
+    originalUrl: URL
+  ) => Effect.Effect<Response, ProxyError>
+  readonly recordAsStub: (
+    request: RequestContext,
+    response: Response
+  ) => Effect.Effect<Stub>
+}
+
+export class ProxyService extends Context.Tag("ProxyService")<ProxyService, ProxyServiceShape>() {}
+
+export const ProxyServiceLive = Layer.effect(
+  ProxyService,
+  Effect.gen(function*() {
+    const uuid = yield* Uuid
+
+    const forward = (
+      ctx: RequestContext,
+      config: ProxyConfigDomain,
+      originalUrl: URL
+    ): Effect.Effect<Response, ProxyError> =>
+      Effect.gen(function*() {
+        // Build target URL preserving path and query
+        const targetBase = config.targetUrl.replace(/\/$/, "")
+        const targetUrl = `${targetBase}${originalUrl.pathname}${originalUrl.search}`
+
+        // Build headers
+        const headers = new Headers()
+        for (const [key, val] of Object.entries(ctx.headers)) {
+          if (!HOP_BY_HOP_HEADERS.has(key.toLowerCase())) {
+            headers.set(key, val)
+          }
+        }
+
+        // Remove headers specified in config
+        for (const h of config.removeHeaders) {
+          headers.delete(h)
+        }
+
+        // Add headers specified in config
+        if (config.addHeaders) {
+          for (const [key, val] of Object.entries(config.addHeaders)) {
+            headers.set(key, val)
+          }
+        }
+
+        // Build body
+        let body: string | undefined
+        if (ctx.body !== undefined && ctx.body !== null) {
+          body = typeof ctx.body === "string" ? ctx.body : JSON.stringify(ctx.body)
+        }
+
+        const response = yield* Effect.tryPromise({
+          try: (signal) =>
+            fetch(targetUrl, {
+              method: ctx.method,
+              headers,
+              ...(body !== undefined && ctx.method !== "GET" && ctx.method !== "HEAD" ? { body } : {}),
+              redirect: config.followRedirects ? "follow" : "manual",
+              signal
+            }),
+          catch: (err) => new ProxyError({ targetUrl, reason: `Failed to reach target: ${err}`, cause: err })
+        }).pipe(Effect.timeoutFail({
+          duration: `${config.timeout} millis`,
+          onTimeout: () => new ProxyError({ targetUrl, reason: `Request timed out after ${config.timeout}ms` })
+        }))
+
+        return response
+      })
+
+    const recordAsStub = (
+      request: RequestContext,
+      response: Response
+    ): Effect.Effect<Stub> =>
+      Effect.gen(function*() {
+        const id = yield* uuid.generateShort
+
+        const respHeaders: Record<string, string> = {}
+        response.headers.forEach((val, key) => {
+          respHeaders[key] = val
+        })
+
+        const respText = yield* Effect.promise(() => response.text())
+        let respBody: unknown = respText
+        const contentType = response.headers.get("content-type") ?? ""
+        if (contentType.includes("application/json") && respText) {
+          try {
+            respBody = JSON.parse(respText)
+          } catch {
+            // keep as string
+          }
+        }
+
+        return {
+          id: NonEmptyString.make(id),
+          predicates: [
+            { field: "method" as const, operator: "equals" as const, value: request.method, caseSensitive: true },
+            { field: "path" as const, operator: "equals" as const, value: request.path, caseSensitive: true }
+          ],
+          responses: [{
+            status: response.status,
+            headers: respHeaders,
+            body: respBody
+          }],
+          responseMode: "sequential" as const
+        }
+      })
+
+    return { forward, recordAsStub } satisfies ProxyServiceShape
+  })
+)