Duolith docs

0166. Transports, live updates and resilience are options set on the domain, with measured defaults

  • Status: Accepted (Mik, 18 Nov 2026)
  • Date: 2026-11-18
  • Decided by: Mik asked on 18 Nov 2026 whether generated APIs could use "gRPC or some other extremely performant and highly secure protocol", then for WebSockets and newer protocols to be researched, for scalability and fault tolerance "similar to Elixir and Phoenix", and for these to be "configurable … I just want to know our options and how we can take inspiration from these different frameworks". This record is that map, with the integrator's proposed defaults, pending his approval.
  • Planning item: none (after version 1, with decisions 0163 to 0165)

Context

Decisions 0163 to 0165 give a generated server whose operations come from domain files and run through one compiled pipeline. They leave open how bytes travel between a client and that server, how a server tells clients that something changed, and how the server behaves under load and failure.

Two facts shape every answer here:

  • We generate both ends from one definition. Most of what a protocol like gRPC sells (a contract, typed clients, strict messages) the domain files already give. So a transport is a choice of wire, not of framework, and one operation can be offered over more than one wire at no cost to the author.
  • Our targets differ in what they can speak. A browser, a Cloudflare Worker, a Vercel function, Bun, Node and Axum do not support the same protocols. A default has to work on all of them. An option may work on some.

What is true on each target was checked on 18 Nov 2026. The sources are listed at the end. Where a source was a blog and not a specification, or where sources disagreed, the text says so.

What each target can speak

BrowserCloudflare WorkersVercelBunNodeAxum
HTTP/1.1 and HTTP/2, JSONYesYesYesYesYesYes
HTTP/3 to the clientYes, chosen by the browserYes, at Cloudflare's edgeYes, at Vercel's edgeExperimental in Bun.serve since 1.3.14 (May 2026)Experimental, behind --experimental-quicThrough a proxy or a QUIC crate
Native gRPC (HTTP/2 with trailers)No. Browsers do not expose what gRPC needsPrivate beta since August 2026: unary and server streaming, translated to gRPC-Web. No two-way streamingNoYes, node:http2 since 1.1.31YesYes
gRPC-Web and ConnectYes, with no proxyYes, plain requestsYesYesYesYes. The connectrpc crate is a Tower service, pre-1.0
Server-sent eventsYesYesYes, until the function's time limitYesYesYes
WebSocketYesYes, with Durable Objects that sleep between messagesYes since 2026, closed at the function's time limit (300 s, up to 800 s on paid plans)Yes, built inYesYes
WebTransportYes. Baseline since March 2026, Safari from 26.4Not foundNot foundNot yet ("a separate project")No built-in serverYes, by crate

Decision

1. One operation, several wires, chosen by settings

An operation in a domain file is not tied to a protocol. The build can offer it over any of the wires below. Which ones are on is set with the same four levels as store rules (decision 0165): the framework's default, the app in duolith.yaml, the domain, then one operation or model. Every name in these settings is resolved by the build (decision 0164, section 1a).

# duolith.yaml: the app's defaults
server:
  api:
    faces: [http]           # http | connect (which also answers gRPC and gRPC-Web)
    encoding: [json]        # json | binary. JSON is always answered
    batch: true             # calls made in the same moment travel as one request
  live:
    over: [sse]             # sse | websocket | webtransport, tried from the last to the first
    resume: true
  resilience:
    concurrency: adaptive   # adaptive | a number | off
    breakers: on
    workers: auto
# domains/prices.domain.yaml: one domain choosing differently
api: { encoding: [binary, json] }
shapes:
  Quote:
    identity: [symbol]
    live: true              # subscribers are told when a Quote changes
commands:
  placeOrder:
    concurrency: 8          # at most 8 running at once; the rest wait briefly or are refused

