ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
//! EXIT SOURCES, ready-made — the one adapter this crate ships, behind the one feature that names a
//! runtime.
//!
//! [`App::halt_on`](crate::App::halt_on) takes a [`conduit::Receiver<()>`](crate::conduit::Receiver)
//! and asks nothing about where it came from, which is what keeps the seat runtime-agnostic: a
//! handler is the application's act, and a library that installed one would be taking a
//! process-wide decision on somebody else's behalf. This module is the exception that proves the
//! rule — an adapter for the runtime a deployment has ALREADY chosen, compiled only where that
//! deployment says so.
//!
//! # The whole module rides `tokio-signal`, and the default graph names no runtime
//!
//! `ingraph` has no `tokio` in its default dependency graph and this changes nothing about that:
//! the feature is off unless a build asks for it, and asking for it is a build that already has a
//! tokio runtime to spawn on. The agnostic law is the crate's, and a named runtime behind a named
//! feature is how a library keeps it while still being usable.
//!
//! # UNIX SIGNALS ride the docs rather than a dependency
//!
//! There is no `sighup()` here, and the absence is deliberate: the shape is four lines an
//! application writes against whatever it already has, and shipping one would be shipping a
//! preference about which signals mean *stop*. Under tokio it is
//! [`tokio::signal::unix`](https://docs.rs/tokio/latest/tokio/signal/unix/):
//!
//! ```ignore
//! use ingraph::conduit;
//! use tokio::signal::unix::{SignalKind, signal};
//!
//! /// A line that speaks the first time this process is sent `SIGTERM`.
//! fn sigterm() -> std::io::Result<conduit::Receiver<()>> {
//!   let (fired, source) = conduit::bounded(1);
//!   let mut term = signal(SignalKind::terminate())?;
//!   tokio::spawn(async move {
//!     term.recv().await;
//!     let _ = fired.try_send(());
//!   });
//!   Ok(source)
//! }
//! ```
//!
//! and under any other runtime it is the same four lines with that runtime's own handler in the
//! middle. Register as many as the deployment has —
//! [`halt_on`](crate::App::halt_on) takes each on its own line, and whichever speaks first wakes the
//! park.

use crate::conduit::{self, Receiver};

/// **A LINE THAT SPEAKS WHEN THE PROCESS IS INTERRUPTED** — `Ctrl-C`, or `SIGINT` on unix — ready
/// for [`App::halt_on`](crate::App::halt_on).
///
/// The handler is tokio's ([`tokio::signal::ctrl_c`]) and the line is this crate's, which is the
/// whole of the adapter: what comes back is an ordinary exit source, indistinguishable at the seat
/// from one an application wired itself.
///
/// # It must be called FROM a tokio runtime
///
/// The wait is a task, so this spawns — and [`tokio::spawn`] panics outside a runtime context. A
/// daemon calls it inside its `#[tokio::main]` (or inside `Runtime::block_on` / an
/// `EnterGuard`) and hands the line to the app:
///
/// ```ignore
/// # async fn wire(app: &mut ingraph::App<()>) {
/// app.halt_on(ingraph::signal::ctrl_c());
/// // …and then, on whatever thread is not the executor's:
/// // app.until_stopped();
/// # }
/// ```
///
/// # It fires ONCE, and a handler that could not be installed stays SILENT
///
/// The task ends with the first interrupt, and the line's capacity is one — a second `Ctrl-C`
/// reaches nothing here, which is right: the wind-down is already under way and saying so twice is
/// the same instruction. A deployment that wants the second press to be *abort now* wires that
/// itself, against the same `App`.
///
/// Where tokio REFUSES to install the handler, the line is held open and never speaks. The
/// alternative would be to let the sender go, and a hang-up is news
/// [`halt_on`](crate::App::halt_on) reads as *time to stop* — so a failure to install would become
/// an immediate wind-down nobody asked for. Silence is the honest answer: the deployment stops the
/// way it would have if this source had never been registered.
#[must_use]
pub fn ctrl_c() -> Receiver<()> {
  let (fired, source) = conduit::bounded(1);
  tokio::spawn(async move {
    match tokio::signal::ctrl_c().await {
      // Capacity one and one send ever, so the only refusal is a deployment that has already gone.
      Ok(()) => {
        let _ = fired.try_send(());
      }
      // HOLD the line rather than let it go — see the function's own note. The task is dropped with
      // the runtime, which is where a process's handlers end anyway.
      Err(_) => core::future::pending::<()>().await,
    }
  });
  source
}

#[cfg(test)]
mod tests {
  use crate::conduit::Receiver;

  /// **THE ADAPTER IS AN EXIT SOURCE** — the whole of what this module owes, checked by naming it
  /// rather than by running it.
  ///
  /// NOTHING IS INSTALLED HERE, deliberately: a signal handler is process-wide, so a unit test that
  /// installed one would change the behaviour of every other test in the binary and of the harness
  /// running them. What can be checked without that is the only thing worth checking — that the
  /// function exists under its feature and that its answer is the type
  /// [`App::halt_on`](crate::App::halt_on) takes — and coercing it to a `fn` pointer of exactly
  /// that shape is what checks it.
  #[test]
  fn the_gated_adapter_answers_the_seat_s_own_type() {
    let source: fn() -> Receiver<()> = super::ctrl_c;
    // Named so the coercion is a compile and not an unused-binding warning. Calling it is what this
    // test refuses to do.
    let _ = source;
  }
}