docs(spec): http-sql media type, optional QUERY binding, plain headers, server policy; renumber to 0.0.1 - #28
Merged
Conversation
…n headers, server policy Additive bump from 0.2. application/http-sql+json is the media type; application/json stays accepted on requests so curl keeps working, and the two are interchangeable server-side. QUERY (RFC 10008) is an optional read binding executed exactly like POST, advertised with Accept-Query; the safe promise belongs to the client and the spec says plainly that CDNs cache GET only today. Version headers drop the X- prefix per RFC 6648, with the old names sent alongside through 0.x. Section 12.1 gives the ordinary controls that make raw SQL over HTTP sane (one database per token, least-privilege role, read-only mode, allowlist, limits, no sniffing), each mapped to a registered error code. Section 13 states the standards-tree registration intent and declines application/sql. Also: the checks directory and section 10 are renamed and the fixture table with them; the example servers send both version headers, accept both request media types, and respond with the http-sql media type. Grounded in RESEARCH-HTTPSQL-GRAVEYARD (legion document, surface http-sql). Claude-Session: https://claude.ai/code/session_01RjiPB8PpLbDdK8soLAUPwQ Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…age edits Operator ruling: the spec has not earned a number; these are draft edits, not a 0.3. Title, status, header values, checks, examples, and the history entry now say v0.2 with an "unreleased draft edits" line, and the status reads "still being thought through". Claude-Session: https://claude.ai/code/session_01RjiPB8PpLbDdK8soLAUPwQ Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
ssilvius
changed the title
Operator ruling. The first two drafts were numbered 0.1 and 0.2 before the spec had earned a number; the count restarts at 0.0.1 and section 11 now says what the numbers mean: below 0.1 is thinking-stage and nothing may pin to it; the minor moves when a second independent implementation has dogfooded the shape; 1.0 is the first number a product may build on. Header values, checks, example servers, the reference client, and every prose reference follow. History keeps the old entries as "formerly 0.2" and "formerly 0.1". Claude-Session: https://claude.ai/code/session_01RjiPB8PpLbDdK8soLAUPwQ Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
ssilvius
changed the title
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
1 participant
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.
Closes #27.
Acceptance criteria mapping
Media type (section 2).
SPEC.md section 2 now lists
application/http-sql+jsonorapplication/jsonas accepted request types, says servers MUST NOT treat them differently, sets the response type toapplication/http-sql+json, and keeps the 415 rule for anything else. Evidence: SPEC.md lines 17-27; checks R-4 (both types accepted) and the new R-6 (response type);REQUEST_MEDIA_TYPESandisJsonMediaTypein all three example servers; the Hono middleware rewrites JSON responses to the http-sql type.QUERY (section 2.1).
New subsection: a server MAY accept
QUERY; body and envelopes are those ofPOST; "MUST execute a QUERY request the same way it executes the same body sent as POST; it MUST NOT parse or classify the SQL to decide";Accept-Query: application/http-sql+jsonSHOULD be emitted; the client owns the safe promise; the non-normative note states CDNs and the Workers Cache API cacheGETonly as of 2026 and names the 303Locationpath; "POST remains the only required method." The reference server deliberately does not opt in, so it stays at its size. Evidence: SPEC.md section 2.1; 10.1 MAY list; checks "Optional" bullet.Headers (section 9).
Http-Sql-Version: 0.0.1MUST;X-Http-Sql-VersionSHOULD ride along through 0.x, deprecated with the RFC 6648 citation;Http-Sql-Accept-Versionwith theX-synonym accepted. Evidence: SPEC.md section 9; 10.1 item 9 and 10.2 SHOULD; checks H-1/H-2;VERSION_HEADERin reference-server.ts and the middleware in both Cloudflare examples set both names from oneVERSIONconstant.Server policy (section 12.1).
Non-normative table: one database per token, least-privilege role, read-only mode, statement allowlist, limits, no sniffing; each row names the registered error code it fires (
permission_error,not_allowed,payload_too_large,rate_limited,unsupported_media_type); closing paragraph states that the engine enforces policy, not a parser, and why SQL rewriting is out. Section 12 also gained the QUERY bullet (a server MUST NOT weaken authorization because the method was QUERY). Evidence: SPEC.md section 12 and 12.1.IANA (section 13).
Standards-tree intent with the RFC, citing RFC 6838 section 3.1 and the GraphQL-over-HTTP precedent; vendor tree ruled out with the reason;
application/sql(RFC 6922) recorded as considered and declined because it cannot carry parameters. Evidence: SPEC.md section 13.Renumbered to 0.0.1.
The spec is thinking-stage, so the count restarts below 0.1. SPEC.md line 1 and the status line say 0.0.1; section 11 is rewritten: below 0.1 nothing may pin to the shape, the minor moves when a second independent implementation has dogfooded it, 1.0 is the first number a product may build on; the history keeps the old entries as "formerly 0.2" and "formerly 0.1". Header values (section 9), checks H-1/H-2,
const VERSION = "0.0.1"in all three example servers, the reference client'shttp-sql-accept-versionheader, README status, and implementations.md all follow. Evidence: SPEC.md section 11; a content search for v0.1, v0.2, or 0.x in prose returns zero hits.Checks and examples.
checks/README.md: R-4 names both accepted media types, R-6 added for the response type, H-1/H-2 name
Http-Sql-Version: 0.0.1, and the fixture table ishttp_sql_check_notesin all three places it appears. reference-server.ts, worker-to-d1, and durable-object send both version headers from oneVERSIONconstant, accept both request types throughREQUEST_MEDIA_TYPESinisJsonMediaType, respond with the http-sql media type, and their 415 message names both types. Evidence: the diff for those five files.Banned word.
conformance/renamed tochecks/(git rename, 85% similarity); section 10 is "What a server and a client must do" with "Servers" and "Clients" subsections; every remaining prose use was reworded ("a server that follows this spec", "check V-1", "known failure", "passing is self-reported"). Evidence: a case-insensitive content search for the stem returns zero hits across the repo.Not done
Column types in the result envelope, the large-result story, a declinable and visible
atomic(#13), a Postgres-backed second server, and the checks runner are each their own decision and are listed as out of scope on #27. I did not addQUERYto any example server, because section 2.1 is optional and the reference is meant to stay fifty lines. I did not register anything with IANA; section 13 states intent only.🤖 Generated with Claude Code
https://claude.ai/code/session_01RjiPB8PpLbDdK8soLAUPwQ