Whatever the wire, the request runs the same compiled pipeline (decision 0165). Limits, the caller, validation, allow: rules and the answer's field filter run after decoding, in the same order. A new wire cannot skip a step, and the security conformance suite runs against every wire that is on.

2. Requests and answers: the options

OptionWhat it isWhere it runsBorrowed fromProposed
HTTP and JSON over HTTP/2 and HTTP/3Queries are GET with a derived key, so a CDN can answer them. Commands are POST. Errors are RFC 9457EverywhereThe web itselfDefault
BatchingCalls a page makes in the same moment go as one request and come back as one streamed answerEverywhereCap'n Web's pipelining, tRPC's batch linkDefault for loaders and queries a page starts together. A query the CDN can answer (decision 0168) is left out of the batch and sent by itself, so the batch never hides it from the cache
Binary encodingThe same operations with bodies in the protobuf wire format. The encoder and decoder are generated from the shapes, with no library. Chosen by content type, with JSON always availableEverywheregRPC, ConnectOption, per domain or operation
Connect faceThe operations also answer the Connect protocol, and so gRPC and gRPC-Web, from the same handler. The build writes .proto files from the domains, so Swift, Kotlin, Go or Python clients can be generated by anyoneEverywhere for single calls. Two-way streaming only on Bun, Node and AxumConnect RPCOption, per app or domain
Native gRPC between servicesWhat the Connect face gives where the runtime has full HTTP/2, with mutual TLSBun, Node, AxumgRPCOption, comes with the Connect face
Shared dictionary compression (RFC 9842)The browser keeps a dictionary and the server sends only what differs. Cloudflare measured a 272 KB script at 2.6 KB against 92 KB with gzip. Chrome and Edge only todayStatic files first. API answers later, and never for an answer that mixes a secret with text the caller choseChrome, CloudflareOption for built files now. Watch for API answers
**HTTP QUERY** (RFC 10008, June 2026)A safe, cacheable request with a body, for queries too large for an addressSources disagree on whether fetch can send it yet, and caches do not key on the body yetThe IETFLater

Why JSON stays the default, and binary is an option. The honest reading of the evidence is that binary is not simply faster.

  • In browsers, JSON.parse is native code. One careful 2025 comparison found that some binary formats (Protobuf, Avro, Bebop) can beat JSON on a large, number-heavy payload. It also found MessagePack and CBOR among the slowest, and that compression "almost totally wipes out the size differences".
  • On phones, the app's script engine has no just-in-time compiler, so a decoder written in script may lose to the engine's own JSON parser. That has to be measured on a device before it is recommended there.
  • A cached answer at the edge beats any encoding, and only GET with JSON or binary bodies gets that for free. gRPC's POST to one address does not.
  • So the benchmark of decision 0165 gains a row per wire and encoding for each target, and the build report says, for a domain with encoding: [binary, json], what binary saved in bytes and time. An option that does not win in the measurement is not recommended in the docs.

Why not gRPC as the one protocol. A browser cannot speak it and neither can a Vercel function. A Worker speaks a translated subset. It would make the edge and the browser second-class, which are the two places this framework most needs to be fast. Offered as a face on the same operations, it costs the author nothing and gives other languages a client.

Why binary means protobuf's wire format. It is the most compact of the candidates when both ends know the schema, the browser evidence favours it over the self-describing formats, and it is what makes the Connect and gRPC face possible. Field numbers are assigned by the build, recorded in a lock file beside the domain, and never reused. duolith domains diff (decision 0164) fails a change that would renumber one. Our own decoder refuses unknown fields from our own clients, which the protobuf default does not.

3. Live updates: the options

Today stream() in a page listens to server-sent events or a WebSocket that the author's own server provides. With domains the server can do this itself, because it knows which model every answer holds and which command changes it.

**A model marked live: true tells its subscribers when it changes.** A page that reads state.load(prices.quote({ symbol })) is subscribed, with nothing more to write. When a command's changes: touches that model, the server pushes to the pages holding it. The push is either the new value or a notice to load again, by the model's store rules, and the data core updates every binding. Subscribing runs the same allow: rules as the query, per model key, so a client cannot subscribe to what it could not read.

