fv-streams 0.1.0

The FusionVault Streams standalone runner: run a stream pipeline defined in one TOML file against Kafka or Redpanda with no control plane, including the built-in Nexmark event generator.
Documentation
//! `fv-streams run <pipeline.toml>` — the standalone runner. Everything it does is the library
//! (`fv_streams::Pipeline`); this file is argument parsing, Ctrl-C, and the optional profiler.

use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;

use fv_streams::Pipeline;

fn usage() -> ! {
    eprintln!("fv-streams — run TOML-defined stream pipelines (FusionVault Streams)\n");
    eprintln!("USAGE:\n  fv-streams run <pipeline.toml>\n");
    eprintln!("Engine settings come from STREAM_* environment variables or the pipeline's [settings]");
    eprintln!("table (the environment wins). See the README for the full table.");
    std::process::exit(2)
}

#[tokio::main]
async fn main() {
    let args: Vec<String> = std::env::args().collect();
    let path = match (args.get(1).map(String::as_str), args.get(2)) {
        (Some("run"), Some(p)) => p.clone(),
        _ => usage(),
    };
    let pipeline = match Pipeline::load(&path) {
        Ok(p) => p,
        Err(e) => {
            eprintln!("fv-streams: {e}");
            std::process::exit(1);
        }
    };

    // Ctrl-C / SIGTERM → the stop flag → the next heartbeat returns Stop → the engine's ordered
    // shutdown (final checkpoint → flush-emit → offsets land synchronously).
    let stop = Arc::new(AtomicBool::new(false));
    {
        let stop = stop.clone();
        tokio::spawn(async move {
            let _ = tokio::signal::ctrl_c().await;
            eprintln!("\nfv-streams: stop requested — unwinding (final checkpoint + flush)…");
            stop.store(true, Ordering::Relaxed);
        });
    }

    // Opt-in in-process CPU profiling. Build with `--features profiling`, run with
    // `FV_PROFILE=/path/flame.svg` — a ~499Hz signal-sampling profiler wraps the whole run and
    // writes a flamegraph on shutdown. Zero cost when the variable is unset; absent from default
    // builds. Frequency 499 (prime) avoids lockstep with periodic work.
    #[cfg(feature = "profiling")]
    let profiler = std::env::var("FV_PROFILE").ok().and_then(|out| {
        match pprof::ProfilerGuardBuilder::default()
            .frequency(499)
            .blocklist(&["libc", "libgcc", "pthread", "vdso"])
            .build()
        {
            Ok(g) => {
                println!("fv-streams: profiling ON → {out}");
                Some((g, out))
            }
            Err(e) => {
                eprintln!("fv-streams: profiler failed to start: {e}");
                None
            }
        }
    });

    if let Err(e) = pipeline.run(stop).await {
        eprintln!("fv-streams: {e}");
        std::process::exit(1);
    }

    #[cfg(feature = "profiling")]
    if let Some((guard, out)) = profiler {
        match guard.report().build() {
            Ok(report) => match std::fs::File::create(&out) {
                Ok(f) => match report.flamegraph(f) {
                    Ok(()) => println!("fv-streams: flamegraph written → {out}"),
                    Err(e) => eprintln!("fv-streams: flamegraph write failed: {e}"),
                },
                Err(e) => eprintln!("fv-streams: cannot create {out}: {e}"),
            },
            Err(e) => eprintln!("fv-streams: profile report failed: {e}"),
        }
    }
}