canic-core 0.22.0

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
99
100
101
102
103
104
105
106
107
108
109

//! Pool admin DTOs.
//!
//! This module defines the command and response types used at the
//! boundary of the pool workflow (endpoints, admin APIs).
//!
//! These types:
//! - are pure data
//! - contain no logic
//! - are safe to serialize / expose
//!
//! They must NOT:
//! - perform validation
//! - call ops or workflow
//! - embed policy or orchestration logic

use crate::{cdk::types::Cycles, dto::prelude::*};

///
/// CanisterPoolResponse
/// Read-only pool snapshot for endpoints.
///

#[derive(CandidType, Clone, Debug, Deserialize)]
pub struct CanisterPoolResponse {
    pub entries: Vec<CanisterPoolEntry>,
}

///
/// CanisterPoolEntry
///

#[derive(CandidType, Clone, Debug, Deserialize)]
pub struct CanisterPoolEntry {
    pub pid: Principal,
    pub created_at: u64,
    pub cycles: Cycles,
    pub status: CanisterPoolStatus,
    pub role: Option<CanisterRole>,
    pub parent: Option<Principal>,
    pub module_hash: Option<Vec<u8>>,
}

///
/// CanisterPoolStatus
///

#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
pub enum CanisterPoolStatus {
    PendingReset,
    Ready,
    Failed { reason: String },
}

///
/// PoolAdminCommand
///
/// These represent *intent*, not execution.
/// Validation and authorization are handled elsewhere.
///

#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
pub enum PoolAdminCommand {
    /// Create a fresh empty pool canister.
    CreateEmpty,

    /// Recycle an existing canister back into the pool.
    Recycle { pid: Principal },

    /// Import a canister into the pool immediately (synchronous).
    ImportImmediate { pid: Principal },

    /// Queue one or more canisters for pool import.
    ImportQueued { pids: Vec<Principal> },
}

///
/// PoolAdminResponse
/// These describe *what happened*, not *how* it happened.
///

#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
pub enum PoolAdminResponse {
    /// A new pool canister was created.
    Created { pid: Principal },

    /// A canister was successfully recycled into the pool.
    Recycled,

    /// A canister was imported immediately.
    Imported,

    /// One or more canisters were queued for import.
    QueuedImported { result: PoolBatchResult },

    /// Failed pool entries were requeued.
    FailedRequeued { result: PoolBatchResult },
}

///
/// PoolBatchResult
///

#[derive(CandidType, Clone, Debug, Deserialize, Eq, PartialEq)]
pub struct PoolBatchResult {
    pub total: u64,
    pub added: u64,
    pub requeued: u64,
    pub skipped: u64,
}