Struct Ctx 

pub struct Ctx<'a> { /* private fields */ }

Handed to a plugin for each chunk.

A stage must say what happens to the chunk: pass_through forwards it untouched, forward emits different bytes, and doing neither drops it. Passthrough is the fast path and costs nothing (the next stage receives the same slice).

Several calls to forward in one turn emit one unit, not several: the bytes concatenate and are delivered together. boundary is how a stage says otherwise.

Implementations

impl<'a> Ctx<'a>

pub fn new( meta: &'a PipelineMeta, stage: &'a str, input: &'a [u8], emission: &'a mut Emission, sink: &'a mut dyn EffectSink, ) -> Self

pub fn stage(&self) -> &str

This stage’s display name, as it appears in logs.

pub fn meta(&self) -> &PipelineMeta

pub fn direction(&self) -> Direction

pub fn input(&self) -> &[u8]

The chunk this call was given. Empty during Plugin::on_eof.

pub fn pass_through(&mut self)

Forward the input unchanged, without copying it.

pub fn forward(&mut self, bytes: &[u8])

Emit bytes downstream. Performs a copy. Use pass_through when the bytes are the input.

Appends: calling this twice emits both, in order, as one unit. Call boundary between them to emit two.

pub fn drop_chunk(&mut self)

Explicitly swallow the chunk. Emitting nothing does the same thing; this exists so a filter can state the intent.

pub fn boundary(&mut self)

End the current unit. What was forwarded since the last boundary is delivered on its own: one write at a byte sink, one message at a datagram sink, one parcel across a detached boundary, and one on_bytes call at every stage below.

Only worth calling when those splits are the point, as with a stage cutting a stream into fixed-size records. Framing is not free: each stage below is then called once per unit rather than once per chunk, so a stage that emits many small units is asking the rest of the segment to run many times. A stage that only rewrites bytes should leave the framing it was given alone and say nothing.

The trailing unit does not need one: whatever is forwarded after the last boundary is closed automatically, so no bytes can be lost by forgetting.

Ignored when nothing has been forwarded since the last call, so a stage cannot emit an empty unit by accident.

pub fn rearm(&mut self)

Restart this stage’s tick schedule: the next on_tick falls a full interval from now rather than wherever the existing cadence happens to land.

A stage cannot read a clock, so it cannot measure how long it has been holding something. What it can do is say when the waiting started, and this is how. A stage that begins accumulating calls this, and its next tick then means “an interval since you asked” rather than “an interval since some earlier moment you know nothing about”.

Without it, tick_interval is a cadence rather than a delay: a tick that came due while bytes were flowing fires at the next opportunity, which can be immediately after the bytes it is about arrived.

Cheap to call, and harmless to call often: it sets a flag the host reads once at the end of the call. Ignored for a stage that asked for no ticks.

pub fn side_write(&mut self, channel: ChannelId, bytes: &[u8])

Stage bytes for a side channel obtained from BuildCtx::open_channel.

pub fn log(&mut self, level: LogLevel, message: &str)

pub fn pace(&mut self, delay: Duration)

Ask the host to wait delay before reading upstream again.

Applied after this call returns and after whatever was emitted has been written, so the bytes in hand are never held hostage by the wait. On a socket this is real backpressure: the read stops, the receive buffer fills, the window closes and the peer slows down. Nothing is buffered on this side.

pub fn halt(&mut self, reason: &str)

Ask the host to stop reading upstream, as if it had reached end of stream. reason is logged against this stage.