citadel_proto 0.13.0

Networking library for the Citadel Protocol
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

//! Kernel Module for Citadel Protocol
//!
//! This module implements the core kernel functionality that bridges the high-level API
//! with the low-level protocol implementation. It provides runtime management,
//! asynchronous execution, and event handling for the Citadel Protocol.
//!
//! # Features
//!
//! - Asynchronous runtime management
//! - Event-driven architecture
//! - Multi-threaded execution support
//! - Configurable concurrency control
//! - Account management integration
//! - Protocol type abstraction
//! - Session security management
//!
//! # Important Notes
//!
//! - Single-threaded lower level, multi-threaded upper level
//! - Configurable concurrency limits for event handling
//! - Handles both client and server node types
//! - Integrates with account management system
//! - Supports multiple underlying protocols
//!
//! # Related Components
//!
//! - `kernel_communicator`: Asynchronous callback handling
//! - `kernel_executor`: Multi-threaded runtime management
//! - `kernel_trait`: High-level API interface
//! - `HdpServer`: Low-level protocol implementation
//! - `AccountManager`: User account management

use crate::proto::session::ServerOnlySessionInitSettings;
use citadel_crypt::ratchets::Ratchet;
use citadel_io::tokio::macros::support::Future;
use citadel_io::tokio::runtime::Handle;
use citadel_user::account_manager::AccountManager;
use citadel_wire::exports::ClientConfig;
use citadel_wire::hypernode_type::NodeType;
use std::sync::Arc;

use crate::error::NetworkError;
use crate::macros::ContextRequirements;
use crate::prelude::ServerUnderlyingProtocol;

/// for handling easy asynchronous callbacks
pub mod kernel_communicator;
/// The mid-level entity in this crate which uses a multithreaded tokio runtime
/// with a single-threaded lower-level [HdpServer]
pub mod kernel_executor;
/// The entity which interfaces the lower-level [HdpServer] and the higher-level API
pub mod kernel_trait;

pub trait RuntimeFuture: Future<Output = Result<(), NetworkError>> + ContextRequirements {}
impl<T: Future<Output = Result<(), NetworkError>> + ContextRequirements> RuntimeFuture for T {}

#[derive(Default, Debug, Clone, Eq, PartialEq)]
/// Used for fine-tuning parameters within the [`KernelExecutor`]
pub struct KernelExecutorSettings {
    max_concurrency: Option<usize>,
}

impl KernelExecutorSettings {
    /// Determines the maximum number of concurrent asynchronous subroutines executed for
    /// [`NetKernel::on_node_event_received`]. Default is None, implying there is no limit
    pub fn with_max_concurrency(mut self, max_concurrency: impl Into<Option<usize>>) -> Self {
        self.max_concurrency = max_concurrency.into();
        self
    }
}

pub struct KernelExecutorArguments<K, R: Ratchet> {
    pub rt: Handle,
    pub hypernode_type: NodeType,
    pub account_manager: AccountManager<R, R>,
    pub kernel: K,
    pub underlying_proto: ServerUnderlyingProtocol,
    pub client_config: Option<Arc<ClientConfig>>,
    pub kernel_executor_settings: KernelExecutorSettings,
    pub stun_servers: Option<Vec<String>>,
    pub server_only_session_init_settings: Option<ServerOnlySessionInitSettings>,
}