docs(#4): raise X-Http-Sql-Version emission from SHOULD to MUST - #16
Merged
Conversation
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>
1 task
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
SPEC.md section 9 stated the
X-Http-Sql-Versionresponse 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-Versionand 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-Versionresponse 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...HEADreturns exactlySPEC.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-35the version header is set by a Hono middleware that runs itsc.res.headers.set(...)only afterawait next()returns normally; the bearer-auth middleware at line 39 rejects by throwing, so the 401 envelope produced by theapp.onErrorhandler at lines 71-77 plausibly escapes without the header. The same after-next()pattern appears inexamples/cloudflare-durable-object/src/index.ts:25-28, though there the DO's ownjson()helper hardcodes the header inJSON_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-sideX-Http-Sql-Accept-Versionrequirement levels, to the versioning policy in section 11, or to implementations.md, none of which restate the server header rule.Closes #4