Crate tocat_api 

Public plugin API for tocat.

A plugin is a synchronous byte transformer. It is handed a chunk of bytes that arrived from upstream and decides what to forward downstream. Anything that touches the outside world (writing a dump file, emitting a log line) is not performed by the plugin. It is queued as an [Effect] and applied by the host after the call returns.

That split is deliberate. It keeps plugins pure and trivially testable, it keeps all I/O on the host’s async runtime, and it is the shape a WASM guest has to take anyway (guest calls a host import, host performs the syscall). A future WasmPlugin implements Plugin like any other; nothing in the relay needs to change.

The same split covers time. A stage cannot await and cannot read a clock (a guest has no way to reach one) so a stage that needs time rather than traffic to drive it declares a period with Plugin::tick_interval and is called back through Plugin::on_tick. The host holds the timer and decides when anyone is due.

Composition

Plugins are declared once and instantiated per direction. A declaration list [a, b] with direction = "both" produces:

source --> a --> b --> sink        (Direction::SourceToSink)
source <-- a <-- b <-- sink        (Direction::SinkToSource)

The reverse pipeline is the mirror of the declaration order, so wrapping plugins (framing, compression, encryption) nest correctly without the user having to write the pipeline out twice. Each direction gets its own instance, so per-direction state (byte offsets, codec state) never leaks across paths.

Re-exports

pub use crate::channel::ChannelId;

pub use crate::channel::ChannelTarget;

pub use crate::channel::HostBuilder;

pub use crate::error::PluginError;

pub use crate::error::Result;

pub use crate::forgiving::Forgiving;

pub use crate::interval::Interval;

pub use crate::interval::ParseIntervalError;

pub use crate::normalize::canonical;

pub use crate::normalize::normalize;

pub use crate::pipeline::BoundaryFault;

pub use crate::pipeline::Chain;

pub use crate::pipeline::Emitted;

pub use crate::pipeline::Pipeline;

pub use crate::pipeline::Registry;

pub use crate::pipeline::Segment;

pub use crate::pipeline::Side;

pub use crate::plugin::BuildCtx;

pub use crate::plugin::Ctx;

pub use crate::plugin::EffectSink;

pub use crate::plugin::Emission;

pub use crate::plugin::Execution;

pub use crate::plugin::ExternalStage;

pub use crate::plugin::PipelineMeta;

pub use crate::plugin::Plugin;

pub use crate::plugin::PluginFactory;

pub use crate::plugin::Stage;

pub use crate::plugin::StageInfo;

pub use crate::plugin::StderrMode;

pub use crate::size::ByteSize;

pub use crate::size::ParseSizeError;

Modules

channel

Side channels: the only way a plugin reaches the outside world.

error

Errors crossing the plugin boundary.

forgiving

forgiving.rs: the deserializer that applies normalize to a plugin’s own config, without the plugin having to know.

interval

normalize

normalize.rs: one spelling rule for every identifier tocat matches.

pipeline

Composition: chains of Plugin stages, and the registry that builds them.

plugin

The plugin traits and the contexts they are driven through.

size

size.rs: one grammar for every byte count tocat accepts.

Structs

ParseDirectionError

PluginSpec

A declared pipeline entry: which plugin, on which path, with what config.

Enums

Boundaries

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

Direction

One of the two byte paths through the relay.

DirectionSpec

Which path(s) a declared plugin applies to.

Emit

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

LogLevel

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

Needs

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