OptionWhat it isFitsProposed
One multiplexed stream per clientEvery subscription of a client shares one connection, as Phoenix Channels share one socket for many topics. Here a topic is a model key, so there is nothing to nameAll of the belowDefault shape
Server-sent eventsOne long GET the server writes to. Rides HTTP/2 and HTTP/3, passes proxies and CDNs, and reconnects by itself. One-way, which is enough because commands already travel as requestsEverywhere, including Workers and VercelDefault wire
Resume from an offsetEach message has an offset. A client that reconnects asks for everything after the last one it saw, so nothing is missed across a dropped connection, a deploy or a function's time limitEverywhereDefault. Borrowed from Durable Streams and Phoenix's rejoin
WebSocketTwo-way and lower overhead per message. Worth it for high-frequency two-way traffic such as typing, cursors and gamesBun (built in), Axum, Node, Workers with Durable Objects, Vercel with reconnectsOption
WebTransportMany streams and unreliable datagrams over HTTP/3, with no stream blocking another. Baseline in browsers since March 2026Axum first. Bun and Node when their servers have itOption, Axum first
PresenceWho is here now, kept without a single point of failure. Phoenix does it with a merge-friendly data typeNeeds the shared storeLater
Pushed screen updatesPhoenix LiveView sends only the changed parts of a screen. Our render functions already split a screen into fixed text and holes, so a kept page could push only its changed holesServer companionLater, worth a spike

Between instances, a push travels through the store seam of decision 0165 as a new kind of state, live, with the same rules: Redis publish and subscribe, Postgres LISTEN, Cloudflare Durable Objects, or memory for one instance. Phoenix.PubSub is the model: the application publishes to a topic and does not know how many machines there are.

over: [sse, websocket] means the client tries the last and falls back toward the first. Every client can use server-sent events, so there is always a working wire. Connections carry a heartbeat, reconnect with a growing, randomised wait so a deploy does not bring every client back at the same instant, and are closed gracefully when a server drains.

4. Scaling and surviving failure: what we take from Elixir and Phoenix

Elixir runs on a virtual machine built for this: millions of isolated processes, each cheap to start and safe to lose, watched by supervisors that restart them. Our targets are not that machine, and no setting makes them one. JavaScript runs one thread per isolate with no pre-emption. What can be taken are the ideas, each mapped to what a target really has.

Idea in Elixir and PhoenixWhat we takeHow, per targetProposed
Processes are isolated. One failing does not harm anotherA failing request never harms another, and a failing part never takes the server downEvery request already has its own deadline and error step (decision 0165). On Axum each request is a task whose panic is caught. On Workers the platform gives each request an isolate. On Bun and Node, heavy or risky work can be marked runs: apart to run in a worker thread that can be killedDefault, with runs: apart as an option
Let it crash, under a supervisorThe generated server starts as a small tree of supervised parts: the listener, each store connection, the event publisher, the scheduler. A part that fails is restarted with a growing wait, and one that keeps failing marks the server not ready, so the platform replaces itGenerated into the server's entry on Bun, Node and Axum. On Workers and Vercel the platform is the supervisorDefault
Bounded mailboxes and back-pressure (GenStage, Broadway)The server refuses work it cannot finish in time, rather than queueing without limit and failing everythingAn adaptive limit on running requests, per operation, that grows while latency is healthy and shrinks when it rises. Past it, a request waits briefly, then gets 503 with Retry-After. concurrency: on an operation sets a fixed bulkhead insteadDefault: adaptive
A failing dependency is cut off (the fuse library)A store or outbound service that keeps failing is not called for a while, and the store rule's ifDown applies at once instead of after a timeoutCircuit breakers generated around each store and each declared service, with their state in health and metricsDefault
Timeouts everywhere, passed downA request's deadline travels to every store call and outbound call it makes, so work for a caller who has gone is cancelledAbortSignal in JavaScript, a dropped future in Rust. Already in decision 0165, here made a rule for generated service calls tooDefault
Phoenix.PubSub and clusteringInstances share nothing in memory that matters. Anything shared goes through the store seam, so adding instances is the only step in scaling outDecision 0165's stores and the live kind above. Every core is used: reusePort on Bun, a cluster on Node, Tokio's threads on AxumDefault
Durable background jobs (Oban)Work that must happen later, or must not be lost, is a job stored before it runs, with retries, a limit on attempts, uniqueness by model identity and a scheduleDecision 0167: a job is a workflow of one step, declared under workflows:. There is no separate job mechanism and no runs: laterSee decision 0167
Telemetry events (:telemetry)Every step emits one named event with the same fields on every target, so dashboards and alerts are written onceThe Record step of decision 0165, with fixed event names in the specDefault
Hot upgrades and rolling deploysA deploy drops no request and no subscriber. A client built against an older domain version is told plainlyGraceful drain, resume by offset for live connections, and the build's domain version sent by the client. A server that can no longer serve that version answers with a typed "update needed"Default
Presence, LiveViewSee the live table aboveLater

