ceos/opencode
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
opencode/packages/http-recorder/CONTEXT.md

3 KiB
Raw Permalink Blame History

HTTP Recorder

The HTTP recorder is a public testing library for recording real Effect transport traffic into deterministic cassettes and replaying it without contacting the upstream service.

Language

Library Version: The independently managed semantic version of @opencode-ai/http-recorder published to npm. Avoid: OpenCode version

OpenCode Release Version: The version applied to OpenCode applications and packages by the repository-wide release process. It does not determine the Library Version.

Effect Compatibility Version: The exact Effect 4 beta against which the package's unstable HTTP and socket integrations are built and verified.

Provider Conversation: A finite WebSocket connection in which either peer may send first, the client sends one or more JSON commands, server frames follow in causal order, and the application closes after a terminal event.

Connection Identity: The explicit cassette name supplied to the WebSocket recorder. It identifies the recorded conversation during replay.

Completed Conversation: A WebSocket socket run that opened and finished successfully after recording a valid finite transcript.

Client Frame Match: The replay check that requires an outgoing application frame to equal the next recorded client frame after redaction. Text JSON ignores object-key order; other text and binary frames match exactly.

Relationships

  • The Library Version begins with the public beta at 0.1.0 and advances independently through Changesets.
  • Repository-wide OpenCode release synchronization must not rewrite the Library Version.
  • The initial Effect Compatibility Version is 4.0.0-beta.83; compatibility with later Effect betas is not implied.
  • Changing the Effect Compatibility Version requires a new Library Version and clean-consumer package verification.
  • A Provider Conversation is the canonical WebSocket scenario for evaluating the public beta contract; arbitrary socket emulation is not implied.
  • Application code owns WebSocket construction, including URL, protocols, timeout, authentication, and close policy; the recorder decorates the resulting Effect Socket.Socket service.
  • Connection Identity, not the live WebSocket destination, selects and validates a replay. The beta does not validate URL or handshake configuration during replay.
  • Only a Completed Conversation is committed to a cassette; failed, interrupted, unopened, or invalid runs do not produce a recording.
  • Replay requires every recorded frame to be consumed before application close.
  • Terminal close codes, close reasons, connection timing, and transport failures are not cassette events in the first public beta.
  • Every outgoing replay frame must satisfy the Client Frame Match before later server frames are released.
  • The first public beta does not expose a custom WebSocket frame matcher.
  • Replay starts incoming frame handlers in recorded order and may run them concurrently; it waits for every handler before the socket run completes but does not guarantee handler completion order.