Skip to content

docs: day-one client list -- which http-sql clients we supply, and the rule they follow #29

Description

@ssilvius

Problem

http-sql has one reference client (TypeScript, ~40 lines) and smugglr's Rust profile. The prior-art research (legion document RESEARCH-HTTPSQL-GRAVEYARD) found that a spec with no popular client loses to a client with no spec: PlanetScale implemented Neon's undocumented endpoint because Neon's driver had users. Operator direction: create the day-one list of clients we supply, so traffic has a way in from every runtime our first segments use.

Acceptance criteria

  • A clients.md at the repo root lists the Tier 1 clients that ship before anything is announced, ordered by where http-sql traffic originates, each with runtime, audience, proposed package name, and the reason it is day one.
  • The same document states the rule every client follows: fetch and JSON only, the request headers and body shapes, tagged-value handling, error mapping including statementIndex and unknown vendor codes, no sessions or query builder, and the completion criterion (passes the client cases in checks/ against the reference server).
  • A per-language table pins what bigint and blob decode to, so no client can round a 64-bit integer and call itself done.
  • A Tier 2 list with the reason each is not day one, and a declined list, so absence is not read as an oversight.
  • The document says where the clients live and under what license.
  • README links to it.

Out of scope

Writing any client. Package names are proposals until the first one is published.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions