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 predicted_cache_creation_tokens_5m: u32,
116    pub predicted_cache_creation_tokens_1h: u32,
117    pub predicted_uncached_input_tokens: u32,
118    pub plan_capacity_ratio: f64,
119    pub organization_type: Box<str>,
120    pub rate_limit_tier: Box<str>,
121    pub seat_tier: Box<str>,
122}
123
124/// Borrowed mirror of [`UpstreamCandidate`].
125#[derive(Archive, Serialize)]
126pub struct UpstreamCandidateRef<'a> {
127    #[rkyv(with = InlineAsBox)]
128    pub upstream_id: &'a str,
129    #[rkyv(with = InlineAsBox)]
130    pub name: &'a str,
131    #[rkyv(with = InlineAsBox)]
132    pub kind: &'a str,
133    pub observed_at_unix_secs: u64,
134    pub predicted_cache_read_tokens: u32,
135    pub predicted_cache_creation_tokens_5m: u32,
136    pub predicted_cache_creation_tokens_1h: u32,
137    pub predicted_uncached_input_tokens: u32,
138    pub plan_capacity_ratio: f64,
139    #[rkyv(with = InlineAsBox)]
140    pub organization_type: &'a str,
141    #[rkyv(with = InlineAsBox)]
142    pub rate_limit_tier: &'a str,
143    #[rkyv(with = InlineAsBox)]
144    pub seat_tier: &'a str,
145}
146
147/// Model pricing summary supplied to filter plugins.
148#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
149#[rkyv(derive(Debug))]
150pub struct CachePricingSummary {
151    pub status: Box<str>,
152    pub input_micros_per_million: Option<u64>,
153    pub cache_creation_5m_micros_per_million: Option<u64>,
154    pub cache_creation_1h_micros_per_million: Option<u64>,
155    pub cache_read_micros_per_million: Option<u64>,
156}
157
158/// Borrowed mirror of [`CachePricingSummary`].
159#[derive(Archive, Serialize)]
160pub struct CachePricingSummaryRef<'a> {
161    #[rkyv(with = InlineAsBox)]
162    pub status: &'a str,
163    pub input_micros_per_million: Option<u64>,
164    pub cache_creation_5m_micros_per_million: Option<u64>,
165    pub cache_creation_1h_micros_per_million: Option<u64>,
166    pub cache_read_micros_per_million: Option<u64>,
167}
168
169/// One header on the inbound request.
170#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
171#[rkyv(derive(Debug))]
172pub struct Header {
173    pub name: Box<str>,
174    /// Raw header bytes — never base64'd. The whole point of the rkyv wire is
175    /// to remove that encode/decode hop.
176    pub value: Box<[u8]>,
177}
178
179/// Borrowed mirror of [`Header`].
180#[derive(Archive, Serialize)]
181pub struct HeaderRef<'a> {
182    #[rkyv(with = InlineAsBox)]
183    pub name: &'a str,
184    #[rkyv(with = InlineAsBox)]
185    pub value: &'a [u8],
186}
187
188/// Filter hook input (owned form used by the guest).
189#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
190#[rkyv(derive(Debug))]
191pub struct FilterRequest {
192    pub request_id: Box<str>,
193    pub thread_id: Option<Box<str>>,
194    pub canonical_model_id: Box<str>,
195    pub cache_pricing: CachePricingSummary,
196    pub method: Box<str>,
197    pub path: Box<str>,
198    pub query: Option<Box<str>>,
199    pub headers: Box<[Header]>,
200    pub body: Box<[u8]>,
201    pub principal: Principal,
202    pub candidates: Box<[UpstreamCandidate]>,
203}
204
205/// Borrowed mirror of [`FilterRequest`] used by the host encode path.
206/// Serialising this emits the same archived byte layout as
207/// [`FilterRequest`] so the guest reads it via
208/// `rkyv::access::<ArchivedFilterRequest, _>` unchanged.
209#[derive(Archive, Serialize)]
210pub struct FilterRequestRef<'a> {
211    #[rkyv(with = InlineAsBox)]
212    pub request_id: &'a str,
213    pub thread_id: Option<QueryRef<'a>>,
214    #[rkyv(with = InlineAsBox)]
215    pub canonical_model_id: &'a str,
216    pub cache_pricing: CachePricingSummaryRef<'a>,
217    #[rkyv(with = InlineAsBox)]
218    pub method: &'a str,
219    #[rkyv(with = InlineAsBox)]
220    pub path: &'a str,
221    pub query: Option<QueryRef<'a>>,
222    #[rkyv(with = InlineAsBox)]
223    pub headers: &'a [HeaderRef<'a>],
224    #[rkyv(with = InlineAsBox)]
225    pub body: &'a [u8],
226    pub principal: PrincipalRef<'a>,
227    #[rkyv(with = InlineAsBox)]
228    pub candidates: &'a [UpstreamCandidateRef<'a>],
229}
230
231/// Borrowed wrapper for the optional `query` field. Necessary because
232/// `Option<InlineAsBox<&'a str>>` does not compose directly at the
233/// derive layer; a named struct pushes the `#[rkyv(with = ...)]`
234/// attribute onto the inner reference.
235#[derive(Archive, Serialize)]
236pub struct QueryRef<'a> {
237    #[rkyv(with = InlineAsBox)]
238    pub value: &'a str,
239}
240
241/// Decision the plugin made for one candidate.
242#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
243#[rkyv(derive(Debug))]
244pub struct PerCandidateReason {
245    pub upstream_id: Box<str>,
246    /// `"accept"` or `"reject"` — kept as string so plugins remain forward-
247    /// compatible with future decision variants without a host re-bump.
248    pub decision: Box<str>,
249    pub reason: Box<str>,
250}
251
252/// Filter hook output.
253///
254/// Guest packs `(out_ptr, out_len)` into a single `u64` (`(ptr << 32) | len`)
255/// for the return value of `cc_lb_filter`. The host reads the bytes via
256/// `Memory::data(&store)` and runs `rkyv::access::<ArchivedFilterResponse, _>`.
257#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
258#[rkyv(derive(Debug))]
259pub struct FilterResponse {
260    pub results: Box<[PerCandidateReason]>,
261}
262
263/// Upstream backend exposed to plugins. Mirrors
264/// `cc_lb_plugin_api::Upstream` (currently a single variant —
265/// extending the host enum requires extending this one in lockstep
266/// and bumping a wire schema tag).
267#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
268#[rkyv(derive(Debug))]
269pub enum Upstream {
270    AnthropicDirect {
271        /// Operator-configured base URL override, if any.
272        base_url: Option<Box<str>>,
273    },
274}
275
276/// Borrowed mirror of [`Upstream`].
277#[derive(Archive, Serialize)]
278pub enum UpstreamRef<'a> {
279    AnthropicDirect { base_url: Option<QueryRef<'a>> },
280}
281
282/// Shape hook input (owned form).
283#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
284#[rkyv(derive(Debug))]
285pub struct ShapeRequest {
286    pub request_id: Box<str>,
287    pub method: Box<str>,
288    pub path: Box<str>,
289    pub query: Option<Box<str>>,
290    pub headers: Box<[Header]>,
291    pub body: Box<[u8]>,
292    pub principal: Principal,
293    pub upstream: Upstream,
294}
295
296/// Borrowed mirror of [`ShapeRequest`] used by the host encode path.
297#[derive(Archive, Serialize)]
298pub struct ShapeRequestRef<'a> {
299    #[rkyv(with = InlineAsBox)]
300    pub request_id: &'a str,
301    #[rkyv(with = InlineAsBox)]
302    pub method: &'a str,
303    #[rkyv(with = InlineAsBox)]
304    pub path: &'a str,
305    pub query: Option<QueryRef<'a>>,
306    #[rkyv(with = InlineAsBox)]
307    pub headers: &'a [HeaderRef<'a>],
308    #[rkyv(with = InlineAsBox)]
309    pub body: &'a [u8],
310    pub principal: PrincipalRef<'a>,
311    pub upstream: UpstreamRef<'a>,
312}
313
314/// Shape hook output — the upstream-bound request the plugin produced.
315#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
316#[rkyv(derive(Debug))]
317pub struct ShapeResponse {
318    pub url: Box<str>,
319    pub method: Box<str>,
320    pub headers: Box<[Header]>,
321    pub body: Box<[u8]>,
322}
323
324/// Lifecycle event delivered to the observe hook. rkyv mirror of
325/// `cc_lb_plugin_api::ObserveEvent`.
326#[derive(Archive, Serialize, Deserialize, Clone, Debug)]
327#[rkyv(derive(Debug))]
328pub enum ObserveEvent {
329    RequestStarted {
330        request_id: Box<str>,
331        downstream_user_agent: Option<Box<str>>,
332    },
333    AuthnComplete {
334        principal_id: Box<str>,
335        principal_kind: Box<str>,
336    },
337    UpstreamChosen {
338        upstream: Upstream,
339    },
340    Chunk {
341        batch_index: u64,
342        event_count: u64,
343        total_bytes: u64,
344    },
345    RequestFinished {
346        status: u16,
347        input_tokens: Option<u64>,
348        output_tokens: Option<u64>,
349        cache_creation_input_tokens: Option<u64>,
350        cache_read_input_tokens: Option<u64>,
351        duration_ms: u64,
352    },
353    Error {
354        code: Box<str>,
355        message: Box<str>,
356        source: Box<str>,
357    },
358}
359
360include!(concat!(env!("OUT_DIR"), "/wire_schema_impls.rs"));
cc_lb_plugin_wire/v1/mod.rs

cc_lb_plugin_wire/v1/
mod.rs
