Enum StreamError 

pub enum StreamError {
    ConnectionFailed {
        url: String,
        reason: String,
    },
    Disconnected {
        url: String,
    },
    ReconnectExhausted {
        url: String,
        attempts: u32,
    },
    ParseError {
        exchange: String,
        reason: String,
    },
    StaleFeed {
        feed_id: String,
        elapsed_ms: u64,
        threshold_ms: u64,
    },
    UnknownFeed {
        feed_id: String,
    },
    ConfigError {
        reason: String,
    },
    BookReconstructionFailed {
        symbol: String,
        reason: String,
    },
    BookCrossed {
        symbol: String,
        bid: Decimal,
        ask: Decimal,
    },
    SequenceGap {
        symbol: String,
        expected: u64,
        got: u64,
    },
    Backpressure {
        channel: String,
        depth: usize,
        capacity: usize,
    },
    UnknownExchange(String),
    Io(String),
    WebSocket(String),
    RingBufferFull {
        capacity: usize,
    },
    RingBufferEmpty,
    AggregationError {
        reason: String,
    },
    NormalizationError {
        reason: String,
    },
    InvalidTick {
        reason: String,
    },
    LorentzConfigError {
        reason: String,
    },
    FinPrimitives(String),
}

Unified error type for all fin-stream pipeline operations.

Each variant carries enough context to reconstruct the failure site without inspecting internal state. The Display impl is machine-parseable: field values never contain the literal substring used as a delimiter.

Variants

ConnectionFailed

WebSocket connection failed.

Fields

url: String

The WebSocket URL that could not be reached.

reason: String

Human-readable description of the failure.

Disconnected

WebSocket disconnected unexpectedly.

Fields

url: String

The WebSocket URL that was disconnected.

ReconnectExhausted

Reconnection attempts exhausted.

Fields

url: String

The target URL for reconnection.

attempts: u32

Total number of reconnect attempts made.

ParseError

Tick deserialization failed.

Fields

exchange: String

Name of the exchange that sent the unparseable tick.

reason: String

Description of the parse failure.

StaleFeed

Feed is stale – no data received within staleness threshold.

Fields

feed_id: String

Identifier of the stale feed.

elapsed_ms: u64

Milliseconds since the last tick was received.

threshold_ms: u64

Configured staleness threshold in milliseconds.

UnknownFeed

Feed identifier is not registered with the health monitor.

Fields

feed_id: String

Identifier of the feed that was not found.

ConfigError

A configuration parameter is invalid.

Returned by constructors when a parameter violates documented invariants (e.g. reconnect multiplier < 1.0, zero channel capacity). Distinct from runtime errors such as ConnectionFailed.

Fields

reason: String

Description of the configuration violation.

BookReconstructionFailed

Order book reconstruction failed.

Fields

symbol: String

Symbol whose order book could not be reconstructed.

reason: String

Description of the reconstruction failure.

BookCrossed

Order book is crossed (bid >= ask).

Fields

symbol: String

Symbol with the crossed book.

bid: Decimal

Best bid price.

ask: Decimal

Best ask price.

SequenceGap

Order book sequence gap detected — one or more deltas were skipped.

Fields

symbol: String

Symbol whose delta stream has a gap.

expected: u64

The sequence number that was expected.

got: u64

The sequence number that was actually received.

Backpressure

Backpressure: the downstream channel is full.

Fields

channel: String

Name or URL of the backpressured channel.

depth: usize

Current number of items queued.

capacity: usize

Maximum capacity of the channel.

UnknownExchange(String)

Invalid exchange format.

Io(String)

I/O error.

WebSocket(String)

WebSocket protocol error.

RingBufferFull

SPSC ring buffer is full; the producer must back off or drop the item.

This variant is returned by crate::ring::SpscRing::push when the buffer has no free slots. It never panics.

Fields

capacity: usize

Configured usable capacity of the ring buffer (N - 1 slots).

RingBufferEmpty

SPSC ring buffer is empty; no item is available for the consumer.

This variant is returned by crate::ring::SpscRing::pop when there are no pending items. Callers should retry or park the consumer thread.

AggregationError

An error occurred during OHLCV bar aggregation.

Wraps structural errors such as receiving a tick for the wrong symbol or a timeframe with a zero-duration period.

Fields

reason: String

Description of the aggregation failure.

NormalizationError

An error occurred during coordinate normalization.

Typically indicates that the normalizer received a value outside the expected numeric range, or that the rolling window is not yet seeded.

Fields

reason: String

Description of the normalization failure.

InvalidTick

A tick failed structural validation before entering the pipeline.

Examples: negative price, zero quantity, timestamp in the past beyond the configured tolerance.

Fields

reason: String

Description of the validation failure.

LorentzConfigError

The Lorentz transform configuration is invalid.

The relativistic velocity parameter beta (v/c) must satisfy 0 <= beta < 1. A beta of exactly 1 (or above) would produce a division by zero in the Lorentz factor gamma = 1 / sqrt(1 - beta^2).

Fields

reason: String

Description of the configuration error.

FinPrimitives(String)

An error propagated from the fin-primitives crate.

Allows ? to be used on fin_primitives operations inside fin-stream pipelines without an explicit .map_err().

Implementations

impl StreamError

pub fn is_fatal(&self) -> bool

Returns true for errors that are not recoverable without a code or configuration change.

Fatal errors indicate a programming mistake or invalid configuration: misconfigured parameters, unknown exchanges, exhausted reconnect budgets, or corrupted book state that cannot be repaired by retrying.

pub fn source_module(&self) -> &'static str

