zeekayandHanzo Dev 6c01f84d7c docs(schema): the schema described a wire we stopped sending ...

d05974f moved headers and trailers from a JSON map to length-prefixed
pairs and regenerated the golden vectors. schema/zap_http.zap — which
calls itself the source of truth — was never updated, so the one file a
reimplementer reads first described a JSON map<Text, List(Text)> and a
`List(Header)` struct list that no encoder has emitted since.

Three things were wrong, all of them the kind that only surface as a
byte mismatch in someone else's language:

  - headers/trailer are Data slots holding `count` then
    {keyLen,key,valLen,value}*, all little-endian. A repeated name is
    repeated pairs; there is no values list. An empty block is a null
    {0,0} slot, NOT a count=0 block.
  - streaming was "reserved for a follow-up slice"; it shipped.
    FrameResponseHead/FrameData/FrameEnd are 0x03/0x04/0x05, so the
    closing note's "today there are exactly two" type IDs was off by
    three.
  - the preamble credited a zap-proto/go runtime dependency that
    codec.go replaced by being its own encoder and decoder.

Also written down because a port gets them wrong once each: relOffset
is measured from the slot's own position, relOffset==0 is NULL whatever
the length word says, the frame is little-endian but the transport's
length prefix is big-endian, and Host/Content-Length are frame-owned so
they must never appear as pairs.

No code changes — the schema is documentation, not a codegen input
(Makefile: "no code-generation step"). wire.go's offsets remain the
binding; this makes the document agree with them.

Co-authored-by: Hanzo Dev <[email protected]>

2026-07-27 20:46:49 -07:00

..

zap_http.zap

docs(schema): the schema described a wire we stopped sending

2026-07-27 20:46:49 -07:00