Module streaming_proxy 

Streaming proxy for forwarding command/event JSONL streams (task 4.10).

Unstable 0.x API — this module may change between minor versions without notice. Consumers MUST pin an exact version and test against upgrades.

Overview

The StreamingProxy reads JSONL commands from any reader, dispatches them to a ProxyHandler, and writes JSONL responses/events to any writer. It bridges the SDK command model (SdkCommand/SdkResponse) with an external transport without requiring a live provider or specific I/O backend.

Framing

Strict JSONL: one JSON object per line, \n delimiter, flushed after each write. Empty lines are silently skipped. Malformed JSON produces a proxy_error response with the line number and parse error.

Backpressure

Events emitted by the handler are buffered in a bounded synchronous channel (configurable via ProxyConfig::event_channel_capacity, default 256). When the buffer is full, new events are dropped with a tracing warning. This prevents a slow consumer from blocking the handler.

Cancellation

The proxy accepts a tokio_util::sync::CancellationToken. Cancellation is observed between blocking input reads. When observed, the proxy emits a proxy_cancelled event, stops reading new commands, drains remaining buffered events, and exits cleanly.

Client Disconnect

If a write to the output fails (broken pipe, closed connection), the proxy stops processing, logs the error, and returns. It does not panic.

Secret Redaction

When enabled (default), SecretRedactor scans event JSON for common secret patterns:

• sk-ant-* (Anthropic API keys)
• sk-* (OpenAI API keys)
• Bearer tokens / JWTs (eyJ*)
• JSON fields named password, secret, token, api_key, apikey, private_key, access_token, refresh_token

Matching values are replaced with [REDACTED]. Custom patterns can be added via SecretRedactor::new.

Protocol Sequence

→ {"type":"proxy_ready","schema_version":2}     // first output
← {"type":"session_info"}                       // command from client
→ {"type":"response","command":"session_info","success":true,"data":{...}}
→ {"type":"AgentStart"}                         // async event
→ {"type":"AgentEnd","messages":[...]}           // async event
← {"type":"quit"}                               // client ends session
→ {"type":"response","command":"quit","success":true}
                                                // proxy exits

Structs

ProxyConfig

Configuration for the streaming proxy.

SecretRedactor

Redacts common secret patterns from JSON event payloads.

StreamingProxy

A streaming proxy that reads JSONL commands, dispatches to a handler, and writes JSONL responses/events.

Enums

ProxyEvent

An event emitted through the proxy’s event channel.

StreamingProxyError

Errors from the streaming proxy.

Traits

ProxyHandler

Handler for incoming proxy commands.