Source subsystem for this error: "ws", "book", "ring", "aggregator", "session", "lorentz", or "other".

Useful for routing errors to subsystem-specific metrics or alert channels without pattern-matching every variant.

pub fn is_recoverable(&self) -> bool

Returns true if this error can potentially be resolved by retrying — the inverse of is_fatal. Returns true for errors that can be recovered from without a full reconnect.

pub fn is_network_error(&self) -> bool

Returns true for errors that originate from a network connection.

Network errors include WebSocket protocol failures, connection drops, and reconnect exhaustion. They are distinct from data errors (bad book state, bad tick data) or config errors.

pub fn is_book_error(&self) -> bool

Returns true for errors that originate in the order book subsystem.

Book errors indicate structural problems with the market data feed (sequence gaps, crossed books, failed reconstruction) that typically require a book reset or feed reconnection to resolve.

pub fn variant_name(&self) -> &'static str

Returns the enum variant name as a static string.

Useful for structured logging and metrics without allocating a dynamic string from the Display impl.

pub fn is_config_error(&self) -> bool

Returns true if this is a configuration error.

pub fn is_feed_error(&self) -> bool

Returns true if this error relates to a feed (stale or unknown).

pub fn is_parse_error(&self) -> bool

Returns true if this is a tick parse error.

pub fn is_book_reconstruction_error(&self) -> bool

Returns true if this is a book reconstruction failure.

pub fn is_computation_error(&self) -> bool

Returns true if this error is related to computation or physics transforms.

Covers LorentzConfigError (invalid beta value).

pub fn is_ring_error(&self) -> bool

Returns true if this error is related to the ring buffer (full or empty).

pub fn category(&self) -> &'static str

Human-readable category string for this error.

Returns one of "connection", "data", "pipeline", "book", "config", or "other". Useful for metrics labels and structured logging without pattern-matching every variant.

pub fn is_pipeline_error(&self) -> bool

Returns true for errors that arise inside the processing pipeline.

Pipeline errors indicate internal structural failures — ring buffer full or empty, aggregation shape mismatch, normalization range violations, or Lorentz configuration errors. They do not indicate bad input data or network problems.

pub fn is_connection_error(&self) -> bool

Returns true for errors that indicate a connection-layer failure.

Connection errors arise from network problems: initial connection refused, unexpected disconnection, or reconnection attempts exhausted. Unlike data errors, these may resolve by reconnecting or waiting.

pub fn is_data_error(&self) -> bool

Returns true for errors that indicate bad data from the exchange.

Data errors arise from malformed or logically inconsistent market data: parse failures, invalid tick values, crossed order books, or sequence gaps. They do not imply a network problem — reconnecting won’t help.

pub fn is_transient(&self) -> bool

Returns true for errors that are transient and worth retrying.

Transient errors arise from external conditions (network drops, full buffers, stale feeds) that may resolve on their own. Permanent errors indicate misconfiguration or invalid data that will not self-heal.

Example

use fin_stream::StreamError;

let e = StreamError::WebSocket("connection reset".into());
assert!(e.is_transient());

let e = StreamError::ConfigError { reason: "multiplier < 1".into() };
assert!(!e.is_transient());

pub fn affected_symbol(&self) -> Option<&str>

The primary symbol, URL, or feed identifier associated with this error, if any.

Returns None for errors that are not tied to a specific identifier (e.g. ring buffer errors, pipeline errors without a symbol field). Useful for routing errors to per-symbol dashboards or alert channels.

pub fn is_sequence_gap(&self) -> bool

Returns true if this is a sequence gap error (missed delta).

pub fn is_data_integrity_error(&self) -> bool

Returns true for errors that indicate a data integrity violation: a crossed order book or a sequence gap in the delta stream.

These errors mean the feed’s internal state may be corrupted and typically require a book reset or reconnect.

pub fn is_symbol_error(&self) -> bool

Returns true if this error is associated with a specific symbol or feed ID.

Covers book errors and feed-health errors that carry an identifier.

pub fn to_error_code(&self) -> u32

Returns a numeric error code for this variant.

Codes are grouped by category:

• 1xxx: connection errors
• 2xxx: feed/parse errors
• 3xxx: configuration errors
• 4xxx: book errors
• 5xxx: backpressure/buffer errors
• 6xxx: data errors
• 7xxx: computation errors

pub fn has_url(&self) -> bool

Returns true if this error contains a URL field.

pub fn error_category_code(&self) -> u32

Returns the high-level category code (thousands digit of to_error_code).

• 1: connection, 2: feed/parse, 3: config, 4: book, 5: buffer, 6: data, 7: computation

pub fn is_buffer_error(&self) -> bool

Returns true for ring-buffer and backpressure errors (category 5xxx).

pub fn is_normalization_error(&self) -> bool

Returns true if this is a normalization or aggregation error.

pub fn is_agg_error(&self) -> bool

Returns true if this is an aggregation error.

pub fn is_sequence_error(&self) -> bool

Returns true if this is a sequence gap error.

pub fn severity_level(&self) -> u8

Numeric severity level: 1 = informational, 2 = warning, 3 = error, 4 = critical.

• 4 (critical): ReconnectExhausted
• 3 (error): connection, book, and lorentz config errors
• 2 (warning): stale feed, sequence gap, backpressure, buffer full/empty
• 1 (informational): parse, normalization, aggregation, unknown feed, invalid tick

Trait Implementations

impl Debug for StreamError

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

Formats the value using the given formatter.

impl Display for StreamError

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

Formats the value using the given formatter.

impl Error for StreamError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<FinError> for StreamError

fn from(e: FinError) -> Self

Converts to this type from the input type.