Enum StreamCursor 

pub enum StreamCursor {
    Start,
    End,
    At(String),
}

Opaque cursor for read_stream / tail_stream — re-export of ff_core::contracts::StreamCursor. Wire tokens: "start", "end", "<ms>", "<ms>-<seq>". Bare - / + are rejected — use StreamCursor::Start / StreamCursor::End instead. Opaque cursor for attempt-stream reads/tails.

Replaces the bare &str / String stream-id parameters previously carried on read_stream / tail_stream / ReadStreamParams / TailStreamParams. The wire form is a flat string — serde is transparent via try_from/into — so ?from=start&to=end and ?after=123-0 continue to work for REST clients.

Public wire grammar

The ONLY accepted tokens are:

• "start" — first entry in the stream (XRANGE - equivalent). Valid in read_stream / ReadStreamParams.
• "end" — latest entry in the stream (XRANGE + equivalent). Valid in read_stream / ReadStreamParams.
• "<ms>" or "<ms>-<seq>" — a concrete Valkey Stream entry id. Valid everywhere.

The bare XRANGE/XREAD markers "-" and "+" are NOT accepted on the wire. The opaque StreamCursor grammar is the public contract; the Valkey -/+ markers are an internal implementation detail carried only inside the Lua-adjacent ReadFramesArgs / xread_block path via StreamCursor::to_wire.

For XREAD (tail), the documented “from the beginning” convention is StreamCursor::At("0-0".into()) — use the convenience constructor StreamCursor::from_beginning which returns exactly that value. Start / End are rejected by the SDK’s tail_stream boundary because XREAD does not accept - / + as cursors. The StreamCursor::is_concrete helper centralises this Start/End-vs-At decision for boundary-validation call sites.

Why an enum instead of a string

A string parameter lets malformed ids escape to the Lua/Valkey layer, surfacing as a script error and HTTP 500. An enum with fallible FromStr / TryFrom<String> catches every malformed input at the wire boundary with a structured error, and prevents bare - / + from leaking into consumer code as tacit extensions of the public API.

Variants

Start

First entry in the stream (XRANGE start marker).

End

Latest entry in the stream (XRANGE end marker).

At(String)

A concrete Valkey Stream entry id (<ms> or <ms>-<seq>).

For XREAD-style tails, the documented “from the beginning” convention is At("0-0".to_owned()) — see StreamCursor::from_beginning.

Implementations

impl StreamCursor

pub fn from_beginning() -> StreamCursor

Convenience constructor for the XREAD-from-beginning convention ("0-0"). XREAD’s last_id is exclusive, so passing this as the after cursor returns every entry in the stream.

pub fn start() -> StreamCursor

Serde default helper — emits StreamCursor::Start. Used as #[serde(default = "StreamCursor::start")] on REST query structs.

pub fn end() -> StreamCursor

Serde default helper — emits StreamCursor::End.

pub fn beginning() -> StreamCursor

Serde default helper — emits StreamCursor::from_beginning(). Used as the default for TailStreamParams::after.

pub fn is_concrete(&self) -> bool

True iff this cursor is a concrete entry id ("<ms>" / "<ms>-<seq>"). False for the open markers Start / End.

Used by boundaries like XREAD (tailing) that do not accept open markers — rejecting a cursor is equivalent to !cursor.is_concrete(). Centralised here to keep the SDK and REST guards in lock-step.

Trait Implementations

impl Clone for StreamCursor

fn clone(&self) -> StreamCursor

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StreamCursor

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for StreamCursor

fn deserialize<D>( deserializer: D, ) -> Result<StreamCursor, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for StreamCursor

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl FromStr for StreamCursor

type Err = StreamCursorParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<StreamCursor, <StreamCursor as FromStr>::Err>

Parses a string s to return a value of this type.

impl Hash for StreamCursor

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for StreamCursor

fn eq(&self, other: &StreamCursor) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for StreamCursor

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<String> for StreamCursor

type Error = StreamCursorParseError

The type returned in the event of a conversion error.

fn try_from( s: String, ) -> Result<StreamCursor, <StreamCursor as TryFrom<String>>::Error>

Performs the conversion.

impl Eq for StreamCursor

impl StructuralPartialEq for StreamCursor