turbomcp_core/
lib.rs

1//! # TurboMCP Core
2//!
3//! Foundation crate for the Model Context Protocol (MCP) SDK providing core types,
4//! error handling, and optimized abstractions for building MCP applications.
5//!
6//! ## Features
7//!
8//! - **SIMD-Accelerated JSON** - Fast processing with `simd-json` and `sonic-rs`
9//! - **Rich Error Handling** - Comprehensive error types with context information
10//! - **Session Management** - Configurable LRU eviction and lifecycle management
11//! - **Zero-Copy Processing** - Memory-efficient message handling with `Bytes`
12//! - **Request Context** - Full request/response context tracking for observability
13//! - **Performance Optimized** - Memory-bounded state management with cleanup tasks
14//! - **Observability Ready** - Built-in support for tracing and metrics collection
15//!
16//! ## Architecture
17//!
18//! ```text
19//! turbomcp-core/
20//! ├── error/          # Error types and handling
21//! ├── message/        # Message types and serialization
22//! ├── types/          # Core protocol types
23//! ├── context/        # Request/response context
24//! ├── session/        # Session management
25//! ├── registry/       # Component registry
26//! ├── state/          # State management
27//! └── utils/          # Utility functions
28//! ```
29//!
30//! ## Usage
31//!
32//! This crate provides the foundation types and utilities used by other `TurboMCP` crates.
33//! It is typically not used directly but imported by the main `turbomcp` SDK.
34
35#![warn(
36    missing_docs,
37    missing_debug_implementations,
38    rust_2018_idioms,
39    unreachable_pub,
40    clippy::all
41)]
42#![deny(unsafe_code)]
43#![cfg_attr(docsrs, feature(doc_cfg))]
44#![allow(
45    clippy::module_name_repetitions,
46    clippy::missing_errors_doc,  // Error documentation in progress
47    clippy::cast_possible_truncation,  // Intentional in metrics/performance code
48    clippy::cast_possible_wrap,  // Intentional in metrics/performance code  
49    clippy::cast_precision_loss,  // Intentional for f64 metrics
50    clippy::cast_sign_loss,  // Intentional for metrics
51    clippy::must_use_candidate,  // Too pedantic for library APIs
52    clippy::return_self_not_must_use,  // Constructor methods don't need must_use
53    clippy::struct_excessive_bools,  // Sometimes bools are the right design
54    clippy::missing_panics_doc,  // Panic docs added where genuinely needed
55    clippy::default_trait_access,  // Default::default() is sometimes clearer
56    clippy::significant_drop_tightening,  // Overly pedantic about drop timing
57    clippy::used_underscore_binding  // Sometimes underscore bindings are needed
58)]
59
60pub mod context;
61pub mod error;
62pub mod error_utils;
63pub mod message;
64pub mod registry;
65pub mod session;
66pub mod state;
67pub mod types;
68pub mod utils;
69
70#[cfg(feature = "fancy-errors")]
71pub mod config;
72
73// Re-export commonly used types
74pub use context::{
75    ClientId, ClientIdExtractor, ClientSession, RequestContext, RequestContextExt, RequestInfo,
76    ResponseContext,
77};
78pub use error::{Error, ErrorKind, Result};
79pub use message::{Message, MessageId, MessageMetadata};
80pub use session::{SessionAnalytics, SessionConfig, SessionManager};
81pub use state::StateManager;
82pub use types::{ContentType, ProtocolVersion, Timestamp};
83
84/// Current MCP protocol version supported by this SDK
85pub const PROTOCOL_VERSION: &str = "2025-06-18";
86
87/// Supported protocol versions for compatibility
88pub const SUPPORTED_VERSIONS: &[&str] = &["2025-06-18", "2025-03-26", "2024-11-05"];
89
90/// Maximum message size in bytes (16MB)
91pub const MAX_MESSAGE_SIZE: usize = 16 * 1024 * 1024;
92
93/// Default timeout for operations in milliseconds
94pub const DEFAULT_TIMEOUT_MS: u64 = 30_000;
95
96/// SDK version information
97pub const SDK_VERSION: &str = env!("CARGO_PKG_VERSION");
98
99/// SDK name identifier
100pub const SDK_NAME: &str = "turbomcp";
101
102#[cfg(test)]
103mod tests {
104    use super::*;
105
106    #[test]
107    fn test_version_constants() {
108        // These constants are compile-time defined and should never be empty
109        assert!(SUPPORTED_VERSIONS.contains(&PROTOCOL_VERSION));
110    }
111
112    #[test]
113    fn test_size_constants() {
114        // Constants are statically verified at compile-time
115        // These tests document our design constraints
116
117        // Verify message size is reasonable for MCP protocol
118        const _: () = assert!(
119            MAX_MESSAGE_SIZE > 1024,
120            "MAX_MESSAGE_SIZE must be larger than 1KB"
121        );
122        const _: () = assert!(
123            MAX_MESSAGE_SIZE == 16 * 1024 * 1024,
124            "MAX_MESSAGE_SIZE must be 16MB"
125        );
126
127        // Verify timeout allows for reasonable operation completion
128        const _: () = assert!(
129            DEFAULT_TIMEOUT_MS > 1000,
130            "DEFAULT_TIMEOUT_MS must be larger than 1 second"
131        );
132        const _: () = assert!(
133            DEFAULT_TIMEOUT_MS == 30_000,
134            "DEFAULT_TIMEOUT_MS must be 30 seconds"
135        );
136    }
137}
turbomcp_core/lib.rs

turbomcp_core/
lib.rs
