Appearance
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 fnawaited 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'svalue(pendingstaysfalse; an error setserrorand keepsvalue: the function's error, or aNetworkErrorwhen 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'
@primaryfields (anidfield 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 ofpending). - 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 firstfiltertrees (later stages read only rows those give), asqltext'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;
sqlwrites 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
sqlread 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(andpush) withlive = trueinweft.toml's[db]installsweft_live_notify()and anAFTER INSERT OR UPDATE OR DELETEtrigger per table that sends the change on theweft_livechannel (NOTIFY; the rows, or only their keys past 7,000 bytes). A server with live calls on a Postgres poolLISTENs there, ignoring its own connections' notifications. Without triggers, servers on one Postgres database send their committed write sets to each other onweft_live_bus, so several instances share invalidations either way. SQLite's update hook catches what the write set doesn't describe (cascades,sqlwrites) 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 };subscribegives the function that ends it.for await v of ch { body }, in aneffect, listens to channelch:bodyruns 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 islet off = ch.subscribe(v => body)with the effect returning() => off()(everyfor awaitof the effect): so an effect with one returns no cleanup of its own, andfor awaitelsewhere, over something that isn't a channel, or withmutor an index isfor-await(E4014). Server code subscribes withsubscribe.- On the server,
sendreaches every connection subscribed to the channel, andsubscribegets what clients send on it (in the sending connection's request context:request()is the connection's request). In the browser,sendgoes to the server's subscribers only (with none, it is dropped), andsubscribegets what the server sends. Values arrive checked againstT(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/ticketwithx-weft-call: 1): the request it was fetched with (its cookies: the session) is the connection's, sostd/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/infosays whether WebTransport is offered (its URL and its certificate's SHA-256 hash). - WebTransport listens on UDP when
WEFT_LIVE_WT_PORTis set (0: a free port), with a self-signed certificate valid for 13 days (renewed by a restart) unlessWEFT_LIVE_CERT/WEFT_LIVE_KEYname 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).
| kind | from | payload |
|---|---|---|
1 hello | client | { ticket, session?, last? }: a new connection, or one resuming session after sequence last |
2 call | client | { id, file, name, args, token? }: a live call (token: the snapshot's, to continue from its version) |
3 drop | client | { id } |
4 join, 5 leave | client | { channel } |
6 send | client | { channel, value } |
7 ack | client | { seq }: every frame up to seq arrived |
8 ping, 9 pong | both | null |
101 welcome | server | { session, resumed, seq } |
102 result | server | { id, v, value, key }: a call's whole value at version v, and the key columns it is diffed by (null: sent whole) |
103 patch | server | { 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 error | server | { id?, channel?, error }: a call that failed, a refused join |
105 message | server | { channel, value } |
- Sequence numbers: every
result,patch,errorandmessagehas 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 afterlastis 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 itsresult(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
- Live is a
query fnawaited 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. - A channel in a component is listened to with
for awaitin an effect, so the listening ends with the effect without a cleanup to write. - Calls are grouped by principal scope after their first run (what handles their reads used), not by session.
- A ticket fetched over HTTP authenticates both transports (WebTransport sends no cookies) and keeps other sites out without an
Origincheck. - Patches by key, computed on the wire form; a value without keys is sent whole.