plexor-codec-capnp 0.1.0-alpha.2

Cap'n Proto codec implementation for the Plexo distributed system architecture.
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
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

# Plexor Codec: Cap'n Proto

**plexor-codec-capnp** provides a high-performance binary codec implementation for the [Plexor](https://github.com/my-org/plexor) distributed system architecture using [Cap'n Proto](https://capnproto.org/).

It is designed for scenarios requiring extremely low latency and high throughput, as Cap'n Proto messages avoid the heavy serialization/deserialization steps common in other formats.

## Features

- **High Performance**: Designed for low-latency messaging.
- **Schema Evolution**: Robust handling of schema changes.
- **Plexor Integration**: Implements `Codec` for `plexor-core`.
- **Flexible Mapping**: Supports both raw Cap'n Proto types and ergonomic Rust structs via `capnp_conv`.

> **Note on Performance**: While the Cap'n Proto format is highly efficient, using the `capnp_conv` mapping layer introduces a small amount of overhead when translating between native Rust structs and the Cap'n Proto memory layout. Although not quite as efficient as using raw Cap'n Proto readers and builders, it remains significantly faster than JSON (as shown in the benchmarks below). For absolute maximum performance where every microsecond counts, users should consider using the raw generated Cap'n Proto readers and builders directly.

### Benchmarks

Comparison between `plexor-codec-serde-json` and `plexor-codec-capnp` (approximate values). Detailed benchmarks can be found in [examples/codec-comparison-benchmark/](../examples/codec-comparison-benchmark/).

| Operation | Size | JSON (Serde) | Cap'n Proto (`capnp_conv`) | Speedup |
| :--- | :--- | :--- | :--- | :--- |
| **Encode** | 100 B | ~447 ns | ~352 ns | **~1.3x** |
| **Decode** | 100 B | ~958 ns | ~333 ns | **~2.9x** |
| **Encode** | 10 KB | ~31.6 µs | ~5.5 µs | **~5.7x** |
| **Decode** | 10 KB | ~71.2 µs | ~5.6 µs | **~12.7x** |
| **Encode** | 1 MB | ~3.2 ms | ~513 µs | **~6.2x** |
| **Decode** | 1 MB | ~7.2 ms | ~540 µs | **~13.3x** |

*Benchmarks run on a Framework 13 (AMD Ryzen 7 7840U, 32GB RAM) running Linux (x86_64).*

## Usage

### 1. Add Dependencies & Build Script

**Cargo.toml**:
```toml
[dependencies]
plexor-core = "0.1.0-alpha.1"
plexor-codec-capnp = "0.1.0-alpha.1"
capnp = "0.20"
capnp_conv = "0.3"

[build-dependencies]
capnpc = "0.20"
```

**build.rs**:
```rust
fn main() {
    capnpc::CompilerCommand::new()
        .file("schema/my_schema.capnp")
        // .output_path("src/schema/") // Optional: customize output
        .run()
        .expect("compiling schema");
}
```

### 2. Define Schema (my_schema.capnp)

```capnp
@0x1234567890abcdef;

struct MyMessage {
  content @0 :Text;
  count @1 :UInt32;
}
```

### 3. Define Rust Struct & Neuron

Use `capnp_conv` to map your Rust struct to the Cap'n Proto schema.

```rust
use capnp_conv::capnp_conv;
use plexor_codec_capnp::CapnpCodec;
use plexor_core::neuron::NeuronImpl;
use plexor_core::namespace::NamespaceImpl;
use std::sync::Arc;

// Include the generated capnp code (adjust path as needed)
// include!(concat!(env!("OUT_DIR"), "/my_schema_capnp.rs")); 
// Or if you output to src:
mod my_schema_capnp { include!("schema/my_schema_capnp.rs"); }

#[derive(Debug, Clone)]
#[capnp_conv(my_schema_capnp::my_message)]
struct MyMessage {
    content: String,
    count: u32,
}

// Define the Neuron
let neuron = NeuronImpl::<MyMessage, CapnpCodec>::new_arc(
    Arc::new(NamespaceImpl {
        delimiter: ".",
        parts: vec!["my", "capnp", "message"],
    })
);
```

## License

Mozilla Public License, version 2.0.