CI / UI Checks (pull_request) Successful in 10s
CI / Rust Checks (pull_request) Successful in 31m1s
CI / Rust Feature Validation (pull_request) Skipped
CI / Frontend E2E (pull_request) Skipped
CI / Community Image Smoke (pull_request) Skipped
CI / Required Checks (pull_request) Successful in 1s
CI / Deploy (pull_request) Skipped
975 lines
34 KiB
Rust
975 lines
34 KiB
Rust
//! Fixtures and helpers of the in-crate section 7.2 test seam (`app::dispatch_observer`).
|
|
//!
|
|
//! This file is the `support` child module of `crate::app::dispatch_observer` (wired with `#[path]`
|
|
//! there). It holds everything the observed tests need but no test itself: the real router harness,
|
|
//! the counted session store, the counted loopback upstream, the registry/operation/agent fixtures
|
|
//! and the shared assertions. It lives one directory above `src/app/` for the same reason the
|
|
//! `tests` module does — `scripts/check-execution-boundaries.py` reserves that prefix for service
|
|
//! modules without an HTTP client or a persistence dependency. Everything here is `#[cfg(test)]`.
|
|
|
|
//! Behavioural harness of the BUILD-internal semantic observer (Story 3.1 section 7.2).
|
|
//!
|
|
//! This file is the `tests` child module of `crate::app::dispatch_observer` (wired with `#[path]`
|
|
//! there), so the module path — and therefore the sanctioned selector
|
|
//! `cargo test -p crank-community-mcp --lib app::dispatch_observer::` — is unchanged. It is not a
|
|
//! separate crate target and it is `#[cfg(test)]`-only.
|
|
//!
|
|
//! Why the file is not under `src/app/`: `scripts/check-execution-boundaries.py` treats the whole
|
|
//! `crates/crank-community-mcp/src/app/` prefix as service-module scope and forbids an HTTP-client
|
|
//! (`reqwest`) or persistence (`sqlx`/migration) dependency there. This harness needs both — a real
|
|
//! PostgreSQL schema through `crank_test_support::postgres_schema_url` and a real request through the
|
|
//! served router — so the harness sits one directory above the scoped prefix while the observer
|
|
//! itself (markers, scope, counters, no dependency) stays at the approved `src/app/` path.
|
|
|
|
use std::{
|
|
collections::BTreeMap,
|
|
sync::{
|
|
Arc,
|
|
atomic::{AtomicUsize, Ordering},
|
|
},
|
|
time::Duration,
|
|
};
|
|
|
|
use axum::{Json, Router, extract::State, http::header, routing::post};
|
|
use base64::{Engine as _, engine::general_purpose::URL_SAFE_NO_PAD};
|
|
use crank_core::{
|
|
Agent, AgentId, AgentOperationBinding, AgentStatus, AgentVersion, ExecutionConfig, HttpMethod,
|
|
Operation, OperationId, OperationStatus, PlatformApiKey, PlatformApiKeyId, PlatformApiKeyKind,
|
|
PlatformApiKeyScope, PlatformApiKeyStatus, Protocol, RestTarget, Target, ToolDescription,
|
|
ToolSelectionPolicy, WorkspaceId,
|
|
};
|
|
use crank_mapping::{MappingRule, MappingSet};
|
|
use crank_registry::{
|
|
CreateAgentRequest, CreatePlatformApiKeyRequest, PostgresRegistry, PublishAgentRequest,
|
|
PublishRequest,
|
|
};
|
|
use crank_runtime::{
|
|
InMemoryCoordinationStateStore, RequestRateLimitConfig, RequestRateLimiter, SecretCrypto,
|
|
};
|
|
use crank_schema::{Schema, SchemaKind};
|
|
use serde_json::{Value, json};
|
|
use sha2::{Digest, Sha256};
|
|
use time::{OffsetDateTime, format_description::well_known::Rfc3339};
|
|
use tokio::net::TcpListener;
|
|
|
|
use super::{observe, observe_with_registration};
|
|
use crate::{
|
|
auth::CommunityMachineCredentialVerifier,
|
|
build_app,
|
|
protocol::{
|
|
CAPABILITY_DESCRIPTORS, CapabilityId, CapabilityIdDescriptor, CapabilityRegistry,
|
|
FeatureSet, HeaderSet, Kind, METHOD_DESCRIPTORS, MethodDescriptor, MethodHandler, Roster,
|
|
},
|
|
session::{InMemorySessionStore, SessionState, SessionStoreError, TransportSessionStore},
|
|
};
|
|
|
|
pub(super) const LEGACY_REVISION: &str = "2025-11-25";
|
|
pub(super) const MODERN_REVISION: &str = "2026-07-28";
|
|
pub(super) const TOOL_NAME: &str = "create_lead";
|
|
pub(super) const WORKSPACE_SLUG: &str = "default";
|
|
pub(super) const AGENT_SLUG: &str = "dispatch-observer";
|
|
pub(super) const META_PROTOCOL_VERSION: &str = "io.modelcontextprotocol/protocolVersion";
|
|
pub(super) const META_CLIENT_CAPABILITIES: &str = "io.modelcontextprotocol/clientCapabilities";
|
|
pub(super) const META_CLIENT_INFO: &str = "io.modelcontextprotocol/clientInfo";
|
|
|
|
/// One observed endpoint: the real router, the observer that counts its own requests and the counted
|
|
/// loopback upstream that every real tool execution must reach.
|
|
pub(super) struct Harness {
|
|
client: reqwest::Client,
|
|
mcp_url: String,
|
|
api_key: String,
|
|
counters: Arc<CounterSet>,
|
|
session_counters: Arc<SessionCounters>,
|
|
upstream_calls: Arc<AtomicUsize>,
|
|
}
|
|
|
|
pub(super) struct Upstream {
|
|
base_url: String,
|
|
calls: Arc<AtomicUsize>,
|
|
}
|
|
|
|
/// The session-store operations of the observed requests (section 7.2 honest naming: these count
|
|
/// *session-store operations*, never dispatch, era or service entries).
|
|
#[derive(Debug, Default)]
|
|
pub(super) struct SessionCounters {
|
|
get: AtomicUsize,
|
|
create: AtomicUsize,
|
|
mark_initialized: AtomicUsize,
|
|
}
|
|
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
pub(super) struct SessionOps {
|
|
pub(super) get: usize,
|
|
pub(super) create: usize,
|
|
pub(super) mark_initialized: usize,
|
|
}
|
|
|
|
impl SessionCounters {
|
|
pub(super) fn snapshot(&self) -> SessionOps {
|
|
SessionOps {
|
|
get: self.get.load(Ordering::SeqCst),
|
|
create: self.create.load(Ordering::SeqCst),
|
|
mark_initialized: self.mark_initialized.load(Ordering::SeqCst),
|
|
}
|
|
}
|
|
}
|
|
|
|
/// The observed session store: one real `InMemorySessionStore` plus per-operation counters, so a
|
|
/// request that touches the session store before (or instead of) the expected path is visible.
|
|
#[derive(Default)]
|
|
pub(super) struct CountedSessionStore {
|
|
inner: InMemorySessionStore,
|
|
counters: Arc<SessionCounters>,
|
|
}
|
|
|
|
impl CountedSessionStore {
|
|
pub(super) fn snapshot(&self) -> SessionOps {
|
|
self.counters.snapshot()
|
|
}
|
|
|
|
/// Inspect retained state without incrementing the HTTP request's session-read oracle.
|
|
pub(super) async fn retained(&self, id: &str) -> Option<SessionState> {
|
|
self.inner.get(id).await.unwrap()
|
|
}
|
|
}
|
|
|
|
#[async_trait::async_trait]
|
|
impl TransportSessionStore for CountedSessionStore {
|
|
async fn create(
|
|
&self,
|
|
protocol_version: &str,
|
|
workspace_slug: &str,
|
|
agent_slug: &str,
|
|
supports_elicitation: bool,
|
|
now: OffsetDateTime,
|
|
expires_at: Option<OffsetDateTime>,
|
|
) -> Result<String, SessionStoreError> {
|
|
self.counters.create.fetch_add(1, Ordering::SeqCst);
|
|
self.inner
|
|
.create(
|
|
protocol_version,
|
|
workspace_slug,
|
|
agent_slug,
|
|
supports_elicitation,
|
|
now,
|
|
expires_at,
|
|
)
|
|
.await
|
|
}
|
|
|
|
async fn get(&self, session_id: &str) -> Result<Option<SessionState>, SessionStoreError> {
|
|
self.counters.get.fetch_add(1, Ordering::SeqCst);
|
|
self.inner.get(session_id).await
|
|
}
|
|
|
|
async fn mark_initialized(
|
|
&self,
|
|
session_id: &str,
|
|
now: OffsetDateTime,
|
|
) -> Result<bool, SessionStoreError> {
|
|
self.counters
|
|
.mark_initialized
|
|
.fetch_add(1, Ordering::SeqCst);
|
|
self.inner.mark_initialized(session_id, now).await
|
|
}
|
|
|
|
async fn delete(&self, session_id: &str) -> Result<bool, SessionStoreError> {
|
|
self.inner.delete(session_id).await
|
|
}
|
|
|
|
async fn cleanup_expired(&self, now: OffsetDateTime) -> Result<u64, SessionStoreError> {
|
|
self.inner.cleanup_expired(now).await
|
|
}
|
|
|
|
async fn active_count(&self, now: OffsetDateTime) -> Result<u64, SessionStoreError> {
|
|
self.inner.active_count(now).await
|
|
}
|
|
}
|
|
|
|
impl Harness {
|
|
pub(super) async fn started() -> Self {
|
|
Self::started_with_registration(None).await
|
|
}
|
|
|
|
/// One observed endpoint, optionally served with an explicit registration snapshot (F5: the
|
|
/// add/remove proof runs against this real router, not against a registry unit query).
|
|
pub(super) async fn started_with_registration(
|
|
registration: Option<Arc<CapabilityRegistry>>,
|
|
) -> Self {
|
|
let registry = test_registry().await;
|
|
let upstream = spawn_counted_upstream().await;
|
|
let operation = test_operation(&upstream.base_url);
|
|
let workspace_id = workspace_id();
|
|
registry
|
|
.create_operation(&workspace_id, &operation, Some("alice"))
|
|
.await
|
|
.expect("the operation must be created");
|
|
registry
|
|
.publish_operation(PublishRequest {
|
|
workspace_id: &workspace_id,
|
|
operation_id: &operation.id,
|
|
version: 1,
|
|
published_at: &test_time(),
|
|
published_by: Some("alice"),
|
|
})
|
|
.await
|
|
.expect("the operation must be published");
|
|
publish_agent(®istry, &operation).await;
|
|
let api_key = create_api_key(®istry).await;
|
|
|
|
let counters = Arc::new(CounterSet::default());
|
|
let session_counters = Arc::new(SessionCounters::default());
|
|
let sessions = Arc::new(CountedSessionStore {
|
|
inner: InMemorySessionStore::default(),
|
|
counters: Arc::clone(&session_counters),
|
|
});
|
|
let app = observe_requests(
|
|
build_app(
|
|
registry,
|
|
Duration::from_millis(0),
|
|
Some("https://crank.example.com".to_owned()),
|
|
SecretCrypto::new("test-master-key-00000000000000000000000000000000")
|
|
.expect("a valid test master key"),
|
|
crank_runtime::community_with_outbound_policy(
|
|
crank_runtime::OutboundHttpPolicy::allowing_hosts(["127.0.0.1"]),
|
|
)
|
|
.build(),
|
|
RequestRateLimiter::new(
|
|
RequestRateLimitConfig::new(10_000, 10_000).expect("a valid rate limit"),
|
|
),
|
|
Arc::new(InMemoryCoordinationStateStore::default()),
|
|
sessions,
|
|
Arc::new(CommunityMachineCredentialVerifier),
|
|
),
|
|
Arc::clone(&counters),
|
|
registration,
|
|
);
|
|
let base_url = spawn_server(app).await;
|
|
|
|
Self {
|
|
client: reqwest::Client::new(),
|
|
mcp_url: format!("{base_url}/v1/{WORKSPACE_SLUG}/{AGENT_SLUG}"),
|
|
api_key,
|
|
counters,
|
|
session_counters,
|
|
upstream_calls: upstream.calls,
|
|
}
|
|
}
|
|
|
|
pub(super) fn snapshot(&self) -> Snapshot {
|
|
self.counters.snapshot()
|
|
}
|
|
|
|
pub(super) fn session_ops(&self) -> SessionOps {
|
|
self.session_counters.snapshot()
|
|
}
|
|
|
|
pub(super) fn upstream_calls(&self) -> usize {
|
|
self.upstream_calls.load(Ordering::SeqCst)
|
|
}
|
|
|
|
pub(super) async fn post(&self, headers: &[(&str, &str)], body: &Value) -> reqwest::Response {
|
|
let mut request = self
|
|
.client
|
|
.post(&self.mcp_url)
|
|
.header(header::ACCEPT, "application/json, text/event-stream")
|
|
.header(header::AUTHORIZATION, format!("Bearer {}", self.api_key));
|
|
for (name, value) in headers {
|
|
request = request.header(*name, *value);
|
|
}
|
|
request
|
|
.json(body)
|
|
.send()
|
|
.await
|
|
.expect("the observed request must complete")
|
|
}
|
|
|
|
/// A legacy session, primed through the real lifecycle methods.
|
|
pub(super) async fn initialize_legacy_session(&self) -> String {
|
|
let response = self
|
|
.post(
|
|
&[("MCP-Protocol-Version", LEGACY_REVISION)],
|
|
&json!({
|
|
"jsonrpc": "2.0",
|
|
"id": 1,
|
|
"method": "initialize",
|
|
"params": { "protocolVersion": LEGACY_REVISION, "capabilities": {} }
|
|
}),
|
|
)
|
|
.await;
|
|
assert_eq!(
|
|
response.status().as_u16(),
|
|
200,
|
|
"the legacy initialize must succeed"
|
|
);
|
|
let session_id = response
|
|
.headers()
|
|
.get("MCP-Session-Id")
|
|
.expect("initialize must mint a session")
|
|
.to_str()
|
|
.expect("the session id must be a header string")
|
|
.to_owned();
|
|
|
|
let initialized = self
|
|
.post(
|
|
&[
|
|
("MCP-Protocol-Version", LEGACY_REVISION),
|
|
("MCP-Session-Id", session_id.as_str()),
|
|
],
|
|
&json!({
|
|
"jsonrpc": "2.0",
|
|
"method": "notifications/initialized",
|
|
"params": {}
|
|
}),
|
|
)
|
|
.await;
|
|
assert_eq!(
|
|
initialized.status().as_u16(),
|
|
202,
|
|
"the initialized notification must be acknowledged"
|
|
);
|
|
session_id
|
|
}
|
|
}
|
|
|
|
/// Install the request-scoped observer (and, when given, the F5 registration snapshot) around every
|
|
/// request of this router.
|
|
///
|
|
/// The layer runs inside the request task and awaits the inner service, so the markers deep in the
|
|
/// handler see exactly this request's counters and the dispatch asks exactly this request's
|
|
/// registration. Nothing global is mutated.
|
|
pub(super) fn observe_requests(
|
|
app: Router,
|
|
counters: Arc<CounterSet>,
|
|
registration: Option<Arc<CapabilityRegistry>>,
|
|
) -> Router {
|
|
app.layer(axum::middleware::from_fn(
|
|
move |request: axum::extract::Request, next: axum::middleware::Next| {
|
|
let counters = Arc::clone(&counters);
|
|
let registration = registration.clone();
|
|
async move {
|
|
match registration {
|
|
Some(registration) => {
|
|
observe_with_registration(
|
|
registration,
|
|
observe(counters, next.run(request)),
|
|
)
|
|
.await
|
|
}
|
|
None => observe(counters, next.run(request)).await,
|
|
}
|
|
}
|
|
},
|
|
))
|
|
}
|
|
|
|
pub(super) async fn spawn_server(app: Router) -> String {
|
|
let listener = TcpListener::bind("127.0.0.1:0")
|
|
.await
|
|
.expect("a loopback listener must bind");
|
|
let address = listener
|
|
.local_addr()
|
|
.expect("a bound listener has an address");
|
|
tokio::spawn(async move {
|
|
let _ = axum::serve(listener, app).await;
|
|
});
|
|
format!("http://{address}")
|
|
}
|
|
|
|
/// The counted loopback upstream: every arrival is one real outbound tool execution.
|
|
pub(super) async fn spawn_counted_upstream() -> Upstream {
|
|
let calls = Arc::new(AtomicUsize::new(0));
|
|
let state = Arc::clone(&calls);
|
|
let app = Router::new()
|
|
.route("/crm/leads", post(create_lead))
|
|
.with_state(state);
|
|
Upstream {
|
|
base_url: spawn_server(app).await,
|
|
calls,
|
|
}
|
|
}
|
|
|
|
pub(super) async fn create_lead(
|
|
State(calls): State<Arc<AtomicUsize>>,
|
|
Json(payload): Json<Value>,
|
|
) -> Json<Value> {
|
|
calls.fetch_add(1, Ordering::SeqCst);
|
|
// The fixture echoes the request's own payload in its identifier, so every valid call has a
|
|
// *distinguishable* scoped output: two valid calls can never be confused with one another
|
|
// (section 7.2 requires a scoped output per case, not one shared constant).
|
|
let email = payload["email"].as_str().unwrap_or("unknown").to_owned();
|
|
Json(json!({ "id": format!("lead_for_{email}"), "email": payload["email"] }))
|
|
}
|
|
|
|
pub(super) async fn test_registry() -> PostgresRegistry {
|
|
let database_url = crank_test_support::postgres_schema_url("crank_dispatch_observer").await;
|
|
let pool = sqlx::PgPool::connect(&database_url)
|
|
.await
|
|
.expect("the test PostgreSQL must accept connections");
|
|
crank_registry::MigrationAuthority::apply(&pool)
|
|
.await
|
|
.expect("the migrations must apply");
|
|
PostgresRegistry::connect(&database_url)
|
|
.await
|
|
.expect("the registry must connect")
|
|
}
|
|
|
|
pub(super) fn test_time() -> OffsetDateTime {
|
|
OffsetDateTime::parse("2026-03-26T10:00:00Z", &Rfc3339).expect("a pinned timestamp")
|
|
}
|
|
|
|
pub(super) fn workspace_id() -> WorkspaceId {
|
|
WorkspaceId::new("ws_default")
|
|
}
|
|
|
|
pub(super) fn agent_id() -> AgentId {
|
|
AgentId::new(format!("agent_{AGENT_SLUG}"))
|
|
}
|
|
|
|
pub(crate) async fn publish_agent(
|
|
registry: &PostgresRegistry,
|
|
operation: &Operation<Schema, MappingSet>,
|
|
) {
|
|
let agent = Agent {
|
|
id: agent_id(),
|
|
workspace_id: workspace_id(),
|
|
slug: AGENT_SLUG.to_owned(),
|
|
display_name: "Dispatch observer agent".to_owned(),
|
|
description: "Curated MCP toolset".to_owned(),
|
|
status: AgentStatus::Draft,
|
|
current_draft_version: 1,
|
|
latest_published_version: None,
|
|
created_at: test_time(),
|
|
updated_at: test_time(),
|
|
published_at: None,
|
|
};
|
|
let version = AgentVersion {
|
|
agent_id: agent_id(),
|
|
version: 1,
|
|
status: AgentStatus::Draft,
|
|
instructions: json!({}),
|
|
tool_selection_policy: ToolSelectionPolicy::default(),
|
|
created_at: test_time(),
|
|
};
|
|
let bindings = vec![AgentOperationBinding {
|
|
operation_id: operation.id.clone(),
|
|
operation_version: 1,
|
|
tool_name: operation.name.clone(),
|
|
tool_title: operation.tool_description.title.clone(),
|
|
tool_description_override: None,
|
|
enabled: true,
|
|
}];
|
|
|
|
registry
|
|
.create_agent(CreateAgentRequest {
|
|
agent: &agent,
|
|
version: &version,
|
|
bindings: &bindings,
|
|
})
|
|
.await
|
|
.expect("the agent must be created");
|
|
registry
|
|
.publish_agent(PublishAgentRequest {
|
|
workspace_id: &workspace_id(),
|
|
agent_id: &agent_id(),
|
|
version: 1,
|
|
published_at: &test_time(),
|
|
published_by: Some("alice"),
|
|
expected_state: None,
|
|
})
|
|
.await
|
|
.expect("the agent must be published");
|
|
}
|
|
|
|
pub(crate) async fn create_api_key(registry: &PostgresRegistry) -> String {
|
|
let secret = format!("crk_dispatch_observer_{}", uuid::Uuid::now_v7().simple());
|
|
let api_key = PlatformApiKey {
|
|
id: PlatformApiKeyId::new("pk_dispatch_observer"),
|
|
workspace_id: workspace_id(),
|
|
agent_id: Some(agent_id()),
|
|
key_kind: PlatformApiKeyKind::McpClient,
|
|
name: "dispatch-observer".to_owned(),
|
|
prefix: secret.chars().take(16).collect(),
|
|
scopes: vec![PlatformApiKeyScope::Read, PlatformApiKeyScope::Write],
|
|
status: PlatformApiKeyStatus::Active,
|
|
created_at: test_time(),
|
|
last_used_at: None,
|
|
expires_at: None,
|
|
allowed_origins: Vec::new(),
|
|
};
|
|
registry
|
|
.create_platform_api_key(CreatePlatformApiKeyRequest {
|
|
api_key: &api_key,
|
|
secret_hash: &hash_access_secret(&secret),
|
|
})
|
|
.await
|
|
.expect("the API key must be created");
|
|
secret
|
|
}
|
|
|
|
pub(super) fn hash_access_secret(secret: &str) -> String {
|
|
URL_SAFE_NO_PAD.encode(Sha256::digest(secret.as_bytes()))
|
|
}
|
|
|
|
pub(crate) fn test_operation(base_url: &str) -> Operation<Schema, MappingSet> {
|
|
Operation {
|
|
id: OperationId::new(format!("op_{TOOL_NAME}")),
|
|
name: TOOL_NAME.to_owned(),
|
|
display_name: "Create Lead".to_owned(),
|
|
category: "sales".to_owned(),
|
|
protocol: Protocol::Rest,
|
|
security_level: crank_core::OperationSecurityLevel::Standard,
|
|
status: OperationStatus::Published,
|
|
version: 1,
|
|
target: Target::Rest(RestTarget {
|
|
base_url: base_url.to_owned(),
|
|
method: HttpMethod::Post,
|
|
path_template: "/crm/leads".to_owned(),
|
|
static_headers: BTreeMap::new(),
|
|
request_contract: None,
|
|
response_contract: Vec::new(),
|
|
multipart_field_mime_types: BTreeMap::new(),
|
|
}),
|
|
input_schema: object_schema("email"),
|
|
output_schema: object_schema("id"),
|
|
input_mapping: MappingSet {
|
|
rules: vec![MappingRule {
|
|
source: "$.mcp.email".to_owned(),
|
|
target: "$.request.body.email".to_owned(),
|
|
required: true,
|
|
default_value: None,
|
|
transform: None,
|
|
condition: None,
|
|
notes: None,
|
|
}],
|
|
},
|
|
output_mapping: MappingSet {
|
|
rules: vec![MappingRule {
|
|
source: "$.response.body.id".to_owned(),
|
|
target: "$.output.id".to_owned(),
|
|
required: true,
|
|
default_value: None,
|
|
transform: None,
|
|
condition: None,
|
|
notes: None,
|
|
}],
|
|
},
|
|
execution_config: ExecutionConfig {
|
|
timeout_ms: 1_000,
|
|
retry_policy: None,
|
|
response_cache: None,
|
|
idempotency: None,
|
|
safety: None,
|
|
approval_policy: None,
|
|
execution_policy: None,
|
|
auth_profile_ref: None,
|
|
headers: BTreeMap::new(),
|
|
},
|
|
tool_description: ToolDescription {
|
|
title: "Create Lead".to_owned(),
|
|
description: "Creates a CRM lead".to_owned(),
|
|
tags: Vec::new(),
|
|
examples: Vec::new(),
|
|
},
|
|
samples: None,
|
|
generated_draft: None,
|
|
config_export: None,
|
|
wizard_state: None,
|
|
created_at: test_time(),
|
|
updated_at: test_time(),
|
|
published_at: Some(test_time()),
|
|
}
|
|
}
|
|
|
|
pub(super) fn object_schema(field_name: &str) -> Schema {
|
|
Schema {
|
|
kind: SchemaKind::Object,
|
|
format: None,
|
|
description: None,
|
|
required: true,
|
|
nullable: false,
|
|
default_value: None,
|
|
fields: BTreeMap::from([(
|
|
field_name.to_owned(),
|
|
Schema {
|
|
kind: SchemaKind::String,
|
|
format: None,
|
|
description: None,
|
|
required: true,
|
|
nullable: false,
|
|
default_value: None,
|
|
fields: BTreeMap::new(),
|
|
items: None,
|
|
enum_values: Vec::new(),
|
|
variants: Vec::new(),
|
|
},
|
|
)]),
|
|
items: None,
|
|
enum_values: Vec::new(),
|
|
variants: Vec::new(),
|
|
}
|
|
}
|
|
|
|
pub(super) fn modern_meta() -> Value {
|
|
json!({
|
|
META_PROTOCOL_VERSION: MODERN_REVISION,
|
|
META_CLIENT_CAPABILITIES: {},
|
|
META_CLIENT_INFO: { "name": "crank-dispatch-observer", "version": "0.1.0" }
|
|
})
|
|
}
|
|
|
|
pub(super) fn legacy_tool_call(id: u64, email: &str) -> Value {
|
|
json!({
|
|
"jsonrpc": "2.0",
|
|
"id": id,
|
|
"method": "tools/call",
|
|
"params": { "name": TOOL_NAME, "arguments": { "email": email } }
|
|
})
|
|
}
|
|
|
|
/// One legacy `initialize` request body (the valid request form of the lifecycle operation).
|
|
pub(super) fn legacy_initialize(id: u64) -> Value {
|
|
json!({
|
|
"jsonrpc": "2.0",
|
|
"id": id,
|
|
"method": "initialize",
|
|
"params": { "protocolVersion": LEGACY_REVISION, "capabilities": {} }
|
|
})
|
|
}
|
|
|
|
/// One legacy `notifications/initialized` notification body (the valid notification form).
|
|
///
|
|
/// The `params` carry a valid `InitializeParams` payload so that the *only* difference from its
|
|
/// request-shaped negative is the presence of `id`: a wire name must never be served as the other
|
|
/// lifecycle action because of the envelope kind (G2).
|
|
pub(super) fn initialized_notification() -> Value {
|
|
json!({
|
|
"jsonrpc": "2.0",
|
|
"method": "notifications/initialized",
|
|
"params": { "protocolVersion": LEGACY_REVISION, "capabilities": {} }
|
|
})
|
|
}
|
|
|
|
pub(super) fn modern_tool_call(id: u64, email: &str) -> Value {
|
|
json!({
|
|
"jsonrpc": "2.0",
|
|
"id": id,
|
|
"method": "tools/call",
|
|
"params": {
|
|
"_meta": modern_meta(),
|
|
"name": TOOL_NAME,
|
|
"arguments": { "email": email }
|
|
}
|
|
})
|
|
}
|
|
|
|
pub(super) fn legacy_headers(session_id: &str) -> Vec<(&'static str, String)> {
|
|
vec![
|
|
("MCP-Protocol-Version", LEGACY_REVISION.to_owned()),
|
|
("MCP-Session-Id", session_id.to_owned()),
|
|
]
|
|
}
|
|
|
|
pub(super) fn modern_headers() -> Vec<(&'static str, String)> {
|
|
vec![
|
|
("MCP-Protocol-Version", MODERN_REVISION.to_owned()),
|
|
("Mcp-Method", "tools/call".to_owned()),
|
|
("Mcp-Name", TOOL_NAME.to_owned()),
|
|
]
|
|
}
|
|
|
|
pub(super) fn header_refs<'a>(
|
|
headers: &'a [(&'static str, String)],
|
|
) -> Vec<(&'static str, &'a str)> {
|
|
headers
|
|
.iter()
|
|
.map(|(name, value)| (*name, value.as_str()))
|
|
.collect()
|
|
}
|
|
|
|
pub(super) async fn json_body(response: reqwest::Response) -> Value {
|
|
let status = response.status();
|
|
let body = response
|
|
.text()
|
|
.await
|
|
.expect("the observed response body must be readable");
|
|
serde_json::from_str(&body).unwrap_or_else(|error| {
|
|
panic!("expected a JSON-RPC body, got status {status} body {body:?}: {error}")
|
|
})
|
|
}
|
|
|
|
/// Compare the marker deltas of one observed request with the section 7.2 table row.
|
|
pub(super) fn assert_deltas(case: &str, before: Snapshot, after: Snapshot, expected: Snapshot) {
|
|
let actual = Snapshot::new(
|
|
after.admission - before.admission,
|
|
after.era_modern - before.era_modern,
|
|
after.era_legacy - before.era_legacy,
|
|
after.tools_service - before.tools_service,
|
|
);
|
|
assert_eq!(
|
|
actual, expected,
|
|
"{case}: admission/era-modern/era-legacy/tools-service deltas must be \
|
|
(admission, era_modern, era_legacy, tools_service) = {expected:?}, got {actual:?}"
|
|
);
|
|
}
|
|
|
|
pub(super) fn assert_no_result(case: &str, body: &Value) {
|
|
assert!(
|
|
body.get("result").is_none(),
|
|
"{case}: a rejected request must not return a result, got {body}"
|
|
);
|
|
assert!(
|
|
!body["error"].is_null(),
|
|
"{case}: a rejected request must return a JSON-RPC error, got {body}"
|
|
);
|
|
}
|
|
|
|
/// Compare the session-store operation deltas of one observed request.
|
|
///
|
|
/// Section 7.2 honest naming: these counters count *session-store operations* (`get`/`create`/
|
|
/// `mark_initialized`), never dispatch, era-adapter or service entries — an in-service branch can
|
|
/// reject before any outbound call, so no conclusion about a service entry is drawn from them.
|
|
pub(super) fn assert_session_ops(
|
|
case: &str,
|
|
before: SessionOps,
|
|
after: SessionOps,
|
|
expected: SessionOps,
|
|
) {
|
|
let actual = SessionOps {
|
|
get: after.get - before.get,
|
|
create: after.create - before.create,
|
|
mark_initialized: after.mark_initialized - before.mark_initialized,
|
|
};
|
|
assert_eq!(
|
|
actual, expected,
|
|
"{case}: session-store operation deltas (get, create, mark_initialized) must be {expected:?}, \
|
|
got {actual:?}"
|
|
);
|
|
}
|
|
|
|
/// The scoped output of one valid call: the fixture echoes the request's own payload.
|
|
pub(super) fn assert_scoped_output(case: &str, body: &Value, email: &str) {
|
|
assert_eq!(
|
|
body["result"]["structuredContent"]["id"],
|
|
format!("lead_for_{email}"),
|
|
"{case}: the valid call must return *its own* scoped output, got {body}"
|
|
);
|
|
}
|
|
|
|
/// One valid legacy `tools/call`: its own era-adapter, the owning Tools service, exactly one outbound
|
|
/// call, the request's own scoped output and the admission's session reads.
|
|
pub(super) async fn run_valid_legacy_call(
|
|
harness: &Harness,
|
|
session: &str,
|
|
id: u64,
|
|
email: &str,
|
|
case: &str,
|
|
) {
|
|
let before = harness.snapshot();
|
|
let ops_before = harness.session_ops();
|
|
let arrivals = harness.upstream_calls();
|
|
let response = harness
|
|
.post(
|
|
&header_refs(&legacy_headers(session)),
|
|
&legacy_tool_call(id, email),
|
|
)
|
|
.await;
|
|
assert_eq!(
|
|
response.status().as_u16(),
|
|
200,
|
|
"{case}: a valid legacy call must be served"
|
|
);
|
|
let body = json_body(response).await;
|
|
assert_scoped_output(case, &body, email);
|
|
assert_deltas(case, before, harness.snapshot(), Snapshot::new(1, 0, 1, 1));
|
|
assert_eq!(
|
|
harness.upstream_calls() - arrivals,
|
|
1,
|
|
"{case}: a valid call makes exactly one outbound call"
|
|
);
|
|
// A legacy request that carries a session is read by the admission (revision check) and again by
|
|
// the adapter's session requirement: two reads, no creation and no mutation of the session.
|
|
assert_session_ops(
|
|
case,
|
|
ops_before,
|
|
harness.session_ops(),
|
|
SessionOps {
|
|
get: 2,
|
|
create: 0,
|
|
mark_initialized: 0,
|
|
},
|
|
);
|
|
}
|
|
|
|
/// One valid legacy `initialize` request: mints its own session, enters its own era-adapter, never
|
|
/// touches the Tools service and makes no outbound call (the request-form control of G2).
|
|
pub(super) async fn run_valid_legacy_initialize(harness: &Harness, id: u64, case: &str) {
|
|
let before = harness.snapshot();
|
|
let ops_before = harness.session_ops();
|
|
let arrivals = harness.upstream_calls();
|
|
let response = harness
|
|
.post(
|
|
&[("MCP-Protocol-Version", LEGACY_REVISION)],
|
|
&legacy_initialize(id),
|
|
)
|
|
.await;
|
|
assert_eq!(
|
|
response.status().as_u16(),
|
|
200,
|
|
"{case}: a valid legacy initialize must be served"
|
|
);
|
|
let session_id = response
|
|
.headers()
|
|
.get("MCP-Session-Id")
|
|
.expect("a valid initialize must mint a session")
|
|
.to_str()
|
|
.expect("the session id must be a header string")
|
|
.to_owned();
|
|
assert!(
|
|
!session_id.is_empty(),
|
|
"{case}: the minted session id must not be empty"
|
|
);
|
|
let body = json_body(response).await;
|
|
assert_eq!(
|
|
body["result"]["protocolVersion"], LEGACY_REVISION,
|
|
"{case}: the initialize result must name the negotiated revision, got {body}"
|
|
);
|
|
assert_deltas(case, before, harness.snapshot(), Snapshot::new(1, 0, 1, 0));
|
|
assert_eq!(harness.upstream_calls(), arrivals);
|
|
// The initialize request itself carries no session carrier, so the admission never reads the
|
|
// store: the one operation is the session creation of the lifecycle handler.
|
|
assert_session_ops(
|
|
case,
|
|
ops_before,
|
|
harness.session_ops(),
|
|
SessionOps {
|
|
get: 0,
|
|
create: 1,
|
|
mark_initialized: 0,
|
|
},
|
|
);
|
|
}
|
|
|
|
/// One valid legacy `notifications/initialized` on an existing session: acknowledged, its own
|
|
/// era-adapter, no Tools service, no outbound call, exactly one session initialization (G2 control).
|
|
pub(super) async fn run_valid_initialized_notification(
|
|
harness: &Harness,
|
|
session: &str,
|
|
case: &str,
|
|
) {
|
|
let before = harness.snapshot();
|
|
let ops_before = harness.session_ops();
|
|
let arrivals = harness.upstream_calls();
|
|
let response = harness
|
|
.post(
|
|
&header_refs(&legacy_headers(session)),
|
|
&initialized_notification(),
|
|
)
|
|
.await;
|
|
assert_eq!(
|
|
response.status().as_u16(),
|
|
202,
|
|
"{case}: the initialized notification must be acknowledged"
|
|
);
|
|
assert_deltas(case, before, harness.snapshot(), Snapshot::new(1, 0, 1, 0));
|
|
assert_eq!(harness.upstream_calls(), arrivals);
|
|
// The admission's revision check reads the carried session, and the lifecycle handler reads it
|
|
// once more before marking it initialized.
|
|
assert_session_ops(
|
|
case,
|
|
ops_before,
|
|
harness.session_ops(),
|
|
SessionOps {
|
|
get: 2,
|
|
create: 0,
|
|
mark_initialized: 1,
|
|
},
|
|
);
|
|
}
|
|
|
|
/// One valid modern `tools/call`: its own era-adapter, the owning Tools service, exactly one outbound
|
|
/// call, its own scoped output and *no* session-store operation at all (the modern era is stateless).
|
|
pub(super) async fn run_valid_modern_call(harness: &Harness, id: u64, email: &str, case: &str) {
|
|
let before = harness.snapshot();
|
|
let ops_before = harness.session_ops();
|
|
let arrivals = harness.upstream_calls();
|
|
let response = harness
|
|
.post(
|
|
&header_refs(&modern_headers()),
|
|
&modern_tool_call(id, email),
|
|
)
|
|
.await;
|
|
assert_eq!(
|
|
response.status().as_u16(),
|
|
200,
|
|
"{case}: a valid modern call must be served"
|
|
);
|
|
let body = json_body(response).await;
|
|
assert_scoped_output(case, &body, email);
|
|
assert_eq!(body["result"]["resultType"], "complete");
|
|
assert_deltas(case, before, harness.snapshot(), Snapshot::new(1, 1, 0, 1));
|
|
assert_eq!(
|
|
harness.upstream_calls() - arrivals,
|
|
1,
|
|
"{case}: a valid call makes exactly one outbound call"
|
|
);
|
|
assert_session_ops(
|
|
case,
|
|
ops_before,
|
|
harness.session_ops(),
|
|
SessionOps {
|
|
get: 0,
|
|
create: 0,
|
|
mark_initialized: 0,
|
|
},
|
|
);
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------------------------
|
|
// The inert private registration used by the F5 add/remove proof (never registered in production).
|
|
// ---------------------------------------------------------------------------------------------
|
|
|
|
/// The inert private capability and method used only by the F5 proof (never registered in production).
|
|
pub(super) fn inert_registration_extra() -> (CapabilityIdDescriptor, MethodDescriptor) {
|
|
(
|
|
CapabilityIdDescriptor {
|
|
id: CapabilityId::InertTest,
|
|
roster: Roster::Server,
|
|
kind: Kind::Capability,
|
|
extension: None,
|
|
deprecated: None,
|
|
sub_features: FeatureSet(&["enabled"]),
|
|
advertised: Some(("inert_test_capability", &[("enabled", true)])),
|
|
revisions: &[MODERN_REVISION, LEGACY_REVISION],
|
|
},
|
|
MethodDescriptor {
|
|
name: INERT_METHOD_NAME,
|
|
capability: CapabilityId::InertTest,
|
|
kind: Kind::Method,
|
|
required_headers: HeaderSet(&[]),
|
|
handler: MethodHandler::Ping,
|
|
},
|
|
)
|
|
}
|
|
|
|
pub(super) const INERT_METHOD_NAME: &str = "inert/echo";
|
|
|
|
/// See [`inert_registration_extra`]: the "remove" case is the production registration itself (no inert
|
|
/// capability, no inert method); the "add" case is the same tables plus the inert descriptor pair.
|
|
pub(super) fn registration_without_inert_method() -> CapabilityRegistry {
|
|
CapabilityRegistry::new(CAPABILITY_DESCRIPTORS, METHOD_DESCRIPTORS)
|
|
.expect("the production tables are a valid registration")
|
|
}
|
|
|
|
pub(super) fn registration_with_inert_method() -> CapabilityRegistry {
|
|
let mut capabilities = CAPABILITY_DESCRIPTORS.to_vec();
|
|
capabilities.push(inert_registration_extra().0);
|
|
let mut methods = METHOD_DESCRIPTORS.to_vec();
|
|
methods.push(inert_registration_extra().1);
|
|
CapabilityRegistry::new(&capabilities, &methods)
|
|
.expect("the inert method descriptor is a valid registration")
|
|
}
|
|
|
|
// Re-exported for the sibling `tests` module.
|
|
pub(super) use super::{CounterSet, Snapshot};
|