canic 0.99.16

Canic — a canister orchestration and management toolkit for the Internet Computer
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

//! Module: macros::endpoints::topology
//!
//! Responsibility: emit topology state, Directory, children, and placement views.
//! Does not own: topology state, placement policy, or authorization policy.
//! Boundary: exposes facade macros that delegate immediately to core APIs.

/// Emit the root-only Fleet-state snapshot endpoint.
#[macro_export]
macro_rules! canic_emit_topology_state_endpoints {
    () => {
        #[cfg(canic_is_root)]
        #[$crate::canic_query(requires(caller::is_controller()))]
        async fn canic_fleet_state()
        -> Result<::canic::dto::state::FleetStateResponse, ::canic::Error> {
            Ok($crate::__internal::core::api::state::FleetStateQuery::snapshot())
        }
    };
}

/// Emit shared topology Directory query endpoints.
#[macro_export]
macro_rules! canic_emit_topology_directory_endpoints {
    () => {
        #[$crate::canic_query(public)]
        fn canic_fleet_directory(
            page: ::canic::dto::page::PageRequest,
        ) -> Result<::canic::dto::topology::FleetDirectoryPageResponse, ::canic::Error> {
            $crate::__internal::core::api::topology::directory::FleetDirectoryApi::page(page)
                .map_err(::canic::Error::from)
        }

        #[$crate::canic_query(public)]
        fn canic_subnet_directory(
            page: ::canic::dto::page::PageRequest,
        ) -> Result<::canic::dto::topology::SubnetDirectoryPageResponse, ::canic::Error> {
            $crate::__internal::core::api::topology::directory::SubnetDirectoryApi::page(page)
                .map_err(::canic::Error::from)
        }
    };
}

/// Emit the shared topology-children query endpoint.
#[macro_export]
macro_rules! canic_emit_topology_children_endpoints {
    () => {
        #[$crate::canic_query(public)]
        fn canic_canister_children(
            page: ::canic::dto::page::PageRequest,
        ) -> Result<::canic::dto::page::Page<::canic::dto::canister::CanisterInfo>, ::canic::Error>
        {
            Ok($crate::__internal::core::api::topology::children::CanisterChildrenApi::page(page))
        }
    };
}

/// Emit shared scaling and sharding placement view endpoints.
#[macro_export]
macro_rules! canic_emit_topology_placement_endpoints {
    () => {
        #[cfg(canic_has_scaling)]
        #[$crate::canic_query(requires(caller::is_controller()))]
        async fn canic_scaling_registry()
        -> Result<::canic::dto::placement::scaling::ScalingRegistryResponse, ::canic::Error> {
            Ok($crate::__internal::core::api::placement::scaling::ScalingApi::registry())
        }

        #[cfg(canic_has_sharding)]
        #[$crate::canic_query(requires(caller::is_controller()))]
        async fn canic_sharding_registry()
        -> Result<::canic::dto::placement::sharding::ShardingRegistryResponse, ::canic::Error> {
            Ok($crate::__internal::core::api::placement::sharding::ShardingApi::registry())
        }

        #[cfg(canic_has_sharding)]
        #[$crate::canic_query(requires(caller::is_controller()))]
        async fn canic_sharding_partition_keys(
            pool: String,
            shard_pid: ::canic::__internal::cdk::Principal,
        ) -> Result<::canic::dto::placement::sharding::ShardingPartitionKeysResponse, ::canic::Error> {
            Ok($crate::__internal::core::api::placement::sharding::ShardingApi::partition_keys(&pool, shard_pid))
        }
    };
}

/// Emit the standard topology view endpoint bundle.
#[macro_export]
macro_rules! canic_bundle_topology_views_endpoints {
    () => {
        #[cfg(not(canic_disable_bundle_topology_state))]
        $crate::canic_emit_topology_state_endpoints!();
        #[cfg(not(canic_disable_bundle_topology_directory))]
        $crate::canic_emit_topology_directory_endpoints!();
        #[cfg(not(canic_disable_bundle_topology_children))]
        $crate::canic_emit_topology_children_endpoints!();
        #[cfg(not(canic_disable_bundle_topology_placement))]
        $crate::canic_emit_topology_placement_endpoints!();
    };
}