How does XREAD with the BLOCK option behave when tailing a Redis Stream, and what does passing the special ID $ mean?

## The shape of the command ``` XREAD [COUNT n] [BLOCK ms] STREAMS key [key ...] id [id ...] ``` All keys come first, then all IDs, positionally matched. The IDs are **exclusive**: you receive entries with an ID strictly greater than the one you passed, which is exactly right when the ID you pass is the last one you handled. ## What BLOCK actually does Without `BLOCK`, `XREAD` is a poll: if nothing is newer than your ID, you get a nil reply immediately. Polling in a tight loop wastes CPU and round trips and still adds latency equal to your poll interval. With `BLOCK ms`: - If matching entries **already exist**, they are returned immediately — `BLOCK` only applies when there is nothing to return. This is important: `BLOCK` never delays available data. - Otherwise the client is **parked**. Redis registers it as waiting on those keys and returns to serving other clients. It is not spinning and it is not holding the execution thread; the single-threaded event loop keeps running normally. - When an `XADD` appends to a watched key, Redis signals the key and the blocked client is served, typically at the end of the current command's execution. - If `ms` elapses first, the reply is **nil** (RESP2 null array). `BLOCK 0` means no timeout at all. Because the client is genuinely idle while parked, you must be careful with **client-side socket timeouts**: a driver configured with, say, a 3-second read timeout and `BLOCK 5000` will tear down the connection before Redis replies. The rule is to set the socket timeout comfortably above the BLOCK duration, or use a client whose stream API handles it (Lettuce, redis-py, go-redis all expose this). ## The `$` ID `$` is sugar for "whatever `last-generated-id` currently is". Redis substitutes it when it processes the command. Use it once, when a consumer starts and only cares about live traffic: ``` XREAD BLOCK 0 STREAMS events $ ``` Then never again. The failure mode of using it repeatedly: 1. `XREAD BLOCK 5000 STREAMS events $` blocks; entry `A` arrives; you get `A`. 2. You spend 40 ms processing `A`. During those 40 ms entries `B` and `C` are appended. 3. You call `XREAD BLOCK 5000 STREAMS events $` again. `$` now resolves past `C`. **`B` and `C` are never delivered to you** and nothing reports an error. The fix is a one-line discipline: take the **last ID of the last entry in the reply** and use it as the next call's ID. Other special IDs: `0` (or `0-0`) reads from the very beginning — the cold-start / resume-without-cursor case; `+` in `XREAD` (Redis 7.4+) means "the last entry currently in the stream", handy for peeking at the newest entry. ## Reading several streams at once ``` XREAD BLOCK 0 STREAMS orders payments 1699-4 1700-0 ``` One blocked call can wait on many streams; you are woken by whichever gets data first, and the reply tells you which stream each batch came from. Track one cursor **per stream**. This is much cheaper than one connection per stream, but note the reply may contain entries from only some streams, so your loop must update only the cursors it actually advanced. ## Guarantees and limits of plain XREAD Plain `XREAD` is a **fan-out** read: every consumer that reads with its own cursor sees every entry. There is no server-side position, no acknowledgement, no in-flight tracking, and no load balancing of entries across a set of workers. Those belong to a different mechanism in Redis Streams; do not attribute them to `XREAD`. So the delivery semantics are entirely determined by where you persist the cursor: - Persist **after** processing → at-least-once, duplicates after a crash. Almost always the right choice; make handlers idempotent. - Persist **before** processing → at-most-once, silent loss after a crash. And because the cursor lives in your process, an unclean restart of a consumer that only ever used `$` starts from "now" and skips everything accumulated while it was down. Store the cursor durably if that matters. ## Interaction with trimming A blocked reader that falls behind can have entries trimmed out from under it: `XTRIM`/`MAXLEN` deletes by position regardless of who has read what. The reader is not notified — it simply receives the next surviving entry. Retention must be sized against your worst-case consumer downtime. ## A correct loop, in words Start with a stored cursor if you have one, else `$` for live-only or `0` to replay. Call `XREAD COUNT n BLOCK 5000 STREAMS key cursor`. On nil, loop again (the timeout is also your liveness heartbeat — it lets the process notice shutdown signals). On entries, process them, set `cursor` to the last ID, persist it, and loop. Use a dedicated connection for the blocking call.