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

feat(http-recorder): prepare independent beta release

Browse source
This commit is contained in:
Kit Langton 2026-06-22 18:12:14 -04:00
commit 81eea42e80
17 changed files with 485 additions and 85 deletions
Download patch file Download diff file Expand all files Collapse all files

43
packages/http-recorder/CONTEXT.md Normal file
View file

@ -0,0 +1,43 @@
# 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.