icarus_canister/
lib.rs

1// Copyright (c) 2025 Icarus Team. All Rights Reserved.
2// Licensed under BSL-1.1. See LICENSE and NOTICE files.
3// Signature verification and telemetry must remain intact.
4
5// #![warn(missing_docs)] // TODO: Enable after adding all documentation
6
7//! ICP canister integration for Icarus MCP servers
8//!
9//! This crate provides the canister implementation details for running
10//! MCP servers on the Internet Computer.
11
12pub mod auth;
13pub mod auth_tools;
14pub mod easy_storage;
15pub mod endpoints;
16pub mod http;
17pub mod lifecycle;
18pub mod macros;
19pub mod memory;
20pub mod result;
21pub mod stable_ext;
22pub mod state;
23pub mod storage;
24pub mod timers;
25pub mod tools;
26
27pub use auth::{
28    add_user, authenticate, get_auth_audit, get_auth_status, get_authorized_users, get_user,
29    init_auth, list_users, remove_user, require_any_of_roles, require_exact_role,
30    require_none_of_roles, require_role_or_higher, update_user_role, AuthAction, AuthAuditEntry,
31    AuthInfo, AuthRole, User,
32};
33pub use endpoints::{
34    get_owner as get_canister_owner, http_request, icarus_metadata, HttpRequest, HttpResponse,
35};
36pub use lifecycle::{init, init_with_caller, post_upgrade, pre_upgrade};
37pub use stable_ext::{StableBTreeMapExt, StableCellExt};
38pub use state::{assert_owner, get_owner, is_owner, IcarusCanisterState};
39pub use storage::{StableCounter, StableMap};
40
41// Re-export the macros from icarus-derive
42pub use icarus_derive::{
43    icarus_canister, icarus_module, icarus_tool, IcarusStorable, IcarusStorage, IcarusType,
44};
45
46// Re-export commonly used macros (defined with #[macro_export])
47// Note: These macros are automatically available at the crate root due to #[macro_export]
48
49/// Comprehensive prelude for Icarus canister development
50///
51/// This module contains all the commonly used imports, so developers only need:
52/// `use icarus_canister::prelude::*;`
53pub mod prelude {
54    // Core IC CDK types and macros
55    pub use candid::{CandidType, Principal};
56    pub use ic_cdk::{api, storage, trap};
57    pub use ic_cdk_macros::{init, post_upgrade, pre_upgrade, query, update};
58
59    // Stable structures for persistence
60    pub use ic_stable_structures::{
61        memory_manager::{MemoryId, MemoryManager, VirtualMemory},
62        storable::Bound as StorableBound,
63        DefaultMemoryImpl, StableBTreeMap, StableCell, Storable,
64    };
65
66    // Serde for serialization
67    pub use serde::{Deserialize, Serialize};
68    pub use serde_json;
69
70    // Icarus core functionality
71    pub use crate::{
72        // Authentication system
73        auth::{
74            add_user, authenticate, get_auth_audit, get_auth_status, get_authorized_users,
75            get_user, init_auth, list_users, remove_user, require_any_of_roles, require_exact_role,
76            require_none_of_roles, require_role_or_higher, update_user_role, AuthAction,
77            AuthAuditEntry, AuthInfo, AuthRole, User,
78        },
79        // Easy storage patterns
80        easy_storage::{CounterCell, StorageCell, StorageMap},
81
82        // HTTP endpoints - exclude get_owner to avoid conflict
83        endpoints::{
84            get_owner as get_canister_owner, http_request, icarus_metadata, HttpRequest,
85            HttpResponse,
86        },
87
88        // HTTP outcalls for external data
89        http,
90
91        icarus_module,
92        icarus_storage,
93        // Macros for tool definition
94        icarus_tool,
95        init_memory,
96        // Lifecycle hooks
97        lifecycle::*,
98        // Memory management
99        memory::{get_memory, MEMORY_MANAGER},
100        // Memory management macros
101        memory_id,
102        // Result types and error handling
103        result::{IcarusError, IcarusResult, TrapExt},
104
105        stable_storage,
106        // State management
107        state::*,
108        // Storage utilities
109        storage::*,
110        // Timer system for autonomous operations
111        timers,
112
113        tool_metadata,
114        IcarusStorable,
115        IcarusStorage,
116        IcarusType,
117    };
118
119    // Common type aliases
120    pub type Memory = VirtualMemory<DefaultMemoryImpl>;
121    pub type Map<K, V> = StableBTreeMap<K, V, Memory>;
122    pub type Cell<T> = StableCell<T, Memory>;
123
124    // Common Result type for tools
125    pub type ToolResult<T> = Result<T, String>;
126}
icarus_canister/lib.rs

icarus_canister/
lib.rs
