@neurocode-ai/http-recorder 1.18.13 → 1.18.15

package/src/redaction.ts

@@ -0,0 +1,117 @@
+import { Schema } from "effect"
+
+export const REDACTED = "[REDACTED]"
+
+const DEFAULT_REDACT_HEADERS = [
+  "authorization",
+  "cookie",
+  "proxy-authorization",
+  "set-cookie",
+  "x-api-key",
+  "x-amz-security-token",
+  "x-goog-api-key",
+]
+
+const DEFAULT_REDACT_QUERY = [
+  "access_token",
+  "api-key",
+  "api_key",
+  "apikey",
+  "code",
+  "key",
+  "signature",
+  "sig",
+  "token",
+  "x-amz-credential",
+  "x-amz-security-token",
+  "x-amz-signature",
+]
+
+const SECRET_PATTERNS: ReadonlyArray<{ readonly label: string; readonly pattern: RegExp }> = [
+  { label: "bearer token", pattern: /\bBearer\s+[A-Za-z0-9._~+/=-]{16,}\b/i },
+  { label: "API key", pattern: /\bsk-[A-Za-z0-9][A-Za-z0-9_-]{20,}\b/ },
+  { label: "Anthropic API key", pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/ },
+  { label: "Google API key", pattern: /\bAIza[0-9A-Za-z_-]{20,}\b/ },
+  { label: "AWS access key", pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
+  { label: "GitHub token", pattern: /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/ },
+  { label: "private key", pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+]
+
+const ENV_SECRET_NAMES = /(?:API|AUTH|BEARER|CREDENTIAL|KEY|PASSWORD|SECRET|TOKEN)/i
+const SAFE_ENV_VALUES = new Set(["fixture", "test", "test-key"])
+
+const envSecrets = () =>
+  Object.entries(process.env).flatMap(([name, value]) => {
+    if (!value) return []
+    if (!ENV_SECRET_NAMES.test(name)) return []
+    if (value.length < 12) return []
+    if (SAFE_ENV_VALUES.has(value.toLowerCase())) return []
+    return [{ name, value }]
+  })
+
+const pathFor = (base: string, key: string) => (base ? `${base}.${key}` : key)
+
+const stringEntries = (value: unknown, base = ""): ReadonlyArray<{ readonly path: string; readonly value: string }> => {
+  if (typeof value === "string") return [{ path: base, value }]
+  if (Array.isArray(value)) return value.flatMap((item, index) => stringEntries(item, `${base}[${index}]`))
+  if (value && typeof value === "object") {
+    return Object.entries(value).flatMap(([key, child]) => stringEntries(child, pathFor(base, key)))
+  }
+  return []
+}
+
+const redactionSet = (values: ReadonlyArray<string> | undefined, defaults: ReadonlyArray<string>) =>
+  new Set([...defaults, ...(values ?? [])].map((value) => value.toLowerCase()))
+
+export type UrlRedactor = (url: string) => string
+
+export const redactUrl = (
+  raw: string,
+  query: ReadonlyArray<string> = DEFAULT_REDACT_QUERY,
+  urlRedactor?: UrlRedactor,
+) => {
+  if (!URL.canParse(raw)) return urlRedactor?.(raw) ?? raw
+  const url = new URL(raw)
+  if (url.username) url.username = REDACTED
+  if (url.password) url.password = REDACTED
+  const redacted = redactionSet(query, DEFAULT_REDACT_QUERY)
+  for (const key of url.searchParams.keys()) {
+    if (redacted.has(key.toLowerCase())) url.searchParams.set(key, REDACTED)
+  }
+  return urlRedactor?.(url.toString()) ?? url.toString()
+}
+
+export const redactHeaders = (
+  headers: Record<string, string>,
+  allow: ReadonlyArray<string>,
+  redact: ReadonlyArray<string> = DEFAULT_REDACT_HEADERS,
+) => {
+  const allowed = new Set(allow.map((name) => name.toLowerCase()))
+  const redacted = redactionSet(redact, DEFAULT_REDACT_HEADERS)
+  return Object.fromEntries(
+    Object.entries(headers)
+      .map(([name, value]) => [name.toLowerCase(), value] as const)
+      .filter(([name]) => allowed.has(name))
+      .map(([name, value]) => [name, redacted.has(name) ? REDACTED : value] as const)
+      .toSorted(([a], [b]) => a.localeCompare(b)),
+  )
+}
+
+export const SecretFindingSchema = Schema.Struct({
+  path: Schema.String,
+  reason: Schema.String,
+})
+export type SecretFinding = Schema.Schema.Type<typeof SecretFindingSchema>
+
+export const secretFindings = (value: unknown): ReadonlyArray<SecretFinding> => {
+  const environment = envSecrets()
+  return stringEntries(value).flatMap((entry) => [
+    ...SECRET_PATTERNS.filter((item) => item.pattern.test(entry.value)).map((item) => ({
+      path: entry.path,
+      reason: item.label,
+    })),
+    ...environment
+      .filter((item) => entry.value.includes(item.value))
+      .map((item) => ({ path: entry.path, reason: `environment secret ${item.name}` })),
+  ])
+}

package/src/redactor.ts

@@ -0,0 +1,135 @@
+import { Option } from "effect"
+import { decodeJson } from "./matching.js"
+import { REDACTED, redactHeaders, redactUrl } from "./redaction.js"
+import type { RedactOptions, RequestSnapshot, ResponseSnapshot } from "./types.js"
+
+export type { RedactOptions } from "./types.js"
+
+export const DEFAULT_REQUEST_HEADERS: ReadonlyArray<string> = ["content-type", "accept", "openai-beta"]
+export const DEFAULT_RESPONSE_HEADERS: ReadonlyArray<string> = ["content-type"]
+
+const identity = <T>(value: T) => value
+
+export interface Redactor {
+  readonly request: (snapshot: RequestSnapshot) => RequestSnapshot
+  readonly response: (snapshot: ResponseSnapshot) => ResponseSnapshot
+}
+
+export const compose = (...redactors: ReadonlyArray<Partial<Redactor>>): Redactor => {
+  const requests = redactors.map((r) => r.request).filter((fn): fn is Redactor["request"] => fn !== undefined)
+  const responses = redactors.map((r) => r.response).filter((fn): fn is Redactor["response"] => fn !== undefined)
+  return {
+    request: requests.length === 0 ? identity : (snapshot) => requests.reduce((acc, fn) => fn(acc), snapshot),
+    response: responses.length === 0 ? identity : (snapshot) => responses.reduce((acc, fn) => fn(acc), snapshot),
+  }
+}
+
+export interface HeaderOptions {
+  readonly allow?: ReadonlyArray<string>
+  readonly redact?: ReadonlyArray<string>
+}
+
+export const requestHeaders = (options: HeaderOptions = {}): Partial<Redactor> => ({
+  request: (snapshot) => ({
+    ...snapshot,
+    headers: redactHeaders(snapshot.headers, options.allow ?? DEFAULT_REQUEST_HEADERS, options.redact),
+  }),
+})
+
+export const responseHeaders = (options: HeaderOptions = {}): Partial<Redactor> => ({
+  response: (snapshot) => ({
+    ...snapshot,
+    headers: redactHeaders(snapshot.headers, options.allow ?? DEFAULT_RESPONSE_HEADERS, options.redact),
+  }),
+})
+
+export interface UrlOptions {
+  readonly query?: ReadonlyArray<string>
+  readonly transform?: (url: string) => string
+}
+
+export const url = (options: UrlOptions = {}): Partial<Redactor> => ({
+  request: (snapshot) => ({ ...snapshot, url: redactUrl(snapshot.url, options.query, options.transform) }),
+})
+
+export const body = (transform: (parsed: unknown) => unknown): Partial<Redactor> => ({
+  request: (snapshot) => ({
+    ...snapshot,
+    body: Option.match(decodeJson(snapshot.body), {
+      onNone: () => snapshot.body,
+      onSome: (parsed) => JSON.stringify(transform(parsed)),
+    }),
+  }),
+})
+
+export interface DefaultRedactorOverrides {
+  readonly requestHeaders?: HeaderOptions
+  readonly responseHeaders?: HeaderOptions
+  readonly url?: UrlOptions
+  readonly body?: (parsed: unknown) => unknown
+}
+
+const DEFAULT_REDACT_JSON_FIELDS = [
+  "access_token",
+  "api_key",
+  "apikey",
+  "client_secret",
+  "password",
+  "refresh_token",
+  "secret",
+  "token",
+]
+
+const normalizeField = (field: string) => field.replace(/[^a-z0-9]/gi, "").toLowerCase()
+
+const redactJsonFields = (value: unknown, fields: ReadonlySet<string>): unknown => {
+  if (Array.isArray(value)) return value.map((item) => redactJsonFields(item, fields))
+  if (!value || typeof value !== "object") return value
+  return Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [
+      key,
+      fields.has(normalizeField(key)) ? REDACTED : redactJsonFields(child, fields),
+    ]),
+  )
+}
+
+const redactBody = (value: string, fields: ReadonlySet<string>, transform: ((body: string) => string) | undefined) => {
+  const redacted = Option.match(decodeJson(value), {
+    onNone: () => value,
+    onSome: (parsed) => JSON.stringify(redactJsonFields(parsed, fields)),
+  })
+  return transform?.(redacted) ?? redacted
+}
+
+export const make = (options: RedactOptions = {}): Redactor => {
+  const fields = new Set([...DEFAULT_REDACT_JSON_FIELDS, ...(options.jsonFields ?? [])].map(normalizeField))
+  return compose(
+    requestHeaders({
+      allow: [...DEFAULT_REQUEST_HEADERS, ...(options.allowRequestHeaders ?? []), ...(options.headers ?? [])],
+      redact: options.headers,
+    }),
+    responseHeaders({
+      allow: [...DEFAULT_RESPONSE_HEADERS, ...(options.allowResponseHeaders ?? []), ...(options.headers ?? [])],
+      redact: options.headers,
+    }),
+    url({ query: options.queryParameters, transform: options.url }),
+    {
+      request: (snapshot) => ({
+        ...snapshot,
+        body: redactBody(snapshot.body, fields, options.body),
+      }),
+      response: (snapshot) => ({
+        ...snapshot,
+        body: redactBody(snapshot.body, fields, options.body),
+      }),
+    },
+  )
+}
+
+export const defaults = (overrides: DefaultRedactorOverrides = {}): Redactor =>
+  compose(
+    requestHeaders(overrides.requestHeaders),
+    responseHeaders(overrides.responseHeaders),
+    url(overrides.url),
+    ...(overrides.body ? [body(overrides.body)] : []),
+  )

