fv-streams-ops 0.3.0

Stateful streaming operators for FusionVault Streams: event-time tumbling and sliding windows with keyed incremental aggregation, session windows, stream joins, top-N and last-N, watermarks and snapshots. Pure and synchronous — no I/O, no runtime.
Documentation
//! The state tier's errors — what the immutable-file layer under the operators reports when the
//! filesystem, or a file's contents, refuse what the runtime asked. Every message names the
//! operation and the path; where the state is unrecoverable it names the remedy
//! (`STREAM_RESET_STATE=1`), so a FAILED build says what to do, not only what broke.
//!
//! Two escalation paths share this type. Once-per-epoch and once-at-start work (a checkpoint, a
//! restore) returns it as a `Result`, and the engine fails the build with the message. The data
//! path (`push` / `advance`) is deliberately infallible — a `Result` per key would put a branch on
//! the hottest loop in the engine — so its two I/O sites (thawing a frozen window shard, freezing
//! a join batch under memory pressure) escalate through [`state_fault`]: a `#[cold]` panic
//! carrying the same typed diagnostic, which the task runtime already catches and reports as a
//! FAILED build. The success path of both sites is byte-for-byte what it was.

use std::fmt;
use std::path::{Path, PathBuf};

/// Why the state tier could not do what the runtime asked.
#[derive(Debug)]
pub enum StateError {
    /// A filesystem operation on a state file failed: a lost spill directory, a full disk,
    /// permissions.
    Io {
        /// What was being done (`"thaw shard 3"`, `"write checkpoint file"`).
        op: String,
        path: PathBuf,
        source: std::io::Error,
    },
    /// A write or encode step on a state file failed for a reason that is not a plain I/O error
    /// (an Arrow writer refused the batch, say).
    Failed { op: String, path: PathBuf, detail: String },
    /// A state file or snapshot did not decode as this operator's state.
    Corrupt {
        /// What was being read (`"thaw shard 3 from …"`).
        what: String,
        detail: String,
    },
    /// A checkpoint references a state shape this operator never writes — it belongs to another
    /// topology.
    Unsupported { what: String },
}

impl StateError {
    pub fn io(op: impl Into<String>, path: impl AsRef<Path>, source: std::io::Error) -> Self {
        Self::Io {
            op: op.into(),
            path: path.as_ref().to_path_buf(),
            source,
        }
    }
    pub fn failed(op: impl Into<String>, path: impl AsRef<Path>, detail: impl Into<String>) -> Self {
        Self::Failed {
            op: op.into(),
            path: path.as_ref().to_path_buf(),
            detail: detail.into(),
        }
    }
    pub fn corrupt(what: impl Into<String>, detail: impl Into<String>) -> Self {
        Self::Corrupt {
            what: what.into(),
            detail: detail.into(),
        }
    }
    pub fn unsupported(what: impl Into<String>) -> Self {
        Self::Unsupported { what: what.into() }
    }
}

const RESET: &str = "set STREAM_RESET_STATE=1 to start fresh and discard the checkpoint";

impl fmt::Display for StateError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Io { op, path, source } => write!(f, "state io: {op} {}: {source}", path.display()),
            Self::Failed { op, path, detail } => write!(f, "state: {op} {}: {detail}", path.display()),
            Self::Corrupt { what, detail } => write!(f, "state corrupt: {what}: {detail} — {RESET}"),
            Self::Unsupported { what } => write!(f, "state unsupported: {what} — {RESET}"),
        }
    }
}

impl std::error::Error for StateError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Io { source, .. } => Some(source),
            _ => None,
        }
    }
}

impl From<StateError> for String {
    fn from(e: StateError) -> Self {
        e.to_string()
    }
}

/// The data path's escalation for a state fault it cannot return: a `#[cold]` panic carrying the
/// typed diagnostic. The task runtime catches it (`catch_unwind`) and fails the BUILD with this
/// message — the same outcome a `Result` would reach, without a branch on the success path.
#[cold]
#[inline(never)]
pub fn state_fault(e: StateError) -> ! {
    panic!("{e}")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn messages_name_the_operation_the_path_and_the_remedy_where_there_is_one() {
        let io = StateError::io(
            "thaw shard 3",
            "/spill/shard-3.arrow",
            std::io::Error::from(std::io::ErrorKind::NotFound),
        );
        let s = io.to_string();
        assert!(s.contains("thaw shard 3") && s.contains("/spill/shard-3.arrow"), "{s}");
        assert!(
            !s.contains("STREAM_RESET_STATE"),
            "an io fault is not a reset case: {s}"
        );

        let c = StateError::corrupt("thaw shard 3 from /spill/x", "bad envelope").to_string();
        assert!(c.contains("bad envelope") && c.contains("STREAM_RESET_STATE=1"), "{c}");

        let u = StateError::unsupported("file-backed state for a lookup join").to_string();
        assert!(u.contains("STREAM_RESET_STATE=1"), "{u}");

        let as_string: String = StateError::failed("freeze join batch", "/spill/j.arrow", "writer refused").into();
        assert!(as_string.starts_with("state: freeze join batch"), "{as_string}");
    }

    #[test]
    fn state_fault_panics_with_the_typed_message() {
        let r = std::panic::catch_unwind(|| {
            state_fault(StateError::unsupported("a foreign manifest"));
        });
        let msg = r.unwrap_err().downcast::<String>().expect("a String payload");
        assert!(msg.contains("state unsupported: a foreign manifest"), "{msg}");
    }
}