tocat-api

The plugin contract for tocat, a socat-inspired relay. Depend on this to write a plugin; depend on tocat to run one.

$ cargo add tocat-api

A plugin is a synchronous byte transformer. It is handed a chunk and decides what to forward, and anything that touches the outside world (writing a dump file, emitting a log line, waiting, stopping the transfer) is queued as an effect for the host to perform rather than done in place:

impl Plugin for Upper {
    fn name(&self) -> &str { "upper" }

    fn on_bytes(&mut self, ctx: &mut Ctx<'_>, input: &[u8]) -> Result<()> {
        ctx.forward(&input.to_ascii_uppercase());
        Ok(())
    }
}

Three properties follow from that split, and they are the reason for it: a stage is testable without a runtime, nothing in it can stall a reactor thread, and the same shape compiles to a WebAssembly guest, which cannot own a socket or a clock at all.

This crate depends on serde and nothing else. No tokio, no I/O, no relay.

Documentation

The plugin API section of the book, under docs/ in the repository, covers the trait, units and boundaries, ticks, effects and testing.

License

MIT or Apache-2.0, at your option.