icydb 0.292.0

IcyDB — A schema-first typed query engine and persistence runtime for Internet Computer canisters
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

//! Native database RPC contracts shared by clients and host adapters.
//!
//! This module carries method identities and delegates all framing/admission to
//! IC Wire. IC exports, authorization and lifecycle remain adapter responsibilities.

use ic_wire::{Error, Limits};
use serde::{Serialize, de::DeserializeOwned};

const ID_BASE: u64 = u64::from_le_bytes(*b"ICYDBW00");

// One declaration owns every projection of the fixed method identity roster.
macro_rules! define_methods {
    ($( $variant:ident => ($name:literal, $id:literal), )*) => {
        /// A database RPC method and its exact byte-contract identity.
        #[derive(Clone, Copy, Debug, Eq, PartialEq)]
        pub enum RpcMethod {
            $( #[doc = $name] $variant, )*
        }

        impl RpcMethod {
            /// Maintained native RPC methods, in declaration order.
            pub const ALL: &[Self] = &[$( Self::$variant, )*];

            /// Exact public IC method name.
            #[must_use]
            pub const fn name(self) -> &'static str {
                match self { $( Self::$variant => $name, )* }
            }

            /// Current protocol identity. Payload changes require explicit coordination.
            #[must_use]
            pub const fn id(self) -> u64 {
                ID_BASE + match self { $( Self::$variant => $id, )* }
            }

            /// Resolve one exact public method name.
            #[must_use]
            pub fn from_name(name: &str) -> Option<Self> {
                match name { $( $name => Some(Self::$variant), )* _ => None }
            }

            /// Resolve one declared protocol identity.
            #[must_use]
            pub const fn from_id(id: u64) -> Option<Self> {
                match id.wrapping_sub(ID_BASE) {
                    $( $id => Some(Self::$variant), )* _ => None,
                }
            }
        }
    };
}

define_methods! {
    Query => ("icydb_query", 1),
    Ddl => ("icydb_ddl", 2),
    Update => ("icydb_update", 3),
    Integrity => ("icydb_integrity", 4),
    FixturesReset => ("icydb_fixtures_reset", 5),
    FixturesLoad => ("icydb_fixtures_load", 6),
    Metrics => ("icydb_metrics", 7),
    MetricsReset => ("icydb_metrics_reset", 8),
    Snapshot => ("icydb_snapshot", 9),
    Schema => ("icydb_schema", 10),
    SchemaMigrate => ("icydb_schema_migrate", 11),
    SchemaMigration => ("icydb_schema_migration", 12),
}

impl RpcMethod {
    /// Encode one canonical request for this endpoint.
    pub fn encode_request<T: Serialize>(self, value: T, limits: Limits) -> Result<Vec<u8>, Error> {
        ic_wire::native::encode_request(self.id(), &value, limits)
    }
    /// Admit identity, direction, resources and request payload primitives.
    /// Collection ordering and uniqueness remain the caller's semantic contract.
    pub fn decode_request<T: DeserializeOwned>(
        self,
        bytes: &[u8],
        limits: Limits,
    ) -> Result<T, Error> {
        ic_wire::native::decode_request(self.id(), bytes, limits)
    }
    /// Encode one canonical response for this endpoint.
    pub fn encode_response<T: Serialize>(self, value: T, limits: Limits) -> Result<Vec<u8>, Error> {
        ic_wire::native::encode_response(self.id(), &value, limits)
    }
    /// Admit identity, direction, resources and response payload primitives.
    /// Retain received bytes when exact frame identity is needed after decoding.
    pub fn decode_response<T: DeserializeOwned>(
        self,
        bytes: &[u8],
        limits: Limits,
    ) -> Result<T, Error> {
        ic_wire::native::decode_response(self.id(), bytes, limits)
    }
}