ic_wire/shape/
mod.rs

1use alloc::boxed::Box;
2use serde::{Serialize, de::DeserializeOwned};
3
4/// Worst-case bounds for one finite value.
5#[derive(Clone, Copy, Debug)]
6pub struct Shape {
7    /// Maximum canonical Postcard payload bytes.
8    pub bytes: usize,
9    /// Maximum requested heap bytes owned by the decoded value.
10    pub heap: usize,
11    /// Maximum visited value nodes, including zero-byte values.
12    pub nodes: usize,
13    /// Maximum nested value depth.
14    pub depth: usize,
15}
16impl Shape {
17    /// A leaf with no allocation.
18    pub const fn scalar(bytes: usize) -> Self {
19        Self {
20            bytes,
21            heap: 0,
22            nodes: 1,
23            depth: 1,
24        }
25    }
26    /// A record with these children. Overflow saturates and fails admission.
27    pub const fn record(children: &[Self]) -> Self {
28        let mut out = Self::scalar(0);
29        let mut i = 0;
30        while i < children.len() {
31            let child = children[i];
32            out.bytes = out.bytes.saturating_add(child.bytes);
33            out.heap = out.heap.saturating_add(child.heap);
34            out.nodes = out.nodes.saturating_add(child.nodes);
35            let depth = child.depth.saturating_add(1);
36            if depth > out.depth {
37                out.depth = depth;
38            }
39            i += 1;
40        }
41        out
42    }
43    /// A tagged choice, using the largest bound in each dimension.
44    pub const fn choice(tag_bytes: usize, alternatives: &[Self]) -> Self {
45        let mut out = Self::scalar(0);
46        let mut i = 0;
47        while i < alternatives.len() {
48            let child = alternatives[i];
49            if child.bytes > out.bytes {
50                out.bytes = child.bytes;
51            }
52            if child.heap > out.heap {
53                out.heap = child.heap;
54            }
55            if child.nodes > out.nodes {
56                out.nodes = child.nodes;
57            }
58            if child.depth > out.depth {
59                out.depth = child.depth;
60            }
61            i += 1;
62        }
63        out.bytes = out.bytes.saturating_add(tag_bytes);
64        out.nodes = out.nodes.saturating_add(1);
65        out.depth = out.depth.saturating_add(1);
66        out
67    }
68}
69
70/// Finite values. Prefer the derive with explicit field identities.
71///
72/// Manual implementations must provide honest bounds, reject before excessive
73/// allocation/work, and serialize deterministically. Unbounded Serde types have
74/// no implementation. Recursive types are unsupported.
75pub trait Wire: Serialize + DeserializeOwned {
76    /// Static resource authority for this value.
77    const SHAPE: Shape;
78    /// Static projection metadata; custom implementations must opt in honestly.
79    const SCHEMA: crate::schema::Schema = crate::schema::Schema::Opaque;
80}
81
82/// Consumer-selected allowances for finite schema or explicit native admission.
83#[derive(Clone, Copy, Debug)]
84pub struct Limits {
85    /// Maximum encoding bytes; framed APIs include the 11-byte header.
86    pub bytes: usize,
87    /// Maximum value heap plus codec scratch (excludes caller input).
88    pub allocation: usize,
89    /// Maximum visited value nodes, including unit elements.
90    pub nodes: usize,
91    /// Maximum nesting depth.
92    pub depth: usize,
93}
94macro_rules! scalars {
95    ($($ty:ty => ($bytes:expr, $schema:expr)),* $(,)?) => { $(
96        impl Wire for $ty {
97            const SHAPE: Shape = Shape::scalar($bytes);
98            const SCHEMA: crate::schema::Schema = $schema;
99        }
100    )* };
101}
102use crate::schema::Schema;
103scalars! { () => (0, Schema::Unit), bool => (1, Schema::Bool),
104u8 => (1, Schema::Unsigned(8)), i8 => (1, Schema::Signed(8)),
105u16 => (3, Schema::Unsigned(16)), i16 => (3, Schema::Signed(16)),
106u32 => (5, Schema::Unsigned(32)), i32 => (5, Schema::Signed(32)),
107u64 => (10, Schema::Unsigned(64)), i64 => (10, Schema::Signed(64)),
108u128 => (19, Schema::Unsigned(128)), i128 => (19, Schema::Signed(128)) }
109impl<T: Wire> Wire for Option<T> {
110    const SHAPE: Shape = Shape::choice(1, &[T::SHAPE]);
111    const SCHEMA: Schema = Schema::Option(&T::SCHEMA);
112}
113impl<T: Wire, E: Wire> Wire for Result<T, E> {
114    const SHAPE: Shape = Shape::choice(1, &[T::SHAPE, E::SHAPE]);
115    const SCHEMA: Schema = Schema::Result(&T::SCHEMA, &E::SCHEMA);
116}
117
118// Serde boxes are transparent: only owned heap storage changes. Saturation
119// preserves the existing fail-closed admission rule, including nested boxes.
120impl<T: Wire> Wire for Box<T> {
121    const SHAPE: Shape = Shape {
122        heap: core::mem::size_of::<T>().saturating_add(T::SHAPE.heap),
123        ..T::SHAPE
124    };
125    const SCHEMA: Schema = T::SCHEMA;
126}
127
128impl<T: Wire, const N: usize> Wire for [T; N]
129where
130    [T; N]: Serialize + DeserializeOwned,
131{
132    const SCHEMA: Schema = Schema::Array(&T::SCHEMA, N);
133    const SHAPE: Shape = Shape {
134        bytes: T::SHAPE.bytes.saturating_mul(N),
135        heap: T::SHAPE.heap.saturating_mul(N),
136        nodes: 1_usize.saturating_add(T::SHAPE.nodes.saturating_mul(N)),
137        depth: T::SHAPE.depth.saturating_add(1),
138    };
139}
ic_wire/shape/mod.rs

ic_wire/shape/
mod.rs
