docs(clients): the day-one client list and the rule every client follows - #30
Open
ssilvius wants to merge 2 commits into
Open
docs(clients): the day-one client list and the rule every client follows#30ssilvius wants to merge 2 commits into
ssilvius wants to merge 2 commits into
Conversation
Seven Tier 1 clients ordered by where traffic originates (TS/JS, Rust with a CLI, Python, C# with a Unity package, Drizzle driver, Kysely dialect, MCP server), a Tier 2 fast-follow (Go, Unreal via the Rust C-ABI, Swift, Kotlin, a Neon-driver server adapter), and what is declined. The rule: a client is fetch and JSON, no sessions, no query builder, and it is done when it passes the client cases in checks/ against the reference server. A per-language table pins what bigint and blob decode to, since that is the only place clients differ. Claude-Session: https://claude.ai/code/session_01RjiPB8PpLbDdK8soLAUPwQ Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…it on the C-ABI Operator direction. Unreal joins the day-one list as its own client: FHttpModule transport, FJsonObject envelope, int64 and TArray<uint8> for the tagged forms, results on the game thread, a Blueprint-callable node. The Tier 2 row becomes the later option of moving the plugin onto the shared Rust C-ABI once smugglr-core defines it. Claude-Session: https://claude.ai/code/session_01RjiPB8PpLbDdK8soLAUPwQ Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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 #29.
Acceptance criteria mapping
Tier 1 list, ordered by traffic origin.
clients.md"Tier 1" table: TypeScript/JavaScript (browser, Workers, Deno, Vercel Edge, Node, Bun), Rust with ahttp-sqlbinary, Python, C# with a Unity package, Unreal (UE 5.x and 6, a native plugin on FHttpModule with a Blueprint node), a Drizzle driver, a Kysely dialect, and an MCP server, each with runtime, audience, proposed package name, and the reason it is day one. Order follows where http-sql traffic originates (edge-era JS first, then the languages the first segments use). Evidence: clients.md lines 33-44.The rule every client follows.
clients.md"The rule for every client": POST (QUERY where the runtime allows),Content-Type: application/http-sql+json,Http-Sql-Accept-Version: 0.0.1, caller-supplied bearer,{sql, params}or{batch, atomic}, taggedblob/bigint, envelope fields returned as natural types, one typed error per registered code withstatementIndexon non-atomic batch failures and unknownvendor:codes mapped by status family, no sessions or connection objects or query builder or schema knowledge, and the completion criterion: passes the client cases inchecks/against the reference server. Evidence: clients.md lines 7-18.Lossless types per language.
clients.md"Lossless types per language" table pinsbigintandblobfor TypeScript, Rust, Python, C#, C++ (Unreal), Go, Swift, and Kotlin, with a note per language on the transport or serializer, and states that a client rounding a 64-bit integer is not done. Evidence: clients.md lines 20-31.Tier 2 and declined, with reasons.
"Tier 2: fast follow" gives Go, the later move of the Unreal plugin onto the Rust C-ABI, Swift, Kotlin, and the Neon-driver server adapter, each with why it is not day one; "Declined for day one" names PHP, Ruby, Java, Elixir with the reason and the path in through implementations.md. Evidence: clients.md lines 46-58.
Where they live and license.
"Where they live":
clients/<language>/in this repo so spec, checks, and clients version together under one CI job; published independently; MIT like the spec. Evidence: clients.md lines 60-62.README link.
README "Where to read" gains a
clients.mdbullet. Evidence: README.md line 47.Not done
No client code. Package names are proposals until the first publish. The Unreal plugin ships on FHttpModule and does not wait on smugglr-core's C-ABI; moving it onto the shared crate later is Tier 2 and is theirs to time.
🤖 Generated with Claude Code
https://claude.ai/code/session_01RjiPB8PpLbDdK8soLAUPwQ