Enum PulsarPosition 

pub enum PulsarPosition {
    Earliest,
    Latest,
    MessageId(MessageIdData),
    Timestamp(u64),
}

A position in a topic’s retained log, accepted by Seeker::seek.

Captured positions (Positioned::position) carry the pinned semantics the framework defines: seeking to one redelivers exactly that message. The timestamp form keeps the broker’s own publish-time semantics instead.

The constructors exist because the start_at(..) clause of #[subscriber] recovers the position type from the constructor path; a bare variant path does not name its type in the tokens the macro sees.

Examples

use ruststream_pulsar::prelude::*;
use serde::Deserialize;

#[derive(Deserialize)]
struct Tick {
    price: f64,
    replay_from: Option<u64>,
}

/// A price board: the backlog is stale on startup, so the subscription opens at the tip, and
/// a tick that asks for a replay rewinds it to a point in time.
#[subscriber(
    PulsarSubscription::new("ticks", "board"),
    start_at(PulsarPosition::latest())
)]
async fn show(tick: &Tick, Ctx(seeker): Ctx<SeekHandle>) -> HandlerOutcome {
    tracing::info!(price = tick.price, "tick shown");
    if let Some(millis) = tick.replay_from
        && seeker.seek(PulsarPosition::timestamp(millis)).await.is_err()
    {
        return HandlerOutcome::retry();
    }
    HandlerOutcome::ack()
}

Variants

Earliest

The beginning of the log: every message the topics still retain is redelivered.

This is a seek, not the server-side initial position, which Pulsar applies only when a subscription is first created. A subscription is durable broker-side state, so a start_at(PulsarPosition::earliest()) clause rewinds an existing subscription’s cursor on every startup, replaying the retained backlog each time the service starts.

Latest

The tip of the log: only messages published after the seek are delivered.

MessageId(MessageIdData)

The position of a delivered message.

Timestamp(u64)

Publish time, in milliseconds since the Unix epoch.

Implementations

impl PulsarPosition

pub fn earliest() -> Self

The beginning of the log; see PulsarPosition::Earliest for how it interacts with a durable subscription’s cursor.

Examples

use ruststream_pulsar::prelude::*;
use serde::Deserialize;

#[derive(Deserialize)]
struct Job {
    id: u64,
    resume_at: Option<u64>,
}

/// Reads the whole retained backlog on every startup, and skips forward past a region the
/// producer marked poisoned.
#[subscriber(
    PulsarSubscription::pattern("persistent://public/default/orders-.*", "audit"),
    start_at(PulsarPosition::earliest())
)]
async fn audit(job: &Job, Ctx(seeker): Ctx<SeekHandle>) -> HandlerOutcome {
    tracing::info!(job.id, "audited");
    if let Some(millis) = job.resume_at
        && seeker.seek(PulsarPosition::timestamp(millis)).await.is_err()
    {
        return HandlerOutcome::retry();
    }
    HandlerOutcome::ack()
}

pub fn latest() -> Self

The tip of the log; see PulsarPosition::Latest.

pub fn timestamp(millis: u64) -> Self

A publish time, in milliseconds since the Unix epoch; see PulsarPosition::Timestamp.

Trait Implementations

impl Clone for PulsarPosition

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PulsarPosition

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

Formats the value using the given formatter.

impl Eq for PulsarPosition

impl PartialEq for PulsarPosition

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for PulsarPosition