What we do not claim: pre-emptive scheduling, a process per connection at Erlang's cost, or hot code swapping inside a running process. Axum comes closest and is the target to recommend when those properties matter most.

5. Security: what a transport adds, and what it does not

A binary protocol is not a more secure one. gRPC and JSON over HTTPS both rest on TLS, and an attacker can read a protobuf message as easily as JSON. What protects an API is who may call it, what is validated, and what is limited, which is the pipeline of decision 0165. The options that do add security are these:

OptionWhat it addsProposed
TLS 1.3 and HSTSAlready in decisions 0163 and 0165Default
The server holds the tokensWith the server companion, a browser gets only a __Host- session cookie. Access tokens for other services stay on the server. The sources call this pattern the safest for browser apps todayDefault for browsers
Sender-constrained tokens (DPoP, RFC 9449)A stolen token is useless without the client's private key. Each request carries a small signed proof. Strongest in native apps, where the key lives in the phone's secure hardware. In browsers a script injected into the page can still sign while the page is openOption, recommended for native apps and outside clients
Mutual TLSBoth ends prove who they are, for calls between servicesOption on Bun, Node and Axum
Signed requests (HTTP Message Signatures, RFC 9421)A request or webhook that cannot be altered or replayedOption. Inbound webhooks already verify signatures (decision 0165)
Strict decodingThe generated binary decoder checks every length against the shape's limit before reading, and refuses unknown fields, depth past the shape's own, and numbers out of rangeDefault whenever binary is on
Subscriptions are authorisedJoining a model's updates runs its allow: rules, and again when the caller's session changesDefault
Batches are counted honestlyA batch of ten calls counts as ten against limits, since cheap pipelining is also cheap for an attacker, as Cap'n Web's authors warnDefault

6. What we looked at and are not adopting

Looked atWhy not, and what we keep
Cap'n Web (Cloudflare, 2025, experimental)It has no schema and no validation unless added, and its wire is JSON. Its best idea, several dependent calls in one round trip, is the batching above
tRPC, oRPC, Hono RPCContracts are TypeScript types, so clients are TypeScript only. Domains already give those types, and other languages too
GraphQLA second query language and resolver layer, with caching and limits that are hard to make safe. A page's loaders batched into one request cover the same need
MessagePack and CBORSelf-describing, so larger than protobuf when both ends have the schema, and among the slowest decoders in the browser comparison
FlatBuffers and Cap'n Proto encodingsBuilt for reading in place from memory, which script engines do poorly. The comparison dropped Cap'n Proto as too slow there
Socket.IO-style librariesA dependency and a private protocol. The multiplexed stream above is generated

