Skip to content

Reads, views & events

Reading an app never changes it. There are three ways to read: run a view, subscribe to the app’s events, and call the inspection routes that describe the app without running it.

POST /apps/{app}/views { method, args, consistency?, minIndex? } runs a method against a replica’s applied state. The run gets the same host as a call — the caller’s account and organization standing, the app’s keys, blobs and files, synchronous views of other apps — plus search, and whatever it writes is discarded.

consistency Where it runs What it sees
omitted (strong) Any replica, once it has applied the index the app’s leader named after confirming it still leads Every write committed before the view started
"stale" Any replica; this node if it is one That replica’s applied state, at least minIndex if given

A strong view is linearizable, through a read index. The replica that takes it asks the app’s leader for its applied index (internal/app/index); the leader first confirms with a quorum that it still leads, then names the index, and runs no WASM. The replica answers once it has applied that far. Every write acknowledged before the view arrived is at or below that index, and Raft gives every replica the same entries up to it, so the write is visible whichever replica answers. The leader answers its own strong views directly. A replica that cannot apply the index within 2 seconds (Config::read_wait), or whose leader runs an earlier release without the route, sends the view to the leader instead. calimero_replica_strong_views_total counts the views a replica answered itself.

A stale view saves the round to the leader and reads whatever the replica has. With minIndex (the index a call answered), a stale view waits up to 2 seconds for the replica to apply that entry and answers 503 NOT_CAUGHT_UP otherwise: read-your-writes without going through the leader.

A node that holds no replica of the app forwards a view to one that does, with the same 5-second bound as calls.

Who may run a view is judged on fresh system state: the node that takes the request makes one read-index round on the system group, so a revocation committed through any node before the view holds. A call is judged the same way and also costs one round: the app’s leader reuses the entry node’s index rather than asking again (One round per request gives the argument).

The answer is { index, result, receipt }: the applied index the view ran at, the result, and a receipt.

Any method may be called as a view, and its writes are dropped, with one exception: a method the app lists as a confirm method answers 412, because it must be called through /intents with a passkey assertion. The reverse also holds: a method the ABI declares #[app::view] runs as a strong view even when called through /intents.

An app names the text fields to index on a table (#[table(search = [..])]), and a view asks with Table::search(text, SearchOpts), which goes to the host through the WIT search interface (words, prefix, substring or fuzzy; 20 hits by default, at most 100, a query of at most 256 bytes). The node keeps the indexes (calimero-search’s tantivy ContextIndex, one per app) in memory, built from the table’s records and the ABI’s state.search (crates/node/src/component/search.rs):

  • Before a view runs, the node brings the app’s indexes up to the very state the view reads. If it knows which record keys the entries since its last build touched (the last TOUCHED_RING = 4096 entries are kept in memory), it re-reads just those; otherwise it rebuilds from a full scan of the records. A field is indexed from its first 64 KiB of text.
  • Indexes are derived data. They are never replicated, never written to disk, and rebuilt after a restart or when the app moves to this node. Indexes that survive a restart are not done yet.
  • Only views search. A call cannot, so node-local derived data never steers a write.

A run may emit events (env::emit(event, audience)). They are part of the outcome, so they are committed with the entry and applied on every replica: each replica appends them to the app’s event ring (EVENT_RING, the last 10 000 events) with their audience and the account that caused them.

GET /apps/{app}/events?from=N is a server-sent event stream: first the ring’s events from entry N on, then live ones as entries apply. Each event is an SSE event named by its kind, with its data as JSON and the id index:seq, so a client that reconnects passes the last index it saw and misses nothing the ring still holds. A node that hosts no replica proxies the stream from one. Inside the sealed channel the stream is sealed frame by frame like any other response.

  • A subscriber receives an event only while it reaches the app and is in the event’s audience (SystemState::receives), judged on the system state as it stands when the event goes out, so a member removed from a team stops receiving that team’s events at once:

    Audience Who receives
    all Everyone who reaches the app
    caller The account whose run emitted it
    accounts([..]) The listed accounts (at most 1000)
    team(id) The members of that team of the app’s organization
    org-members(org), org-admins(org) The app’s organization’s members (member and up), or its admins and owner

    A call’s answer carries the events its caller is in the audience of, under the same rule.

  • A node serves at most 4096 event and presence streams at once (MAX_EVENT_STREAMS); past that it answers 429 RATE_LIMITED.

  • Events are not the place for secrets: they are returned in call answers and stored in the ring.

These describe an app without running it:

Route What it returns
GET /apps/{app} The directory record: bundle, owner, organization, access, replicas, metadata, last upgrade
GET /apps/{app}/storage Keys, bytes and blobs the app’s state holds, and lastWriteAt, from a replica
GET /apps/{app}/abi The bundle’s embedded ABI
GET /apps/{app}/attestation?nonce= Every replica’s receipt-key attestation (verify_app_cluster)
GET /apps/{app}/presence Who is present now (Presence)

Each goes through the same gate as a view: the caller must reach the app.

Nothing on this page. The Ops API has no view, event or storage route; its status and metrics report counts and Raft positions only.