@lesomnus/grpc-dgram 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+`@lesomnus/grpc-dgram` is the TypeScript port of gRPC-dgram. The wire
+protocol it speaks is unversioned by design (`docs/PROTOCOL.md`, §10.6); a
+package version is a cut of that text at one date, and a minor bump while the
+major is 0 means the wire broke. Both ends of a channel must be deployed
+together.
+
+## 0.1.0 — 2026-09-12
+
+**Wire, breaking against 0.0.1** — a peer on 0.0.1 cannot talk to one on
+0.1.0:
+
+- `Metadata` is an ordered list of entries, `repeated Entry { key, values }`,
+  emitted in ascending key order; a receiver merges a repeated key (§11).
+- `Frame.conn_window` (field 18) advertises the connection window: the client
+  on every OPEN, the server on every H and T. The assumed-then-raised window
+  is gone, with everything that existed only for it (§4.2.1).
+- The wire unit is spelled `Envelope`; the adapter seam is `EnvelopeSender`
+  (`sendFrames`) beside `FrameHandler`, and batching is a seam, not a
+  component (§4.1).
+- Field 6 is unassigned and held for `ack`; a breaking generation of the wire
+  sets flag bit 64 on the first frame of every call (§10.6).
+- A proto `string` field that is not valid UTF-8 makes the envelope
+  undecodable and dropped whole, as in the Go core (§5, §11).
+
+**Behaviour**
+
+- The per-peer connection window (`limits.maxPeerWindow`, §4.2.1): one ledger
+  per peer, `sid = 0` grants, overrun fails only the offending call.
+- A call RESET before the `Conn` has locked to a server incarnation refunds
+  the connection credit its frames took (§4.2.1 *Sending*).
+- Interceptors: `interceptors: [...]` on `ConnOptions` and `ServerOptions`,
+  unary and stream, chained in gRPC's order.
+- `ProtocolStats` and `Counters` (§14), so a browser client reports gaps.
+- WebTransport datagrams: `@lesomnus/grpc-dgram/transport/webtransport`.
+- The wasm bridge: `dial({ entryPoint })` for a second server in one
+  instance, a per-dial `readyTimeoutMs`, and the timers a Go program leaves
+  pending are cancelled when it exits.
+
+## 0.0.1 — 2026-08-08
+
+First publish. Deprecated on 2026-09-12: it speaks a wire that 0.1.0 broke.

package/README.md

@@ -1,12 +1,12 @@
 # @lesomnus/grpc-dgram
 
 TypeScript port of [gRPC-dgram](../): gRPC-style RPC over unreliable datagram
-channels, implementing the **dRPC wire protocol v1.1** (`../docs/PROTOCOL.md`).
+channels, implementing the **dRPC wire protocol** (`../docs/PROTOCOL.md`).
 Wire-compatible with the Go implementation — the §5 golden byte vectors are
 shared between the two test suites — so a TS client interoperates with a Go
 server and vice versa.
 
