@yolk-sdk/emulators 0.1.0-canary.96

package/src/emulator-compose.ts

@@ -0,0 +1,147 @@
+/**
+ * Composition of several kernel-built emulators behind one origin (internal; not a package
+ * export).
+ *
+ * The router takes one route per origin, so every route of one service origin must be answered by
+ * one fetch handler. When an origin carries routes of different wire cores (OpenCode Go serves
+ * Chat Completions, Messages, Responses, and usage under `https://opencode.ai`; Anthropic, Codex,
+ * and Grok serve their subscription-usage route next to their model route), each core keeps its
+ * own manifest, ledger, faults, turns, and control plane, and this module dispatches by path:
+ *
+ * - an API request whose path is a part's route path goes to that part; any other API request goes
+ *   to the fallback part (which fails it closed as an unknown route and records it);
+ * - `/_emulate/<part>/...` is that part's control plane (`/_emulate/...` inside the part);
+ * - `POST /_emulate/reset` resets every part.
+ *
+ * Runtime-portable Web APIs only; no Node builtins and no SDK imports.
+ */
+import { controlError, jsonResponse, type EmulatorCoverage } from './emulator-kernel.ts'
+
+/** What composition needs from each emulator. */
+export type ComposedPart = {
+  readonly fetch: (request: Request) => Promise<Response>
+  readonly reset: () => void
+  readonly coverage: () => EmulatorCoverage
+}
+
+export type ComposedRoute = {
+  /** Control-plane name: `/_emulate/<name>/...`. */
+  readonly name: string
+  /** API paths this part answers (its manifest paths). */
+  readonly paths: ReadonlyArray<string>
+  readonly part: ComposedPart
+}
+
+const requestPath = (request: Request): string =>
+  URL.canParse(request.url) ? new URL(request.url).pathname : '/'
+
+/** `/_emulate/<name>[/rest]` as the part's own control-plane path, or undefined. */
+const partControlPath = (path: string, name: string): string | undefined => {
+  const prefix = `/_emulate/${name}`
+
+  if (path === prefix) return '/_emulate'
+
+  return path.startsWith(`${prefix}/`) ? `/_emulate${path.slice(prefix.length)}` : undefined
+}
+
+/** Re-send a control-plane request to a part under its own control-plane path. */
+const forwardControl = async (
+  request: Request,
+  part: ComposedPart,
+  path: string
+): Promise<Response> => {
+  const url = new URL(request.url)
+
+  url.pathname = path
+
+  const body =
+    request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.text()
+
+  return part.fetch(new Request(url, { method: request.method, headers: request.headers, body }))
+}
+
+export const isControlPlanePath = (path: string): boolean =>
+  path === '/_emulate' || path.startsWith('/_emulate/')
+
+/** Every part's coverage in route order, with the unknown-route counts summed. */
+export const combinedCoverage = (parts: ReadonlyArray<ComposedPart>): EmulatorCoverage => {
+  const coverages = parts.map(part => part.coverage())
+
+  return {
+    routes: coverages.flatMap(coverage => coverage.routes),
+    unknownRouteRequests: coverages.reduce(
+      (total, coverage) => total + coverage.unknownRouteRequests,
+      0
+    )
+  }
+}
+
+export type ComposedFetchOptions = {
+  readonly routes: ReadonlyArray<ComposedRoute>
+  /** Answers API requests on no part's path (and fails them closed). */
+  readonly fallback: ComposedPart
+  /**
+   * Answers the remaining `/_emulate/*` requests (not a part's prefix, not `POST
+   * /_emulate/reset`). Defaults to a 404 control error.
+   */
+  readonly control?: (request: Request, path: string) => Promise<Response>
+}
+
+/** One fetch handler over several parts. Never rejects. */
+export const composeFetch =
+  (options: ComposedFetchOptions) =>
+  (request: Request): Promise<Response> => {
+    const handle = async (): Promise<Response> => {
+      const path = requestPath(request)
+
+      if (!isControlPlanePath(path)) {
+        const route = options.routes.find(candidate => candidate.paths.includes(path))
+
+        return (route?.part ?? options.fallback).fetch(request)
+      }
+
+      for (const route of options.routes) {
+        const partPath = partControlPath(path, route.name)
+
+        if (partPath !== undefined) return forwardControl(request, route.part, partPath)
+      }
+
+      if (path === '/_emulate/reset' && request.method === 'POST') {
+        options.fallback.reset()
+
+        for (const route of options.routes) route.part.reset()
+
+        return jsonResponse(200, { reset: true })
+      }
+
+      return options.control === undefined
+        ? controlError(404, 'unknown control-plane route')
+        : options.control(request, path)
+    }
+
+    return handle().catch(() => controlError(500, 'emulator failed to handle the request'))
+  }
+
+/**
+ * A wire-core emulator with its subscription-usage route on the same origin: `path` goes to
+ * `usage`, `/_emulate/usage/...` is the usage control plane, `POST /_emulate/reset` and `reset()`
+ * reset both, and everything else (other API paths, other `/_emulate/*` routes) is the primary
+ * emulator's, unchanged. The primary's ledger, faults, script, and coverage stay its own.
+ */
+export const withSubscriptionUsage = <Primary extends ComposedPart, Usage extends ComposedPart>(
+  primary: Primary,
+  usage: Usage,
+  path: string
+): Primary & { readonly usage: Usage } => ({
+  ...primary,
+  fetch: composeFetch({
+    routes: [{ name: 'usage', paths: [path], part: usage }],
+    fallback: primary,
+    control: request => primary.fetch(request)
+  }),
+  reset: () => {
+    primary.reset()
+    usage.reset()
+  },
+  usage
+})

package/src/emulator-http.ts

@@ -0,0 +1,184 @@
+/**
+ * HTTP rules shared by the emulators (internal): which statuses and headers a fault or scripted
+ * error may answer with, which request header and query parameter names carry credentials, and the
+ * marker a stateful core route uses to report a handler that threw.
+ *
+ * Faults and scripted errors always carry a body and never redirect, so 1xx, 204, 205, and every
+ * 3xx (including 304) are rejected when the fault or turn is added, as are invalid header names or
+ * values, a `location` header, and the framing headers the server sets itself. Route statuses
+ * (for example a fixture's bodiless 204 or its 202 with a `Location`) follow the fixtures instead.
+ *
+ * Runtime-portable (no Node builtins): the emulators are plain Web fetch handlers.
+ */
+import { Predicate } from 'effect'
+import * as Schema from 'effect/Schema'
+
+/** Why a status cannot answer an emulated request, or `undefined` when it can. */
+const emulatorStatusProblem = (status: number): string | undefined =>
+  status >= 300 && status <= 399
+    ? 'emulators never redirect: 3xx statuses are not allowed'
+    : status === 204 || status === 205
+      ? 'a 204 or 205 response cannot carry a body'
+      : undefined
+
+/** Statuses a fault or scripted error may answer with: 200-599 without 204, 205, and 3xx. */
+export const EmulatorResponseStatus = Schema.Int.check(
+  Schema.isBetween({ minimum: 200, maximum: 599 }),
+  Schema.makeFilter(emulatorStatusProblem)
+)
+
+// RFC 9110 token characters for header names.
+const headerNamePattern = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
+
+// Visible ASCII, space, tab, and obs-text: what both web `Headers` and Node's HTTP server accept.
+const headerValuePattern = /^[\t\x20-\x7e\x80-\xff]*$/
+
+const framingHeaders: ReadonlySet<string> = new Set([
+  'content-length',
+  'transfer-encoding',
+  'connection',
+  'keep-alive',
+  'upgrade'
+])
+
+/** Why a header record cannot be sent by an emulator, or `undefined` when it can. */
+const emulatorHeaderRecordProblem = (
+  headers: Readonly<Record<string, string>>
+): string | undefined => {
+  for (const [name, value] of Object.entries(headers)) {
+    if (!headerNamePattern.test(name)) {
+      return `header name ${JSON.stringify(name)} is not a valid HTTP token`
+    }
+
+    if (name.toLowerCase() === 'location') {
+      return 'emulators never redirect: a location header is not allowed'
+    }
+
+    // The server frames the body itself; a hand-set framing header would corrupt the response.
+    if (framingHeaders.has(name.toLowerCase())) {
+      return `header ${name} is set by the server and cannot be scripted`
+    }
+
+    if (!headerValuePattern.test(value)) {
+      return `header ${name} has a value with control or non-Latin-1 characters`
+    }
+  }
+
+  return undefined
+}
+
+/** Response headers for a fault or scripted error: valid names and values, and no `location`. */
+export const EmulatorHeaderRecord = Schema.Record(Schema.String, Schema.String).check(
+  Schema.makeFilter(emulatorHeaderRecordProblem)
+)
+
+// Header names that carry credentials or session state: the same rule as the conformance wire
+// helpers (`isCredentialHeaderName` in `@yolk-sdk/conformance`), copied because emulator source
+// never imports SDK packages.
+const credentialHeaderNames: ReadonlySet<string> = new Set([
+  'authorization',
+  'proxy-authorization',
+  'cookie',
+  'set-cookie',
+  'x-api-key',
+  'api-key',
+  'x-goog-api-key',
+  'x-auth-token',
+  'x-access-token',
+  'x-amz-security-token',
+  'x-vercel-oidc-token',
+  'x-csrf-token'
+])
+
+const credentialHeaderPattern = /(api[-_]?key|secret|password|cookie|authorization)/i
+
+const credentialHeaderSegmentPattern = /(^|[-_])(token|key|auth)([-_]|$)/i
+
+/** True for header names that carry credentials or session state. */
+export const isCredentialHeaderName = (name: string): boolean => {
+  const lower = name.toLowerCase()
+
+  return (
+    credentialHeaderNames.has(lower) ||
+    credentialHeaderPattern.test(lower) ||
+    credentialHeaderSegmentPattern.test(lower)
+  )
+}
+
+/** What a redacted credential value becomes in a ledger. */
+export const redactedCredentialValue = '<redacted>'
+
+const isJsonRecord = (value: Schema.Json): value is Schema.JsonObject =>
+  value !== null && Predicate.isObject(value) && !Array.isArray(value)
+
+/**
+ * A JSON value safe to keep in a ledger: every object key that `isCredentialHeaderName` accepts
+ * (for example `requests[].headers.Authorization` in a Graph `$batch` body), at any depth, has
+ * its value replaced by `<redacted>`. Other values are copied unchanged.
+ */
+export const redactCredentialFields = (value: Schema.Json): Schema.Json => {
+  if (Array.isArray(value)) return value.map(redactCredentialFields)
+
+  if (!isJsonRecord(value)) return value
+
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [
+      key,
+      isCredentialHeaderName(key) ? redactedCredentialValue : redactCredentialFields(entry)
+    ])
+  )
+}
+
+// Query parameter names that carry credentials: the same list as the conformance fixture scan
+// (`credentialParamPattern` in `@yolk-sdk/conformance`, reported as `credential_query_param`),
+// copied because emulator source never imports SDK packages. It adds the presigned-URL
+// `x-amz-signature` and `x-amz-credential`, which the header rule does not cover.
+const credentialQueryParamPattern =
+  /^(api[_-]?key|key|token|access[_-]?token|refresh[_-]?token|id[_-]?token|auth|secret|password|client[_-]?secret|x-amz-signature|x-amz-credential|x-amz-security-token)$/i
+
+/**
+ * True for query parameter names that carry credentials: every name the conformance fixture scan
+ * reports as a credential query parameter, plus every name `isCredentialHeaderName` accepts.
+ */
+export const isCredentialQueryKey = (name: string): boolean =>
+  credentialQueryParamPattern.test(name) || isCredentialHeaderName(name)
+
+/**
+ * Query parameters safe to keep in a ledger: the value of every key that `isCredentialQueryKey`
+ * accepts (for example `access_token`, `api_key`, or `X-Amz-Signature`) is replaced by
+ * `<redacted>`.
+ */
+export const redactCredentialQuery = (query: URLSearchParams): Readonly<Record<string, string>> =>
+  Object.fromEntries(
+    [...query].map(([key, value]) => [
+      key,
+      isCredentialQueryKey(key) ? redactedCredentialValue : value
+    ])
+  )
+
+/**
+ * Internal response header a stateful core route sets on the bodiless 500 it answers when its
+ * handler throws. The wrapper never forwards it: it answers its own error envelope 500 instead
+ * and records `responseError` in the ledger.
+ */
+export const handlerFailedHeader = 'x-emulator-handler-failed'
+
+/** The core route's answer when its handler threw (see `handlerFailedHeader`). */
+export const handlerFailedResponse = (): Response =>
+  new Response(null, { status: 500, headers: { [handlerFailedHeader]: '1' } })
+
+/**
+ * Internal request header a stateful wrapper sets on the requests it forwards to its core: the
+ * id of the wrapper's job for that request (the fault decision the core route asks for, and what
+ * the route decided). Ids come from a counter that never resets (the ledger sequence does), so a
+ * ledger clear never makes two jobs share one. Clients cannot set it: wrappers build the core
+ * request headers themselves.
+ */
+export const emulatorJobHeader = 'x-emulator-job-id'
+
+/**
+ * What a core route answers when the wrapper returns the real answer itself (a fault, or in the
+ * shared wrapper's resolved mode a refusal), so that answer never depends on the core runtime's
+ * lifecycle: a reset or a close before it is read never cancels it.
+ */
+export const answeredOutsideCore = (): Response => new Response(null, { status: 204 })