ic_wire/shape/
mod.rs

1use alloc::boxed::Box;
2use serde::Serialize;
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.
75/// Decoding additionally requires `Deserialize` for the input lifetime; a Wire
76/// value may borrow input or support encoding only.
77pub trait Wire: Serialize {
78    /// Static resource authority for this value.
79    const SHAPE: Shape;
80    /// Static projection metadata; custom implementations must opt in honestly.
81    const SCHEMA: crate::schema::Schema = crate::schema::Schema::Opaque;
82}
83
84/// Consumer-selected allowances for finite schema or explicit native admission.
85#[derive(Clone, Copy, Debug)]
86pub struct Limits {
87    /// Maximum encoding bytes; framed APIs include the 11-byte header.
88    pub bytes: usize,
89    /// Maximum value heap plus codec scratch (excludes caller input).
90    pub allocation: usize,
91    /// Maximum visited value nodes, including unit elements.
92    pub nodes: usize,
93    /// Maximum nesting depth.
94    pub depth: usize,
95}
96macro_rules! scalars {
97    ($($ty:ty => ($bytes:expr, $schema:expr)),* $(,)?) => { $(
98        impl Wire for $ty {
99            const SHAPE: Shape = Shape::scalar($bytes);
100            const SCHEMA: crate::schema::Schema = $schema;
101        }
102    )* };
103}
104use crate::schema::Schema;
105scalars! { () => (0, Schema::Unit), bool => (1, Schema::Bool),
106u8 => (1, Schema::Unsigned(8)), i8 => (1, Schema::Signed(8)),
107u16 => (3, Schema::Unsigned(16)), i16 => (3, Schema::Signed(16)),
108u32 => (5, Schema::Unsigned(32)), i32 => (5, Schema::Signed(32)),
109u64 => (10, Schema::Unsigned(64)), i64 => (10, Schema::Signed(64)),
110u128 => (19, Schema::Unsigned(128)), i128 => (19, Schema::Signed(128)) }
111impl<T: Wire> Wire for Option<T> {
112    const SHAPE: Shape = Shape::choice(1, &[T::SHAPE]);
113    const SCHEMA: Schema = Schema::Option(&T::SCHEMA);
114}
115impl<T: Wire, E: Wire> Wire for Result<T, E> {
116    const SHAPE: Shape = Shape::choice(1, &[T::SHAPE, E::SHAPE]);
117    const SCHEMA: Schema = Schema::Result(&T::SCHEMA, &E::SCHEMA);
118}
119
120// Serde boxes are transparent: only owned heap storage changes. Saturation
121// preserves the existing fail-closed admission rule, including nested boxes.
122impl<T: Wire> Wire for Box<T> {
123    const SHAPE: Shape = Shape {
124        heap: core::mem::size_of::<T>().saturating_add(T::SHAPE.heap),
125        ..T::SHAPE
126    };
127    const SCHEMA: Schema = T::SCHEMA;
128}
129
130impl<T: Wire, const N: usize> Wire for [T; N]
131where
132    [T; N]: Serialize,
133{
134    const SCHEMA: Schema = Schema::Array(&T::SCHEMA, N);
135    const SHAPE: Shape = Shape {
136        bytes: T::SHAPE.bytes.saturating_mul(N),
137        heap: T::SHAPE.heap.saturating_mul(N),
138        nodes: 1_usize.saturating_add(T::SHAPE.nodes.saturating_mul(N)),
139        depth: T::SHAPE.depth.saturating_add(1),
140    };
141}
ic_wire/shape/mod.rs

ic_wire/shape/
mod.rs