-- **Zero runtime dependencies.** The three wire messages (`Frame`, `Envelop`,
+- **Zero runtime dependencies.** The three wire messages (`Frame`, `Envelope`,
   `Metadata`) are hand-encoded; user payloads go through pluggable
   per-method marshallers (protobuf-es, JSON, anything that produces bytes).
   A **protobuf-es binding** (`@lesomnus/grpc-dgram/transport/protobuf-es`, optional peer
@@ -17,22 +17,37 @@ server and vice versa.
   mode machinery: seq windows and dedup, epoch/`peer_epoch` incarnation
   isolation, control-frame retransmission, tombstones + aged watermark,
   PING/probe liveness, and the §15 resource caps. On a reliable transport all
-  timers are off, sequencing is strict fail-loud (§10.6), and **per-stream
-  flow control** (§4.2.1) keeps one slow consumer from stalling the other
-  calls on the channel — the browser case where a blocked receive path would
-  otherwise wedge the whole event loop.
-- **v1.1 surface.** Binary metadata (`-bin` keys carry arbitrary octets;
+  timers are off, sequencing is strict fail-loud (§10.6), and **flow
+  control** (§4.2.1) keeps one slow consumer from stalling the other calls on
+  the channel — the browser case where a blocked receive path would otherwise
+  wedge the whole event loop: a credit window per stream, and beside it a
+  connection window per peer (`limits.maxPeerWindow`, 1024 messages by
+  default, advertised on every OPEN by a `Conn` and on every H and T by a
+  `Server`) that bounds what one peer can pin across *all* of its calls, as
+  HTTP/2's does.
+- **gRPC-fidelity surface.** Binary metadata (`-bin` keys carry arbitrary octets;
   base64 at the TS API, raw bytes on the wire), rich status details on the
   terminal frame, per-message compression (`gzip` via the platform's
   `CompressionStream`, never expanding a payload), per-call recv/send size
   caps, and the shape/modifier flag split (§7.1) — an unimplemented flag bit
   fails the call instead of silently corrupting or gapping it.
 - **WebSocket adapter** (`@lesomnus/grpc-dgram/transport/websocket`), the TS
-  twin of the Go `transport/gorilla` adapter: reliable mode, one Envelop per
+  twin of the Go `transport/gorilla` adapter: reliable mode, one Envelope per
   message, and the §4.5 teardown duty carried by `onclose`/`onerror` plus a
   keepalive — browser-safe (WhatWG `WebSocket`, `binaryType='arraybuffer'`).
   `dialWebSocket(url)` is a `Conn` in one line; `new WebSocketTransport(ws)` is
   the path for a socket you brought yourself.
+- **WebTransport datagram adapter** (`@lesomnus/grpc-dgram/transport/webtransport`),
+  the TS twin of the Go `transport/webtransport` adapter: unreliable mode over
+  the session's datagrams, one Envelope per datagram — the browser's datagram
+  channel with no signaling, a URL and nothing else. `dialWebTransport(url)` is
+  a `Conn` in one line (`https://` only; `serverCertificateHashes` pins a
+  development certificate), `new WebTransportDatagramTransport(wt)` the path
+  for a session you brought. The size ceiling follows the session's own
+  `datagrams.maxDatagramSize` (1200 B when it reports none), and the §4.5
+  teardown comes from the session — `closed` settling, `ready` rejecting — not
+  the read loop. Client only: Node has no `WebTransport`, so the server side is
+  the Go module.
 - **Message-port adapter** (`@lesomnus/grpc-dgram/transport/port`), the TS twin
   of the Go `transport/jsport` adapter: `PortTransport`/`PortGateway` over
   anything with `postMessage` and a `message` event — a `MessagePort`, a
@@ -72,7 +87,8 @@ server and vice versa.
 
 **Getting a connection.** Four cases, and the verb says which:
 `new Conn(new XTransport(ch), opts)` when you already hold the channel;
-`dialUdp` / `dialWebSocket` / `dialWorker` when the library should make it —
+`dialUdp` / `dialWebSocket` / `dialWebTransport` / `dialWorker` when the
+library should make it —
 each hands back a `Conn`, and takes one options bag, since `ConnOptions` and an
 adapter's own options share no key; `open(app)` when there is no peer yet,
 which returns a `Sock` whose `dial()` is the connection; and, on the serving
@@ -204,34 +220,58 @@ else maps to `UNKNOWN`).
 | `drpc.ErrMessageTooLarge` | `MessageTooLargeError` (adapters throw it or set it as `cause`) |
 | `NewPeerContext` / `NewReliableContext` | `FrameContext { peer, reliable, signal }` argument to `handle` |
 | mutexes + atomics | none needed: state transitions are synchronous between `await` points |
-
-Deliberately not ported (yet): client/server interceptors, the observability
-surface (Go's `stats.Handler` + `ProtocolStats`), and `Envelop` batching
-(`Coalescer` — deferred to M8 in Go; every envelop carries one frame, as the
-shipped Go adapters do).
+| `WithProtocolStats(obs)` (repeatable) | `protocolStats: obs` or `protocolStats: [obs, …]` on `ConnOptions` / `ServerOptions`; `Counters.observe` is the ready-made observer |
+| `ProtocolEventKind` (`EventSkipped` … `EventFlowStall`, `EventFlowResume`, `EventPeerFlowStall`, `EventPeerFlowResume`) | `ProtocolEventKind`, the strings Go's `String()` fixes (`'skipped'` … `'flow-stall'`, `'flow-resume'`, `'peer-flow-stall'`, `'peer-flow-resume'`); `Counters` keeps `flowStall` / `flowResume` and `peerFlowStall` / `peerFlowResume` apart, as Go does |
+| `WithLimits(Limits{MaxPeerWindow: n})` (the §4.2.1 connection window) | `limits: { maxPeerWindow: n }` on `ConnOptions` / `ServerOptions` — advertised as `Frame.connWindow` on every OPEN (`Conn`) and on every H and T (`Server`), the peer honouring the first it hears; floored at `W_CONN` (1024, exported beside `W_INIT`) because a client streams on that assumption until the server's first H or T; capped at 2³² − 1 — the wire's uint32 — so `Infinity` means that much, not off |
+| `WithChainUnaryInterceptor(…)` / `ChainUnaryInterceptor(…)` and the stream twins | `unaryInterceptors: […]` / `streamInterceptors: […]` on `ConnOptions` / `ServerOptions` — same order (element 0 outermost), `(req, call, next)` shape; see `docs/typescript.md` |
+
+Deliberately not ported (yet): the `stats.Handler` bridge (a grpc-go type; the
+drpc half of the observability surface,
+`ProtocolStats`/`Counters`, is ported — `protocolStats` on `ConnOptions` and
+`ServerOptions`, `docs/observability.md`).
+
+Batching is the application's policy in both languages and neither ships a
+batcher (`docs/TODO.md` §1); both ship the seam to write one against. Here it
+is `EnvelopeSender`, implemented by every exported adapter class as
+`sendFrames`, with `handle` delegating to it so an override reaches the same
+code the core would. It
+mirrors that class's own `handle`: `sendFrames(frames)` where `handle` takes
+a frame alone, `sendFrames(frames, ctx)` where `handle` takes a
+`FrameContext` — on the gateways the ctx *is* the address, so a batch may
+hold only frames whose contexts name one peer. Subclass the adapter and override `handle`: the core finds
+`reliable()`, `attachConn()` and `close()` structurally, so the prototype
+keeps all three. `src/transport/node-udp/batcher.test.ts` is the worked
+example, per-peer gateway batching included.
 
 Receive-path note for browsers: an `RTCDataChannel` cannot pause delivery, so
-adapter-level buffering is unavoidable — but since v1.1 the *protocol* paces
+adapter-level buffering is unavoidable — but since per-stream flow control the *protocol* paces
 the sender instead of the receiver (§4.2.1 flow control), so a slow consumer
 no longer needs the receive path to block at all, and never stalls the other
 calls sharing the channel.
 
 ## Tests
 
-`pnpm test` — 353 tests mirroring the Go suites: the §5 golden wire vectors
-byte-for-byte (including the v1.1 vectors generated from the Go
+`pnpm test` — 575 tests mirroring the Go suites: the §5 golden wire vectors
+byte-for-byte (including the 2026-07-25 vectors generated from the Go
 implementation), e2e for all four RPC types, the §10 timeout system under
 deterministic fake-timer loss (blackhole, lost terminals/acks/half-closes,
 probes, liveness), the §6.5 restart walkthroughs, §15 caps and §4.2 drop
-policies, §4.2.1 flow control (advertisement, parking, grants, `T_stall`,
-overrun), compression, size caps and binary metadata, each adapter
-(WebRTC/WebSocket/Port/UDP/protobuf-es/Connect) next to its source, `open()`
+policies, §4.2.1 flow control — per stream (advertisement, parking, grants,
+`T_stall`, overrun) and per peer (the advertisement on every OPEN / H / T and
+its once-only adoption, the `W_conn` assumption until it arrives, absent =
+off, `sid = 0` grants, the starvation clause, credit returned for every
+non-buffered frame, one stall budget across both windows, the evicted
+sender's stash) — compression, size caps and binary metadata, each adapter
+(WebRTC/WebSocket/WebTransport/Port/UDP/protobuf-es/Connect) next to its
+source, `open()`
 and the worker it ships against a fake `Go` (`src/wasm/`), and two
 cross-language conformance tests driving a real Go `drpc.Server`: one over
 loopback UDP, one a `js/wasm` build of the server loaded into the test process
 and talked to across a `MessageChannel` — the second being where reliable mode
 is genuinely reliable rather than asserted, so the §4.2.1 windows are exercised
-between the two implementations.
+between the two implementations — per stream, and on `sid = 0` past `W_conn`
+each way across three streams, which completes only because both ends grant
+on the connection window.
 
 **Layout.** Unit and per-adapter tests are **co-located** next to their source
 (`src/wire.test.ts`, `src/transport/webrtc/index.test.ts`, …); cross-cutting