Module plugin 

The plugin traits and the contexts they are driven through.

The lifecycle is four calls and two contexts. PluginFactory::build runs once per direction per connection with a BuildCtx: this is where config is deserialized, side channels are reserved, and anything derived from the stage’s fixed position is cached. Plugin::on_bytes then runs per chunk with a Ctx, Plugin::on_tick runs on a schedule the stage asks for, and Plugin::on_eof once at the end: the last chance for a stage holding buffered bytes to emit them, and where a codec writes its epilogue.

The split between the two contexts is the point: everything expensive or fallible belongs to build time, so the per-chunk path is a synchronous call that either forwards a slice or writes into a buffer.

A call emits one unit by default, however many times it forwards: the pieces concatenate, and the host delivers them as one write. A stage that needs them kept apart says so with Ctx::boundary, which is what turns a stage that merely accumulates bytes into one that records them.

Modules

exports

The names a guest exports, so that a host looks them up from the same place a guest is documented against.

Structs

BuildCtx

Handed to a PluginFactory while constructing one instance.

Ctx

Handed to a plugin for each chunk.

Emission

What one call to a stage produced: the bytes it emitted, how they are framed, and what it asked the host to do about its own schedule.

ExternalStage

A subprocess to run as a stage, with the relay’s bytes on its stdin and its stdout continuing downstream.

LogRecord

One queued log record: a level, and a string in the guest’s memory.

Outbox

What a call left behind for the host.

PipelineMeta

Static description of the path a pipeline instance sits on.

StageInfo

Where a stage sits in its pipeline, and what it is called.

Enums

Boundaries

What a stage does to the message boundaries passing through it.

Emit

What a stage decided to do with the chunk it was given.

Execution

Where the host runs a stage.

Level

Severity of a queued log record, in the order every logging library writes them.

LogLevel

Severity of a record a stage asked the host to log.

Needs

What a stage needs of the path it is placed on.

Stage

What a factory produced.

StderrMode

What to do with a child’s stderr.

Constants

TOCAT_ABI_VERSION

Bumped for any change to what the host reads or to what a value means: the struct below, the set of exports, or the interpretation of either. A guest reporting a different version is refused when it loads rather than being read as garbage.

TOCAT_BOUNDARIES_FUSE

The units this stage was given do not reach the stage below. Anything that buffers across calls, splits, or coalesces.

TOCAT_BOUNDARIES_MASK

Mask for the boundary effect in tocat_boundaries: bits 0 and 1.

TOCAT_BOUNDARIES_PRESERVE

One unit in, one unit out.

TOCAT_BOUNDARIES_SEAL

One unit in, one unit out, and the boundary is also written into the bytes, so it survives a stage below that fuses. What frame does.

TOCAT_BOUNDARIES_SPLIT

The units below are read out of the bytes rather than inherited from above, so the ones from above do not survive. What unframe does.

TOCAT_DEBUG

TOCAT_EMIT_BUFFERED

Forward bytes, framed by bounds.

TOCAT_EMIT_PASSTHROUGH

Forward the input unchanged. The host does not read the guest’s bytes at all, and nothing is copied in either direction.

TOCAT_EMIT_PENDING

Forward nothing. Emitting nothing means the same thing; this exists so that a filter can say it on purpose.

TOCAT_ERROR

TOCAT_FLAG_ERROR

Fail the path, with message as the reason.

TOCAT_FLAG_HALT

End the path: upstream end of stream arriving early, and a success.

TOCAT_FLAG_PACE

Wait pace_ns before reading upstream again.

TOCAT_FLAG_REARM

Restart this stage’s tick schedule from now.

TOCAT_INFO

TOCAT_LOG_RECORD_LEN

Bytes per record in the log array.

TOCAT_NEEDS_BOTH

Both of the above.

TOCAT_NEEDS_DOWNSTREAM

The units this stage emits must reach the endpoint below or a TOCAT_BOUNDARIES_SEAL stage, or what it emitted cannot be read back.

TOCAT_NEEDS_MASK

Mask for the requirement in tocat_boundaries: bits 2 and 3.

TOCAT_NEEDS_NOTHING

The stage works on any path.

TOCAT_NEEDS_UPSTREAM

Every call must carry one whole message, so boundaries have to reach this stage from the endpoint above or from a TOCAT_BOUNDARIES_SPLIT stage.

TOCAT_OUTBOX_LEN

Bytes the host reads at tocat_outbox().

TOCAT_TRACE

TOCAT_WARN

Traits

EffectSink

Collects the side effects a plugin asks for during one call.

Plugin

One stage of a pipeline. Instances are per-direction and per-connection.

PluginFactory

Constructs Plugin instances from a declared entry.

Functions

pack_boundaries

Pack what tocat_boundaries returns.

unpack_boundaries

Read what tocat_boundaries returned.