Skip to content

Read Options

Reading the stream is one operation with a shared set of options, whether you read with xs cat, the HTTP GET / endpoint, the .cat Nushell command, or a processor’s config. This page describes what each option does. Each surface’s own page lists how to spell them; the mapping table below ties the names together.

The read model

A read returns historical frames first, in chronological order (by frame ID), then optionally follows the stream for live frames as they are appended. When following, an xs.threshold frame marks the boundary between the historical replay and live frames. It is not emitted when you skip history with new, since there is no replay to bound.

Where to start

By default a read returns all history from the beginning of the stream. These options move the start point:

OptionStart
fromAt a specific frame ID, inclusive
afterAfter a specific frame ID, exclusive
newSkip all history; only frames appended after the read starts

How many

OptionReturns
limitAt most N frames from the start point, then stops
lastThe N most recent frames, in chronological order

Following live

follow keeps the read open after history, streaming live frames as they are appended. A follow can carry a heartbeat: a synthetic xs.pulse frame emitted on an interval, useful to keep a connection warm or to drive periodic work in a processor.

What a follow delivers

A following read delivers every frame appended after it starts, in frame ID order, with no gaps.

The read sends the stored frames first, straight from the store. Frames appended while it does are read from the store afterwards, so a slow replay cannot fall behind. Then xs.threshold, then live frames.

Live frames wait in a buffer of 4096 while the reader takes them. A reader that falls further behind than that is slower than the stream. Its read ends with a last frame that says so:

topic: xs.lagged
meta: {skipped: 506}

Every reader in xs treats xs.lagged as an error:

ReaderOn xs.lagged
actorstops with xs.actor.<name>.fin.error
servicestops with xs.service.<name>.fin.error (the control read or the duplex input)
.cat -f, .last -fthe stream ends with an error
xs cat -f, xs last -fprints the frame, then exits 1 with the reason on stderr
HTTP APIsends the frame as the last line, then the trailer xs-lagged: N (when the request sends TE: trailers), then closes

To resume, read again with after set to the last frame ID you received. What you missed is still in the store and comes back as history.

Terminal window
xs cat ./store --follow --after 03c4tn8fzl0a0000000000000

Ephemeral frames, which are broadcast but never stored, do not come back, and neither do frames a ttl has since removed.

Filtering by topic

topic restricts a read to frames whose topic matches a pattern. The pattern language (exact, prefix.* wildcards, * for all, and comma-separated lists) is described under Topics. A frame matched by more than one pattern in a list is returned once.

Filtering preserves the chronological ordering of the read and does not change the threshold boundary. Synthetic control frames (xs.threshold, heartbeat xs.pulse and xs.lagged) are always delivered to a following read; the filter applies only to stored and broadcast frames.

Output

with-timestamp adds an RFC3339 timestamp to each frame, extracted from its frame ID. The Nushell commands return it as a native datetime.

Spelling by surface

OptionHTTP GET /xs cat / .cat
fromfrom--from
afterafter--after, -a
newnew--new, -n
limitlimit--limit
lastlast--last
followfollow (true or <ms> for a heartbeat)--follow/-f, --pulse <ms> for a heartbeat
topictopic--topic, -T
with-timestampwith-timestamp--with-timestamp

Actors map a subset of these through their config rather than flags: start selects the start bound ("new", "first", or a frame ID), pulse sets the heartbeat interval, and topics is the topic filter. An actor always follows. Services read the stream themselves with .cat, so they use these options directly.