m2m/protocol/mod.rs
1//! M2M Protocol negotiation and session management.
2//!
3//! Implements the M2M Protocol v3.0 handshake for agent-to-agent communication
4//! with capability negotiation, version checks, and session lifecycle management.
5//!
6//! # Protocol Overview
7//!
8//! The M2M Protocol uses a session-based model where agents establish connections
9//! through a capability handshake before exchanging compressed data.
10//!
11//! ## Message Flow
12//!
13//! ```text
14//! Client Server
15//! | |
16//! |-------- HELLO (caps) -------->| Initiate with capabilities
17//! | |
18//! |<----- ACCEPT (caps) ----------| Session established
19//! | or REJECT (reason) | or rejected with code
20//! | |
21//! |======= DATA (compressed) =====>| Exchange payloads
22//! |<===== DATA (compressed) =======|
23//! | |
24//! |-------- PING ---------------->| Keep-alive
25//! |<------- PONG -----------------|
26//! | |
27//! |-------- CLOSE --------------->| Terminate session
28//! ```
29//!
30//! ## State Machine
31//!
32//! Sessions transition through these states:
33//!
34//! | State | Description | Valid Transitions |
35//! |-------------|-----------------------------------|--------------------------|
36//! | `Initial` | New session, no handshake yet | → HelloSent, Established |
37//! | `HelloSent` | HELLO sent, awaiting response | → Established, Closed |
38//! | `Established`| Ready for data exchange | → Closing |
39//! | `Closing` | Graceful shutdown initiated | → Closed |
40//! | `Closed` | Session terminated | (terminal) |
41//!
42//! ## Capabilities
43//!
44//! During handshake, agents advertise their capabilities:
45//!
46//! - **Compression**: Supported algorithms (Token, Brotli, Dictionary)
47//! - **Security**: Threat detection, blocking mode, confidence threshold
48//! - **Extensions**: Custom key-value pairs for future features
49//!
50//! ## Rejection Codes
51//!
52//! | Code | Meaning |
53//! |---------------------|----------------------------------|
54//! | `VersionMismatch` | Protocol version incompatible |
55//! | `NoCommonAlgorithm` | No mutually supported algorithm |
56//! | `SecurityPolicy` | Security policy violation |
57//! | `RateLimited` | Too many requests |
58//! | `Unknown` | Other/unspecified error |
59//!
60//! # Usage
61//!
62//! ## Client Side
63//!
64//! ```rust,ignore
65//! use m2m_core::protocol::{Session, Capabilities};
66//!
67//! // Create session with default capabilities
68//! let mut client = Session::new(Capabilities::default());
69//!
70//! // Initiate handshake
71//! let hello = client.create_hello();
72//! // Send hello to server, receive response...
73//! ```
74//!
75//! ## Server Side
76//!
77//! ```rust,ignore
78//! use m2m_core::protocol::{Session, Capabilities, MessageType};
79//!
80//! let mut server = Session::new(Capabilities::default());
81//!
82//! // Process incoming HELLO
83//! let response = server.process_hello(&incoming_hello)?;
84//! match response.msg_type {
85//! MessageType::Accept => { /* session established */ }
86//! MessageType::Reject => { /* negotiation failed */ }
87//! _ => unreachable!(),
88//! }
89//! ```
90//!
91//! ## Data Exchange
92//!
93//! ```rust,ignore
94//! // After session established
95//! let data_msg = session.compress(r#"{"model":"gpt-4o"}"#)?;
96//! let content = session.decompress(&incoming_data)?;
97//! ```
98
99mod capabilities;
100mod message;
101mod session;
102
103pub use capabilities::{Capabilities, CompressionCaps, NegotiatedCaps, SecurityCaps};
104pub use message::{Message, MessageType, RejectionCode, RejectionInfo};
105pub use session::{Session, SessionState, SessionStats};
106
107/// Protocol version
108pub const PROTOCOL_VERSION: &str = "3.0";
109
110/// Maximum session idle time (5 minutes)
111pub const SESSION_TIMEOUT_SECS: u64 = 300;