canic-core 0.26.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,
}