cc_lb_plugin_wire/v1/mod.rs
1//! Wire schema version 1 (baseline).
2//!
3//! Shared types between host (`cc-lb-runtime-wasmtime`) and guest
4//! (`cc-lb-pdk-wasmtime`) compiled in lockstep.
5//!
6//! Wire types for the three hooks the wasmtime runtime ships:
7//! filter (Phase 1), shape (Phase 2), observe
8//! (Phase 2). Signer extension is intentionally not exposed across
9//! the plugin boundary — host-side built-in `AnthropicKeySigner` /
10//! `AnthropicOAuthSigner` handle credential signing in-process.
11//!
12//! rkyv derives `Archive` + `Serialize` + `Deserialize` for every wire type.
13//! The host calls `rkyv::access::<ArchivedFilterRequest, rkyv::rancor::Error>`
14//! to get a zero-copy `&ArchivedFilterRequest` view straight out of guest
15//! linear memory; the guest mirrors that pattern in reverse for the response.
16//!
17//! ## ABI invariants (review consensus)
18//!
19//! * Every guest-allocated buffer is aligned to `align_of::<Archived<T>>()`
20//! for its root type. rkyv 0.8's default relative pointers require this;
21//! the alignment is propagated through `cc_lb_alloc(size, align)`.
22//! * `Arc`/`Rc` MUST NOT appear in any wire type (rkyv 0.8 Issue #670 —
23//! `ArchivedRc::verify` can be bypassed for DST shared pointers).
24//! * The wire schema is fingerprinted via BLAKE3 of `cc_lb_schema_hash`
25//! custom section content. Host and guest must agree byte-for-byte.
26//!
27//! ## Borrowed-wire optimisation (RFC-0001 #9)
28//!
29//! Host-to-guest request types (FilterRequest, ShapeRequest) come in
30//! two flavours that produce IDENTICAL archived bytes:
31//! * **Owned** (`FilterRequest`, `ShapeRequest`, ...) — owned `Box<str>`
32//! / `Box<[u8]>` fields. Used by the guest for `rkyv::deserialize`
33//! round-trips and for round-trip test fixtures.
34//! * **Borrowed ref** (`FilterRequestRef<'a>`, `ShapeRequestRef<'a>`,
35//! ...) — `&'a str` / `&'a [u8]` fields with `#[rkyv(with =
36//! InlineAsBox)]`. Used by the host in `wire_to_host_wire_request`
37//! so the request body (up to 100 MiB on `/v1/files`) is serialised
38//! IN PLACE from the request pipeline's `bytes::Bytes` without any
39//! `.to_vec()` copy.
40//!
41//! Both variants archive to the same `ArchivedBox<ArchivedSlice<u8>>`
42//! / `ArchivedBox<ArchivedStr>` byte layouts — verified by the wire
43//! round-trip tests in `crates/cc-lb-plugin-wire/tests/borrowed_wire_roundtrip.rs`.
44//! When either variant is written to guest memory, the guest reads it
45//! via `rkyv::access::<ArchivedFilterRequest, _>` — the archived
46//! type name is identical because the owned type is the sole `Archive`
47//! source of truth; the ref type carries `#[rkyv(archived = ...)]` to
48//! reuse the owned type's archived form.
49//!
50//! See `docs/rfc/0001-plugin-runtime-vnext.md`.
51
52use alloc::boxed::Box;
53
54use rkyv::{Archive, Deserialize, Serialize, with::InlineAsBox};
55
56/// Principal context as seen by the filter plugin.
57///
58/// Mirrors `cc_lb_plugin_api::Principal` semantically but the rkyv-derived
59/// wire form is the source of truth on the host↔guest boundary.
60#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
61#[rkyv(derive(Debug))]
62pub struct Principal {
63 pub id: Box<str>,
64 pub kind: Box<str>,
65 /// Free-form key/value claims. Bytes intentionally, not JSON.
66 /// Modelled as a named `Claim` struct (not a tuple) so the
67 /// borrowed [`ClaimRef`] and this owned form archive to the same
68 /// byte layout for host/guest wire compatibility.
69 pub claims: Box<[Claim]>,
70}
71
72/// One claim key/value pair — see [`Principal::claims`]. Named
73/// struct (not tuple) so that `ClaimRef<'a>` matches the archived
74/// byte layout without an extra Ref wrapper.
75#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
76#[rkyv(derive(Debug))]
77pub struct Claim {
78 pub key: Box<str>,
79 pub value: Box<[u8]>,
80}
81
82/// Borrowed mirror of [`Principal`] used by the host encode path. Every
83/// reference field carries `#[rkyv(with = InlineAsBox)]` so serialising
84/// this struct emits the same archived byte layout as [`Principal`].
85#[derive(Archive, Serialize)]
86pub struct PrincipalRef<'a> {
87 #[rkyv(with = InlineAsBox)]
88 pub id: &'a str,
89 #[rkyv(with = InlineAsBox)]
90 pub kind: &'a str,
91 #[rkyv(with = InlineAsBox)]
92 pub claims: &'a [ClaimRef<'a>],
93}
94
95/// One claim entry inside [`PrincipalRef`]. The tuple form used by the
96/// owned type does not have a straight borrowed equivalent, so we
97/// promote it to a named struct with two borrowed fields.
98#[derive(Archive, Serialize)]
99pub struct ClaimRef<'a> {
100 #[rkyv(with = InlineAsBox)]
101 pub key: &'a str,
102 #[rkyv(with = InlineAsBox)]
103 pub value: &'a [u8],
104}
105
106/// One upstream candidate the filter plugin can choose to keep or drop.
107#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
108#[rkyv(derive(Debug))]
109pub struct UpstreamCandidate {
110 pub upstream_id: Box<str>,
111 pub name: Box<str>,
112 pub kind: Box<str>,
113 pub observed_at_unix_secs: u64,
114 pub predicted_cache_read_tokens: u32,
115 pub plan_capacity_ratio: f64,
116 pub organization_type: Box<str>,
117 pub rate_limit_tier: Box<str>,
118 pub seat_tier: Box<str>,
119}
120
121/// Borrowed mirror of [`UpstreamCandidate`].
122#[derive(Archive, Serialize)]
123pub struct UpstreamCandidateRef<'a> {
124 #[rkyv(with = InlineAsBox)]
125 pub upstream_id: &'a str,
126 #[rkyv(with = InlineAsBox)]
127 pub name: &'a str,
128 #[rkyv(with = InlineAsBox)]
129 pub kind: &'a str,
130 pub observed_at_unix_secs: u64,
131 pub predicted_cache_read_tokens: u32,
132 pub plan_capacity_ratio: f64,
133 #[rkyv(with = InlineAsBox)]
134 pub organization_type: &'a str,
135 #[rkyv(with = InlineAsBox)]
136 pub rate_limit_tier: &'a str,
137 #[rkyv(with = InlineAsBox)]
138 pub seat_tier: &'a str,
139}
140
141/// One header on the inbound request.
142#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
143#[rkyv(derive(Debug))]
144pub struct Header {
145 pub name: Box<str>,
146 /// Raw header bytes — never base64'd. The whole point of the rkyv wire is
147 /// to remove that encode/decode hop.
148 pub value: Box<[u8]>,
149}
150
151/// Borrowed mirror of [`Header`].
152#[derive(Archive, Serialize)]
153pub struct HeaderRef<'a> {
154 #[rkyv(with = InlineAsBox)]
155 pub name: &'a str,
156 #[rkyv(with = InlineAsBox)]
157 pub value: &'a [u8],
158}
159
160/// Filter hook input (owned form used by the guest).
161#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
162#[rkyv(derive(Debug))]
163pub struct FilterRequest {
164 pub request_id: Box<str>,
165 pub method: Box<str>,
166 pub path: Box<str>,
167 pub query: Option<Box<str>>,
168 pub headers: Box<[Header]>,
169 pub body: Box<[u8]>,
170 pub principal: Principal,
171 pub candidates: Box<[UpstreamCandidate]>,
172}
173
174/// Borrowed mirror of [`FilterRequest`] used by the host encode path.
175/// Serialising this emits the same archived byte layout as
176/// [`FilterRequest`] so the guest reads it via
177/// `rkyv::access::<ArchivedFilterRequest, _>` unchanged.
178#[derive(Archive, Serialize)]
179pub struct FilterRequestRef<'a> {
180 #[rkyv(with = InlineAsBox)]
181 pub request_id: &'a str,
182 #[rkyv(with = InlineAsBox)]
183 pub method: &'a str,
184 #[rkyv(with = InlineAsBox)]
185 pub path: &'a str,
186 pub query: Option<QueryRef<'a>>,
187 #[rkyv(with = InlineAsBox)]
188 pub headers: &'a [HeaderRef<'a>],
189 #[rkyv(with = InlineAsBox)]
190 pub body: &'a [u8],
191 pub principal: PrincipalRef<'a>,
192 #[rkyv(with = InlineAsBox)]
193 pub candidates: &'a [UpstreamCandidateRef<'a>],
194}
195
196/// Borrowed wrapper for the optional `query` field. Necessary because
197/// `Option<InlineAsBox<&'a str>>` does not compose directly at the
198/// derive layer; a named struct pushes the `#[rkyv(with = ...)]`
199/// attribute onto the inner reference.
200#[derive(Archive, Serialize)]
201pub struct QueryRef<'a> {
202 #[rkyv(with = InlineAsBox)]
203 pub value: &'a str,
204}
205
206/// Decision the plugin made for one candidate.
207#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
208#[rkyv(derive(Debug))]
209pub struct PerCandidateReason {
210 pub upstream_id: Box<str>,
211 /// `"accept"` or `"reject"` — kept as string so plugins remain forward-
212 /// compatible with future decision variants without a host re-bump.
213 pub decision: Box<str>,
214 pub reason: Box<str>,
215}
216
217/// Filter hook output.
218///
219/// Guest packs `(out_ptr, out_len)` into a single `u64` (`(ptr << 32) | len`)
220/// for the return value of `cc_lb_filter`. The host reads the bytes via
221/// `Memory::data(&store)` and runs `rkyv::access::<ArchivedFilterResponse, _>`.
222#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
223#[rkyv(derive(Debug))]
224pub struct FilterResponse {
225 pub results: Box<[PerCandidateReason]>,
226}
227
228/// Upstream backend exposed to plugins. Mirrors
229/// `cc_lb_plugin_api::Upstream` (currently a single variant —
230/// extending the host enum requires extending this one in lockstep
231/// and bumping a wire schema tag).
232#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
233#[rkyv(derive(Debug))]
234pub enum Upstream {
235 AnthropicDirect {
236 /// Operator-configured base URL override, if any.
237 base_url: Option<Box<str>>,
238 },
239}
240
241/// Borrowed mirror of [`Upstream`].
242#[derive(Archive, Serialize)]
243pub enum UpstreamRef<'a> {
244 AnthropicDirect { base_url: Option<QueryRef<'a>> },
245}
246
247/// Shape hook input (owned form).
248#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
249#[rkyv(derive(Debug))]
250pub struct ShapeRequest {
251 pub request_id: Box<str>,
252 pub method: Box<str>,
253 pub path: Box<str>,
254 pub query: Option<Box<str>>,
255 pub headers: Box<[Header]>,
256 pub body: Box<[u8]>,
257 pub principal: Principal,
258 pub upstream: Upstream,
259}
260
261/// Borrowed mirror of [`ShapeRequest`] used by the host encode path.
262#[derive(Archive, Serialize)]
263pub struct ShapeRequestRef<'a> {
264 #[rkyv(with = InlineAsBox)]
265 pub request_id: &'a str,
266 #[rkyv(with = InlineAsBox)]
267 pub method: &'a str,
268 #[rkyv(with = InlineAsBox)]
269 pub path: &'a str,
270 pub query: Option<QueryRef<'a>>,
271 #[rkyv(with = InlineAsBox)]
272 pub headers: &'a [HeaderRef<'a>],
273 #[rkyv(with = InlineAsBox)]
274 pub body: &'a [u8],
275 pub principal: PrincipalRef<'a>,
276 pub upstream: UpstreamRef<'a>,
277}
278
279/// Shape hook output — the upstream-bound request the plugin produced.
280#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
281#[rkyv(derive(Debug))]
282pub struct ShapeResponse {
283 pub url: Box<str>,
284 pub method: Box<str>,
285 pub headers: Box<[Header]>,
286 pub body: Box<[u8]>,
287}
288
289/// Lifecycle event delivered to the observe hook. rkyv mirror of
290/// `cc_lb_plugin_api::ObserveEvent`.
291#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
292#[rkyv(derive(Debug))]
293pub enum ObserveEvent {
294 RequestStarted {
295 request_id: Box<str>,
296 downstream_user_agent: Option<Box<str>>,
297 },
298 AuthnComplete {
299 principal_id: Box<str>,
300 principal_kind: Box<str>,
301 },
302 UpstreamChosen {
303 upstream: Upstream,
304 },
305 Chunk {
306 batch_index: u64,
307 event_count: u64,
308 total_bytes: u64,
309 },
310 RequestFinished {
311 status: u16,
312 input_tokens: Option<u64>,
313 output_tokens: Option<u64>,
314 cache_creation_input_tokens: Option<u64>,
315 cache_read_input_tokens: Option<u64>,
316 duration_ms: u64,
317 },
318 Error {
319 code: Box<str>,
320 message: Box<str>,
321 source: Box<str>,
322 },
323}
324
325include!(concat!(env!("OUT_DIR"), "/wire_schema_impls.rs"));