cc-lb-plugin-conformance 0.2.0

In-process conformance harness for cc-lb wasmtime plugin authors. Verifies plugin ABI and wire fingerprint matches host.
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

# cc-lb-plugin-conformance

`cc-lb-plugin-conformance` is a development dependency for cc-lb wasm plugin
authors. It loads a compiled plugin through the same inspection, admission, and
runtime path used by the host, then runs boundary smoke tests for the exported
hook.

Use it in plugin crates to catch ABI, metadata, wire version, and layout
fingerprint drift before uploading the wasm artifact.

## Add as a Dev-Dependency

```toml
[dev-dependencies]
cc-lb-plugin-conformance = "0.2"
```

Build the plugin for `wasm32-unknown-unknown` before running the test:

```bash
cargo build --release --target wasm32-unknown-unknown
```

## `ConformanceSuite::from_wasm(bytes)`

`ConformanceSuite::from_wasm(bytes)` inspects the artifact and infers the hook
kind when the wasm exports exactly one supported hook.

```rust
use cc_lb_plugin_conformance::ConformanceSuite;

let wasm = std::fs::read(
    "target/wasm32-unknown-unknown/release/my_plugin.wasm",
)?;

let suite = ConformanceSuite::from_wasm(&wasm);
```

Use `for_filter`, `for_shape`, or `for_observe` instead when a single wasm
artifact exports multiple hooks.

## `assert_recognisable_by_current_host()`

`assert_recognisable_by_current_host()` runs the current host admission path:

- compile the wasm module with wasmtime
- verify required exports and import restrictions
- parse plugin and hook metadata
- verify declared wire versions are supported
- verify embedded layout fingerprints match the current host
- run the canonical runtime probe for each declared hook

This is the static gate to run in CI whenever the plugin or host crates change.

## `run()`

`run()` builds a live wasmtime runtime, registers the plugin, and exercises the
hook boundary with canonical sample payloads.

It verifies allocator exports, hook exports, rkyv encode/decode round-trips,
and observe variant handling. It does not verify plugin business semantics such
as routing policy or URL rewriting; keep those assertions in your own tests.

## Sample Test

```rust
use cc_lb_plugin_conformance::ConformanceSuite;

fn wasm_bytes() -> Vec<u8> {
    std::fs::read(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/target/wasm32-unknown-unknown/release/my_plugin.wasm"
    ))
    .expect("build plugin wasm first")
}

#[test]
fn plugin_is_recognisable_by_current_host() {
    let wasm = wasm_bytes();
    ConformanceSuite::from_wasm(&wasm)
        .with_plugin_name("my-plugin")
        .assert_recognisable_by_current_host();
}

#[test]
fn plugin_passes_boundary_smoke() {
    let wasm = wasm_bytes();
    ConformanceSuite::from_wasm(&wasm)
        .with_plugin_name("my-plugin")
        .run();
}
```

## 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>
- Wire README: <https://github.com/isac322/cc-lb/blob/master/crates/cc-lb-plugin-wire/README.md>
- PDK README: <https://github.com/isac322/cc-lb/blob/master/crates/cc-lb-pdk-wasmtime/README.md>

## License

Licensed under the workspace license.