ic-wire 0.3.4

Bounded canonical Postcard contracts for controlled Internet Computer endpoints
Documentation 
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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

use serde::{Serialize, de::DeserializeOwned};

/// Worst-case bounds for one finite value.
#[derive(Clone, Copy, Debug)]
pub struct Shape {
    /// Maximum canonical Postcard payload bytes.
    pub bytes: usize,
    /// Maximum requested heap bytes owned by the decoded value.
    pub heap: usize,
    /// Maximum visited value nodes, including zero-byte values.
    pub nodes: usize,
    /// Maximum nested value depth.
    pub depth: usize,
}
impl Shape {
    /// A leaf with no allocation.
    pub const fn scalar(bytes: usize) -> Self {
        Self {
            bytes,
            heap: 0,
            nodes: 1,
            depth: 1,
        }
    }
    /// A record with these children. Overflow saturates and fails admission.
    pub const fn record(children: &[Self]) -> Self {
        let mut out = Self::scalar(0);
        let mut i = 0;
        while i < children.len() {
            let child = children[i];
            out.bytes = out.bytes.saturating_add(child.bytes);
            out.heap = out.heap.saturating_add(child.heap);
            out.nodes = out.nodes.saturating_add(child.nodes);
            let depth = child.depth.saturating_add(1);
            if depth > out.depth {
                out.depth = depth;
            }
            i += 1;
        }
        out
    }
    /// A tagged choice, using the largest bound in each dimension.
    pub const fn choice(tag_bytes: usize, alternatives: &[Self]) -> Self {
        let mut out = Self::scalar(0);
        let mut i = 0;
        while i < alternatives.len() {
            let child = alternatives[i];
            if child.bytes > out.bytes {
                out.bytes = child.bytes;
            }
            if child.heap > out.heap {
                out.heap = child.heap;
            }
            if child.nodes > out.nodes {
                out.nodes = child.nodes;
            }
            if child.depth > out.depth {
                out.depth = child.depth;
            }
            i += 1;
        }
        out.bytes = out.bytes.saturating_add(tag_bytes);
        out.nodes = out.nodes.saturating_add(1);
        out.depth = out.depth.saturating_add(1);
        out
    }
}

/// Finite values. Prefer the derive with explicit field identities.
///
/// Manual implementations must provide honest bounds, reject before excessive
/// allocation/work, and serialize deterministically. Unbounded Serde types have
/// no implementation. Recursive types are unsupported.
pub trait Wire: Serialize + DeserializeOwned {
    /// Static resource authority for this value.
    const SHAPE: Shape;
    /// Static projection metadata; custom implementations must opt in honestly.
    const SCHEMA: crate::schema::Schema = crate::schema::Schema::Opaque;
}

/// Consumer-selected allowances for finite schema or explicit native admission.
#[derive(Clone, Copy, Debug)]
pub struct Limits {
    /// Maximum encoding bytes; framed APIs include the 11-byte header.
    pub bytes: usize,
    /// Maximum value heap plus codec scratch (excludes caller input).
    pub allocation: usize,
    /// Maximum visited value nodes, including unit elements.
    pub nodes: usize,
    /// Maximum nesting depth.
    pub depth: usize,
}
macro_rules! scalars {
    ($($ty:ty => ($bytes:expr, $schema:expr)),* $(,)?) => { $(
        impl Wire for $ty {
            const SHAPE: Shape = Shape::scalar($bytes);
            const SCHEMA: crate::schema::Schema = $schema;
        }
    )* };
}
use crate::schema::Schema;
scalars! { () => (0, Schema::Unit), bool => (1, Schema::Bool),
u8 => (1, Schema::Unsigned(8)), i8 => (1, Schema::Signed(8)),
u16 => (3, Schema::Unsigned(16)), i16 => (3, Schema::Signed(16)),
u32 => (5, Schema::Unsigned(32)), i32 => (5, Schema::Signed(32)),
u64 => (10, Schema::Unsigned(64)), i64 => (10, Schema::Signed(64)),
u128 => (19, Schema::Unsigned(128)), i128 => (19, Schema::Signed(128)) }
impl<T: Wire> Wire for Option<T> {
    const SHAPE: Shape = Shape::choice(1, &[T::SHAPE]);
    const SCHEMA: Schema = Schema::Option(&T::SCHEMA);
}
impl<T: Wire, E: Wire> Wire for Result<T, E> {
    const SHAPE: Shape = Shape::choice(1, &[T::SHAPE, E::SHAPE]);
    const SCHEMA: Schema = Schema::Result(&T::SCHEMA, &E::SCHEMA);
}

impl<T: Wire, const N: usize> Wire for [T; N]
where
    [T; N]: Serialize + DeserializeOwned,
{
    const SCHEMA: Schema = Schema::Array(&T::SCHEMA, N);
    const SHAPE: Shape = Shape {
        bytes: T::SHAPE.bytes.saturating_mul(N),
        heap: T::SHAPE.heap.saturating_mul(N),
        nodes: 1_usize.saturating_add(T::SHAPE.nodes.saturating_mul(N)),
        depth: T::SHAPE.depth.saturating_add(1),
    };
}