Errors

SeaFileError is the crate's one error type: connect, subscribe, receive, publish and seek failures, a closed broker, an invalid input.

Each variant names the step that failed, with the file path or the stream key it failed on. The client's own error is its source, so the client's types stay out of the crate's API.

Variant	When
`Connect`	the stream file could not be opened or created, or standard input and output could not be attached
`Subscribe`	a subscription could not be opened
`Receive`	an open subscription failed to read
`Publish`	the client refused to write a message
`Seek`	a subscription could not be moved to a position
`NotConnected`	a publisher was used after its broker shut down
`Invalid`	a stream key the client does not take, an empty message on standard output, or a beacon interval that is not a multiple of 1024

A service meets the error in two places. A failed startup carries it as the source of the runtime's error, and the service exits before it reads anything. A publish from a handler returns it inside the core's PublishError, and the handler decides what to do with the delivery. The enum is #[non_exhaustive], so a match on it ends with a wildcard arm.

Example

The stage writes each job's note to standard output as its bytes. A pipe drops an empty line, so an empty note is refused with Invalid; the handler logs the error and finishes the job without the note.

Macros
Manual

examples/sea_broker_errors.rs
#[subscriber("jobs")]
async fn annotate(job: &Job, Out(notes): Out<impl Publisher, Notes>) -> HandlerOutcome {
    let note = Note(job.note.clone().into_bytes());
    if let Err(err) = notes.message(&note).publish().await {
        // An empty note is refused, and the job is done without it.
        tracing::warn!(subscription = "jobs", job.id, error = %err, "note not written");
    }
    HandlerOutcome::ack()
}

examples/manual/sea_broker_errors.rs
struct Annotate;

impl<Entry> Handle<Job, (), Outs<(Entry,)>> for Annotate
where
    Entry: OutEntry<Notes, Wire: Publisher>,
{
    async fn handle(
        &self,
        job: &Job,
        outs: &Outs<(Entry,)>,
        _ctx: &mut Context<'_>,
    ) -> Result<(), HandlerOutcome> {
        let note = Note(job.note.clone().into_bytes());
        if let Err(err) = outs.get(Notes).message(&note).publish().await {
            // An empty note is refused, and the job is done without it.
            tracing::warn!(subscription = "jobs", job.id, error = %err, "note not written");
        }
        Ok(())
    }
}

Example​

Example