Skip to content

docs(#4): raise X-Http-Sql-Version emission from SHOULD to MUST - #16

Merged
ssilvius merged 2 commits into
mainfrom
fix/4-version-header-must
Aug 3, 2026
Merged

docs(#4): raise X-Http-Sql-Version emission from SHOULD to MUST#16
ssilvius merged 2 commits into
mainfrom
fix/4-version-header-must

Conversation

@ssilvius

@ssilvius ssilvius commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Summary

SPEC.md section 9 stated the X-Http-Sql-Version response header as a SHOULD, while section 10.1 item 7 lists emitting that same header under "A v0.1 conforming server MUST" and the conformance suite tests it in the "Required test cases" tables (H-1, H-2). This PR resolves the conflict in the direction the issue rules on: section 9 now reads MUST. Nothing else changes -- one word in one line -- because the other two statements of the rule were already at MUST strength and are now simply consistent with it. Raising rather than demoting keeps version detection reliable for the multi-backend clients the spec exists to serve, and costs shipped implementations nothing since both reference servers already set the header.

Acceptance criteria mapping

1. SPEC.md:180 reads MUST

The single normative keyword on the section 9 sentence introducing the version header was changed from SHOULD to MUST; the line now reads "Conforming servers MUST include the response header:", and the following code fence and the "on every response (including error responses)" qualifier at SPEC.md:186 are untouched, so the scope of the requirement is unchanged -- only its strength. I read all 247 lines of SPEC.md to confirm this is the only place the requirement level for this response header is stated, so no weaker restatement survives elsewhere in the document.

Evidence: SPEC.md:180 -- "Conforming servers MUST include the response header:". The only other mentions of the string in SPEC.md are the illustrative fence at SPEC.md:183 and the conformance list item at SPEC.md:208; SPEC.md:191 and SPEC.md:227 concern the distinct client request header X-Http-Sql-Accept-Version and were deliberately left as MAY/SHOULD.

2. S10.1 item 7 and conformance H-1/H-2 are unchanged and now consistent

Neither file section was edited, which is the correct outcome rather than an omission: both already expressed the header as mandatory, and they were the side of the contradiction the issue rules in favor of. Section 10.1 item 7 sits inside the numbered list introduced by "A v0.1 conforming server MUST:", so it inherits MUST strength. H-1 and H-2 live under the "## Required test cases" heading in the conformance doc, both expecting X-Http-Sql-Version: 0.1 -- H-1 on any successful response, H-2 on any error response, which together match the "on every response (including error responses)" scope in section 9.

Evidence: SPEC.md:200 introduces the MUST list and SPEC.md:208 is item 7, "Emit the X-Http-Sql-Version response header."; conformance/README.md:15 is the "## Required test cases" heading and conformance/README.md:68-69 are H-1 and H-2. git diff --name-only origin/main...HEAD returns exactly SPEC.md, confirming conformance/README.md is unmodified.

Not done

I did not touch the two reference servers, and one of them has a latent gap worth filing separately rather than fixing under a spec-wording issue. In examples/cloudflare-worker-to-d1/src/index.ts:32-35 the version header is set by a Hono middleware that runs its c.res.headers.set(...) only after await next() returns normally; the bearer-auth middleware at line 39 rejects by throwing, so the 401 envelope produced by the app.onError handler at lines 71-77 plausibly escapes without the header. The same after-next() pattern appears in examples/cloudflare-durable-object/src/index.ts:25-28, though there the DO's own json() helper hardcodes the header in JSON_HEADERS (lines 139-146), so DO-originated errors carry it regardless. Confirming this needs a running Worker, not a reading, and the issue's acceptance criteria are strictly about spec text -- so I left the examples alone. I also made no change to the client-side X-Http-Sql-Accept-Version requirement levels, to the versioning policy in section 11, or to implementations.md, none of which restate the server header rule.

Closes #4

S9 stated the version response header as SHOULD while S10.1 item 7 lists
it under "A v0.1 conforming server MUST" and conformance H-1/H-2 sit in
the required test-case tables. Resolve the conflict in favor of MUST, so
version detection is reliable for multi-backend clients.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@ssilvius
ssilvius merged commit 66d2e87 into main Aug 3, 2026
1 check passed
@ssilvius
ssilvius deleted the fix/4-version-header-must branch August 3, 2026 05:27
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.

P1: X-Http-Sql-Version is SHOULD in S9 and MUST in S10.1 -- resolve to MUST

1 participant