Skip to content

docs(gateway): drop the stale "cross-protocol streaming -> 400" claims - #181

Merged
argszero merged 1 commit into
mainfrom
docs/fix-stale-p3b-streaming-claims
Sep 12, 2026
Merged

docs(gateway): drop the stale "cross-protocol streaming -> 400" claims#181
argszero merged 1 commit into
mainfrom
docs/fix-stale-p3b-streaming-claims

Conversation

@argszero

Copy link
Copy Markdown
Owner

Summary

Two module-header doc comments still described the pre-P3-B state, in which streaming requests were restricted to same-protocol passthrough and any cross-protocol streaming request failed with 400.

That restriction no longer exists. 6095ef0 (P3-B) deleted the key filter that enforced it in forward_stream, added src/sse.rs with the protocol-pair SSE converters, and updated that function's own doc comment plus README.md — but left the two module headers behind. The same tree therefore carried two claims that contradict each other:

Location Claim
README.md:12 非流式 + SSE 流式全支持
src/gateway.rs:13 跨协议 → 400 明确报错
src/protocol.rs:14 流式 SSE 转换留 P3-B

Only one protocol pair remains unimplemented — responses upstream → anthropic client — which forward_stream returns an explicit 400 for. The other five pairs are implemented and dispatched:

ARM   openai_chat upstream -> anthropic client
ARM   openai_chat upstream -> responses client
ARM   anthropic   upstream -> openai_chat client
ARM   anthropic   upstream -> responses client
ARM   responses   upstream -> openai_chat client
400   responses   upstream -> anthropic client

Related Issue

None — no issue exists for this. Doc-comment staleness found by a tree scan, not a report.

Changes

  • src/gateway.rs — the module header no longer claims cross-protocol streaming returns 400.
  • src/protocol.rs — the module header no longer claims streaming SSE conversion is deferred to P3-B.
  • 涉及配置/数据结构的改动已同步示例文件 — not applicable (comments only).

Comment-only: 4 insertions, 3 deletions, zero non-comment lines. No production behaviour, no constant, no i18n key, no cache-bust, no config.

Neither comment is replaced with a snapshot of the current coverage. A comment asserting "X is not yet supported" rots the moment X ships, and it is the implementation's own success that invalidates it — the person adding the feature has no reason to look back at a header saying it wasn't there. Both lines now state the invariant (streaming requests are converted cross-protocol too) and point at the authority for the converter list (src/sse.rs + the forward_stream dispatch), so a pair being added or removed later cannot contradict the header.

Tests

Coverage of the claim itself was checked with a throwaway capability checker (tmp/c2025_check.py, not committed):

--source HEAD   present=2  stale=2   exit=1   (both claims contradict the code)
(working tree)  present=0  stale=0   exit=0
--self-test     injected STALE -> STALE, injected FRESH -> OK   (checker still discriminates)

The --self-test leg matters: the fix's whole effect is to delete the corpus being checked, so a green afterwards is vacuous on its own. The checker was also re-run after the fix and did report the two real claims as gone, rather than silently losing track of them.

The behaviour the header now describes is pinned by an existing test, which passes on this branch:

test gateway::tests::sse_cross_protocol_openai_to_anthropic_conversion ... ok

Checklist

  • 分支命名符合约定(docs/
  • Commit message 使用 Conventional Commits 格式(docs(gateway): …
  • 单一职责,改动最小化

Two module-header doc comments still described the pre-P3-B state, in which
streaming requests were restricted to same-protocol passthrough and any
cross-protocol streaming request failed with 400.

That restriction no longer exists. 6095ef0 (P3-B) deleted the key filter that
enforced it in forward_stream, added src/sse.rs with the protocol-pair SSE
converters, and updated that function's own doc comment plus README -- but left
the gateway module header behind. The same tree therefore carried two
contradicting claims:

  README.md:12          "非流式 + SSE 流式全支持"
  src/gateway.rs:13     "跨协议 -> 400 明确报错"

Only one protocol pair remains unimplemented (responses upstream ->
anthropic client), which forward_stream returns 400 for explicitly.

Neither comment is replaced with a snapshot of the current coverage: a comment
asserting "X is not yet supported" rots as soon as X ships, and it is the
implementation's own success that invalidates it. Both now state the invariant
(streaming requests are converted cross-protocol too) and point at the
authority for the converter list, so a future pair being added or removed
cannot contradict the header.
@argszero
argszero merged commit 9db4872 into main Sep 12, 2026
1 check passed
@argszero
argszero deleted the docs/fix-stale-p3b-streaming-claims branch September 12, 2026 07:34
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