package/src/schema.ts

@@ -0,0 +1,87 @@
+import { Schema } from "effect"
+import type {
+  CassetteMetadata,
+  HttpInteraction,
+  RequestSnapshot,
+  ResponseSnapshot,
+  WebSocketEvent,
+  WebSocketInteraction,
+} from "./types.js"
+
+export type {
+  CassetteMetadata,
+  HttpInteraction,
+  RequestSnapshot,
+  ResponseSnapshot,
+  WebSocketEvent,
+  WebSocketInteraction,
+} from "./types.js"
+
+export const RequestSnapshotSchema = Schema.Struct({
+  method: Schema.String,
+  url: Schema.String,
+  headers: Schema.Record(Schema.String, Schema.String),
+  body: Schema.String,
+})
+
+export const ResponseSnapshotSchema = Schema.Struct({
+  status: Schema.Number,
+  headers: Schema.Record(Schema.String, Schema.String),
+  body: Schema.String,
+  bodyEncoding: Schema.optional(Schema.Literals(["text", "base64"])),
+})
+
+export const CassetteMetadataSchema = Schema.Record(Schema.String, Schema.Unknown)
+
+export const HttpInteractionSchema = Schema.Struct({
+  transport: Schema.tag("http"),
+  request: RequestSnapshotSchema,
+  response: ResponseSnapshotSchema,
+})
+
+export const WebSocketEventSchema = Schema.Union([
+  Schema.Struct({
+    direction: Schema.Literals(["client", "server"]),
+    kind: Schema.tag("text"),
+    body: Schema.String,
+  }),
+  Schema.Struct({
+    direction: Schema.Literals(["client", "server"]),
+    kind: Schema.tag("binary"),
+    body: Schema.String,
+    bodyEncoding: Schema.Literal("base64"),
+  }),
+])
+
+export const WebSocketInteractionSchema = Schema.Struct({
+  transport: Schema.tag("websocket"),
+  open: Schema.Struct({
+    url: Schema.String,
+    headers: Schema.Record(Schema.String, Schema.String),
+  }),
+  events: Schema.Array(WebSocketEventSchema),
+})
+
+export const InteractionSchema = Schema.Union([HttpInteractionSchema, WebSocketInteractionSchema]).pipe(
+  Schema.toTaggedUnion("transport"),
+)
+export type Interaction = Schema.Schema.Type<typeof InteractionSchema>
+
+export const isHttpInteraction = InteractionSchema.guards.http
+
+export const isWebSocketInteraction = InteractionSchema.guards.websocket
+
+export const httpInteractions = (interactions: ReadonlyArray<Interaction>) => interactions.filter(isHttpInteraction)
+
+export const webSocketInteractions = (interactions: ReadonlyArray<Interaction>) =>
+  interactions.filter(isWebSocketInteraction)
+
+export const CassetteSchema = Schema.Struct({
+  version: Schema.Literal(1),
+  metadata: Schema.optional(CassetteMetadataSchema),
+  interactions: Schema.Array(InteractionSchema),
+})
+export type Cassette = Schema.Schema.Type<typeof CassetteSchema>
+
+export const decodeCassette = Schema.decodeUnknownSync(CassetteSchema)
+export const encodeCassette = Schema.encodeSync(CassetteSchema)

