Module realtime_peer 

A deterministic stand-in for the realtime agent endpoint.

docs/specs/openai-realtime.md is a contract with two sides. The bridge holds one of them; this module holds the other, so every vector in that spec except the live proof runs in the default cargo test matrix with no account, no credential, no network beyond loopback and no container. A bridge whose only counterparty is the vendor can be tested once a day by whoever holds the key; a bridge whose counterparty is this module is tested by everyone, on every commit, including the failure rows — and the failure rows are the half nobody can produce on demand from a real endpoint.

Cleartext on loopback, deliberately. The peer speaks ws://127.0.0.1:<port> rather than wss://. Certificates are the one fixture cost that spreads: a TLS stand-in needs a trust anchor threaded into every test that reaches it, and the first test that finds that awkward disables verification, which is a worse habit than the one the certificate was for. The client this peer exists for permits cleartext to loopback and refuses it everywhere else, so the seam is closed by the client’s own rule rather than by a certificate this peer would have to issue. certs is still where a test that genuinely needs TLS gets one.

Scripted, never guessed. The peer performs the protocol spine by itself — it checks the bearer, answers with session.created, answers a session.update with session.updated, and records every client event and every appended audio byte — and does nothing else unless a test directs it. Downlink audio, cancels, closes and every malformed frame are directives whose future resolves after the frame is on the socket, so a test orders its script by awaiting the peer rather than by waiting on a clock. No behaviour here is timed.

The negatives are the point. §6’s failure taxonomy is reachable one row at a time: a refused bearer (PeerConfig::expecting_bearer), withheld setup acknowledgements (Withhold), a peer that answers the upgrade and then goes silent (StallPoint), a frame over the 1 MiB bound (RealtimePeer::send_oversize), events that cannot be read (Malformed), a normal close and an abrupt reset. Each is asserted from the client’s side of the socket in this crate’s own tests, because a stand-in whose misbehaviour is a flag nobody observes proves nothing about the bridge tested against it.

Structs

PeerConfig

How the peer behaves, before it is started.

RealtimePeer

A running stand-in peer.

Record

Everything the peer observed, and everything it emitted.

Upgrade

What one upgrade attempt carried.

Enums

CancelPolicy

What the peer does with a response after the client cancels it (§4.3).

ClientEvent

A client event as the peer read it.

Emission

What became of a directed event.

Malformed

One frame the peer sends that no one can read as an event (§5.3, ORB-13 and ORB-18).

PeerError

Everything that can go wrong driving the peer.

StallPoint

Where the peer stops serving the socket while holding it open (ORB-14).

UpgradeOutcome

How one upgrade attempt was answered.

Withhold

Which setup acknowledgement the peer withholds (ORB-15).

Constants

FIXTURE_BEARER

The bearer the peer expects unless a test configures another one.

FRAME_BYTES

The call’s 20 ms packet: 160 bytes of G.711 at 8000 Hz, one byte per sample (RFC 3551 §4.5.14), which spec §4.1 makes the unit of audio in both directions.

F_RAMP_BASE64

Spec §4.2’s F-ramp in base64: the 160 bytes 0x00, 0x01, … 0x9F.

F_SILENCE

Spec §4.2’s F-silence: 20 ms of μ-law digital silence.

F_SILENCE_BASE64

F-silence’s base64, quoted from spec §4.2.

OBSERVATION_BOUND

How long RealtimePeer::observe waits before reporting that it saw nothing.

Functions

tone_bytes

The first frames frames of the tone, concatenated — what a bridge should hand to the media path after receiving that many deltas.

tone_frame

One frame of the tone the peer speaks, by position in the response.