tocat-api 0.2.0

Public plugin API for tocat, a socat-inspired relay
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

# tocat-api

The plugin contract for [tocat](https://crates.io/crates/tocat), a
socat-inspired relay. Depend on this to write a plugin; depend on `tocat` to run
one.

```console
$ 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:

```rust,ignore
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](https://github.com/lkalir/tocat), covers the trait, units and
boundaries, ticks, effects and testing.

## License

MIT or Apache-2.0, at your option.