mcpr_integrations/store/
event.rs

1//! Event types sent from the proxy hot path to the background storage writer.
2//!
3//! These are the "write side" of the storage engine. The proxy constructs events
4//! from MCP request/response data and sends them through an mpsc channel —
5//! never blocking the hot path.
6//!
7//! # Separation from McprEvent
8//!
9//! `mcpr-integrations` has its own `McprEvent` for cloud/stdout emission.
10//! `StoreEvent` is intentionally independent — different schema, different
11//! lifecycle, no coupling between crates. The conversion happens at the
12//! proxy's emit stage (`mcpr_core::proxy::pipeline::emit`) where both are
13//! built from the same locals.
14
15/// Top-level event enum sent through the storage channel.
16///
17/// The background writer dispatches on this to decide which table to write to
18/// and whether to INSERT, UPDATE, or close a session.
19#[derive(Debug)]
20pub enum StoreEvent {
21    /// A completed MCP request — one row in the `requests` table.
22    Request(RequestEvent),
23
24    /// A new MCP session from an `initialize` handshake — one row in `sessions`.
25    Session(SessionEvent),
26
27    /// A session was cleanly closed (transport disconnect).
28    /// Updates `ended_at` on the existing session row.
29    SessionClosed {
30        session_id: String,
31        /// Unix milliseconds (UTC) when the close was detected.
32        ended_at: i64,
33    },
34
35    /// A new `SchemaVersion` was created by the proxy's SchemaManager.
36    /// Writer UPSERTs `server_schema` and appends change rows.
37    SchemaVersion(SchemaVersionEvent),
38}
39
40/// One completed MCP request, ready to be written to the `requests` table.
41///
42/// Built from the same data the proxy already computes for logging and cloud
43/// emission (method, tool name, latency, status, sizes). No extra parsing needed.
44#[derive(Debug)]
45pub struct RequestEvent {
46    /// UUIDv7 generated by mcpr — time-ordered, globally unique.
47    /// Used for cloud sink correlation and as the primary lookup key.
48    pub request_id: String,
49
50    /// Unix milliseconds (UTC) when the request was received.
51    /// Millisecond resolution is sufficient for latency tracking and avoids
52    /// i64 overflow concerns that nanosecond timestamps would introduce.
53    pub ts: i64,
54
55    /// Proxy name from config (e.g., "api-server").
56    /// Tags every row so a shared database can hold data from multiple proxies.
57    pub proxy: String,
58
59    /// MCP session ID from the `mcp-session-id` header.
60    /// Nullable: pre-handshake probes or malformed clients may not have one.
61    /// Soft foreign key to `sessions.session_id` (no hard FK constraint —
62    /// avoids ordering edge cases in the async writer).
63    pub session_id: Option<String>,
64
65    /// MCP JSON-RPC method (e.g., "tools/call", "resources/read", "initialize").
66    /// Stored as-is from the protocol layer — no normalization.
67    pub method: String,
68
69    /// Tool name for `tools/call` requests, None for other methods.
70    /// Extracted from the JSON-RPC params by the proxy's MCP parser.
71    pub tool: Option<String>,
72
73    /// Resource URI for `resources/{read,subscribe,unsubscribe}`.
74    pub resource_uri: Option<String>,
75
76    /// Prompt name for `prompts/get`.
77    pub prompt_name: Option<String>,
78
79    /// Wall-clock time from proxy receiving the request to getting the upstream response.
80    /// Includes network round-trip to upstream — this is what the AI client experiences.
81    /// Stored in microseconds for sub-millisecond precision.
82    pub latency_us: i64,
83
84    /// Whether the request succeeded, failed, or timed out.
85    pub status: RequestStatus,
86
87    /// MCP error code if `status` is `Error` (e.g., "-32600", "-32601").
88    /// None for successful requests.
89    pub error_code: Option<String>,
90
91    /// Human-readable error message, truncated to 512 chars at the call site.
92    /// None for successful requests.
93    pub error_msg: Option<String>,
94
95    /// Request payload size in bytes. None if not measured.
96    pub bytes_in: Option<i64>,
97
98    /// Response payload size in bytes. None if not measured.
99    pub bytes_out: Option<i64>,
100}
101
102/// Emitted once per MCP session, when the proxy intercepts the `initialize` handshake.
103///
104/// The `clientInfo` field in the MCP `initialize` request is the authoritative source
105/// of client identity — we don't guess from headers or user-agent strings.
106#[derive(Debug)]
107pub struct SessionEvent {
108    /// MCP session ID — primary key in the `sessions` table.
109    pub session_id: String,
110
111    /// Which proxy this session connected through.
112    pub proxy: String,
113
114    /// Unix milliseconds (UTC) of the `initialize` request.
115    pub started_at: i64,
116
117    /// Client name from `clientInfo.name` (e.g., "claude-desktop", "cursor").
118    /// None if the client omits `clientInfo` (non-compliant but possible).
119    pub client_name: Option<String>,
120
121    /// Client version from `clientInfo.version` (e.g., "1.2.0").
122    pub client_version: Option<String>,
123
124    /// Normalized platform identifier derived from client_name.
125    /// Values: "claude", "chatgpt", "vscode", "cursor", "unknown".
126    /// Normalization happens at write time via a static lookup table.
127    pub client_platform: Option<String>,
128}
129
130/// A new `SchemaVersion` produced by the proxy's `SchemaManager`.
131///
132/// The writer trusts the event: `SchemaManager` guarantees the payload
133/// differs from the previous version (unchanged ingests return `None`
134/// and produce no event). The writer only diffs against the prior row
135/// to populate `schema_changes`.
136#[derive(Debug)]
137pub struct SchemaVersionEvent {
138    pub ts: i64,
139    /// Proxy name from config (upstream identity).
140    pub proxy: String,
141    pub upstream_url: String,
142    pub method: String,
143    /// Merged `result` payload as JSON string.
144    pub payload: String,
145    /// SHA-256 hex digest of the canonical payload.
146    pub content_hash: String,
147}
148
149/// Outcome of a single MCP request.
150///
151/// Maps to the `status` CHECK constraint in the `requests` table:
152/// `CHECK (status IN ('ok', 'error', 'timeout'))`.
153#[derive(Debug, Clone, Copy, PartialEq, Eq)]
154pub enum RequestStatus {
155    /// Upstream returned a valid MCP response (may still contain application-level errors).
156    Ok,
157    /// Upstream returned an MCP error response (JSON-RPC error object).
158    Error,
159    /// The request timed out before the upstream responded.
160    Timeout,
161}
162
163impl RequestStatus {
164    /// SQL-safe string representation, matching the CHECK constraint values.
165    pub fn as_str(&self) -> &'static str {
166        match self {
167            RequestStatus::Ok => "ok",
168            RequestStatus::Error => "error",
169            RequestStatus::Timeout => "timeout",
170        }
171    }
172}
mcpr_integrations/store/event.rs

mcpr_integrations/store/
event.rs
