Skip to content

refactor(streaming): adopt shared Praxis SSE codec for Responses framing - #942

Draft
leseb wants to merge 1 commit into
praxis-proxy:mainfrom
leseb:leseb/issue-842-praxis-985
Draft

refactor(streaming): adopt shared Praxis SSE codec for Responses framing#942
leseb wants to merge 1 commit into
praxis-proxy:mainfrom
leseb:leseb/issue-842-praxis-985

Conversation

@leseb

@leseb leseb commented Sep 7, 2026

Copy link
Copy Markdown
Contributor

What

Migrate the OpenAI Responses provider-neutral SSE record framing onto the shared praxis_filter::sse codec introduced by praxis-proxy/praxis#1060 (epic praxis#985). SseFrameParser now delegates byte-level line/record framing to SseDecoder while keeping the OpenAI-facing SseFrame / SseParseError surface, the [DONE] sentinel, the event-count budget, timeouts, and lifecycle rules in the Responses consumers unchanged.

Praxis has no release carrying the codec yet, so the praxis core crates are pinned to main at the #1060 merge commit (c4cab79) and Pingora moves to the 0.8.4 fork in lockstep with core.

Scope — migrate only where framing matches the shared contract

  • OpenAI Responses (openai_stream_events, responses::parser) → migrated onto the codec. parse_chunk now takes &Bytes and threads it into the decoder without copying.
  • A2A route-capture scanner + the token-usage counter that reuses it → intentionally not migrated. They are fail-open and recoverable on an oversized record (drop it, resync at the next blank-line boundary), whereas the shared decoder poisons permanently. Adopting the codec there requires a recoverable/resync-on-overflow mode in praxis#986, not another AI-local parser. The gap is documented in the A2A sse module and referenced from the token-usage consumer.
  • Anthropic anthropic_stream_events → deferred to a follow-up PR.

Behavior preservation

max_buffer_bytes maps onto both codec framing bounds (max_line_bytes and max_record_bytes). For the single-data:-line blocks the Responses API emits, the overflow trip point and peak retained bytes match the pre-codec parser; the new() doc describes the mapping truthfully (including how a multi-line record — which the Responses API never emits — is accounted differently). No full-body buffering is introduced and backpressure is not weakened for real traffic.

Duplicate pure-codec framing tests are removed in favor of adapter-focused tests plus the codec's own conformance suite.

Testing

  • make lint
  • make test
  • make doc ✓ (verifies the new intra-doc links)

Refs #842

Migrate the OpenAI Responses provider-neutral SSE record framing onto the
shared `praxis_filter::sse` codec introduced by praxis-proxy/praxis#1060
(epic praxis#985). `SseFrameParser` now delegates byte-level line/record
framing to `SseDecoder` while keeping the OpenAI-facing `SseFrame` /
`SseParseError` surface, the `[DONE]` sentinel, the event-count budget,
timeouts, and lifecycle rules in the Responses consumers unchanged.

Because praxis has no release carrying the codec yet, pin the praxis core
crates to main at the #1060 merge commit and move Pingora to the 0.8.4
fork in lockstep with core.

Consumers are migrated only where their framing matches the shared
contract:

- OpenAI Responses (`openai_stream_events`, `responses::parser`) moves onto
  the codec. `parse_chunk` now takes `&Bytes` and threads it into the
  decoder without copying (zero-copy `slice`/`from_static` in tests).
- The A2A route-capture scanner and the token-usage counter that reuses it
  are intentionally left in place: they are fail-open and recoverable on an
  oversized record (drop it, resync at the next boundary), whereas the
  shared decoder poisons permanently. Adopting the codec there needs a
  recoverable/resync mode in praxis#986, not another AI-local parser; the
  gap is documented in the A2A `sse` module and referenced from the
  token-usage consumer.
- Anthropic `anthropic_stream_events` migration is deferred to a follow-up
  PR.

`max_buffer_bytes` maps onto both codec framing bounds (`max_line_bytes`
and `max_record_bytes`); for the single-`data:`-line blocks the Responses
API emits, the overflow trip point and peak retained bytes match the
pre-codec parser. Duplicate pure-codec framing tests are removed in favor
of adapter-focused tests plus the codec's own conformance suite.

Refs praxis-proxy#842

Signed-off-by: Sébastien Han <seb@redhat.com>
@leseb
leseb requested review from a team and crstrn13 September 7, 2026 06:07
@leseb
leseb marked this pull request as draft September 7, 2026 07:18
@leseb

leseb commented Sep 7, 2026

Copy link
Copy Markdown
Contributor Author

Draft since we need a new core release with the SSE codec code.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant