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.
Search
Section titled “Search”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.
Events
Section titled “Events”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 allEveryone who reaches the app callerThe 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 ( memberand up), or its admins and ownerA 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 answers429 RATE_LIMITED. -
Events are not the place for secrets: they are returned in call answers and stored in the ring.
Inspection
Section titled “Inspection”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.
What the operator can read
Section titled “What the operator can read”Nothing on this page. The Ops API has no view, event or storage route; its status and metrics report counts and Raft positions only.