Skip to content

std/live ​

From the spec

This page is spec/std/live.md, the specification the compiler and the backends are written from. It is rebuilt from the spec with every deploy (how).

Live connections between a page and its server, and live queries over them (docs/plan.md, Live connections and Live queries). The module's signatures are core/crates/weft-check/src/std/live.weft; the server side is the server runtime's (core/crates/weft-runtime/src/server/live.rs), the browser's is src/weft/live.ts, its own entry of the client (live.js, loaded only by pages that import std/live).

weft
import { channel } from "std/live"
import { openTodos } from "lib/server/todos"        // query fn openTodos(filter: Filter): Todo[]

derived todos = await openTodos({ done: false })    // an Async<Todo[]>, kept current
let chat = channel<Message>("chat")
effect {
  for await m of chat { messages.push(m) }          // until the effect ends
}
fn say(text: string) { chat.send({ text }) }

Live calls ​

  • A query fn awaited in an async derived value is live (language.md, Queries, mutations and actions; Async derived values): derived todos = await openTodos(filter) calls it and keeps the call: when a committed write could change its result, the server runs it again and sends the difference. The value follows: each change is a turn that sets the record's value (pending stays false; an error sets error and keeps value: the function's error, or a NetworkError when the connection fails, which the async derived value's body passes on by itself). The call's arguments are its reads: a change of one starts a new call, and the old one is dropped; unmounting drops it.
  • The checker makes such an await f(a, b) std/live's hidden $live(f, [a, b]) (both backends implement it). Any other call of a query fn, and every call of another kind, is one call.
  • Its result is the live value; a list of records is kept by key: its records' @primary fields (an id field when the type carries none), and the checker rejects a list of records with neither (live-key, E2027): a live list must select its table's key.
  • On the server, the call is the function's; server rendering waits for it like any awaited call, and the snapshot marks the async slot (ssr.md) with the call and the version it rendered, so the client subscribes from that version and gets only what changed since (no second fetch, no flash of pending).
  • The query fn's reads, in its own async context (std/db.md, Server functions), count as the live call's.

Live queries on the server ​

A live call runs in a request context made from the connection's (its request(), so the session's user is the caller's), and std/db reports every query it makes there:

  • The read set: per query, its database, table, key columns, principal (scoped or admin) and filter: an object query's conditions with their values, a Query<T> chain's first filter trees (later stages read only rows those give), a sql text's tables (the whole table), and the keys it returned. Relations and joins add their tables' reads.
  • The write set of every committed write: its table, the keys it changed and the rows before and after (inserts: after; deletes: before; sql writes and SQLite's update hook: the table as a whole). A transaction's writes count at its commit; a rolled-back one's never.
  • Matching goes table → filter → keys: a write hits a read of its table when one of its keys is one the read returned, or one of its row images satisfies the read's filter (object conditions and chain trees are evaluated on the row; what can't be evaluated, a sql read or a coarse change, hits). Only hit calls run again.
  • Coalescing: hits mark calls dirty; dirty calls run again once per tick (after the turns queued with the write, at most every WEFT_LIVE_TICK_MS, default 5 ms), however many writes hit them.
  • Fan-out: calls with the same server function, argument and principal scope (the principals and kinds of every handle their reads went through) are one call: it runs once per tick and its patches go to every subscriber. In one tick, identical queries (the same database, query and values, principal and kind) run once.
  • Diffs: a list of keyed records is sent as a patch by key (del: keys gone, put: records new or changed, order: the keys in order when it changed); anything else as the whole value. Each patch carries the call's version, one more than the last.
  • Writes that bypass the app: on Postgres, weft db migrate (and push) with live = true in weft.toml's [db] installs weft_live_notify() and an AFTER INSERT OR UPDATE OR DELETE trigger per table that sends the change on the weft_live channel (NOTIFY; the rows, or only their keys past 7,000 bytes). A server with live calls on a Postgres pool LISTENs there, ignoring its own connections' notifications. Without triggers, servers on one Postgres database send their committed write sets to each other on weft_live_bus, so several instances share invalidations either way. SQLite's update hook catches what the write set doesn't describe (cascades, sql writes) in the process.

