ceos/opencode
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(http-recorder): prepare public beta release (#31018)

Browse source
This commit is contained in:
Kit Langton 2026-06-05 23:01:26 -04:00 • committed by GitHub
commit 54f4974546
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
36 changed files with 2254 additions and 690 deletions
Download patch file Download diff file Expand all files Collapse all files

97
packages/http-recorder/src/cassette.ts
View file

@ -1,8 +1,8 @@
import { Context, Effect, FileSystem, Layer, Schema } from "effect"
import { Context, Effect, FileSystem, Layer, Schema, Semaphore } from "effect"
import * as fs from "node:fs"
import * as path from "node:path"
import { secretFindings, SecretFindingSchema, type SecretFinding } from "./redaction"
import { decodeCassette, encodeCassette, type Cassette, type CassetteMetadata, type Interaction } from "./schema"
import { secretFindings, SecretFindingSchema, type SecretFinding } from "./redaction.js"
import { CassetteSchema, encodeCassette, type Cassette, type CassetteMetadata, type Interaction } from "./schema.js"
const DEFAULT_RECORDINGS_DIR = path.resolve(process.cwd(), "test", "fixtures", "recordings")
@ -38,8 +38,19 @@ export interface Interface {
export class Service extends Context.Service<Service, Interface>()("@opencode-ai/http-recorder/Cassette") {}
const cassettePath = (directory: string, name: string) => {
if (!name || path.isAbsolute(name) || path.win32.isAbsolute(name) || name.split(/[\\/]/).includes(".."))
throw new Error(`Invalid cassette name "${name}"`)
const root = path.resolve(directory)
const target = path.resolve(root, `${name}.json`)
const relative = path.relative(root, target)
if (!relative || relative.startsWith("..") || path.isAbsolute(relative))
throw new Error(`Invalid cassette name "${name}"`)
return target
}
export const hasCassetteSync = (name: string, options: { readonly directory?: string } = {}) =>
fs.existsSync(path.join(options.directory ?? DEFAULT_RECORDINGS_DIR, `${name}.json`))
fs.existsSync(cassettePath(options.directory ?? DEFAULT_RECORDINGS_DIR, name))
const buildCassette = (
name: string,
@ -47,13 +58,13 @@ const buildCassette = (
metadata: CassetteMetadata | undefined,
): Cassette => ({
version: 1,
metadata: { name, recordedAt: new Date().toISOString(), ...(metadata ?? {}) },
metadata: { name, recordedAt: new Date().toISOString(), ...metadata },
interactions,
})
const formatCassette = (cassette: Cassette) => `${JSON.stringify(encodeCassette(cassette), null, 2)}\n`
const parseCassette = (raw: string) => decodeCassette(JSON.parse(raw))
const parseCassette = Schema.decodeUnknownSync(Schema.fromJsonString(CassetteSchema))
const failIfUnsafe = (name: string, findings: ReadonlyArray<SecretFinding>) =>
findings.length === 0 ? Effect.void : Effect.fail(new UnsafeCassetteError({ cassetteName: name, findings }))
@ -67,17 +78,9 @@ export const fileSystem = (
const fs = yield* FileSystem.FileSystem
const directory = options.directory ?? DEFAULT_RECORDINGS_DIR
const recorded = new Map<string, { interactions: Interaction[]; findings: SecretFinding[] }>()
const directoriesEnsured = new Set<string>()
const appendLock = yield* Semaphore.make(1)
const cassettePath = (name: string) => path.join(directory, `${name}.json`)
const ensureDirectory = (name: string) =>
Effect.gen(function* () {
const dir = path.dirname(cassettePath(name))
if (directoriesEnsured.has(dir)) return
yield* fs.makeDirectory(dir, { recursive: true }).pipe(Effect.orDie)
directoriesEnsured.add(dir)
})
const pathFor = (name: string) => cassettePath(directory, name)
const walk = (current: string): Effect.Effect<ReadonlyArray<string>> =>
Effect.gen(function* () {
@ -94,24 +97,32 @@ export const fileSystem = (
return Service.of({
read: (name) =>
fs.readFileString(cassettePath(name)).pipe(
fs.readFileString(pathFor(name)).pipe(
Effect.map((raw) => parseCassette(raw).interactions),
Effect.catch(() => Effect.fail(new CassetteNotFoundError({ cassetteName: name }))),
),
append: (name, interaction, metadata) =>
Effect.gen(function* () {
const entry = recorded.get(name) ?? { interactions: [], findings: [] }
if (!recorded.has(name)) recorded.set(name, entry)
entry.interactions.push(interaction)
entry.findings.push(...secretFindings(interaction))
const cassette = buildCassette(name, entry.interactions, metadata)
const findings = [...entry.findings, ...secretFindings(cassette.metadata ?? {})]
yield* failIfUnsafe(name, findings)
yield* ensureDirectory(name)
yield* fs.writeFileString(cassettePath(name), formatCassette(cassette)).pipe(Effect.orDie)
}),
appendLock.withPermit(
Effect.gen(function* () {
const entry = recorded.get(name) ?? { interactions: [], findings: [] }
const interactions = [...entry.interactions, interaction]
const interactionFindings = [...entry.findings, ...secretFindings(interaction)]
const cassette = buildCassette(name, interactions, metadata)
const findings = [...interactionFindings, ...secretFindings(cassette.metadata ?? {})]
yield* failIfUnsafe(name, findings)
const target = pathFor(name)
yield* fs.makeDirectory(path.dirname(target), { recursive: true }).pipe(Effect.orDie)
const temporary = `${target}.${crypto.randomUUID()}.tmp`
yield* fs.writeFileString(temporary, formatCassette(cassette)).pipe(
Effect.flatMap(() => fs.rename(temporary, target)),
Effect.ensuring(fs.remove(temporary, { force: true }).pipe(Effect.catch(() => Effect.void))),
Effect.orDie,
)
recorded.set(name, { interactions, findings: interactionFindings })
}),
),
exists: (name) =>
fs.access(cassettePath(name)).pipe(
fs.access(pathFor(name)).pipe(
Effect.as(true),
Effect.catch(() => Effect.succeed(false)),
),
@ -139,23 +150,29 @@ export const memory = (initial: Record<string, ReadonlyArray<Interaction>> = {})
Object.entries(initial).map(([name, interactions]) => [name, [...interactions]]),
)
const accumulatedFindings = new Map<string, SecretFinding[]>()
const appendLock = Semaphore.makeUnsafe(1)
return Service.of({
read: (name) =>
stored.has(name)
? Effect.succeed(stored.get(name) ?? [])
: Effect.fail(new CassetteNotFoundError({ cassetteName: name })),
append: (name, interaction, metadata) => {
const existing = stored.get(name)
if (existing) existing.push(interaction)
else stored.set(name, [interaction])
const existingFindings = accumulatedFindings.get(name)
const findings = existingFindings ?? []
if (!existingFindings) accumulatedFindings.set(name, findings)
findings.push(...secretFindings(interaction))
if (metadata) findings.push(...secretFindings({ name, ...metadata }))
return failIfUnsafe(name, findings)
},
append: (name, interaction, metadata) =>
appendLock.withPermit(
Effect.suspend(() => {
const interactions = [...(stored.get(name) ?? []), interaction]
const findings = [...(accumulatedFindings.get(name) ?? []), ...secretFindings(interaction)]
const allFindings = metadata ? [...findings, ...secretFindings({ name, ...metadata })] : findings
return failIfUnsafe(name, allFindings).pipe(
Effect.tap(() =>
Effect.sync(() => {
stored.set(name, interactions)
accumulatedFindings.set(name, findings)
}),
),
)
}),
),
exists: (name) => Effect.sync(() => stored.has(name)),
list: () => Effect.sync(() => Array.from(stored.keys()).toSorted()),
})

155
packages/http-recorder/src/effect.ts
View file

@ -1,141 +1,24 @@
import { NodeFileSystem } from "@effect/platform-node"
import { Effect, Layer, Option } from "effect"
import {
FetchHttpClient,
Headers,
HttpBody,
HttpClient,
HttpClientError,
HttpClientRequest,
HttpClientResponse,
UrlParams,
} from "effect/unstable/http"
import * as CassetteService from "./cassette"
import { defaultMatcher, selectSequential, type RequestMatcher } from "./matching"
import { makeReplayState, resolveAutoMode } from "./recorder"
import { defaults, type Redactor } from "./redactor"
import { redactUrl } from "./redaction"
import { httpInteractions, type CassetteMetadata, type HttpInteraction, type ResponseSnapshot } from "./schema"
import * as Layer from "effect/Layer"
import { FetchHttpClient } from "effect/unstable/http"
import type * as HttpClient from "effect/unstable/http/HttpClient"
import * as CassetteService from "./cassette.js"
import { recordingLayer } from "./internal-effect.js"
import { make } from "./redactor.js"
import type { RecorderOptions } from "./types.js"
export type RecordReplayMode = "auto" | "record" | "replay" | "passthrough"
export interface RecordReplayOptions {
readonly mode?: RecordReplayMode
readonly directory?: string
readonly metadata?: CassetteMetadata
readonly redactor?: Redactor
readonly match?: RequestMatcher
}
const BINARY_CONTENT_TYPES: ReadonlyArray<string> = ["vnd.amazon.eventstream", "octet-stream"]
const isBinaryContentType = (contentType: string | undefined) =>
contentType !== undefined && BINARY_CONTENT_TYPES.some((token) => contentType.toLowerCase().includes(token))
const captureResponseBody = (response: HttpClientResponse.HttpClientResponse, contentType: string | undefined) =>
isBinaryContentType(contentType)
? response.arrayBuffer.pipe(
Effect.map((bytes) => ({ body: Buffer.from(bytes).toString("base64"), bodyEncoding: "base64" as const })),
)
: response.text.pipe(Effect.map((body) => ({ body })))
const decodeResponseBody = (snapshot: ResponseSnapshot) =>
snapshot.bodyEncoding === "base64" ? Buffer.from(snapshot.body, "base64") : snapshot.body
export const redactedErrorRequest = (request: HttpClientRequest.HttpClientRequest) =>
HttpClientRequest.makeWith(
request.method,
redactUrl(request.url),
UrlParams.empty,
Option.none(),
Headers.empty,
HttpBody.empty,
)
const transportError = (request: HttpClientRequest.HttpClientRequest, description: string) =>
new HttpClientError.HttpClientError({
reason: new HttpClientError.TransportError({ request: redactedErrorRequest(request), description }),
})
export const recordingLayer = (
name: string,
options: Omit<RecordReplayOptions, "directory"> = {},
): Layer.Layer<HttpClient.HttpClient, never, HttpClient.HttpClient | CassetteService.Service> =>
Layer.effect(
HttpClient.HttpClient,
Effect.gen(function* () {
const upstream = yield* HttpClient.HttpClient
const cassetteService = yield* CassetteService.Service
const redactor = options.redactor ?? defaults()
const match = options.match ?? defaultMatcher
const requested = options.mode ?? "auto"
const mode = requested === "auto" ? yield* resolveAutoMode(cassetteService, name) : requested
const replay = yield* makeReplayState(cassetteService, name, httpInteractions)
const snapshotRequest = (request: HttpClientRequest.HttpClientRequest) =>
Effect.gen(function* () {
const web = yield* HttpClientRequest.toWeb(request).pipe(Effect.orDie)
return redactor.request({
method: web.method,
url: web.url,
headers: Object.fromEntries(web.headers.entries()),
body: yield* Effect.promise(() => web.text()),
})
})
return HttpClient.make((request) => {
if (mode === "passthrough") return upstream.execute(request)
if (mode === "record") {
return Effect.gen(function* () {
const incoming = yield* snapshotRequest(request)
const response = yield* upstream.execute(request)
const captured = yield* captureResponseBody(response, response.headers["content-type"])
const interaction: HttpInteraction = {
transport: "http",
request: incoming,
response: redactor.response({
status: response.status,
headers: response.headers as Record<string, string>,
...captured,
}),
}
yield* cassetteService
.append(name, interaction, options.metadata)
.pipe(
Effect.catchTag("UnsafeCassetteError", (error) => Effect.fail(transportError(request, error.message))),
)
return HttpClientResponse.fromWeb(
request,
new Response(decodeResponseBody(interaction.response), interaction.response),
)
})
}
return Effect.gen(function* () {
const incoming = yield* snapshotRequest(request)
const interactions = yield* replay.load.pipe(
Effect.mapError(() =>
transportError(request, `Fixture "${name}" not found. Run locally to record it (CI=true forces replay).`),
),
)
const result = selectSequential(interactions, incoming, match, yield* replay.cursor)
if (!result.interaction)
return yield* Effect.fail(
transportError(request, `Fixture "${name}" does not match the current request: ${result.detail}.`),
)
yield* replay.advance
return HttpClientResponse.fromWeb(
request,
new Response(decodeResponseBody(result.interaction.response), result.interaction.response),
)
})
})
}),
)
export const cassetteLayer = (name: string, options: RecordReplayOptions = {}): Layer.Layer<HttpClient.HttpClient> =>
recordingLayer(name, options).pipe(
/**
* Provides a fetch-backed `HttpClient` with cassette recording and replay.
*
* Locally, a missing cassette is recorded from the real service. Existing
* cassettes are replayed, and `CI=true` makes a missing cassette fail.
*/
export const http = (name: string, options: RecorderOptions = {}): Layer.Layer<HttpClient.HttpClient> =>
recordingLayer(name, {
metadata: options.metadata,
redactor: make(options.redact),
match: options.match,
}).pipe(
Layer.provide(CassetteService.fileSystem({ directory: options.directory })),
Layer.provide(FetchHttpClient.layer),
Layer.provide(NodeFileSystem.layer),

39
packages/http-recorder/src/index.ts
View file

@ -1,25 +1,18 @@
export type {
CassetteMetadata,
HttpInteraction,
Interaction,
RequestSnapshot,
ResponseSnapshot,
WebSocketFrame,
WebSocketInteraction,
} from "./schema"
export { CassetteNotFoundError, hasCassetteSync, UnsafeCassetteError } from "./cassette"
export { defaultMatcher, type RequestMatcher } from "./matching"
export { redactHeaders, redactUrl, secretFindings, type SecretFinding } from "./redaction"
export { cassetteLayer, recordingLayer, type RecordReplayMode, type RecordReplayOptions } from "./effect"
export {
makeWebSocketExecutor,
type WebSocketConnection,
type WebSocketExecutor,
type WebSocketRecordReplayOptions,
type WebSocketRequest,
} from "./websocket"
import { http } from "./effect.js"
import { socket } from "./socket.js"
export * as Cassette from "./cassette"
export * as Redactor from "./redactor"
/** HTTP and WebSocket cassette recording. */
export const HttpRecorder = { http, socket } as const
export * as HttpRecorder from "."
export namespace HttpRecorder {
/** Additional JSON metadata stored with a cassette. */
export type CassetteMetadata = import("./types.js").CassetteMetadata
/** Recorder configuration. */
export type RecorderOptions = import("./types.js").RecorderOptions
/** Additive redaction and header-preservation policy. */
export type RedactOptions = import("./types.js").RedactOptions
/** Returns whether an incoming HTTP request matches a recorded request. */
export type RequestMatcher = import("./types.js").RequestMatcher
/** The normalized HTTP request representation used for matching. */
export type RequestSnapshot = import("./types.js").RequestSnapshot
}

189
packages/http-recorder/src/internal-effect.ts Normal file
View file

@ -0,0 +1,189 @@
import { NodeFileSystem } from "@effect/platform-node"
import { Deferred, Effect, Layer, Option, Ref } from "effect"
import {
FetchHttpClient,
Headers,
HttpBody,
HttpClient,
HttpClientError,
HttpClientRequest,
HttpClientResponse,
UrlParams,
} from "effect/unstable/http"
import * as CassetteService from "./cassette.js"
import { defaultMatcher, selectSequential } from "./matching.js"
import { makeReplayState, resolveAutoMode } from "./recorder.js"
import { make, type Redactor } from "./redactor.js"
import { redactUrl } from "./redaction.js"
import { httpInteractions } from "./schema.js"
import type { CassetteMetadata, HttpInteraction, RequestMatcher, ResponseSnapshot } from "./types.js"
export { defaultMatcher }
export type RecordReplayMode = "auto" | "record" | "replay" | "passthrough"
export interface RecordReplayOptions {
readonly mode?: RecordReplayMode
readonly directory?: string
readonly metadata?: CassetteMetadata
readonly redactor?: Redactor
readonly match?: RequestMatcher
}
const TEXT_CONTENT_TYPES = new Set([
"application/graphql",
"application/javascript",
"application/json",
"application/sql",
"application/x-www-form-urlencoded",
"application/xml",
"application/yaml",
"image/svg+xml",
])
const isTextContentType = (contentType: string | undefined) => {
const mediaType = contentType?.split(";", 1)[0]?.trim().toLowerCase()
if (!mediaType) return false
return (
mediaType.startsWith("text/") ||
mediaType.endsWith("+json") ||
mediaType.endsWith("+xml") ||
TEXT_CONTENT_TYPES.has(mediaType)
)
}
const captureResponseBody = (response: HttpClientResponse.HttpClientResponse, contentType: string | undefined) =>
response.arrayBuffer.pipe(
Effect.map((bytes) =>
isTextContentType(contentType)
? { body: new TextDecoder().decode(bytes) }
: { body: Buffer.from(bytes).toString("base64"), bodyEncoding: "base64" as const },
),
)
const decodeResponseBody = (snapshot: ResponseSnapshot) =>
snapshot.bodyEncoding === "base64" ? Buffer.from(snapshot.body, "base64") : snapshot.body
const responseFromSnapshot = (request: HttpClientRequest.HttpClientRequest, snapshot: ResponseSnapshot) =>
HttpClientResponse.fromWeb(
request,
new Response(
request.method === "HEAD" || snapshot.status === 204 || snapshot.status === 205 || snapshot.status === 304
? null
: decodeResponseBody(snapshot),
snapshot,
),
)
export const redactedErrorRequest = (request: HttpClientRequest.HttpClientRequest) =>
HttpClientRequest.makeWith(
request.method,
redactUrl(request.url),
UrlParams.empty,
Option.none(),
Headers.empty,
HttpBody.empty,
)
const transportError = (request: HttpClientRequest.HttpClientRequest, description: string) =>
new HttpClientError.HttpClientError({
reason: new HttpClientError.TransportError({ request: redactedErrorRequest(request), description }),
})
export const recordingLayer = (
name: string,
options: Omit<RecordReplayOptions, "directory"> = {},
): Layer.Layer<HttpClient.HttpClient, never, HttpClient.HttpClient | CassetteService.Service> =>
Layer.effect(
HttpClient.HttpClient,
Effect.gen(function* () {
const upstream = yield* HttpClient.HttpClient
const cassetteService = yield* CassetteService.Service
const redactor = options.redactor ?? make()
const match = options.match ?? defaultMatcher
const requested = options.mode ?? "auto"
const mode = requested === "auto" ? yield* resolveAutoMode(cassetteService, name) : requested
const snapshotRequest = (request: HttpClientRequest.HttpClientRequest) =>
Effect.gen(function* () {
const web = yield* HttpClientRequest.toWeb(request).pipe(Effect.orDie)
return redactor.request({
method: web.method,
url: web.url,
headers: Object.fromEntries(web.headers.entries()),
body: yield* Effect.promise(() => web.text()),
})
})
if (mode === "passthrough") return upstream
if (mode === "record") {
const initial = yield* Deferred.make<void>()
yield* Deferred.succeed(initial, undefined)
const tail = yield* Ref.make(initial)
return HttpClient.make((request) =>
Effect.gen(function* () {
const completed = yield* Deferred.make<void>()
const previous = yield* Ref.modify(tail, (current) => [current, completed])
return yield* Effect.gen(function* () {
const incoming = yield* snapshotRequest(request)
const response = yield* upstream.execute(request)
const captured = yield* captureResponseBody(response, response.headers["content-type"])
const responseSnapshot: ResponseSnapshot = {
status: response.status,
headers: response.headers as Record<string, string>,
...captured,
}
const interaction: HttpInteraction = {
transport: "http",
request: incoming,
response: redactor.response(responseSnapshot),
}
yield* Deferred.await(previous)
yield* cassetteService
.append(name, interaction, options.metadata)
.pipe(
Effect.catchTag("UnsafeCassetteError", (error) =>
Effect.fail(transportError(request, error.message)),
),
)
return responseFromSnapshot(request, responseSnapshot)
}).pipe(Effect.ensuring(Deferred.succeed(completed, undefined)))
}),
)
}
const replay = yield* makeReplayState(cassetteService, name, httpInteractions)
return HttpClient.make((request) =>
Effect.gen(function* () {
const incoming = yield* snapshotRequest(request)
const claimed = yield* replay
.claim((interaction, index, interactions) => {
const result = selectSequential(interactions, incoming, match, index)
if (result.interaction) return Effect.void
return Effect.fail(
transportError(request, `Fixture "${name}" does not match the current request: ${result.detail}.`),
)
})
.pipe(
Effect.mapError((error) =>
error._tag === "CassetteNotFoundError"
? transportError(
request,
`Fixture "${name}" not found. Run locally to record it (CI=true forces replay).`,
)
: error,
),
)
return responseFromSnapshot(request, claimed.interaction.response)
}),
)
}),
)
export const cassetteLayer = (name: string, options: RecordReplayOptions = {}): Layer.Layer<HttpClient.HttpClient> =>
recordingLayer(name, options).pipe(
Layer.provide(CassetteService.fileSystem({ directory: options.directory })),
Layer.provide(FetchHttpClient.layer),
Layer.provide(NodeFileSystem.layer),
)

15
packages/http-recorder/src/internal.ts Normal file
View file

@ -0,0 +1,15 @@
export { CassetteNotFoundError, hasCassetteSync, UnsafeCassetteError } from "./cassette.js"
export { cassetteLayer, recordingLayer, type RecordReplayMode, type RecordReplayOptions } from "./internal-effect.js"
export { redactHeaders, redactUrl, secretFindings, type SecretFinding } from "./redaction.js"
export { socketLayer } from "./socket.js"
export {
makeWebSocketExecutor,
type WebSocketConnection,
type WebSocketExecutor,
type WebSocketRecordReplayOptions,
type WebSocketRequest,
} from "./websocket.js"
export * as Cassette from "./cassette.js"
export * as Redactor from "./redactor.js"
export * as HttpRecorderInternal from "./internal.js"

8
packages/http-recorder/src/matching.ts
View file

@ -1,6 +1,6 @@
import { Option, Schema } from "effect"
import { REDACTED, secretFindings } from "./redaction"
import type { HttpInteraction, RequestSnapshot } from "./schema"
import { REDACTED, secretFindings } from "./redaction.js"
import type { HttpInteraction, RequestMatcher, RequestSnapshot } from "./types.js"
const JsonValue = Schema.fromJsonString(Schema.Unknown)
export const decodeJson = Schema.decodeUnknownOption(JsonValue)
@ -20,7 +20,7 @@ export const canonicalizeJson = (value: unknown): unknown => {
return value
}
export type RequestMatcher = (incoming: RequestSnapshot, recorded: RequestSnapshot) => boolean
export type { RequestMatcher } from "./types.js"
export const canonicalSnapshot = (snapshot: RequestSnapshot): string =>
JSON.stringify({
@ -40,7 +40,7 @@ export const safeText = (value: unknown) => {
if (value === undefined) return "undefined"
if (secretFindings(value).length > 0) return JSON.stringify(REDACTED)
const text = JSON.stringify(value)
if (!text) return String(value)
if (!text) return typeof value
return text.length > 300 ? `${text.slice(0, 300)}...` : text
}

38
packages/http-recorder/src/recorder.ts
View file

@ -1,7 +1,7 @@
import { Effect, Ref, Scope } from "effect"
import type * as CassetteService from "./cassette"
import type { CassetteNotFoundError } from "./cassette"
import type { Interaction } from "./schema"
import { Effect, Scope, SynchronizedRef } from "effect"
import type * as CassetteService from "./cassette.js"
import type { CassetteNotFoundError } from "./cassette.js"
import type { Interaction } from "./schema.js"
const isCI = () => {
const value = process.env.CI
@ -18,9 +18,9 @@ export const resolveAutoMode = (
})
export interface ReplayState<T> {
readonly load: Effect.Effect<ReadonlyArray<T>, CassetteNotFoundError>
readonly cursor: Effect.Effect<number>
readonly advance: Effect.Effect<void>
readonly claim: <E>(
validate: (interaction: T | undefined, index: number, interactions: ReadonlyArray<T>) => Effect.Effect<void, E>,
) => Effect.Effect<{ readonly interaction: T; readonly index: number }, CassetteNotFoundError | E>
}
export const makeReplayState = <T>(
@ -30,19 +30,33 @@ export const makeReplayState = <T>(
): Effect.Effect<ReplayState<T>, never, Scope.Scope> =>
Effect.gen(function* () {
const load = yield* Effect.cached(cassette.read(name).pipe(Effect.map(project)))
const position = yield* Ref.make(0)
const position = yield* SynchronizedRef.make(0)
yield* Effect.addFinalizer(() =>
Effect.gen(function* () {
const used = yield* Ref.get(position)
if (used === 0) return
const used = yield* SynchronizedRef.get(position)
if (used === 0) return yield* Effect.void
const interactions = yield* load.pipe(Effect.orDie)
if (used < interactions.length)
yield* Effect.die(
return yield* Effect.die(
new Error(`Unused recorded interactions in ${name}: used ${used} of ${interactions.length}`),
)
return yield* Effect.void
}),
)
return { load, cursor: Ref.get(position), advance: Ref.update(position, (n) => n + 1) }
return {
claim: (validate) =>
Effect.flatMap(load, (interactions) =>
SynchronizedRef.modifyEffect(position, (index) =>
Effect.gen(function* () {
const interaction = interactions[index]
yield* validate(interaction, index, interactions)
if (interaction === undefined)
return yield* Effect.die("Replay validation accepted a missing interaction")
return [{ interaction, index }, index + 1] as const
}),
),
),
}
})

10
packages/http-recorder/src/redaction.ts
View file

@ -75,7 +75,7 @@ export const redactUrl = (
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()]) {
for (const key of url.searchParams.keys()) {
if (redacted.has(key.toLowerCase())) url.searchParams.set(key, REDACTED)
}
return urlRedactor?.(url.toString()) ?? url.toString()
@ -103,13 +103,15 @@ export const SecretFindingSchema = Schema.Struct({
})
export type SecretFinding = Schema.Schema.Type<typeof SecretFindingSchema>
export const secretFindings = (value: unknown): ReadonlyArray<SecretFinding> =>
stringEntries(value).flatMap((entry) => [
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,
})),
...envSecrets()
...environment
.filter((item) => entry.value.includes(item.value))
.map((item) => ({ path: entry.path, reason: `environment secret ${item.name}` })),
])
}

65
packages/http-recorder/src/redactor.ts
View file

@ -1,7 +1,9 @@
import { Option } from "effect"
import { decodeJson } from "./matching"
import { redactHeaders, redactUrl } from "./redaction"
import type { RequestSnapshot, ResponseSnapshot } from "./schema"
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"]
@ -67,6 +69,63 @@ export interface DefaultRedactorOverrides {
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),

41
packages/http-recorder/src/schema.ts
View file

@ -1,4 +1,21 @@
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,
@ -6,7 +23,6 @@ export const RequestSnapshotSchema = Schema.Struct({
headers: Schema.Record(Schema.String, Schema.String),
body: Schema.String,
})
export type RequestSnapshot = Schema.Schema.Type<typeof RequestSnapshotSchema>
export const ResponseSnapshotSchema = Schema.Struct({
status: Schema.Number,
@ -14,23 +30,28 @@ export const ResponseSnapshotSchema = Schema.Struct({
body: Schema.String,
bodyEncoding: Schema.optional(Schema.Literals(["text", "base64"])),
})
export type ResponseSnapshot = Schema.Schema.Type<typeof ResponseSnapshotSchema>
export const CassetteMetadataSchema = Schema.Record(Schema.String, Schema.Unknown)
export type CassetteMetadata = Schema.Schema.Type<typeof CassetteMetadataSchema>
export const HttpInteractionSchema = Schema.Struct({
transport: Schema.tag("http"),
request: RequestSnapshotSchema,
response: ResponseSnapshotSchema,
})
export type HttpInteraction = Schema.Schema.Type<typeof HttpInteractionSchema>
export const WebSocketFrameSchema = Schema.Union([
Schema.Struct({ kind: Schema.tag("text"), body: Schema.String }),
Schema.Struct({ kind: Schema.tag("binary"), body: Schema.String, bodyEncoding: Schema.Literal("base64") }),
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 type WebSocketFrame = Schema.Schema.Type<typeof WebSocketFrameSchema>
export const WebSocketInteractionSchema = Schema.Struct({
transport: Schema.tag("websocket"),
@ -38,10 +59,8 @@ export const WebSocketInteractionSchema = Schema.Struct({
url: Schema.String,
headers: Schema.Record(Schema.String, Schema.String),
}),
client: Schema.Array(WebSocketFrameSchema),
server: Schema.Array(WebSocketFrameSchema),
events: Schema.Array(WebSocketEventSchema),
})
export type WebSocketInteraction = Schema.Schema.Type<typeof WebSocketInteractionSchema>
export const InteractionSchema = Schema.Union([HttpInteractionSchema, WebSocketInteractionSchema]).pipe(
Schema.toTaggedUnion("transport"),

326
packages/http-recorder/src/socket.ts Normal file
View file

@ -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),
)

108
packages/http-recorder/src/types.ts Normal file
View file

@ -0,0 +1,108 @@
/** Additional JSON metadata stored with a cassette. */
export type CassetteMetadata = Record<string, unknown>
/** The normalized HTTP request representation used for matching. */
export interface RequestSnapshot {
/** HTTP method. */
readonly method: string
/** Fully qualified URL after redaction. */
readonly url: string
/** Allowed and redacted request headers. */
readonly headers: Record<string, string>
/** Request body after redaction. */
readonly body: string
}
/** @internal */
export interface ResponseSnapshot {
/** HTTP status code. */
readonly status: number
/** Allowed and redacted response headers. */
readonly headers: Record<string, string>
/** Text body or base64-encoded binary body. */
readonly body: string
/** Encoding used by `body`; omitted for ordinary text. */
readonly bodyEncoding?: "text" | "base64"
}
/** @internal */
export interface HttpInteraction {
readonly transport: "http"
readonly request: RequestSnapshot
readonly response: ResponseSnapshot
}
/** @internal */
export type WebSocketEvent =
| { readonly direction: "client" | "server"; readonly kind: "text"; readonly body: string }
| {
readonly direction: "client" | "server"
readonly kind: "binary"
readonly body: string
readonly bodyEncoding: "base64"
}
/** @internal */
export interface WebSocketInteraction {
readonly transport: "websocket"
readonly open: {
readonly url: string
readonly headers: Record<string, string>
}
readonly events: ReadonlyArray<WebSocketEvent>
}
/** Returns whether an incoming HTTP request matches a recorded request. */
export type RequestMatcher = (incoming: RequestSnapshot, recorded: RequestSnapshot) => boolean
/** Additive redaction and header-preservation policy. */
export interface RedactOptions {
/** Additional sensitive headers to retain as `[REDACTED]`. */
readonly headers?: ReadonlyArray<string>
/** Additional non-sensitive request headers to preserve for matching. */
readonly allowRequestHeaders?: ReadonlyArray<string>
/** Additional non-sensitive response headers to preserve for replay. */
readonly allowResponseHeaders?: ReadonlyArray<string>
/** Additional sensitive URL query parameter names. */
readonly queryParameters?: ReadonlyArray<string>
/** Additional JSON field names to redact recursively. */
readonly jsonFields?: ReadonlyArray<string>
/** Stabilizes a URL after built-in redaction. */
readonly url?: (url: string) => string
/** Stabilizes a request, response, or text-frame body after built-in redaction. */
readonly body?: (body: string) => string
}
/** Options shared by HTTP recorder layers. */
export interface RecorderOptions {
/** Cassette directory. Defaults to `<cwd>/test/fixtures/recordings`. */
readonly directory?: string
/** Additional metadata stored in the cassette. */
readonly metadata?: CassetteMetadata
/** Additive redaction and header-preservation policy. */
readonly redact?: RedactOptions
/** Custom HTTP request equivalence. */
readonly match?: RequestMatcher
}
/** @internal */
export interface WebSocketRequest {
/** WebSocket URL. */
readonly url: string
/** Headers used for redacted matching; the recorder does not send them. */
readonly headers?: Record<string, string>
}
/** @internal */
export interface WebSocketRecorderOptions {
/** Cassette directory. Defaults to `<cwd>/test/fixtures/recordings`. */
readonly directory?: string
/** Additional metadata stored in the cassette. */
readonly metadata?: CassetteMetadata
/** Additive handshake and text-frame redaction policy. */
readonly redact?: RedactOptions
/** Compare text client frames as canonical JSON instead of exact strings. */
readonly compareClientMessagesAsJson?: boolean
/** WebSocket subprotocols used by `layerWebSocket`. */
readonly protocols?: string | Array<string>
}

173
packages/http-recorder/src/websocket.ts
View file

@ -1,12 +1,11 @@
import { Effect, Option, Ref, Scope, Stream } from "effect"
import { Effect, Option, Ref, Scope, Semaphore, Stream, SynchronizedRef } from "effect"
import type { Headers } from "effect/unstable/http"
import * as CassetteService from "./cassette"
import { canonicalizeJson, decodeJson, safeText } from "./matching"
import { makeReplayState, resolveAutoMode } from "./recorder"
import type { RecordReplayMode } from "./effect"
import { redactUrl } from "./redaction"
import { defaults, type Redactor } from "./redactor"
import { webSocketInteractions, type CassetteMetadata, type WebSocketFrame } from "./schema"
import * as CassetteService from "./cassette.js"
import { canonicalizeJson, decodeJson, safeText } from "./matching.js"
import { makeReplayState, resolveAutoMode } from "./recorder.js"
import type { RecordReplayMode } from "./internal-effect.js"
import { make, type Redactor } from "./redactor.js"
import { webSocketInteractions, type CassetteMetadata, type WebSocketEvent } from "./schema.js"
export interface WebSocketRequest {
readonly url: string
@ -40,50 +39,50 @@ const headersRecord = (headers: Headers.Headers): Record<string, string> =>
),
)
const encodeFrame = (message: string | Uint8Array): WebSocketFrame =>
typeof message === "string"
? { kind: "text", body: message }
: { kind: "binary", body: Buffer.from(message).toString("base64"), bodyEncoding: "base64" }
const textEvent = (direction: "client" | "server", body: string): WebSocketEvent => ({
direction,
kind: "text",
body,
})
const decodeFrameMessage = (frame: WebSocketFrame): string | Uint8Array =>
frame.kind === "text" ? frame.body : new Uint8Array(Buffer.from(frame.body, "base64"))
const decodeFrameText = (frame: WebSocketFrame) =>
frame.kind === "text" ? frame.body : new TextDecoder().decode(Buffer.from(frame.body, "base64"))
const assertEqual = (message: string, actual: unknown, expected: unknown) =>
Effect.sync(() => {
if (JSON.stringify(actual) === JSON.stringify(expected)) return
throw new Error(`${message}: expected ${safeText(expected)}, received ${safeText(actual)}`)
})
const decodeEvent = (event: WebSocketEvent) =>
event.kind === "text" ? event.body : new Uint8Array(Buffer.from(event.body, "base64"))
const jsonOrText = (value: string) => Option.match(decodeJson(value), { onNone: () => value, onSome: canonicalizeJson })
const compareClientMessage = (actual: string, expected: WebSocketFrame | undefined, index: number, asJson: boolean) => {
if (!expected)
return Effect.sync(() => {
throw new Error(`Unexpected WebSocket client frame ${index + 1}: ${safeText(actual)}`)
})
const expectedText = decodeFrameText(expected)
if (!asJson) return assertEqual(`WebSocket client frame ${index + 1}`, actual, expectedText)
return assertEqual(`WebSocket client JSON frame ${index + 1}`, jsonOrText(actual), jsonOrText(expectedText))
}
const assertClientEvent = (actual: string, expected: WebSocketEvent | undefined, index: number, asJson: boolean) =>
Effect.sync(() => {
const matches =
expected?.direction === "client" &&
expected.kind === "text" &&
JSON.stringify(asJson ? jsonOrText(actual) : actual) ===
JSON.stringify(asJson ? jsonOrText(expected.body) : expected.body)
if (matches) return
throw new Error(`WebSocket client frame ${index + 1}: expected ${safeText(expected)}, received ${safeText(actual)}`)
})
export const makeWebSocketExecutor = <E>(
options: WebSocketRecordReplayOptions<E>,
): Effect.Effect<WebSocketExecutor<E>, never, Scope.Scope> =>
Effect.gen(function* () {
const requested = options.mode ?? "auto"
const mode = requested === "auto" ? yield* resolveAutoMode(options.cassette, options.name) : requested
const redactor = options.redactor ?? defaults()
const mode = options.mode ?? (yield* resolveAutoMode(options.cassette, options.name))
const redactor = options.redactor ?? make()
const openSnapshot = (request: WebSocketRequest) => {
const redacted = redactor.request({
const snapshot = redactor.request({
method: "GET",
url: request.url,
headers: headersRecord(request.headers),
body: "",
})
return { url: redacted.url, headers: redacted.headers }
return { url: snapshot.url, headers: snapshot.headers }
}
const redactEvent = (event: 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 }
}
if (mode === "passthrough") return options.live
@ -92,67 +91,81 @@ export const makeWebSocketExecutor = <E>(
return {
open: (request) =>
Effect.gen(function* () {
const client: WebSocketFrame[] = []
const server: WebSocketFrame[] = []
const events: WebSocketEvent[] = []
const connection = yield* options.live.open(request)
const closed = yield* Ref.make(false)
const closeOnce = Effect.gen(function* () {
if (yield* Ref.getAndSet(closed, true)) return
yield* connection.close
yield* options.cassette
.append(
options.name,
{ transport: "websocket", open: openSnapshot(request), client, server },
options.metadata,
)
.pipe(Effect.orDie)
})
const closeLock = yield* Semaphore.make(1)
return {
sendText: (message) =>
connection
.sendText(message)
.pipe(Effect.tap(() => Effect.sync(() => client.push(encodeFrame(message))))),
Effect.sync(() => events.push(redactEvent(textEvent("client", message)))).pipe(
Effect.andThen(connection.sendText(message)),
),
messages: connection.messages.pipe(
Stream.tap((message) => Effect.sync(() => server.push(encodeFrame(message)))),
Stream.tap((message) =>
Effect.sync(() =>
events.push(
typeof message === "string"
? redactEvent(textEvent("server", message))
: {
direction: "server",
kind: "binary",
body: Buffer.from(message).toString("base64"),
bodyEncoding: "base64",
},
),
),
),
),
close: closeLock.withPermit(
Effect.gen(function* () {
if (yield* Ref.get(closed)) return
yield* connection.close
yield* options.cassette
.append(
options.name,
{ transport: "websocket", open: openSnapshot(request), events },
options.metadata,
)
.pipe(Effect.orDie)
yield* Ref.set(closed, true)
}),
),
close: closeOnce,
}
}),
}
}
const replay = yield* makeReplayState(options.cassette, options.name, webSocketInteractions)
return {
open: (request) =>
Effect.gen(function* () {
const interactions = yield* replay.load.pipe(Effect.orDie)
const index = yield* replay.cursor
const interaction = interactions[index]
if (!interaction)
return yield* Effect.die(new Error(`No recorded WebSocket interaction for ${redactUrl(request.url)}`))
yield* replay.advance
yield* assertEqual(`WebSocket open frame ${index + 1}`, openSnapshot(request), interaction.open)
const messageIndex = yield* Ref.make(0)
const claimed = yield* replay
.claim((interaction, index) =>
Effect.sync(() => {
const incoming = canonicalizeJson(openSnapshot(request))
if (interaction && JSON.stringify(incoming) === JSON.stringify(canonicalizeJson(interaction.open)))
return
throw new Error(`WebSocket open ${index + 1} does not match ${safeText(incoming)}`)
}),
)
.pipe(Effect.orDie)
const client = claimed.interaction.events.filter((event) => event.direction === "client")
const server = claimed.interaction.events.filter((event) => event.direction === "server")
const position = yield* SynchronizedRef.make(0)
return {
sendText: (message) =>
Effect.gen(function* () {
const current = yield* Ref.get(messageIndex)
yield* compareClientMessage(
message,
interaction.client[current],
current,
options.compareClientMessagesAsJson === true,
)
yield* Ref.update(messageIndex, (value) => value + 1)
}),
messages: Stream.fromIterable(interaction.server).pipe(Stream.map(decodeFrameMessage)),
SynchronizedRef.updateEffect(position, (index) =>
assertClientEvent(message, client[index], index, options.compareClientMessagesAsJson === true).pipe(
Effect.as(index + 1),
),
),
messages: Stream.fromIterable(server).pipe(Stream.map(decodeEvent)),
close: Effect.gen(function* () {
yield* assertEqual(
`WebSocket client frame count for interaction ${index + 1}`,
yield* Ref.get(messageIndex),
interaction.client.length,
)
const used = yield* SynchronizedRef.get(position)
if (used !== client.length)
return yield* Effect.die(
new Error(`WebSocket client frame count: expected ${client.length}, received ${used}`),
)
}),
}
}),