Loam: durable objects
Loam is glowcap’s storage module for objects and the references they hold. It runs inside your program, saving their state across restarts and loading objects as they are used. The stored graph can be larger than memory.
Consider a shared task board. Bob holds a reference to its “to do” column. Carol keeps a sturdyref to the board, a saved reference that fetches it by name. Restoring the board means recovering its cards and columns together with the access those references gave.
Live network references end when the server stops. Peers use saved names to reconnect to the restored objects.
Programs that host durable objects configure a store during startup. Rooms already handles that in its session runtime. Peers calling those objects use ordinary glowcap references and need no local store. The integration guide covers setup for each API. Concepts covers references and sturdyrefs if they are new to you.
Objects are records, references are edges
Each object is a record: its data, plus edges pointing at other records. “The to-do column holds card #12” is an edge. An edge names a record, not a memory address, which is why it survives a restart.
A strong edge keeps its target alive. A weak one doesn’t. A root keeps a record alive until the application removes that root. Loam also keeps anything reachable from a root along strong edges.
Everything else is garbage once the running program stops holding it, even two records that point at each other. Collection deletes it in small batches you schedule.
Changes are transactions. Moving a card touches two columns, and a transaction saves both changes or neither. Saving a transaction is called committing it.
Objects sleep until called
Most cards on a big board go untouched for months, so Loam lets them sleep: their state stays on disk, and every reference to them keeps working. A call wakes the card, runs it, saves the result, and only then replies.
The Host serves your program’s objects to peers. An attachment joins a Loam store to that Host. A Vat holds objects and runs their code one call at a time.
The reply waits for the save so nobody is told about a change a crash could undo. A crash can still land between the save and the reply, so the change is kept but the caller never hears back. If the caller retries, the change can happen twice. Write methods that are safe to repeat, or use managed access (described below), which keeps receipts for its changes.
Loam’s core decides which reads and writes are needed. Its SQLite and LMDB engines do the disk work, while the surrounding application or binding schedules it.
A card’s behavior receives its saved state and a call, then proposes a reply and new state. It does no I/O. A failed save can discard the proposal, but cannot unsend an email.
Restoring access after a restart
To keep Carol’s sturdyref working, the board gets a publication: a durable secret name, the swiss number at the end of her sturdyref, saved in an index on disk.
After a restart nothing loads until somebody asks. Carol’s fetch finds the name and wakes the board alone, and the column she asks for next wakes after it. Reopen the same store, register its schemas and behaviors, and serve it under the same reachable peer identity.
References inside a record work the same way. A reference to an object on another machine can be saved only if you already hold a sturdyref for it. Loam stores that sturdyref but can’t make one for you. A reference that can’t be found again, like an unresolved promise, is refused before anything is saved.
Sharing with people
Usually, sharing is handing over a reference. Some applications also need to see who has access and change it later. Managed access keeps that record for you, beside the objects.
A grant gives permission over a resource and what sits below it. Bob gets a use reference to access the resource. Alice keeps a separate control reference to pause, resume, or revoke the grant. Bob can use his access but not change it.
If Bob shares onward, the new grant sits under his and is never wider. Every use is checked against all the grants above it, so revoking Bob’s grant cuts off everyone he shared with.
Limits
- Timers, unresolved promises, subscriptions, and handles to outside resources can’t be saved. An interrupted call does not resume after restart.
- Performance charts call latency, memory and restart time from one machine.
- Recovery is tested by killing the process mid-write, not by cutting power. The table of checks lists every Loam check.
- Loam’s full API is in Zig. C and Rust get a narrower subset through
libglowcap_loamand Rust’sloamfeature: create a resource, share it with separate controls, edit it and the references it holds, restart, and fetch the same durable name again. Compiled for the browser, the same Rust feature stores to IndexedDB. TypeScript, Python, and Racket have no direct Loam storage API. They can call objects hosted through Loam over CapTP.
What ships tracks what is built.
Further reading
Chapter 07, durable card, shows the restart in one short program: it moves a card, shuts everything down, and reopens the store to find the move still there.
- Loam guide: the model, a walkthrough of chapter 07, the words used throughout, and how durable actors run.
- Stores, transactions and reads: commits, the cache, and recovering a write whose outcome is unknown.
- Durable names: how a sturdyref finds its actor after a restart.
- Durable capability fields: saving references to other actors and to objects on other machines.
- Collection: deleting unreachable records in small batches while the program runs.
- SQLite operations and LMDB operations: sizing, growing, and compacting the store on disk.
- Managed access: grants, use and control references, revocation, and safe retries.
- C and Rust and the browser: the same resources from other languages.