Channels ​

  • channel<T: data>(name: string): Channel<T>, the same declaration on both sides (a module both import). Channel<T> = { name, send(value: T): void, subscribe(handler: (value: T) => void): () => void }; subscribe gives the function that ends it.
  • for await v of ch { body }, in an effect, listens to channel ch: body runs for each value as it arrives (a turn of its own, as a handler; it may write state, not await), and the effect's cleanup ends it. It is let off = ch.subscribe(v => body) with the effect returning () => off() (every for await of the effect): so an effect with one returns no cleanup of its own, and for await elsewhere, over something that isn't a channel, or with mut or an index is for-await (E4014). Server code subscribes with subscribe.
  • On the server, send reaches every connection subscribed to the channel, and subscribe gets what clients send on it (in the sending connection's request context: request() is the connection's request). In the browser, send goes to the server's subscribers only (with none, it is dropped), and subscribe gets what the server sends. Values arrive checked against T (as); one that doesn't check is dropped and reported.
  • allow(name, check: async (req: Request) => boolean) on the server decides who may subscribe to (and send on) a channel; without one, anyone with a connection may.

Connections ​

  • The page's client opens one connection, on first use: WebTransport (HTTP/3, one bidirectional stream) when the browser has it and the server offers it, else a WebSocket at /_weft/live. It first fetches a ticket (POST /_weft/live/ticket with x-weft-call: 1): the request it was fetched with (its cookies: the session) is the connection's, so std/http's sessions authenticate it, and another site can't open one in the user's name. A ticket is good once, for 30 s. GET /_weft/live/info says whether WebTransport is offered (its URL and its certificate's SHA-256 hash).
  • WebTransport listens on UDP when WEFT_LIVE_WT_PORT is set (0: a free port), with a self-signed certificate valid for 13 days (renewed by a restart) unless WEFT_LIVE_CERT/WEFT_LIVE_KEY name PEM files.
  • Frames are binary: a kind (one byte), a sequence number (8 bytes, big-endian; 0 on frames that have none) and a payload, the wire's value encoding as UTF-8 (server.md, The wire). On WebTransport each frame is preceded by its length (4 bytes, big-endian).
kindfrompayload
1 helloclient{ ticket, session?, last? }: a new connection, or one resuming session after sequence last
2 callclient{ id, file, name, args, token? }: a live call (token: the snapshot's, to continue from its version)
3 dropclient{ id }
4 join, 5 leaveclient{ channel }
6 sendclient{ channel, value }
7 ackclient{ seq }: every frame up to seq arrived
8 ping, 9 pongbothnull
101 welcomeserver{ session, resumed, seq }
102 resultserver{ id, v, value, key }: a call's whole value at version v, and the key columns it is diffed by (null: sent whole)
103 patchserver{ id, v, del, put, order? }, or { id, v, value } for a value without keys; the first one of a continued call also has key
104 errorserver{ id?, channel?, error }: a call that failed, a refused join
105 messageserver{ channel, value }
  • Sequence numbers: every result, patch, error and message has the connection's next number. The server keeps what the client hasn't acknowledged (up to 1 MiB); the client acknowledges every 32 frames or 100 ms.
  • Resume: a client that loses its connection reconnects (backoff from 100 ms to 5 s) with hello { session, last }. The server keeps a session 60 s after its connection drops (its calls go on running); when everything after last is still kept, it is sent again and nothing is lost (resumed: true). Otherwise (the gap is too large, the session is gone or belongs to another sign-in) the client makes every call again and rejoins its channels, each call starting with its result (a full resync); channel messages of the gap are lost.
  • Backpressure: while a connection has more than 256 KiB unacknowledged, its calls' changes wait, and when it drains each sends one patch from what the client last got. Channel messages past 1 MiB unacknowledged close the connection (the client then resumes or resyncs).
  • Heartbeats: the server pings a connection idle for 15 s and closes one silent for 45 s; the client reconnects when it has heard nothing for 45 s.
  • Limits per connection: 100 live calls, 32 channels, frames of 1 MiB; past them the frame is refused with an error (RangeError).
  • stats() (server) gives counters: { connections, calls, runs, reruns, skipped, coalesced, patches, cached } (skipped: writes that hit nothing; coalesced: hits folded into a run already due; cached: identical queries answered from the tick's first).

Decided here ​

  1. Live is a query fn awaited in an async derived value, not a keyword or a library call: the async derived value is what already re-runs on its reads and holds { pending, value, error }, and a query fn is what is safe to run again (read-only, deterministic). The call's arguments are its reads.
  2. A channel in a component is listened to with for await in an effect, so the listening ends with the effect without a cleanup to write.
  3. Calls are grouped by principal scope after their first run (what handles their reads used), not by session.
  4. A ticket fetched over HTTP authenticates both transports (WebTransport sends no cookies) and keeps other sites out without an Origin check.
  5. Patches by key, computed on the wire form; a value without keys is sent whole.

Weft is in development. The reference is the spec as it stands today.