Skip to content

Global pipes

One pipe over every request body, GraphQL operation's variables and WebSocket message's data — registered once, handed the unit it shapes.

A global pipe shapes input across the whole app at once: register it in main, and every route, /graphql operation and WebSocket message runs it before anything decodes its input. It reads the raw JSON through one method, transform, which is handed the unit’s context and the kind of input it holds.

crates/features/src/pipes/trim_strings.rs
use nest_rs::core::{Layer, UnitContext, injectable};
use nest_rs::pipes::{ArgumentKind, GlobalPipe, PipeError};
use serde_json::Value;
#[injectable]
#[derive(Layer)]
pub struct TrimStrings;
impl GlobalPipe for TrimStrings {
fn transform(
&self,
_cx: &UnitContext<'_>,
argument: ArgumentKind,
input: &mut Value,
) -> Result<(), PipeError> {
if argument != ArgumentKind::Body {
return Ok(());
}
if let Some(fields) = input.as_object_mut() {
for field in fields.values_mut() {
if let Value::String(text) = field {
*text = text.trim().to_owned();
}
}
}
Ok(())
}
}
Terminal window
cargo add nest-rs --features pipes

The http feature turns it on, and http is a default.

Unlike a per-argument pipe, a global pipe is a provider: #[injectable], called with &self. The module the app boots lists it once, and the pool registers it unless the app already does:

apps/blog/src/module.rs
use nest_rs::pipes::GlobalPipes;
use features::pipes::TrimStrings;
use nest_rs::core::module;
#[module(
imports = [/* … */],
providers = [GlobalPipes<(TrimStrings,)>],
)]
pub struct BlogModule;

What the pipe injects is held to that module’s imports: a pipe the pool cannot build fails the boot, naming it, whether or not the app serves HTTP; so does a pool a module the app imports declares, or a second one. A pipe a feature’s module lists stays that module’s, and the pool only names it.

argument says which input input is, since a unit’s name cannot say it (the /graphql request is an http.request like a route):

ArgumentKindThe inputWhere it runsA refusal answers
Bodyan HTTP request’s JSON bodyevery route, after its guards; #[no_pipes] opts a route outa 400 problem
Variablesa /graphql operation’s variablesat the endpoint, before any resolver — a POST, or an operation sent over the graphql-ws socket, a subscription includeda GraphQL error; on the socket, the protocol’s error for that operation, which never starts
Dataa WebSocket message’s dataafter the message’s guards and its class gate, before its handleran error frame for the event

cx is the unit’s context, as a guard’s is: cx.edge() and cx.handler() say which site the input is for, cx.reflector() reads its #[meta], and cx.switch_to::<HttpView>() reaches the request a body or a /graphql operation came in — over the graphql-ws socket, the request that opened it; WsView gives a message’s event. The input itself is the argument, never the view’s.

The pool runs once per type however often it is listed, the first listed first. ArgumentKind is #[non_exhaustive]: match it with a fallback arm, as an edge may hand a new kind in a minor release.

  • An HTTP body that is not JSON reaches no pipe.
  • MCP tool arguments and queue payloads take no global pipe: bind a per-argument pipe there (Piped<P>); a type declaring rules is validated there all the same.
  • A WebSocket message no handler reads, an event none serves or a frame no envelope holds, meets no pipe: nothing would read what it made.
  • A pipe reads and writes a serde_json::Value, the one place the framework passes one through: the input is not decoded yet, so there is no type to hand. The handler still receives its argument parsed into its own type, and a per-argument pipe stays typed.
  • Pipes — the per-argument binding, on every edge.
  • Guards — the same UnitContext, run before the pipes.