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:
| Option | Start |
|---|---|
from | At a specific frame ID, inclusive |
after | After a specific frame ID, exclusive |
new | Skip all history; only frames appended after the read starts |
How many
| Option | Returns |
|---|---|
limit | At most N frames from the start point, then stops |
last | The 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.laggedmeta: {skipped: 506}Every reader in xs treats xs.lagged as an error:
| Reader | On xs.lagged |
|---|---|
| actor | stops with xs.actor.<name>.fin.error |
| service | stops with xs.service.<name>.fin.error (the control read or the duplex input) |
.cat -f, .last -f | the stream ends with an error |
xs cat -f, xs last -f | prints the frame, then exits 1 with the reason on stderr |
| HTTP API | sends 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.
xs cat ./store --follow --after 03c4tn8fzl0a0000000000000Ephemeral 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
| Option | HTTP GET / | xs cat / .cat |
|---|---|---|
from | from | --from |
after | after | --after, -a |
new | new | --new, -n |
limit | limit | --limit |
last | last | --last |
follow | follow (true or <ms> for a heartbeat) | --follow/-f, --pulse <ms> for a heartbeat |
topic | topic | --topic, -T |
with-timestamp | with-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.