Stages

Each follows the stage of decisions 0163 to 0165 it depends on, and each is built for every target that can run it.

  1. Batching, the supervised entry, deadlines passed down, breakers and the adaptive limit. These are defaults, so they ship with the first generated server.
  2. live: true over server-sent events with resume, and the live kind in the store seam.
  3. Binary encoding, with the per-wire benchmark and the build report's comparison.
  4. The Connect face with .proto output, then native gRPC and mutual TLS between services.
  5. WebSocket as a live wire. DPoP. (Jobs are decision 0167.)
  6. WebTransport on Axum. Dictionaries for built files. Presence and pushed screen updates as spikes.

Alternatives considered

OptionWhy not
gRPC as the only protocolNot available to browsers or Vercel, a translated subset on Workers, and it gives up CDN caching of queries
Binary by defaultNot proven faster in browsers or on phones, harder to inspect, and the gain mostly vanishes under compression. On by measurement instead
WebSocket as the default live wireTwo-way is rarely needed, since commands are requests. Proxies and serverless limits cut sockets, and it does not ride HTTP/3 on today's runtimes
Depend on Connect's or gRPC's librariesA dependency in every server. The unary protocol is small enough to generate, and the Rust crate is still before 1.0. Revisit for streaming
One fixed choice with no settingsMik asked for a map of options. The targets differ too much for one wire to be best on all of them
Copy Erlang's process model in JavaScriptThe runtimes have no pre-emption or cheap isolation. Promising it would be false. We take supervision, limits and isolation where each target has them

Consequences

  • An author gets a fast, safe default with nothing to choose, and can turn on a wire or behaviour with one resolved setting on the domain, the model or the operation.
  • Every option multiplies the conformance and benchmark matrix by target. An option is added to the docs only when both pass on every target that claims it.
  • New language surface: api:, live:, resilience:, runs: apart and concurrency: in domain files and duolith.yaml, the field-number lock file, the live kind of state, and their diagnostics, schemas and fixtures.
  • stream() (decision 0020) stays for an author's own sources. Live models are the generated path and use the same client module.
  • The facts in the target table age quickly. The table carries its date, and the stage that builds each option checks it again first.

Sources read on 18 Nov 2026

  • Cloudflare Workers and gRPC: Cloudflare's blog of 3 Aug 2026 and InfoQ of 29 Aug 2026.
  • Connect for Rust: Buf's blog of 26 Aug 2026, docs.rs for connectrpc 0.9.1, Connect's RFC 007.
  • Bun: release notes for 1.1.31 (HTTP/2 server and gRPC) and 1.3.14 (experimental HTTP/3). Node: the node:quic documentation.
  • Vercel WebSockets: Vercel's documentation and guide. They disagree on beta or general availability, and a third-party note gives 20 Oct 2026 for general availability.
  • WebTransport: web.dev's Baseline digest for March 2026 and MDN.
  • Compression dictionaries: MDN, the web-features explorer, Cloudflare's blog of 17 Apr 2026.
  • HTTP QUERY: three secondary articles on RFC 10008, which disagree on fetch support. The RFC itself was not read.
  • Cap'n Web: Cloudflare's blog of 22 Sep 2025 and the project's README. Durable Streams: Electric's announcement of 9 Dec 2025.
  • Binary formats in browsers: Adam Faulkner's comparison of 23 Apr 2025. Its numbers are in graphs, so none are quoted here.
  • DPoP: WorkOS's explainer and InfoQ's article of April 2026, both secondary.
  • Elixir, Phoenix, Oban and Broadway are described from general knowledge, not from pages read today.

Mik's answers (18 Nov 2026)

  • Asked for a map of options, not one locked choice. Every option here is a setting.
  • "Build out everything" (18 Nov 2026), after the review of decisions 0163 to 0169.
  • Jobs are workflows of one step (decision 0167). There is no separate job mechanism.