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

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.

Stage

What a factory produced.

StderrMode

What to do with a child’s stderr.

Constants

TOCAT_ABI_VERSION

Bumped for any change to the layout below. A guest reporting a different version is refused when it loads rather than being read as garbage.

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_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.