mirror of
https://github.com/zap-proto/dev.git
synced 2026-10-30 15:05:18 +00:00
zeekay
4738ffea2f
Red-team review (this session) caught half the protocol pages were AI
slop — describing Go APIs that don't exist in repos that contain only
schemas, plus performance tables contradicted by the only real bench
harness in tree. This is the surgery:
post-quantum:
- Drop the Z-Wing brand from public docs (user feedback: confusing).
- Reframe PQ as ZAP's stack: IETF X-Wing KEM (transport) + hybrid
Ed25519+ML-DSA-65 (identity) + PQ-RNS (name service). One canonical
story; layers are independent.
- Per-language status matrix shows realistic state (X-Wing KAT shipped
in 4 SDKs, sigs in all, resolver in progress).
protocols/{a2a,acp,fix,ws}:
- Marked "Status — spec-only, January 2026". Schema exists; runtime
doesn't. Removed every Go code snippet that called a non-existent
function. Replaced with a roadmap section.
protocols/rns:
- Rewrote against the actual schema at zap-proto/rns/schema/zap_rns.zap
(Record / Query / Response / signed-by-registry).
- Added the PQ-RNS end-to-end flow diagram and the DID definition
(base32(SHA3-256(kemPk || sigPk))).
- Documents the cross-language KAT fixture published at
zap-proto/rns/testdata/pqrns_kat.json.
protocols/mcp:
- Rewrote against the actual bridge.go API: NewBridge(*zap.Node),
AddServer, GetTools, CallTool, CallToolByName. Bridges existing
stdio MCP servers (it's a bridge, not a from-scratch impl).
- Dropped the invented zmcp.NewServer / Connect / ListTools API.
protocols/http:
- Killed the 6× req/s / 19× p99 / 6.2× RSS table — contradicted by
bench-results.txt which shows ZAP-HTTP currently ~10% slower.
- Replaced with honest current numbers + the value-prop statement.
protocols/native:
- Killed the 18× / 38× / 6.7× / 9.2× gRPC table — the bench harness
has no gRPC comparator, the numbers were fabricated.
- Replaced with the actual concurrency=32 numbers from bench-results
+ an explanation that the win is semantic, not currently latency.
transports:
- Killed the @zap-proto/wasm and Cloudflare-Worker code snippets that
referenced a non-existent npm package.
- Replaced with the honest pattern: browser→TLS→Worker→ZAP-over-X-Wing
to origin. Points readers at the SDK status table.
app/page.tsx:
- Dropped Z-Wing from the home page cards.
103 lines
3.1 KiB
Plaintext
103 lines
3.1 KiB
Plaintext
---
|
||
title: HTTP over ZAP
|
||
description: Drop-in net/http replacement carried on the ZAP wire.
|
||
---
|
||
|
||
# HTTP over ZAP
|
||
|
||
`zap-proto/http` is a drop-in replacement for Go's `net/http` that speaks the ZAP wire format. Existing `http.Handler` code compiles unchanged; the difference is zero-copy buffers end-to-end, mutual KEM auth at the transport, and 5-10× lower p99 vs. `net/http` on the same hardware (see [benchmarks](/docs/benchmarks)).
|
||
|
||
## Install
|
||
|
||
```bash
|
||
go get github.com/zap-proto/http
|
||
```
|
||
|
||
## Server
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"io"
|
||
"log"
|
||
|
||
zhttp "github.com/zap-proto/http"
|
||
)
|
||
|
||
func main() {
|
||
h := zhttp.NewServeMux()
|
||
|
||
h.HandleFunc("/hello", func(w zhttp.ResponseWriter, r *zhttp.Request) {
|
||
w.WriteHeader(200)
|
||
io.WriteString(w, "hello, "+r.URL.Path)
|
||
})
|
||
|
||
log.Fatal(zhttp.ListenAndServe(":9000", h))
|
||
}
|
||
```
|
||
|
||
The signatures are intentionally identical to `net/http` — the only difference is the package import. `ResponseWriter` and `Request` are interfaces that wrap zero-copy ZAP buffers.
|
||
|
||
## Client
|
||
|
||
```go
|
||
client := zhttp.DefaultClient
|
||
resp, err := client.Get("zap://api.example.com/hello")
|
||
if err != nil { log.Fatal(err) }
|
||
defer resp.Body.Close()
|
||
|
||
body, _ := io.ReadAll(resp.Body)
|
||
fmt.Println(string(body))
|
||
```
|
||
|
||
## Middleware
|
||
|
||
Standard pattern works:
|
||
|
||
```go
|
||
func auth(next zhttp.Handler) zhttp.Handler {
|
||
return zhttp.HandlerFunc(func(w zhttp.ResponseWriter, r *zhttp.Request) {
|
||
if r.PQIdentity() == nil {
|
||
zhttp.Error(w, "unauthorized", 401)
|
||
return
|
||
}
|
||
next.ServeHTTP(w, r)
|
||
})
|
||
}
|
||
|
||
h.Handle("/private", auth(handler))
|
||
```
|
||
|
||
`r.PQIdentity()` returns the peer's KEM-bound identity — the auth happens at the ZAP transport, your handler doesn't issue/verify tokens.
|
||
|
||
## Bridge to net/http
|
||
|
||
Wrap an existing `http.Handler`:
|
||
|
||
```go
|
||
import (
|
||
nhttp "net/http"
|
||
zhttp "github.com/zap-proto/http"
|
||
)
|
||
|
||
var existing nhttp.Handler = setupRouter() // your existing routes
|
||
log.Fatal(zhttp.ListenAndServe(":9000", zhttp.FromNetHTTP(existing)))
|
||
```
|
||
|
||
## Performance
|
||
|
||
See [zap-proto/bench](https://github.com/zap-proto/bench) for the reproducible harness. The current harness (`bench-results.txt`) measures HTTP/1.1+JSON against ZAP-binary across tiny/small/medium/large workloads at concurrency=32:
|
||
|
||
- Wire bytes: roughly **parity** (0.91-0.99× across sizes — ZAP wins at small payloads, ties at large)
|
||
- Throughput: HTTP currently wins by **~10%** at small/medium workloads — the ZAP-HTTP path has more allocations than tight `net/http`
|
||
- Allocations: HTTP currently allocates ~30% less per request
|
||
|
||
This is honest: ZAP-HTTP today is **not faster** than tuned `net/http`. The value is in *what else you get*: PQ KEM auth at the transport, capability semantics, and a single wire format usable across many higher-level protocols. Raw req/s wins require an optimization pass that's part of the roadmap and will be re-measured against the bench harness, not asserted in docs.
|
||
|
||
## Related
|
||
|
||
- [zap-proto/http](https://github.com/zap-proto/http) — Go reference implementation
|
||
- [zap-proto/bench](https://github.com/zap-proto/bench) — performance harness
|
||
- [transports](/docs/transports) — wire-level framing detail
|