Appearance
The server runtime
From the spec
This page is spec/std/server.md, the specification the compiler and the backends are written from. It is rebuilt from the spec with every deploy (how).
How Weft runs as a server (weft run, weft dev): the threads, the event loop, limits, how host functions do real I/O, the value encoding on the network, and server functions over HTTP. The code is core/crates/weft-runtime/src/server/ (the crate's server feature); the modules on it are std/process, std/http, std/auth, std/app, std/sandbox, std/s3 and std/live (process.md, http.md, auth.md, app.md, sandbox.md, s3.md, live.md beside this page). std/time (time.md) is written in Weft and runs on every runtime. weft run seeds random numbers (std/random's random() and uuid(), std/db's @default(uuid)) from the system, so two runs of a script, or two instances of one app, never make the same ids; --seed n (or WEFT_SEED) gives a fixed seed instead. The test host keeps the VM's fixed seed.
One Weft thread per process
- A program runs on one thread: its VM, its loaded modules, every turn. A module's
let mutis process state (language.md, Modules) because there is exactly one of it per process: every request sees the same value. Values are reference counted without atomics and never leave this thread. - I/O runs beside it on a tokio runtime (
WEFT_IO_THREADSthreads, default 2): accepting connections, reading and writing HTTP, the client, timers' sleeps, files. What it produces is plain data (bytes, strings, numbers) sent to the Weft thread, which makes values of it. - Many requests at once: each request is turns on the Weft thread, interleaved with every other request's in the one FIFO queue (
language.md, Scheduling). While one awaits I/O, others run. A request's handler running long blocks the others only for that turn, which the deadline bounds. - To use more cores, run more processes (each with its own module state) behind a balancer. Sandboxed user code runs in VMs of its own (
sandbox.md).
The event loop
server::run loops until the program can do nothing more:
- set the VM's clock to the wall clock; run every queued turn (each followed by the flush); fire every timer that is due; run work queued for between turns;
- print the log's lines, panics, stops and unobserved task errors (stdout for
std/log'slog, stderr for the rest), and drop them; - if
exit(code)was called, end withcode; after SIGINT or SIGTERM, end with 0 once every server has closed; - if nothing is queued, no timer is pending, no I/O is in flight and no server is open, end; else wait for the next host answer or the next timer, whichever comes first.
A script ends when its work is done; a program that called serve runs until it is stopped. A task's error that nothing observes is reported when the queue drains, as in language.md.
Startup
weft run of a script keeps its compiled bytecode in a cache (weft-cli's bc_cache.rs), by a hash of the project's sources (.weft files, weft.toml, weft.lock) and of the weft binary: a run of an unchanged script loads it instead of checking and compiling. Apps, weft dev, programs with components and ones that use std/app or std/sandbox (which read the checked project as they run) aren't cached. The cache is $WEFT_CACHE_DIR, else $XDG_CACHE_HOME/weft/bytecode, else ~/.cache/weft/bytecode; WEFT_CACHE=0 turns it off.
Limits
A script (weft run of a program) has no limits: no fuel or memory limit per turn, no deadline and up to 100,000 active calls, unless WEFT_FUEL or WEFT_MEMORY_MB set one (0 means none). Once a program serves (it starts listening), its turns have the language's budget (language.md, Limits) as a server's: 50,000,000 fuel, 32 MB of allocation, 4,000 calls (WEFT_FUEL, WEFT_MEMORY_MB change them, 0 for none) and a deadline of 250 ms per turn (WEFT_DEADLINE_MS, 0 for none). A turn that runs out is stopped:
- a stop in a request's first turn answers it with a 500;
- a stop in a later turn (a continuation) abandons the task it would have settled, and every task waiting on it (an async caller, a
Task.all): no Weft code sees it end, but the host learns of it and answers the request with a 500 at once; - the server goes on serving; the stop is printed.
A request that takes longer than its server's timeout (30 s by default) is answered with a 504.
Host I/O
What a library's host functions use to do I/O (server::io::Io, documented on the type):
rust
// A host function starting an operation: it returns a pending task to Weft at once.
vm.register_host("std/db.query", true, move |vm, args| {
let sql = text(&args[1]);
let pool = pools.get(id_of(&args[0])); // a Rust object behind a handle
Ok(io.spawn(vm, async move { pool.query(&sql).await }, |vm, rows| match rows {
Ok(rows) => Settled::Value(rows_to_vals(vm, rows)), // on the Weft thread
Err(e) => Settled::fail(db_error(&e)), // a failure: a `DbError` value
}))
});Io::spawn(vm, future, done): runsfutureon the I/O threads;doneturns its output into the task's value or its failure (Settled::fail(err), an error value of the function's error type;Settled::Erroris a panic:bytecode.md, The host) on the Weft thread. What waits on the task runs as turns, in the order answers arrive. The program keeps running while a spawned operation is in flight.Io::hold(): keeps the program running while the guard lives (an open listener).Io::later(f): runsfwith the whole runtime between turns (work that needs more than the VM: rendering a page).Io::after(future, f): runsfutureon the I/O threads, thenfwith the runtime and its output on the Weft thread (host work waiting on I/O without a task: loading an S3 user tree before serving from it).Io::remote(): what an I/O thread holds to run work on the Weft thread.Vm::then_host(task, f): a host continuation on a task, run as a turn of its own when it settles or is abandoned (HostOutcome::SettledorStopped).Vm::native_closure(host, n, captures): a function value calling host functionhostwithcapturesbefore its ownnarguments; how the host gives records with methods (router().get(…), a database handle'squery).- Rust objects behind values are handles (
Val::handle(kind, id)), kept in a table of the library's, on the Weft thread. - Other libraries register their host functions with a
register(vm: &mut Vm, io: &Io)called next toserver::install, before the program loads.
The async context
std/http's request() gives the request the running code serves. The VM carries a host async context with every call (a callee inherits its caller's) and every await (a continuation resumes in the context it was suspended in); the server starts each request's turns in a context of its own and keeps the request under it until it is answered. Timers' callbacks and code the host calls outside a request run in none (request() is null). Nothing in the language changes: this is the host's bookkeeping, read through request().
The wire
Server functions and typed endpoints carry values as JSON: JSON itself where JSON says the value exactly (null, booleans, finite numbers other than -0, strings without lone surrogates, lists, records), and an object tagged "$" for the rest, as the snapshot does (ssr.md, The snapshot):
| value | wire |
|---|---|
NaN, Infinity, -Infinity, -0 | { "$": "number", "v": "NaN" } … |
| a string with a lone surrogate | { "$": "string", "units": [ …code units… ] } |
Map | { "$": "map", "v": [[k, v], …] } |
Set | { "$": "set", "v": [ … ] } |
Bytes | { "$": "bytes", "v": "<base64>" } |
a record with a field starting with $ | { "$": "record", "v": { … } } |
A function, task or handle can't be sent (a panic). Decoding gives json objects for objects; the receiver's as against its declared type checks them (validating types included) and makes records of them. So every value crosses exactly, and every value that arrives is checked.
Server functions over the network
- The client calls a server function as
POST /_weft/server/<file id>/<name>with the arguments' list in the wire form as its body andx-weft-call: 1(which a form on another site can't send: a call without it is a 403). A call a browser says comes from another site (sec-fetch-site, elseorigin) is a 403 too (auth.md, CSRF). The server calls$server.<name>(each argumentasits parameter's type, then the function;bytecode.md) in the request's async context, and answers{ "ok": value }(status 200), or{ "error": e }with the error the function failed with, in the wire form: status 200, or 401, 403 or 429 forstd/auth'sUnauthorized,ForbiddenandRateLimited. Arguments that don't check are a 400, no such function a 404, and a panic or a stop a 500, each with{ "error": { message } }; a panic or stop is printed. Cookies set while it ran (std/auth'ssignIn) go on the answer. - Every
query fn,mutation fnandaction fnhas an entry, exported or not, in a module or a component. - In the browser, the compiler's call is
$.serverCall(file, name, args, resultType): it goes throughRuntimeOptions.server(by defaultfetchServer(): the page's server) and checks the result, or the error, against the declared type on arrival: the call isTask<R ! E | NetworkError>. A call that fails on the way (no connection, an answer that isn't a value or doesn't check) fails withNetworkError { message }, and a 400, 404 or 500 answer withNetworkError { message, status }; an error the server sent is the function's error, as it failed with it. - Client code may import a server module's (
lib/server/**, aserver.weft) server functions and types (spec/app.md, The tree). For the browser such a module compiles to its server functions' calls only; another module keeps the rest of its code; and the server serves only modules the app's entry reaches. - On the server, a page's call of a server function runs in process (no HTTP), in the page request's async context: a
Task<R ! E>, withoutNetworkError.
Typed endpoints
A server.weft's typed methods (spec/app.md, Links) get the same entries. GET <path> calls get: its argument is built from the query parameters by its declared record type (a string field as it is, number and boolean fields parsed, a list field from the key repeated, anything else as JSON text) and checked; POST/PUT/PATCH/DELETE take the argument as a JSON (wire) body (content-type: application/json only, a 415 otherwise, and from this site only: auth.md, CSRF). The result is the wire form of the value (plain JSON for ordinary data); a typed method that fails answers { "error": e } as a server function does (and the client's call gets it, or a NetworkError); a refused argument is a 400 with { "error": … }. In the browser, routes.api.todos.get(args) goes through RuntimeOptions.endpoint (by default fetchEndpoint()), its result checked on arrival. Raw GET(req) handlers serve as they are.
Development
weft dev <file or project> runs the program as a child process and watches the project's files (every file but hidden ones, build/, node_modules/, target/ and data/). When one changes and the project still checks, a new child replaces the old one (module and server state start over); a project that stops checking keeps the last child running and prints the errors. In development a 500's body carries the error (its JSON) or the panic's name and message.
- An app (a project with
routes/) is served throughweft dev's own front door onHOST:PORT(default127.0.0.1:3000), which answers the editor protocol and passes every other request to the child (spec/editor-protocol.md, The server). The new child starts beside the old one and takes over once it serves; the pages then swap the new build's modules in, keeping their components' state (hot swap), instead of reloading. A page that ships no JS reloads (/_weft/dev). - A script (
maininweft.toml) serves on its own; the pages it served reload when it restarts (/_weft/dev, an event stream naming the server; a page whose stream reconnects to another one reloads).
Decided here
- One Weft thread per process, with I/O on tokio beside it, rather than a VM per request or per worker: module state is process state only that way, and values stay unshared.
- A program that serves gets the 250 ms deadline per turn; a script none.
- A stop in a continuation abandons the tasks waiting on it (the host is told; Weft code is not), so a request is answered at once instead of waiting for its timeout.
- Page renders on one runtime run one at a time (their instances are mounted in it); other requests' turns run while a render waits. After each render everything it made is freed (
Runtime::reset_render,Vm::free_instances): instance ids are never reused, so a stale continuation finds its instance gone. - The wire is the snapshot's form plus
Bytes, and objects decode as json for the receiver'sasto check. x-weft-call: 1on server function calls, against cross-site forms, and the browser's word on where a call comes from (sec-fetch-site,origin) against sibling sites and lax CORS policies (auth.md).request()through the host's async context, so server functions and typed endpoints can see the session's user without a parameter the client would have to pass.- A server function's error is an answer (200 with
{ "error": e }, std/auth's with their status): the function's type says it, so it is data like the result; only a panic or a stop is a 500.