package/src/socket.ts

@@ -0,0 +1,326 @@
+import { NodeFileSystem } from "@effect/platform-node"
+import { Deferred, Effect, Exit, FiberSet, Layer, Ref, Scope, Semaphore } from "effect"
+import { Socket } from "effect/unstable/socket"
+import * as CassetteService from "./cassette.js"
+import { canonicalizeJson, decodeJson, safeText } from "./matching.js"
+import { makeReplayState, resolveAutoMode } from "./recorder.js"
+import { make, type Redactor } from "./redactor.js"
+import { webSocketInteractions } from "./schema.js"
+import type {
+  RecorderOptions,
+  WebSocketEvent,
+  WebSocketInteraction,
+  WebSocketRecorderOptions,
+  WebSocketRequest,
+} from "./types.js"
+
+interface ActiveReplay {
+  readonly interaction: WebSocketInteraction
+  readonly progress: Ref.Ref<{ readonly position: number; readonly changed: Deferred.Deferred<void> }>
+  readonly writeLock: Semaphore.Semaphore
+  readonly closed: Ref.Ref<boolean>
+}
+
+interface ActiveRecording {
+  readonly events: Array<WebSocketEvent>
+  readonly eventLock: Semaphore.Semaphore
+  readonly accepting: Ref.Ref<boolean>
+  opened: boolean
+  valid: boolean
+}
+
+type Frame = string | Uint8Array
+
+const encodeEvent = (direction: "client" | "server", message: Frame): WebSocketEvent =>
+  typeof message === "string"
+    ? { direction, kind: "text", body: message }
+    : { direction, kind: "binary", body: Buffer.from(message).toString("base64"), bodyEncoding: "base64" }
+
+const decodeEvent = (event: WebSocketEvent): Frame =>
+  event.kind === "text" ? event.body : new Uint8Array(Buffer.from(event.body, "base64"))
+
+const redactEvent = (event: WebSocketEvent, redactor: Redactor): WebSocketEvent => {
+  if (event.kind === "binary") return event
+  const body =
+    event.direction === "client"
+      ? redactor.request({ method: "WEBSOCKET", url: "", headers: {}, body: event.body }).body
+      : redactor.response({ status: 101, headers: {}, body: event.body }).body
+  return { ...event, body }
+}
+
+const comparable = (event: WebSocketEvent, asJson: boolean) => {
+  if (!asJson || event.kind === "binary") return JSON.stringify(canonicalizeJson(event))
+  const decoded = decodeJson(event.body)
+  return JSON.stringify(
+    canonicalizeJson({
+      ...event,
+      body: decoded._tag === "None" ? event.body : canonicalizeJson(decoded.value),
+    }),
+  )
+}
+
+const assertEvent = (actual: WebSocketEvent, expected: WebSocketEvent | undefined, index: number, asJson: boolean) =>
+  Effect.sync(() => {
+    if (expected && comparable(actual, asJson) === comparable(expected, asJson)) return
+    throw new Error(`WebSocket event ${index + 1}: expected ${safeText(expected)}, received ${safeText(actual)}`)
+  })
+
+const runHandler = <A, E, R>(handler: (value: A) => Effect.Effect<unknown, E, R> | void, value: A) =>
+  Effect.suspend(() => {
+    const result = handler(value)
+    return Effect.isEffect(result) ? Effect.asVoid(result) : Effect.void
+  })
+
+const runReplay = <A, E, R>(
+  state: ActiveReplay,
+  handler: (value: A) => Effect.Effect<unknown, E, R> | void,
+  decode: (event: WebSocketEvent) => A,
+  onOpen: Effect.Effect<void> | undefined,
+) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const handlers = yield* FiberSet.make<unknown, E>()
+      const run = yield* FiberSet.runtime(handlers)<R>()
+      if (onOpen) yield* onOpen
+
+      const drive = Effect.gen(function* () {
+        while (true) {
+          const current = yield* Ref.get(state.progress)
+          const event = state.interaction.events[current.position]
+          if (!event) return
+          if (yield* Ref.get(state.closed))
+            return yield* Effect.die(
+              new Error(
+                `WebSocket closed with unconsumed events: used ${current.position} of ${state.interaction.events.length}`,
+              ),
+            )
+          if (event.direction === "server") {
+            yield* Ref.set(state.progress, {
+              position: current.position + 1,
+              changed: yield* Deferred.make<void>(),
+            })
+            run(runHandler(handler, decode(event)))
+            continue
+          }
+          yield* Deferred.await(current.changed)
+        }
+      })
+
+      yield* drive.pipe(Effect.raceFirst(FiberSet.join(handlers)))
+      yield* FiberSet.awaitEmpty(handlers).pipe(Effect.raceFirst(FiberSet.join(handlers)))
+    }),
+  )
+
+const openSnapshot = (request: WebSocketRequest, redactor: Redactor) => {
+  const snapshot = redactor.request({ method: "GET", url: request.url, headers: request.headers ?? {}, body: "" })
+  return { url: snapshot.url, headers: snapshot.headers }
+}
+
+const makeRecordingSocket = (
+  upstream: Socket.Socket,
+  cassette: CassetteService.Interface,
+  name: string,
+  request: WebSocketRequest,
+  options: WebSocketRecorderOptions,
+  redactor: Redactor,
+) =>
+  Effect.gen(function* () {
+    const active = yield* Ref.make<ActiveRecording | undefined>(undefined)
+    const writeLock = yield* Semaphore.make(1)
+
+    return Socket.make({
+      runRaw: (handler, runOptions) =>
+        Effect.gen(function* () {
+          const state: ActiveRecording = {
+            events: [],
+            eventLock: yield* Semaphore.make(1),
+            accepting: yield* Ref.make(true),
+            opened: false,
+            valid: true,
+          }
+          const occupied = yield* Ref.modify(active, (current) => [current !== undefined, current ?? state])
+          if (occupied) return yield* Effect.die("Concurrent runs of a recorded WebSocket are not supported")
+          yield* upstream
+            .runRaw(
+              (message) => {
+                if (!Ref.getUnsafe(state.accepting)) throw new Error("WebSocket received a frame after closing")
+                state.events.push(redactEvent(encodeEvent("server", message), redactor))
+                return handler(message)
+              },
+              {
+                ...runOptions,
+                onOpen: Effect.gen(function* () {
+                  state.opened = true
+                  if (runOptions?.onOpen) yield* runOptions.onOpen
+                }),
+              },
+            )
+            .pipe(
+              Effect.onExit((exit) =>
+                writeLock.withPermit(
+                  state.eventLock.withPermit(
+                    Effect.gen(function* () {
+                      yield* Ref.set(state.accepting, false)
+                      yield* Ref.set(active, undefined)
+                      if (!Exit.isSuccess(exit) || !state.opened || !state.valid) return
+                      yield* cassette
+                        .append(
+                          name,
+                          {
+                            transport: "websocket",
+                            open: openSnapshot(request, redactor),
+                            events: [...state.events],
+                          },
+                          options.metadata,
+                        )
+                        .pipe(Effect.orDie)
+                    }),
+                  ),
+                ),
+              ),
+            )
+        }),
+      writer: upstream.writer.pipe(
+        Effect.map(
+          (write) => (message) =>
+            writeLock.withPermit(
+              Effect.gen(function* () {
+                if (Socket.isCloseEvent(message)) return yield* write(message)
+                const state = yield* Ref.get(active)
+                if (!state || !(yield* Ref.get(state.accepting)))
+                  return yield* Effect.die("WebSocket writer used without an active socket run")
+                const event = redactEvent(encodeEvent("client", message), redactor)
+                yield* state.eventLock.withPermit(Effect.sync(() => state.events.push(event)))
+                return yield* write(message).pipe(Effect.onError(() => Effect.sync(() => (state.valid = false))))
+              }),
+            ),
+        ),
+      ),
+    })
+  })
+
+const makeReplaySocket = (
+  cassette: CassetteService.Interface,
+  name: string,
+  request: WebSocketRequest,
+  options: WebSocketRecorderOptions,
+  redactor: Redactor,
+): Effect.Effect<Socket.Socket, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const replay = yield* makeReplayState(cassette, name, webSocketInteractions)
+    const active = yield* Ref.make<ActiveReplay | undefined>(undefined)
+
+    return Socket.make({
+      runRaw: (handler, runOptions) =>
+        Effect.gen(function* () {
+          const claimed = yield* replay
+            .claim((interaction, index) =>
+              Effect.sync(() => {
+                const incoming = openSnapshot(request, redactor)
+                if (
+                  interaction &&
+                  JSON.stringify(canonicalizeJson(incoming)) === JSON.stringify(canonicalizeJson(interaction.open))
+                )
+                  return
+                throw new Error(
+                  `WebSocket open ${index + 1}: expected ${safeText(interaction?.open)}, received ${safeText(incoming)}`,
+                )
+              }),
+            )
+            .pipe(Effect.orDie)
+          const progress = yield* Ref.make({ position: 0, changed: yield* Deferred.make<void>() })
+          const writeLock = yield* Semaphore.make(1)
+          const state = {
+            interaction: claimed.interaction,
+            progress,
+            writeLock,
+            closed: yield* Ref.make(false),
+          }
+          const occupied = yield* Ref.modify(active, (current) => [current !== undefined, current ?? state])
+          if (occupied) return yield* Effect.die("Concurrent runs of a replayed WebSocket are not supported")
+          yield* runReplay(state, handler, decodeEvent, runOptions?.onOpen).pipe(
+            Effect.ensuring(Ref.set(active, undefined)),
+          )
+        }),
+      writer: Effect.succeed((message) => {
+        return Ref.get(active).pipe(
+          Effect.flatMap((state) =>
+            state
+              ? state.writeLock.withPermit(
+                  Effect.gen(function* () {
+                    const current = yield* Ref.get(state.progress)
+                    if (Socket.isCloseEvent(message)) {
+                      yield* Ref.set(state.closed, true)
+                      yield* Deferred.succeed(current.changed, undefined)
+                      if (current.position === state.interaction.events.length) return
+                      return yield* Effect.die(
+                        new Error(
+                          `WebSocket closed with unconsumed events: used ${current.position} of ${state.interaction.events.length}`,
+                        ),
+                      )
+                    }
+                    const actual = redactEvent(encodeEvent("client", message), redactor)
+                    yield* assertEvent(
+                      actual,
+                      state.interaction.events[current.position],
+                      current.position,
+                      options.compareClientMessagesAsJson === true,
+                    )
+                    yield* Ref.set(state.progress, {
+                      position: current.position + 1,
+                      changed: yield* Deferred.make<void>(),
+                    })
+                    yield* Deferred.succeed(current.changed, undefined)
+                  }),
+                )
+              : Effect.die("WebSocket writer used without an active socket run"),
+          ),
+        )
+      }),
+    })
+  })
+
+const recordingLayer = (
+  name: string,
+  request: WebSocketRequest,
+  options: WebSocketRecorderOptions,
+  forcedMode?: "record" | "replay",
+): Layer.Layer<Socket.Socket, never, Socket.Socket | CassetteService.Service> =>
+  Layer.effect(
+    Socket.Socket,
+    Effect.gen(function* () {
+      const upstream = yield* Socket.Socket
+      const cassette = yield* CassetteService.Service
+      const redactor = make(options.redact)
+      if ((forcedMode ?? (yield* resolveAutoMode(cassette, name))) === "record")
+        return yield* makeRecordingSocket(upstream, cassette, name, request, options, redactor)
+      return yield* makeReplaySocket(cassette, name, request, options, redactor)
+    }),
+  )
+
+/**
+ * Wraps a provided `Socket.Socket` with cassette recording and replay.
+ *
+ * Supply the ordinary URL-bound Effect socket layer beneath this decorator.
+ * The cassette name identifies the connection; recorder configuration does not
+ * duplicate the transport URL.
+ */
+export const socket = (name: string, options: RecorderOptions = {}): Layer.Layer<Socket.Socket, never, Socket.Socket> =>
+  provideCassette(recordingLayer(name, { url: "" }, { ...options, compareClientMessagesAsJson: true }), options)
+
+/** @internal */
+export const socketLayer = (
+  name: string,
+  request: WebSocketRequest,
+  options: WebSocketRecorderOptions & { readonly mode: "record" | "replay" },
+): Layer.Layer<Socket.Socket, never, Socket.Socket> =>
+  provideCassette(recordingLayer(name, request, options, options.mode), options)
+
+const provideCassette = (
+  layer: Layer.Layer<Socket.Socket, never, Socket.Socket | CassetteService.Service>,
+  options: WebSocketRecorderOptions,
+) =>
+  layer.pipe(
+    Layer.provide(CassetteService.fileSystem({ directory: options.directory })),
+    Layer.provide(NodeFileSystem.layer),
+  )