cc-lb-plugin-wire 0.4.0

Wire types and schema versioning contract for cc-lb wasm plugin authors.
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
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

# cc-lb-plugin-wire

`cc-lb-plugin-wire` is the shared wire contract between the cc-lb host and
wasm plugins. It contains the rkyv request and response types, hook and wire
version enums, layout fingerprint trait, and upload metadata schema used by the
wasmtime runtime.

Use this crate directly when writing plugin code that needs typed hook inputs
and outputs. The `cc-lb-pdk-wasmtime` crate re-exports the same wire types for
the common PDK path.

## What This Crate Provides

- Versioned hook wire types under `cc_lb_plugin_wire::v1`.
- `WireVersion`, currently `WireVersion::V1`.
- `HookKind` for `filter`, `shape`, and `observe` hooks.
- `WireSchema`, implemented by the PDK derive macro for layout fingerprints.
- `PluginMetadata` and `HookMetadata` behind the `std` feature.
- `pack_ret` and `unpack_ret` helpers for guest ABI return values.

## WireVersion, HookKind, and WireSchema

`WireVersion` identifies an incompatible wire layout line. The current baseline
is `V1`. New versions are added when a hook request or response layout changes
incompatibly.

`HookKind` names the three supported plugin hooks:

- `Filter` maps to the `cc_lb_filter` export.
- `Shape` maps to the `cc_lb_shape` export.
- `Observe` maps to the `cc_lb_observe` export.

`WireSchema` exposes a canonical descriptor and BLAKE3 fingerprint for a type.
The trait lives in this crate. The derive macro is re-exported by
`cc-lb-pdk-wasmtime` for plugin authors.

```rust
use cc_lb_pdk_wasmtime::WireSchema;

#[derive(WireSchema)]
pub struct CacheDecision {
    pub upstream_id: Box<str>,
    pub decision: Box<str>,
    pub reason: Box<str>,
}
```

Any field addition, removal, rename, reorder, or type edit changes the derived
descriptor and fingerprint. Plugin authors do not manage hashes manually.

## PluginMetadata Schema

The host expects one `cc_lb.plugin.v1` metadata section in each upload. PDK
macros generate that section from plugin and handler attributes.

Top-level metadata contains:

- `name`
- `version`
- `description`
- `usage`
- `hooks`

Each hook metadata entry contains:

- `wire_version`
- `description`
- `usage`

The upload path rejects missing metadata, unknown hook names, unsupported wire
versions, and empty description or usage text.

## Related Crates

- `cc-lb-plugin-api`: host-facing plugin slots and runtime API types.
- `cc-lb-pdk-wasmtime`: guest PDK runtime helpers and macro re-exports.
- `cc-lb-pdk-wasmtime-macros`: macro implementation for `#[cc_lb_plugin]`,
  `#[handler]`, and `#[derive(WireSchema)]`.
- `cc-lb-plugin-conformance`: in-process ABI and admission test harness.

## Links

- Main repository: <https://github.com/isac322/cc-lb>
- Plugin author guide: <https://github.com/isac322/cc-lb/blob/master/docs/plugin-author-guide.md>
- PDK README: <https://github.com/isac322/cc-lb/blob/master/crates/cc-lb-pdk-wasmtime/README.md>

## License

Licensed under the workspace license.