bsodfather/crank
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

feat: harden community production foundation through story 1.5

Browse Source
This commit is contained in:
bsodfather
2026-08-14 00:21:59 +03:00
parent c30461cc92
commit f6fc2e5c9b
161 changed files with 16758 additions and 2515 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/crank-adapter-rest/src/client.rs
+123 -67
View File
@@ -1,16 +1,20 @@
use std::{
collections::BTreeMap,
env, io,
io,
net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr},
sync::Arc,
time::Duration,
};
use crank_core::{HttpMethod, RestTarget};
use crank_core::{HttpMethod, RestTarget, RuntimeRequestContext};
use crank_metrics::{UpstreamOperationKind, UpstreamOutcome, UpstreamRequestMetrics};
use crank_trace::{ErrorCategory, Stage, StageOutcome};
use futures_util::StreamExt;
use opentelemetry::{global, propagation::Injector, trace::TraceContextExt};
use opentelemetry::{
Context, global,
propagation::Injector,
trace::{SpanContext, SpanId, TraceContextExt, TraceFlags, TraceId, TraceState},
};
use reqwest::{
Client,
dns::{Addrs, Name, Resolve, Resolving},
@@ -49,10 +53,6 @@ impl RestAdapter {
Self::with_policy(OutboundHttpPolicy::default())
}
pub fn from_env() -> Result<Self, RestAdapterError> {
Ok(Self::with_policy(OutboundHttpPolicy::from_env()?))
}
pub fn with_policy(policy: OutboundHttpPolicy) -> Self {
let resolver = Arc::new(PolicyDnsResolver {
policy: policy.clone(),
@@ -73,7 +73,23 @@ impl RestAdapter {
request: &RestRequest,
) -> Result<RestResponse, RestAdapterError> {
let request_metrics = UpstreamRequestMetrics::start(UpstreamOperationKind::Rest);
let result = self.execute_inner(target, request).await;
let result = self.execute_inner(target, request, None).await;
let outcome = match &result {
Ok(_) => UpstreamOutcome::Success,
Err(error) => upstream_outcome(error),
};
request_metrics.complete(outcome);
result
}
pub(crate) async fn execute_with_context(
&self,
target: &RestTarget,
request: &RestRequest,
context: &RuntimeRequestContext,
) -> Result<RestResponse, RestAdapterError> {
let request_metrics = UpstreamRequestMetrics::start(UpstreamOperationKind::Rest);
let result = self.execute_inner(target, request, Some(context)).await;
let outcome = match &result {
Ok(_) => UpstreamOutcome::Success,
Err(error) => upstream_outcome(error),
@@ -86,28 +102,48 @@ impl RestAdapter {
&self,
target: &RestTarget,
request: &RestRequest,
trusted_context: Option<&RuntimeRequestContext>,
) -> Result<RestResponse, RestAdapterError> {
let url = build_url(target, request)?;
self.policy.validate_url(&url)?;
let mut headers = build_headers(target, request)?;
apply_current_trace_context(&mut headers);
let client =
self.client
.as_ref()
.map_err(|details| RestAdapterError::InvalidConfiguration {
details: details.to_string(),
})?;
let mut builder = client
.request(to_reqwest_method(target.method), url)
.headers(headers)
.timeout(Duration::from_millis(request.timeout_ms));
if let Some(body) = &request.body {
builder = builder.json(body);
}
let upstream_span = Stage::UpstreamHttp.span();
if let Some(context) = trusted_context {
set_span_parent_from_traceparent(&upstream_span, context.trace_context.traceparent());
}
let result = async {
let url = build_url(target, request)?;
self.policy.validate_url(&url)?;
let mut headers = build_headers(target, request)?;
if let Some(context) = trusted_context {
for (name, value) in context.outbound_headers() {
let (Ok(name), Ok(value)) =
(HeaderName::try_from(name), HeaderValue::try_from(value))
else {
continue;
};
headers.insert(name, value);
}
}
apply_current_trace_context(&mut headers);
if !headers.contains_key("traceparent")
&& let Some(context) = trusted_context
&& let Ok(value) = HeaderValue::from_str(context.trace_context.traceparent())
{
headers.insert("traceparent", value);
}
let client =
self.client
.as_ref()
.map_err(|details| RestAdapterError::InvalidConfiguration {
details: details.to_string(),
})?;
let mut builder = client
.request(to_reqwest_method(target.method), url)
.headers(headers)
.timeout(Duration::from_millis(request.timeout_ms));
if let Some(body) = &request.body {
builder = builder.json(body);
}
let response = builder.send().await?;
let status = response.status();
let headers = normalize_headers(response.headers());
@@ -174,32 +210,19 @@ impl Default for OutboundHttpPolicy {
}
impl OutboundHttpPolicy {
pub fn from_env() -> Result<Self, RestAdapterError> {
let max_response_bytes = match env::var("CRANK_OUTBOUND_MAX_RESPONSE_BYTES") {
Ok(value) => {
value
.parse::<usize>()
.map_err(|_| RestAdapterError::InvalidConfiguration {
details: "CRANK_OUTBOUND_MAX_RESPONSE_BYTES must be a positive integer"
.to_owned(),
})?
}
Err(env::VarError::NotPresent) => DEFAULT_MAX_RESPONSE_BYTES,
Err(error) => {
return Err(RestAdapterError::InvalidConfiguration {
details: error.to_string(),
});
}
};
pub fn try_new(
allowed_hosts: Vec<String>,
denied_hosts: Vec<String>,
max_response_bytes: usize,
) -> Result<Self, RestAdapterError> {
if max_response_bytes == 0 {
return Err(RestAdapterError::InvalidConfiguration {
details: "CRANK_OUTBOUND_MAX_RESPONSE_BYTES must be greater than zero".to_owned(),
details: "outbound response limit must be greater than zero".to_owned(),
});
}
Ok(Self {
allowed_hosts: host_patterns_from_env("CRANK_OUTBOUND_ALLOWED_HOSTS")?,
denied_hosts: host_patterns_from_env("CRANK_OUTBOUND_DENIED_HOSTS")?,
allowed_hosts: validate_host_patterns(allowed_hosts)?,
denied_hosts: validate_host_patterns(denied_hosts)?,
max_response_bytes,
})
}
@@ -308,20 +331,11 @@ fn boxed_io_error(message: String) -> Box<dyn std::error::Error + Send + Sync> {
Box::new(io::Error::new(io::ErrorKind::PermissionDenied, message))
}
fn host_patterns_from_env(name: &str) -> Result<Vec<String>, RestAdapterError> {
let value = match env::var(name) {
Ok(value) => value,
Err(env::VarError::NotPresent) => return Ok(Vec::new()),
Err(error) => {
return Err(RestAdapterError::InvalidConfiguration {
details: error.to_string(),
});
}
};
value
.split(',')
.map(str::trim)
.filter(|value| !value.is_empty())
fn validate_host_patterns(
values: impl IntoIterator<Item = String>,
) -> Result<Vec<String>, RestAdapterError> {
values
.into_iter()
.map(|value| {
let wildcard = value.starts_with("*.");
let normalized = normalize_host(value.trim_start_matches("*."));
@@ -332,7 +346,7 @@ fn host_patterns_from_env(name: &str) -> Result<Vec<String>, RestAdapterError> {
|| (wildcard && normalized.parse::<IpAddr>().is_ok())
{
return Err(RestAdapterError::InvalidConfiguration {
details: format!("{name} contains an invalid host pattern: {value}"),
details: "outbound host pattern is invalid".to_owned(),
});
}
Ok(if wildcard {
@@ -465,7 +479,7 @@ fn insert_header(headers: &mut HeaderMap, name: &str, value: &str) -> Result<(),
HeaderName::try_from(name).map_err(|_| RestAdapterError::InvalidHeaderName {
header: name.to_owned(),
})?;
if is_trace_propagation_header(&header_name) {
if is_reserved_correlation_header(&header_name) {
return Ok(());
}
let header_value =
@@ -477,12 +491,53 @@ fn insert_header(headers: &mut HeaderMap, name: &str, value: &str) -> Result<(),
Ok(())
}
fn is_trace_propagation_header(name: &HeaderName) -> bool {
matches!(name.as_str(), "traceparent" | "tracestate" | "baggage")
fn is_reserved_correlation_header(name: &HeaderName) -> bool {
matches!(
name.as_str(),
"traceparent"
| "tracestate"
| "baggage"
| "x-request-id"
| "x-trace-id"
| "x-correlation-id"
)
}
fn set_span_parent_from_traceparent(span: &Span, traceparent: &str) -> bool {
let mut parts = traceparent.split('-');
let (Some("00"), Some(trace_id), Some(parent_id), Some(flags), None) = (
parts.next(),
parts.next(),
parts.next(),
parts.next(),
parts.next(),
) else {
return false;
};
let (Ok(trace_id), Ok(parent_id)) = (TraceId::from_hex(trace_id), SpanId::from_hex(parent_id))
else {
return false;
};
let trace_flags = if flags == "01" {
TraceFlags::SAMPLED
} else if flags == "00" {
TraceFlags::default()
} else {
return false;
};
let parent = SpanContext::new(
trace_id,
parent_id,
trace_flags,
true,
TraceState::default(),
);
span.set_parent(Context::new().with_remote_span_context(parent))
.is_ok()
}
fn apply_current_trace_context(headers: &mut HeaderMap) {
for header in ["traceparent", "tracestate", "baggage"] {
for header in ["tracestate", "baggage"] {
headers.remove(header);
}
@@ -490,6 +545,7 @@ fn apply_current_trace_context(headers: &mut HeaderMap) {
if !context.span().span_context().is_valid() {
return;
}
headers.remove("traceparent");
global::get_text_map_propagator(|propagator| {
propagator.inject_context(&context, &mut ReqwestHeaderInjector(headers));
});
crates/crank-adapter-rest/src/lib.rs
+2 -4
View File
@@ -29,16 +29,14 @@ impl ProtocolAdapter for RestAdapter {
context: &RuntimeRequestContext,
) -> Result<AdapterResponse, ProtocolAdapterError> {
let target = rest_target(target)?;
let mut headers = prepared.headers.clone();
headers.extend(context.outbound_headers());
let request = RestRequest {
path_params: prepared.path_params.clone(),
query_params: prepared.query_params.clone(),
headers,
headers: prepared.headers.clone(),
body: prepared.body.clone(),
timeout_ms: prepared.timeout_ms,
};
let response = self.execute(target, &request).await?;
let response = self.execute_with_context(target, &request, context).await?;
Ok(AdapterResponse {
status_code: response.status_code,
crates/crank-adapter-rest/tests/integration/client.rs
+14 -3
View File
@@ -48,7 +48,7 @@ async fn executes_rest_request_and_normalizes_json_response() {
json!({
"id": "42",
"query": "true",
"trace": "trace-123",
"trace": "",
"static": "static",
"payload": { "name": "Ada" }
})
@@ -69,6 +69,7 @@ async fn protocol_context_overrides_mapped_correlation_headers() {
"x-correlation-id".to_owned(),
"static-correlation".to_owned(),
),
("x-trace-id".to_owned(), "static-trace".to_owned()),
]),
});
let prepared = PreparedRequest {
@@ -79,12 +80,17 @@ async fn protocol_context_overrides_mapped_correlation_headers() {
"x-correlation-id".to_owned(),
"mapped-correlation".to_owned(),
),
("x-trace-id".to_owned(), "mapped-trace".to_owned()),
]),
body: Some(json!({ "name": "Ada" })),
timeout_ms: 1_000,
..PreparedRequest::default()
};
let context = RuntimeRequestContext::new("req-runtime", "corr-runtime");
let context = RuntimeRequestContext::new(
crank_core::RequestId::resolve(Some("req-runtime")),
crank_core::TraceContext::parse("00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01")
.unwrap(),
);
let response = adapter
.invoke_unary(&target, &prepared, &context)
@@ -92,7 +98,12 @@ async fn protocol_context_overrides_mapped_correlation_headers() {
.unwrap();
assert_eq!(response.body["request_id"], "req-runtime");
assert_eq!(response.body["correlation_id"], "corr-runtime");
assert_eq!(response.body["correlation_id"], "req-runtime");
assert_eq!(response.body["trace"], "0af7651916cd43dd8448eb211c80319c");
assert_eq!(
&response.body["traceparent"].as_str().unwrap()[3..35],
"0af7651916cd43dd8448eb211c80319c"
);
}
#[tokio::test(flavor = "current_thread")]
crates/crank-community-mcp/src/app.rs
+56 -59
View File
@@ -14,7 +14,7 @@ use axum::{
};
use crank_core::{
ApprovalRequest, ApprovalRequestId, ApprovalRequestStatus, AuthProfile, CoordinationStateStore,
InvocationLevel, InvocationSource, InvocationStatus, OperationApprovalMode,
CorrelationContext, InvocationLevel, InvocationSource, InvocationStatus, OperationApprovalMode,
PlatformApiKeyScope, SecretId,
};
use crank_registry::{
@@ -64,10 +64,12 @@ use crate::{
mod invocation_history;
mod metrics;
mod stages;
mod tool_resolution;
use self::metrics::{ActiveStreamGuard, McpRequestMetrics};
use self::stages::{
enforce_traced_rate_limit, require_traced_approval_access, require_traced_machine_access,
};
pub(super) use self::tool_resolution::{resolve_generated_tool, runtime_operation};
#[cfg(test)]
use invocation_history::observe_invocation_history_outcome;
pub(super) use invocation_history::{InvocationRecord, persist_invocation};
@@ -298,13 +300,13 @@ async fn readiness(State(state): State<Arc<AppState>>) -> Response {
"checks": { "postgres": "ready" }
}))
.into_response(),
Err(error) => (
Err(_) => (
StatusCode::SERVICE_UNAVAILABLE,
Json(json!({
"service": "mcp-server",
"status": "not_ready",
"checks": { "postgres": "not_ready" },
"error": error.to_string()
"error": "database is unavailable"
})),
)
.into_response(),
@@ -363,7 +365,7 @@ async fn approve_request(
payload,
PlatformApiKeyScope::Approve,
ApprovalRequestStatus::Approved,
Some(request_context.request_id),
Some(request_context.correlation),
)
.await
}
@@ -425,7 +427,7 @@ async fn decide_approval_request(
payload: ApprovalDecisionPayload,
required_scope: PlatformApiKeyScope,
status: ApprovalRequestStatus,
execution_request_id: Option<String>,
execution_correlation: Option<CorrelationContext>,
) -> Response {
let agent_path = AgentRoutePath {
workspace_slug: path.workspace_slug,
@@ -496,7 +498,7 @@ async fn decide_approval_request(
&state,
&agent_path,
claimed,
execution_request_id.as_deref(),
execution_correlation.as_ref(),
)
.await
{
@@ -719,11 +721,12 @@ async fn mcp_post(
let mut request_metrics = McpRequestMetrics::invalid();
let response = rejection.into_response();
request_metrics.complete(&response);
return with_request_id_header(response, &request_context.request_id);
return with_request_id_header(response, request_context.request_id());
}
};
let mut request_metrics = McpRequestMetrics::new(&message);
let transport_request_id = request_context.request_id;
let transport_correlation = request_context.correlation;
let transport_request_id = transport_correlation.request_id().to_string();
info!(
name: "mcp.request.received",
request_id = %transport_request_id,
@@ -733,7 +736,8 @@ async fn mcp_post(
"mcp request received"
);
let response = mcp_post_response(&path, state, &headers, &message, &transport_request_id).await;
let response =
mcp_post_response(&path, state, &headers, &message, &transport_correlation).await;
request_metrics.complete(&response);
with_request_id_header(response, &transport_request_id)
}
@@ -743,7 +747,7 @@ async fn mcp_post_response(
state: Arc<AppState>,
headers: &HeaderMap,
message: &Value,
transport_request_id: &str,
transport_correlation: &CorrelationContext,
) -> Response {
if let Err(status) = validate_origin(&state.allowed_origins, headers) {
return status.into_response();
@@ -851,10 +855,10 @@ async fn mcp_post_response(
};
let tool_call_params: ToolCallParams = match serde_json::from_value(params(message)) {
Ok(value) => value,
Err(error) => {
Err(_) => {
return transport_response(
StatusCode::OK,
jsonrpc_error(request_id(message), -32602, error.to_string()),
jsonrpc_error(request_id(message), -32602, "invalid tool call parameters"),
response_mode,
None,
Some(&session.protocol_version),
@@ -883,7 +887,7 @@ async fn mcp_post_response(
&catalog,
&tool_call_params.name,
arguments,
transport_request_id,
transport_correlation,
)
.await
}
@@ -925,8 +929,9 @@ pub(super) async fn handle_tool_call(
resolved: ResolvedToolCall,
arguments: Value,
confirmation_token: Option<String>,
transport_request_id: &str,
transport_correlation: &CorrelationContext,
) -> Response {
let transport_request_id = transport_correlation.request_id().as_str();
if !credential_allows_security_level(credential, resolved.tool.operation.security_level) {
return tool_error_response(
message,
@@ -940,6 +945,7 @@ pub(super) async fn handle_tool_call(
serialize_security_level(resolved.tool.operation.security_level),
),
transport_request_id,
transport_correlation.trace_id().as_str(),
false,
Some("Используйте ключ агента с достаточным уровнем доступа."),
),
@@ -956,7 +962,7 @@ pub(super) async fn handle_tool_call(
arguments,
confirmation_token,
},
transport_request_id,
transport_correlation,
)
.await
}
@@ -1076,8 +1082,9 @@ async fn handle_base_tool_call(
message: &Value,
response_mode: ResponseMode,
execution: ToolCallExecution,
transport_request_id: &str,
transport_correlation: &CorrelationContext,
) -> Response {
let transport_request_id = transport_correlation.request_id().as_str();
let tool = execution.tool;
let arguments = execution.arguments;
let operation = runtime_operation(&tool);
@@ -1096,7 +1103,7 @@ async fn handle_base_tool_call(
response_mode,
&tool,
&arguments,
transport_request_id,
transport_correlation,
)
.instrument(approval_span.clone())
.await;
@@ -1116,16 +1123,17 @@ async fn handle_base_tool_call(
StageOutcome::Allowed.record(&approval_span);
}
let mut runtime_request_context = RuntimeRequestContext::from_request_id(transport_request_id)
.with_response_cache_scope(
tool.workspace_id.as_str().to_owned(),
tool.agent_id.as_str().to_owned(),
)
.with_metering_context(
tool.workspace_id.clone(),
Some(tool.agent_id.clone()),
InvocationSource::AgentToolCall,
);
let mut runtime_request_context =
RuntimeRequestContext::from_correlation(transport_correlation)
.with_response_cache_scope(
tool.workspace_id.as_str().to_owned(),
tool.agent_id.as_str().to_owned(),
)
.with_metering_context(
tool.workspace_id.clone(),
Some(tool.agent_id.clone()),
InvocationSource::AgentToolCall,
);
if let Some(token) = execution.confirmation_token {
runtime_request_context = runtime_request_context.with_confirmation_token(token);
}
@@ -1155,6 +1163,7 @@ async fn handle_base_tool_call(
&tool,
InvocationRecord {
request_id: Some(transport_request_id),
trace_id: Some(transport_correlation.trace_id().as_str()),
tool_name: &tool.tool_name,
status: InvocationStatus::Ok,
level: InvocationLevel::Info,
@@ -1176,10 +1185,11 @@ async fn handle_base_tool_call(
&tool,
InvocationRecord {
request_id: Some(transport_request_id),
trace_id: Some(transport_correlation.trace_id().as_str()),
tool_name: &tool.tool_name,
status: InvocationStatus::Error,
level: InvocationLevel::Error,
message: &error.to_string(),
message: runtime_error_code(&error),
status_code: None,
error_kind: Some(runtime_error_code(&error)),
duration: started_at.elapsed(),
@@ -1193,7 +1203,11 @@ async fn handle_base_tool_call(
message,
response_mode,
&session.protocol_version,
tool_error_contract_from_runtime(&error, transport_request_id),
tool_error_contract_from_runtime(
&error,
transport_request_id,
transport_correlation.trace_id().as_str(),
),
)
}
}
@@ -1211,7 +1225,7 @@ async fn maybe_handle_approval_policy(
response_mode: ResponseMode,
tool: &PublishedAgentTool,
arguments: &Value,
transport_request_id: &str,
transport_correlation: &CorrelationContext,
) -> Option<ApprovalPolicyResult> {
let policy = tool.operation.execution_config.approval_policy.as_ref()?;
if !policy.required {
@@ -1227,7 +1241,7 @@ async fn maybe_handle_approval_policy(
response_mode,
tool,
arguments,
transport_request_id,
transport_correlation,
)
.await
}
@@ -1238,7 +1252,7 @@ async fn maybe_handle_approval_policy(
tool,
arguments,
policy.elicitation_message.as_deref(),
transport_request_id,
transport_correlation,
)),
}
}
@@ -1250,8 +1264,9 @@ async fn maybe_create_custom_pending_approval(
response_mode: ResponseMode,
tool: &PublishedAgentTool,
arguments: &Value,
transport_request_id: &str,
transport_correlation: &CorrelationContext,
) -> Option<ApprovalPolicyResult> {
let transport_request_id = transport_correlation.request_id().as_str();
let policy = tool.operation.execution_config.approval_policy.as_ref()?;
let approval_id = ApprovalRequestId::new(format!("approval_{}", uuid::Uuid::now_v7().simple()));
@@ -1298,6 +1313,7 @@ async fn maybe_create_custom_pending_approval(
tool,
InvocationRecord {
request_id: Some(transport_request_id),
trace_id: Some(transport_correlation.trace_id().as_str()),
tool_name: &tool.tool_name,
status: InvocationStatus::Ok,
level: InvocationLevel::Info,
@@ -1326,8 +1342,9 @@ fn handle_elicitation_approval(
tool: &PublishedAgentTool,
arguments: &Value,
elicitation_message: Option<&str>,
transport_request_id: &str,
transport_correlation: &CorrelationContext,
) -> ApprovalPolicyResult {
let transport_request_id = transport_correlation.request_id().as_str();
if !session.supports_elicitation {
return ApprovalPolicyResult::Error(tool_error_response(
message,
@@ -1337,6 +1354,7 @@ fn handle_elicitation_approval(
"approval_elicitation_not_supported",
"operation requires MCP Elicitation, but the MCP client did not advertise elicitation capability",
transport_request_id,
transport_correlation.trace_id().as_str(),
false,
Some(
"Выберите Custom MCP Approval или подключите MCP-клиент с поддержкой elicitation.",
@@ -1375,10 +1393,10 @@ async fn handle_initialize(
) -> Response {
let initialize_params: InitializeParams = match serde_json::from_value(params(message)) {
Ok(value) => value,
Err(error) => {
Err(_error) => {
return transport_response(
StatusCode::OK,
jsonrpc_error(request_id(message), -32602, error.to_string()),
jsonrpc_error(request_id(message), -32602, "invalid initialize parameters"),
response_mode,
None,
Some(DEFAULT_PROTOCOL_VERSION),
@@ -1513,10 +1531,10 @@ async fn require_initialized_session(
Ok(session)
}
fn internal_jsonrpc_error(message: &Value, error: impl std::fmt::Display) -> Response {
fn internal_jsonrpc_error(message: &Value, _error: impl std::fmt::Display) -> Response {
transport_response(
StatusCode::INTERNAL_SERVER_ERROR,
jsonrpc_error(request_id(message), -32603, error.to_string()),
jsonrpc_error(request_id(message), -32603, "internal server error"),
ResponseMode::Json,
None,
Some(DEFAULT_PROTOCOL_VERSION),
@@ -1614,26 +1632,5 @@ fn add_millis(timestamp: OffsetDateTime, millis: u64) -> OffsetDateTime {
timestamp + delta
}
pub(super) fn resolve_generated_tool(
tools: &[PublishedAgentTool],
tool_name: &str,
) -> Option<ResolvedToolCall> {
for tool in tools {
if tool.tool_name == tool_name {
return Some(ResolvedToolCall { tool: tool.clone() });
}
}
None
}
pub(super) fn runtime_operation(tool: &PublishedAgentTool) -> RuntimeOperation {
let mut operation = RuntimeOperation::from(tool.operation.clone());
operation.tool_name = tool.tool_name.clone();
operation.tool_description.title = tool.tool_title.clone();
operation.tool_description.description = tool.tool_description.clone();
operation
}
#[cfg(test)]
mod tests;
crates/crank-community-mcp/src/app/invocation_history.rs
+5
View File
@@ -15,6 +15,7 @@ use super::AppState;
pub(crate) struct InvocationRecord<'a> {
pub(crate) request_id: Option<&'a str>,
pub(crate) trace_id: Option<&'a str>,
pub(crate) tool_name: &'a str,
pub(crate) status: InvocationStatus,
pub(crate) level: InvocationLevel,
@@ -42,6 +43,7 @@ pub(crate) async fn persist_invocation(
tool_name: record.tool_name.to_owned(),
message: record.message.to_owned(),
request_id: record.request_id.map(ToOwned::to_owned),
trace_id: record.trace_id.map(ToOwned::to_owned),
status_code: record.status_code,
duration_ms: u64::try_from(record.duration.as_millis()).unwrap_or(u64::MAX),
error_kind: record.error_kind.map(ToOwned::to_owned),
@@ -79,6 +81,7 @@ pub(crate) async fn persist_invocation(
observe_invocation_history_outcome(
outcome,
record.request_id,
record.trace_id,
record.status,
InvocationSource::AgentToolCall,
);
@@ -88,6 +91,7 @@ pub(crate) async fn persist_invocation(
pub(super) fn observe_invocation_history_outcome(
outcome: InvocationHistoryWriteOutcome,
request_id: Option<&str>,
trace_id: Option<&str>,
status: InvocationStatus,
source: InvocationSource,
) {
@@ -100,6 +104,7 @@ pub(super) fn observe_invocation_history_outcome(
warn!(
name: "mcp.invocation_history.lost",
request_id = request_id.unwrap_or_default(),
trace_id = trace_id.unwrap_or_default(),
source = invocation_source_label(source),
invocation_status = invocation_status_label(status),
error_category = loss.category.as_str(),
crates/crank-community-mcp/src/app/tests.rs
+3
View File
@@ -37,6 +37,7 @@ async fn tool_error_response_includes_structured_context() {
"streaming_payload_error",
"request root must be an object",
"req-1",
"0af7651916cd43dd8448eb211c80319c",
false,
Some("Проверьте параметры вызова инструмента."),
),
@@ -59,6 +60,7 @@ async fn tool_error_response_includes_structured_context() {
"message": "request root must be an object",
"recoverable": false,
"request_id": "req-1",
"trace_id": "0af7651916cd43dd8448eb211c80319c",
"suggested_action": "Проверьте параметры вызова инструмента."
})
);
@@ -146,6 +148,7 @@ fn emits_bounded_history_loss_incident() {
category: InvocationHistoryLossCategory::Unavailable,
}),
Some("req_mcp_dc08"),
Some("0af7651916cd43dd8448eb211c80319c"),
InvocationStatus::Ok,
crank_core::InvocationSource::AgentToolCall,
);
crates/crank-community-mcp/src/app/tool_resolution.rs
+23
View File
@@ -0,0 +1,23 @@
use crank_registry::PublishedAgentTool;
use crank_runtime::RuntimeOperation;
use super::ResolvedToolCall;
pub(crate) fn resolve_generated_tool(
tools: &[PublishedAgentTool],
tool_name: &str,
) -> Option<ResolvedToolCall> {
tools
.iter()
.find(|tool| tool.tool_name == tool_name)
.cloned()
.map(|tool| ResolvedToolCall { tool })
}
pub(crate) fn runtime_operation(tool: &PublishedAgentTool) -> RuntimeOperation {
let mut operation = RuntimeOperation::from(tool.operation.clone());
operation.tool_name = tool.tool_name.clone();
operation.tool_description.title = tool.tool_title.clone();
operation.tool_description.description = tool.tool_description.clone();
operation
}
crates/crank-community-mcp/src/approval_execution.rs
+15 -8
View File
@@ -5,7 +5,7 @@ use axum::{
response::{IntoResponse, Response},
};
use crank_core::{ApprovalRequestStatus, InvocationLevel, InvocationSource, InvocationStatus};
use crank_observability::RequestId;
use crank_core::{CorrelationContext, RequestId, TraceContext};
use crank_registry::{ApprovalRequestRecord, FinishApprovalRequest};
use crank_runtime::{RuntimeExecutionRequest, RuntimeRequestContext};
use crank_trace::{DbOperation, ErrorCategory, Stage, StageOutcome, observe_db_query};
@@ -18,7 +18,7 @@ use crate::{
AgentRoutePath, AppState, InvocationRecord, build_request_preview, persist_invocation,
resolve_operation_auth, runtime_operation,
},
tool_error::runtime_error_code,
tool_error::{runtime_error_code, safe_runtime_error_message},
};
const RECOVERY_INTERVAL: std::time::Duration = std::time::Duration::from_secs(5);
@@ -64,7 +64,10 @@ async fn recover_approved_requests(state: &Arc<AppState>) {
continue;
};
let recovery_span = Stage::ApprovalRecovery.span();
let result = execute_approved_request(state, &path, approval, None)
let trace_context = crank_trace::trace_context_for_span(&recovery_span)
.unwrap_or_else(TraceContext::generate);
let correlation = CorrelationContext::new(RequestId::generate(), trace_context);
let result = execute_approved_request(state, &path, approval, Some(&correlation))
.instrument(recovery_span.clone())
.await;
match &result {
@@ -162,9 +165,12 @@ pub(super) async fn execute_approved_request(
state: &Arc<AppState>,
path: &AgentRoutePath,
approval: ApprovalRequestRecord,
request_id: Option<&str>,
correlation: Option<&CorrelationContext>,
) -> Result<ApprovalRequestRecord, Response> {
let request_id = RequestId::resolve(request_id).into_string();
let correlation = correlation
.cloned()
.unwrap_or_else(CorrelationContext::generate);
let request_id = correlation.request_id().as_str();
let tools = state
.catalog
.list_tools(&path.workspace_slug, &path.agent_slug)
@@ -184,7 +190,7 @@ pub(super) async fn execute_approved_request(
&approval.approval.request_payload,
);
let started_at = Instant::now();
let runtime_request_context = RuntimeRequestContext::from_request_id(request_id.clone())
let runtime_request_context = RuntimeRequestContext::from_correlation(&correlation)
.with_response_cache_scope(
tool.workspace_id.as_str().to_owned(),
tool.agent_id.as_str().to_owned(),
@@ -226,7 +232,7 @@ pub(super) async fn execute_approved_request(
json!({
"error": {
"code": runtime_error_code(&error),
"message": error.to_string(),
"message": safe_runtime_error_message(&error),
}
}),
InvocationStatus::Error,
@@ -240,7 +246,8 @@ pub(super) async fn execute_approved_request(
state,
&tool,
InvocationRecord {
request_id: Some(&request_id),
request_id: Some(request_id),
trace_id: Some(correlation.trace_id().as_str()),
tool_name: &tool.tool_name,
status: invocation_status,
level: invocation_level,
crates/crank-community-mcp/src/jsonrpc.rs
+23 -4
View File
@@ -45,16 +45,35 @@ pub fn jsonrpc_result(id: Value, result: Value) -> Value {
}
pub fn jsonrpc_error(id: Value, code: i64, message: impl Into<String>) -> Value {
let mut error = json!({
"code": code,
"message": message.into()
});
let (request_id, trace_id) = crank_observability::current_request_correlation();
if request_id.is_some() && trace_id.is_some() {
error["data"] = correlated_error_data(json!({}));
}
json!({
"jsonrpc": "2.0",
"id": id,
"error": {
"code": code,
"message": message.into()
}
"error": error
})
}
pub fn correlated_error_data(mut data: Value) -> Value {
if !data.is_object() {
data = json!({});
}
let (request_id, trace_id) = crank_observability::current_request_correlation();
if let Some(request_id) = request_id {
data["request_id"] = Value::String(request_id);
}
if let Some(trace_id) = trace_id {
data["trace_id"] = Value::String(trace_id);
}
data
}
pub fn negotiated_protocol_version(requested: &str) -> Option<&'static str> {
SUPPORTED_PROTOCOL_VERSIONS
.iter()
crates/crank-community-mcp/src/rate_limit.rs
+4 -4
View File
@@ -11,7 +11,7 @@ use serde_json::{Value, json};
use crate::{
access::{bearer_token, hash_access_secret},
app::{AgentRoutePath, AppState},
jsonrpc::request_id,
jsonrpc::{correlated_error_data, request_id},
transport::{ResponseMode, session_id_from_headers, transport_response},
};
@@ -39,7 +39,7 @@ pub(super) fn rate_limited_jsonrpc_response(
"error": {
"code": -32603,
"message": "rate limit service unavailable",
"data": { "code": "rate_limit_unavailable" }
"data": correlated_error_data(json!({ "code": "rate_limit_unavailable" }))
}
}),
response_mode,
@@ -53,10 +53,10 @@ pub(super) fn rate_limited_jsonrpc_response(
"error": {
"code": -32029,
"message": "request rate limit exceeded",
"data": {
"data": correlated_error_data(json!({
"code": "request_rate_limited",
"retry_after_ms": rejection.retry_after_ms,
}
}))
}
});
crates/crank-community-mcp/src/request_context.rs
+83 -15
View File
@@ -1,33 +1,101 @@
use axum::{extract::Request, http::HeaderValue, middleware::Next, response::Response};
use crank_observability::{RequestId, set_remote_trace_parent, with_request_correlation};
use crank_core::{CorrelationContext, RequestId, TraceContext};
use crank_observability::{set_remote_trace_parent, with_request_correlation};
use tracing::{Instrument, info_span};
use crate::transport::HEADER_X_REQUEST_ID;
const HEADER_X_TRACE_ID: axum::http::HeaderName = axum::http::HeaderName::from_static("x-trace-id");
#[derive(Clone, Debug)]
pub(super) struct RequestContext {
pub(super) request_id: String,
pub(super) correlation: CorrelationContext,
}
impl RequestContext {
pub(super) fn request_id(&self) -> &str {
self.correlation.request_id().as_str()
}
}
pub(super) async fn apply_request_context(mut request: Request, next: Next) -> Response {
let request_id = RequestId::resolve_from_headers(request.headers()).into_string();
let context = RequestContext {
request_id: request_id.clone(),
};
let (request_id, remote_parent) = resolve_correlation(request.headers());
let span = info_span!(
target: "crank::trace",
"mcp.request",
request_id = %request_id,
trace_id = tracing::field::Empty,
);
set_remote_trace_parent(&span, request.headers());
request.extensions_mut().insert(context);
if let Some(remote_parent) = remote_parent.as_ref() {
set_canonical_parent(&span, remote_parent);
}
let trace_context = crank_trace::trace_context_for_span(&span).unwrap_or_else(|| {
remote_parent
.as_ref()
.map_or_else(TraceContext::generate, TraceContext::continue_local)
});
span.record("trace_id", trace_context.trace_id().as_str());
let context = RequestContext {
correlation: CorrelationContext::new(request_id, trace_context),
};
request.extensions_mut().insert(context.clone());
with_request_correlation(request_id.clone(), async move {
let mut response = next.run(request).instrument(span).await;
if let Ok(value) = HeaderValue::from_str(&request_id) {
response.headers_mut().insert(HEADER_X_REQUEST_ID, value);
}
response
})
with_request_correlation(
context.correlation.request_id().to_string(),
context.correlation.trace_id().to_string(),
async move {
let mut response = next.run(request).instrument(span).await;
if let Ok(value) = HeaderValue::from_str(context.correlation.request_id().as_str()) {
response.headers_mut().insert(HEADER_X_REQUEST_ID, value);
}
if let Ok(value) = HeaderValue::from_str(context.correlation.trace_id().as_str()) {
response.headers_mut().insert(HEADER_X_TRACE_ID, value);
}
response
},
)
.await
}
fn resolve_correlation(headers: &axum::http::HeaderMap) -> (RequestId, Option<TraceContext>) {
let _tracestate_accepted = one_auxiliary_header_within_budget(
headers,
"tracestate",
TraceContext::tracestate_within_budget,
);
let _baggage_accepted =
one_auxiliary_header_within_budget(headers, "baggage", TraceContext::baggage_within_budget);
let mut request_ids = headers.get_all(HEADER_X_REQUEST_ID).iter();
let request_id = request_ids.next().and_then(|value| value.to_str().ok());
let request_id = if request_ids.next().is_some() {
RequestId::generate()
} else {
RequestId::resolve(request_id)
};
let mut traceparents = headers.get_all("traceparent").iter();
let traceparent = traceparents.next().and_then(|value| value.to_str().ok());
let remote_parent = if traceparents.next().is_some() {
None
} else {
traceparent.and_then(|value| TraceContext::parse(value).ok())
};
(request_id, remote_parent)
}
fn one_auxiliary_header_within_budget(
headers: &axum::http::HeaderMap,
name: &'static str,
validate: fn(&str) -> bool,
) -> bool {
let mut values = headers.get_all(name).iter();
let value = values.next().and_then(|value| value.to_str().ok());
values.next().is_none() && value.is_some_and(validate)
}
fn set_canonical_parent(span: &tracing::Span, context: &TraceContext) {
let mut headers = axum::http::HeaderMap::new();
if let Ok(value) = HeaderValue::from_str(context.traceparent()) {
headers.insert("traceparent", value);
set_remote_trace_parent(span, &headers);
}
}
crates/crank-community-mcp/src/session.rs
+5 -119
View File
@@ -130,7 +130,11 @@ pub struct PostgresTransportSessionStore {
impl PostgresTransportSessionStore {
pub async fn from_pool(pool: PgPool) -> Result<Self, SessionStoreError> {
apply_postgres_migrations(&pool).await?;
crank_registry::MigrationAuthority::require_current(&pool)
.await
.map_err(|error| SessionStoreError {
details: error.to_string(),
})?;
Ok(Self { pool })
}
@@ -413,124 +417,6 @@ impl TransportSessionStore for PostgresTransportSessionStore {
}
}
async fn apply_postgres_migrations(pool: &PgPool) -> Result<(), SessionStoreError> {
let mut transaction = pool.begin().await.map_err(|error| SessionStoreError {
details: error.to_string(),
})?;
query("select pg_advisory_xact_lock($1)")
.bind(0x4352_414E_4B4D_4350_i64)
.execute(&mut *transaction)
.await
.map_err(|error| SessionStoreError {
details: error.to_string(),
})?;
query(
"create table if not exists __crank_mcp_migrations (
version integer primary key,
checksum text not null,
applied_at timestamptz not null default now()
)",
)
.execute(&mut *transaction)
.await
.map_err(|error| SessionStoreError {
details: error.to_string(),
})?;
let applied = query("select checksum from __crank_mcp_migrations where version = 1")
.fetch_optional(&mut *transaction)
.await
.map_err(|error| SessionStoreError {
details: error.to_string(),
})?;
if let Some(row) = applied {
let checksum = row.get::<String, _>("checksum");
if checksum != "mcp-transport-sessions-v1" {
return Err(SessionStoreError {
details: format!("modified MCP migration version 1: {checksum}"),
});
}
transaction
.commit()
.await
.map_err(|error| SessionStoreError {
details: error.to_string(),
})?;
return Ok(());
}
query(
"create table if not exists mcp_transport_sessions (
id text primary key,
protocol_version text not null,
initialized boolean not null default false,
supports_elicitation boolean not null default false,
workspace_slug text not null,
agent_slug text not null,
created_at timestamptz not null,
updated_at timestamptz not null,
expires_at timestamptz null
)",
)
.execute(&mut *transaction)
.await
.map_err(|error| SessionStoreError {
details: error.to_string(),
})?;
query("alter table mcp_transport_sessions add column if not exists supports_elicitation boolean not null default false")
.execute(&mut *transaction)
.await
.map_err(|error| SessionStoreError {
details: error.to_string(),
})?;
query(
"alter table mcp_transport_sessions add column if not exists expires_at timestamptz null",
)
.execute(&mut *transaction)
.await
.map_err(|error| SessionStoreError {
details: error.to_string(),
})?;
query(
"create index if not exists mcp_transport_sessions_workspace_agent_idx
on mcp_transport_sessions(workspace_slug, agent_slug, updated_at desc)",
)
.execute(&mut *transaction)
.await
.map_err(|error| SessionStoreError {
details: error.to_string(),
})?;
query(
"create index if not exists mcp_transport_sessions_expires_at_idx
on mcp_transport_sessions(expires_at)
where expires_at is not null",
)
.execute(&mut *transaction)
.await
.map_err(|error| SessionStoreError {
details: error.to_string(),
})?;
query("insert into __crank_mcp_migrations (version, checksum) values (1, $1)")
.bind("mcp-transport-sessions-v1")
.execute(&mut *transaction)
.await
.map_err(|error| SessionStoreError {
details: error.to_string(),
})?;
transaction
.commit()
.await
.map_err(|error| SessionStoreError {
details: error.to_string(),
})?;
Ok(())
}
fn is_expired(session: &SessionState, now: OffsetDateTime) -> bool {
session
.expires_at
crates/crank-community-mcp/src/tool_error.rs
+8 -2
View File
@@ -14,11 +14,13 @@ pub struct ToolErrorContract {
#[serde(skip_serializing_if = "Option::is_none")]
pub upstream_status: Option<u16>,
pub request_id: String,
pub trace_id: String,
}
pub fn tool_error_contract_from_runtime(
error: &RuntimeError,
request_id: &str,
trace_id: &str,
) -> ToolErrorContract {
let error_code = runtime_error_code(error);
ToolErrorContract {
@@ -29,6 +31,7 @@ pub fn tool_error_contract_from_runtime(
suggested_action: suggested_action(error),
upstream_status: upstream_status(error),
request_id: request_id.to_owned(),
trace_id: trace_id.to_owned(),
}
}
@@ -36,6 +39,7 @@ pub fn generic_tool_error_contract(
error_code: &'static str,
message: impl Into<String>,
request_id: &str,
trace_id: &str,
recoverable: bool,
suggested_action: Option<&'static str>,
) -> ToolErrorContract {
@@ -47,6 +51,7 @@ pub fn generic_tool_error_contract(
suggested_action,
upstream_status: None,
request_id: request_id.to_owned(),
trace_id: trace_id.to_owned(),
}
}
@@ -64,7 +69,8 @@ pub fn tool_error_value(error: &ToolErrorContract) -> Value {
"error_code": "runtime_error",
"message": "Не удалось выполнить инструмент.",
"recoverable": false,
"request_id": error.request_id
"request_id": error.request_id,
"trace_id": error.trace_id
})
})
}
@@ -109,7 +115,7 @@ fn upstream_status_code(status: u16) -> &'static str {
}
}
fn safe_runtime_error_message(error: &RuntimeError) -> String {
pub(crate) fn safe_runtime_error_message(error: &RuntimeError) -> String {
match error {
RuntimeError::Schema(_) => "Входные параметры не прошли проверку схемы.".to_owned(),
RuntimeError::Mapping(_) => {
crates/crank-community-mcp/src/tool_search.rs
+8 -6
View File
@@ -1,7 +1,7 @@
use std::{collections::BTreeSet, sync::Arc};
use axum::{http::StatusCode, response::Response};
use crank_core::{ToolAccessMode, search_tool_catalog};
use crank_core::{CorrelationContext, ToolAccessMode, search_tool_catalog};
use crank_registry::PublishedAgentCatalog;
use crank_trace::{ErrorCategory, Stage, StageOutcome};
use serde::Deserialize;
@@ -46,8 +46,9 @@ pub(super) async fn handle_catalog_tool_call(
catalog: &PublishedAgentCatalog,
tool_name: &str,
arguments: Value,
transport_request_id: &str,
transport_correlation: &CorrelationContext,
) -> Response {
let transport_request_id = transport_correlation.request_id().as_str();
match catalog.tool_selection_policy.mode {
ToolAccessMode::Direct => {
execute_catalog_tool(
@@ -59,7 +60,7 @@ pub(super) async fn handle_catalog_tool_call(
catalog,
tool_name,
arguments,
transport_request_id,
transport_correlation,
)
.await
}
@@ -90,6 +91,7 @@ pub(super) async fn handle_catalog_tool_call(
proxy.catalog_revision
),
transport_request_id,
transport_correlation.trace_id().as_str(),
true,
Some(
"Повторите search_tools и вызовите инструмент с новой версией каталога.",
@@ -106,7 +108,7 @@ pub(super) async fn handle_catalog_tool_call(
catalog,
&proxy.name,
proxy.arguments,
transport_request_id,
transport_correlation,
)
.await
}
@@ -126,7 +128,7 @@ async fn execute_catalog_tool(
catalog: &PublishedAgentCatalog,
tool_name: &str,
mut arguments: Value,
transport_request_id: &str,
transport_correlation: &CorrelationContext,
) -> Response {
let resolve_span = Stage::McpToolsResolve.span();
let resolved = resolve_span.in_scope(|| resolve_generated_tool(&catalog.tools, tool_name));
@@ -158,7 +160,7 @@ async fn execute_catalog_tool(
resolved,
arguments,
confirmation_token,
transport_request_id,
transport_correlation,
)
.await
}
crates/crank-community-mcp/tests/integration/session.rs
+9 -1
View File
@@ -1,5 +1,5 @@
use crank_community_mcp::session::{PostgresTransportSessionStore, TransportSessionStore};
use crank_registry::PostgresPoolConfig;
use crank_registry::{MigrationAuthority, PostgresPoolConfig};
use sqlx::postgres::{PgConnectOptions, PgPoolOptions};
use time::{OffsetDateTime, format_description::well_known::Rfc3339};
@@ -13,9 +13,15 @@ fn truncate_to_micros(value: OffsetDateTime) -> OffsetDateTime {
.unwrap()
}
async fn migrate(database_url: &str) {
let pool = sqlx::PgPool::connect(database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
}
#[tokio::test]
async fn postgres_transport_sessions_survive_store_reconnect() {
let database_url = crank_test_support::postgres_schema_url("test_mcp_transport").await;
migrate(&database_url).await;
let connect_options = database_url.parse::<PgConnectOptions>().unwrap();
let pool_config = PostgresPoolConfig::default();
let store_a = PostgresTransportSessionStore::connect_with_options_and_pool_config(
@@ -61,6 +67,7 @@ async fn postgres_transport_sessions_survive_store_reconnect() {
#[tokio::test]
async fn postgres_transport_sessions_evict_expired_rows_on_read() {
let database_url = crank_test_support::postgres_schema_url("test_mcp_transport").await;
migrate(&database_url).await;
let connect_options = database_url.parse::<PgConnectOptions>().unwrap();
let store = PostgresTransportSessionStore::connect_with_options_and_pool_config(
connect_options.clone(),
@@ -101,6 +108,7 @@ async fn postgres_transport_sessions_evict_expired_rows_on_read() {
#[tokio::test]
async fn postgres_transport_session_cleanup_removes_abandoned_expired_rows() {
let database_url = crank_test_support::postgres_schema_url("test_mcp_cleanup").await;
migrate(&database_url).await;
let store = PostgresTransportSessionStore::connect_with_options_and_pool_config(
database_url.parse::<PgConnectOptions>().unwrap(),
PostgresPoolConfig::default(),
crates/crank-community-mcp/tests/unit/tool_error.rs
+4
View File
@@ -14,12 +14,14 @@ fn maps_upstream_429_to_recoverable_structured_tool_error() {
}),
}),
"req-429",
"0af7651916cd43dd8448eb211c80319c",
);
assert_eq!(contract.error_code, "upstream_rate_limited");
assert!(contract.recoverable);
assert_eq!(contract.upstream_status, Some(429));
assert_eq!(contract.request_id, "req-429");
assert_eq!(contract.trace_id, "0af7651916cd43dd8448eb211c80319c");
assert_eq!(contract.suggested_action, Some("Повторите запрос позже."));
assert!(!contract.message.contains("internal_trace"));
}
@@ -32,12 +34,14 @@ fn maps_mapping_error_to_non_recoverable_structured_tool_error() {
reason: "expected string".to_owned(),
},
"req-map",
"0af7651916cd43dd8448eb211c80319c",
);
assert_eq!(contract.error_code, "runtime_error");
assert!(!contract.recoverable);
assert_eq!(contract.upstream_status, None);
assert_eq!(contract.request_id, "req-map");
assert_eq!(contract.trace_id, "0af7651916cd43dd8448eb211c80319c");
assert_eq!(
contract.suggested_action,
Some("Проверьте параметры вызова инструмента.")
crates/crank-config/Cargo.toml
+13
View File
@@ -0,0 +1,13 @@
[package]
name = "crank-config"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
publish.workspace = true
[dependencies]
serde.workspace = true
serde_json.workspace = true
sha2.workspace = true
url.workspace = true
crates/crank-config/src/bin/crank-config-contract.rs
+73
View File
@@ -0,0 +1,73 @@
use std::{env, fs, path::Path};
use crank_config::render::{
BEGIN_MARKER, DOC_BEGIN_MARKER, DOC_END_MARKER, END_MARKER, env_section, reference_section,
replace_marked, schema_json,
};
fn main() {
if let Err(error) = run() {
eprintln!("config contract check failed: {error}");
std::process::exit(1);
}
}
fn run() -> Result<(), String> {
let mode = env::args().nth(1).unwrap_or_else(|| "--check".to_owned());
if !matches!(mode.as_str(), "--check" | "--write") {
return Err("expected --check or --write".to_owned());
}
let write = mode == "--write";
sync_file(
Path::new("docs/schemas/runtime-config.schema.json"),
schema_json(),
write,
)?;
for (path, production) in [
(".env.example", false),
("deploy/community/.env.example", true),
("deploy/community/.env.images.example", true),
] {
sync_marked(
Path::new(path),
BEGIN_MARKER,
END_MARKER,
&env_section(production),
write,
)?;
}
sync_marked(
Path::new("docs/runtime-config.md"),
DOC_BEGIN_MARKER,
DOC_END_MARKER,
&reference_section(),
write,
)?;
Ok(())
}
fn sync_marked(
path: &Path,
begin: &str,
end: &str,
replacement: &str,
write: bool,
) -> Result<(), String> {
let current =
fs::read_to_string(path).map_err(|_| format!("cannot read {}", path.display()))?;
let expected = replace_marked(&current, begin, end, replacement)
.ok_or_else(|| format!("missing generated markers in {}", path.display()))?;
sync_file(path, expected, write)
}
fn sync_file(path: &Path, expected: String, write: bool) -> Result<(), String> {
let current = fs::read_to_string(path).unwrap_or_default();
if current == expected {
return Ok(());
}
if write {
fs::write(path, expected).map_err(|_| format!("cannot write {}", path.display()))
} else {
Err(format!("{} is out of date", path.display()))
}
}
crates/crank-config/src/debug.rs
+120
View File
@@ -0,0 +1,120 @@
use std::fmt;
use crate::{
AdminProcessConfig, CacheSettings, DatabaseSettings, McpProcessConfig, MetricsSettings,
MigratorConfig, ObservabilitySettings, OtlpSettings, OutboundSettings, RuntimeSettings,
};
impl fmt::Debug for DatabaseSettings {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("DatabaseSettings")
.field("url", &self.url.as_ref().map(|_| "configured"))
.field("password", &self.password)
.field("pool", &self.pool)
.finish_non_exhaustive()
}
}
impl fmt::Debug for CacheSettings {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("CacheSettings")
.field("backend", &self.backend)
.field("url", &self.url.as_ref().map(|_| "configured"))
.finish()
}
}
impl fmt::Debug for OutboundSettings {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("OutboundSettings")
.field("allowed_host_count", &self.allowed_hosts.len())
.field("denied_host_count", &self.denied_hosts.len())
.field("max_response_bytes", &self.max_response_bytes)
.finish()
}
}
impl fmt::Debug for RuntimeSettings {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("RuntimeSettings")
.field("master_key", &self.master_key)
.field("base_url", &self.base_url.as_ref().map(|_| "configured"))
.field("max_concurrent_unary", &self.max_concurrent_unary)
.field("max_concurrent_sessions", &self.max_concurrent_sessions)
.field("cache", &self.cache)
.field("outbound", &self.outbound)
.finish()
}
}
impl fmt::Debug for MetricsSettings {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("MetricsSettings")
.field("enabled", &self.enabled)
.field("loopback", &self.bind_addr.ip().is_loopback())
.field(
"bearer_token",
&self.bearer_token.as_ref().map(|_| "configured"),
)
.finish()
}
}
impl fmt::Debug for OtlpSettings {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("OtlpSettings")
.field("endpoint", &self.endpoint.as_ref().map(|_| "configured"))
.field(
"traces_endpoint",
&self.traces_endpoint.as_ref().map(|_| "configured"),
)
.field("headers", &self.headers.as_ref().map(|_| "configured"))
.field(
"traces_headers",
&self.traces_headers.as_ref().map(|_| "configured"),
)
.field("max_queue_size", &self.max_queue_size)
.field("max_export_batch_size", &self.max_export_batch_size)
.finish_non_exhaustive()
}
}
impl fmt::Debug for ObservabilitySettings {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("ObservabilitySettings")
.field("environment", &"configured")
.field("log_filter", &"configured")
.field(
"sentry_dsn",
&self.sentry_dsn.as_ref().map(|_| "configured"),
)
.field("metrics", &self.metrics)
.field("otlp", &self.otlp)
.finish()
}
}
impl fmt::Debug for AdminProcessConfig {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("AdminProcessConfig")
.field("database", &self.database)
.field("runtime", &self.runtime)
.field("observability", &self.observability)
.field("storage_root", &"configured")
.field("session_secret", &self.session_secret)
.field("password_pepper", &self.password_pepper)
.field("bootstrap_password", &self.bootstrap_password)
.finish_non_exhaustive()
}
}
impl fmt::Debug for McpProcessConfig {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("McpProcessConfig")
.field("database", &self.database)
.field("runtime", &self.runtime)
.field("observability", &self.observability)
.finish_non_exhaustive()
}
}
impl fmt::Debug for MigratorConfig {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("MigratorConfig")
.field("database", &self.database)
.field("fingerprint", &self.fingerprint())
.finish()
}
}
crates/crank-config/src/diagnostic.rs
+206
View File
@@ -0,0 +1,206 @@
use std::fmt;
use serde::{Serialize, Serializer};
const MAX_DIAGNOSTICS: usize = 100;
#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub enum DiagnosticCode {
MissingRequired,
InvalidEncoding,
InvalidType,
OutOfRange,
UnknownField,
Conflict,
UnsafeCombination,
DeprecatedNoEffect,
}
impl Serialize for DiagnosticCode {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
serializer.serialize_str(self.as_str())
}
}
impl DiagnosticCode {
pub const fn as_str(self) -> &'static str {
match self {
Self::MissingRequired => "config.missing_required",
Self::InvalidEncoding => "config.invalid_encoding",
Self::InvalidType => "config.invalid_type",
Self::OutOfRange => "config.out_of_range",
Self::UnknownField => "config.unknown_field",
Self::Conflict => "config.conflict",
Self::UnsafeCombination => "config.unsafe_combination",
Self::DeprecatedNoEffect => "config.deprecated_no_effect",
}
}
}
#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize)]
pub struct Diagnostic {
pub code: DiagnosticCode,
pub field: String,
pub message_ru: &'static str,
pub message_en: &'static str,
}
impl Diagnostic {
pub(crate) fn new(code: DiagnosticCode, field: impl Into<String>) -> Self {
let (message_ru, message_en) = match code {
DiagnosticCode::MissingRequired => (
"Обязательный параметр не настроен.",
"A required configuration field is not configured.",
),
DiagnosticCode::InvalidEncoding => (
"Параметр должен быть корректной строкой UTF-8.",
"The configuration field must be valid UTF-8.",
),
DiagnosticCode::InvalidType => (
"Параметр имеет недопустимый тип или формат.",
"The configuration field has an invalid type or format.",
),
DiagnosticCode::OutOfRange => (
"Параметр находится вне допустимых границ.",
"The configuration field is outside its allowed bounds.",
),
DiagnosticCode::UnknownField => (
"Неизвестный параметр в управляемом пространстве имён.",
"Unknown field in an owned configuration namespace.",
),
DiagnosticCode::Conflict => (
"Одновременно заданы конфликтующие источники конфигурации.",
"Conflicting configuration sources are set at the same time.",
),
DiagnosticCode::UnsafeCombination => (
"Комбинация параметров небезопасна или противоречива.",
"The configuration combination is unsafe or inconsistent.",
),
DiagnosticCode::DeprecatedNoEffect => (
"Устаревший параметр не имеет поддерживаемого эффекта.",
"The deprecated field has no supported effect.",
),
};
let mut field = field.into();
if field.len() > 256 {
let mut boundary = 256;
while !field.is_char_boundary(boundary) {
boundary -= 1;
}
field.truncate(boundary);
}
Self {
code,
field,
message_ru,
message_en,
}
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ConfigError {
diagnostics: Vec<Diagnostic>,
omitted: usize,
}
impl ConfigError {
pub fn single(code: DiagnosticCode, field: impl Into<String>) -> Self {
Self::from_diagnostics(vec![Diagnostic::new(code, field)])
}
pub(crate) fn from_diagnostics(mut diagnostics: Vec<Diagnostic>) -> Self {
diagnostics.sort();
diagnostics.dedup();
let mut omitted = diagnostics.len().saturating_sub(MAX_DIAGNOSTICS);
diagnostics.truncate(MAX_DIAGNOSTICS);
while serialized_len(&diagnostics, omitted) > 65_536 && !diagnostics.is_empty() {
diagnostics.pop();
omitted += 1;
}
Self {
diagnostics,
omitted,
}
}
pub fn diagnostics(&self) -> &[Diagnostic] {
&self.diagnostics
}
pub fn omitted(&self) -> usize {
self.omitted
}
pub fn to_json(&self) -> String {
#[derive(Serialize)]
struct Report<'a> {
diagnostics: &'a [Diagnostic],
omitted: usize,
}
serde_json::to_string(&Report {
diagnostics: &self.diagnostics,
omitted: self.omitted,
})
.unwrap_or_else(|_| "{\"diagnostics\":[],\"omitted\":0}".to_owned())
}
}
fn serialized_len(diagnostics: &[Diagnostic], omitted: usize) -> usize {
#[derive(Serialize)]
struct Report<'a> {
diagnostics: &'a [Diagnostic],
omitted: usize,
}
serde_json::to_vec(&Report {
diagnostics,
omitted,
})
.map_or(usize::MAX, |value| value.len())
}
impl fmt::Display for ConfigError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
for (index, diagnostic) in self.diagnostics.iter().enumerate() {
if index > 0 {
formatter.write_str("; ")?;
}
write!(
formatter,
"{} field={} ru={} en={}",
diagnostic.code.as_str(),
diagnostic.field,
diagnostic.message_ru,
diagnostic.message_en
)?;
}
if self.omitted > 0 {
write!(formatter, "; diagnostics_omitted={}", self.omitted)?;
}
Ok(())
}
}
impl std::error::Error for ConfigError {}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn unicode_fields_and_worst_case_json_remain_bounded() {
let field = format!("{}{}", "\\\"".repeat(120), "💣".repeat(100));
let diagnostics = (0..200)
.map(|index| Diagnostic::new(DiagnosticCode::InvalidType, format!("{index}:{field}")))
.collect();
let error = ConfigError::from_diagnostics(diagnostics);
let json = error.to_json();
assert!(json.len() <= 65_536);
assert!(error.omitted() > 0);
assert!(serde_json::from_str::<serde_json::Value>(&json).is_ok());
assert!(json.contains("config.invalid_type"));
}
}
crates/crank-config/src/fingerprint.rs
+11
View File
@@ -0,0 +1,11 @@
use sha2::{Digest, Sha256};
pub(crate) fn sha256_hex(parts: impl IntoIterator<Item = String>) -> String {
let mut hasher = Sha256::new();
hasher.update(b"crank-config-fingerprint-v1\0");
for part in parts {
hasher.update(part.len().to_le_bytes());
hasher.update(part.as_bytes());
}
format!("{:x}", hasher.finalize())
}
crates/crank-config/src/lib.rs
+25
View File
@@ -0,0 +1,25 @@
//! Typed bootstrap configuration contract for Crank processes.
mod debug;
mod diagnostic;
mod fingerprint;
mod migrator;
mod process;
pub mod render;
mod schema;
mod source;
mod validation;
mod value;
pub use diagnostic::{ConfigError, Diagnostic, DiagnosticCode};
pub use migrator::{MigratorConfig, parse_migrator};
pub use process::{
AdminProcessConfig, CacheBackend, CacheSettings, DatabaseSettings, DeprecationRecord,
EffectiveConfig, McpProcessConfig, MetricsSettings, ObservabilitySettings, OtlpSettings,
OutboundSettings, PoolSettings, ProcessKind, RateLimitSettings, RuntimeSettings, parse_process,
};
pub use schema::{
FieldMode, FieldSpec, ProcessScope, Sensitivity, deployment_field_registry, field_registry,
};
pub use source::ConfigSource;
pub use value::SecretString;
crates/crank-config/src/migrator.rs
+47
View File
@@ -0,0 +1,47 @@
use crate::{
ConfigError, ConfigSource, DatabaseSettings, DeprecationRecord, fingerprint::sha256_hex,
process::parse_database_source,
};
#[derive(Clone)]
pub struct MigratorConfig {
pub database: DatabaseSettings,
fingerprint: String,
deprecations: Vec<DeprecationRecord>,
}
impl MigratorConfig {
pub fn fingerprint(&self) -> &str {
&self.fingerprint
}
pub fn deprecations(&self) -> &[DeprecationRecord] {
&self.deprecations
}
}
pub fn parse_migrator(source: ConfigSource) -> Result<MigratorConfig, ConfigError> {
let (database, deprecations) = parse_database_source(source.retain_for_migrator())?;
let fingerprint = sha256_hex([
"schema=crank-config-migrator-v1".to_owned(),
format!("url={}", database.url.is_some()),
format!("host={}", database.host.to_ascii_lowercase()),
format!("port={}", database.port),
format!("database={}", database.database),
format!("username={}", database.username),
format!("password={}", database.password.is_configured()),
format!(
"pool={}:{}:{}:{}:{}",
database.pool.max_connections,
database.pool.min_connections,
database.pool.acquire_timeout_ms,
database.pool.idle_timeout_ms,
database.pool.max_lifetime_ms
),
]);
Ok(MigratorConfig {
database,
fingerprint,
deprecations,
})
}
crates/crank-config/src/process.rs
+1000
View File
File diff suppressed because it is too large Load Diff
crates/crank-config/src/render.rs
+110
View File
@@ -0,0 +1,110 @@
use serde::Serialize;
use crate::{FieldMode, FieldSpec, Sensitivity, deployment_field_registry, field_registry};
pub const BEGIN_MARKER: &str = "# BEGIN GENERATED CRANK RUNTIME CONFIG";
pub const END_MARKER: &str = "# END GENERATED CRANK RUNTIME CONFIG";
pub const DOC_BEGIN_MARKER: &str = "<!-- BEGIN GENERATED CRANK RUNTIME CONFIG -->";
pub const DOC_END_MARKER: &str = "<!-- END GENERATED CRANK RUNTIME CONFIG -->";
#[derive(Serialize)]
struct RuntimeContract<'a> {
schema_version: u32,
generated_by: &'static str,
fields: &'a [FieldSpec],
deployment_only_fields: &'static [&'static str],
}
pub fn schema_json() -> String {
let contract = RuntimeContract {
schema_version: 1,
generated_by: "crank-config",
fields: field_registry(),
deployment_only_fields: deployment_field_registry(),
};
let mut rendered = serde_json::to_string_pretty(&contract).expect("static contract serializes");
rendered.push('\n');
rendered
}
pub fn env_section(production: bool) -> String {
let mut output = String::new();
output.push_str(BEGIN_MARKER);
output.push('\n');
for field in field_registry()
.iter()
.filter(|field| field.mode == FieldMode::Effective)
{
let value = example_value(field, production);
output.push_str(field.env_name);
output.push('=');
output.push_str(&value);
output.push('\n');
}
output.push_str(END_MARKER);
output.push('\n');
output
}
pub fn reference_section() -> String {
let mut output = String::new();
output.push_str(DOC_BEGIN_MARKER);
output.push_str("\n\n| Environment | Semantic path | Process | Type/unit | Default | Bounds | Sensitivity | Mode |\n");
output.push_str("|---|---|---|---|---|---|---|---|\n");
for field in field_registry() {
let unit = field.unit.unwrap_or("-");
let default = match (field.sensitivity, field.default, field.required) {
(Sensitivity::Secret, Some(_), _) => "configured",
(Sensitivity::Secret, None, true) => "required/blank",
(Sensitivity::Secret, None, false) => "blank",
(_, Some(default), _) => default,
(_, None, true) => "required/blank",
(_, None, false) => "blank",
};
let bounds = match (field.minimum, field.maximum) {
(Some(minimum), Some(maximum)) => format!("{minimum}..={maximum}"),
_ => "-".to_owned(),
};
output.push_str(&format!(
"| `{}` | `{}` | `{:?}` | `{}/{}` | `{}` | `{}` | `{:?}` | `{:?}` |\n",
field.env_name,
field.semantic_path,
field.process,
field.value_type,
unit,
default,
bounds,
field.sensitivity,
field.mode,
));
}
output.push('\n');
output.push_str(DOC_END_MARKER);
output.push('\n');
output
}
pub fn replace_marked(content: &str, begin: &str, end: &str, replacement: &str) -> Option<String> {
let start = content.find(begin)?;
let tail = &content[start..];
let end_offset = tail.find(end)? + end.len();
let suffix_start = start + end_offset;
let mut rendered = String::with_capacity(content.len() + replacement.len());
rendered.push_str(&content[..start]);
rendered.push_str(replacement.trim_end());
rendered.push_str(&content[suffix_start..]);
Some(rendered)
}
fn example_value(field: &FieldSpec, production: bool) -> String {
if field.sensitivity == Sensitivity::Secret {
return String::new();
}
match (field.env_name, production) {
("CRANK_ENVIRONMENT", true) => "production".to_owned(),
("CRANK_BASE_URL", _) => "http://localhost:3000".to_owned(),
("POSTGRES_HOST", true) => "postgres".to_owned(),
("CRANK_TRUST_FORWARDED_HEADERS", true) => "true".to_owned(),
_ => field.default.unwrap_or("").to_owned(),
}
}
crates/crank-config/src/schema.rs
+797
View File
@@ -0,0 +1,797 @@
use serde::Serialize;
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum ProcessScope {
Shared,
AdminApi,
McpServer,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum Sensitivity {
Public,
Internal,
Secret,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum FieldMode {
Effective,
DeprecatedNoEffect,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
pub struct FieldSpec {
pub semantic_path: &'static str,
pub env_name: &'static str,
pub process: ProcessScope,
pub value_type: &'static str,
pub unit: Option<&'static str>,
pub default: Option<&'static str>,
pub required: bool,
pub minimum: Option<u64>,
pub maximum: Option<u64>,
pub sensitivity: Sensitivity,
pub mode: FieldMode,
pub compatibility: Option<&'static str>,
pub rules: &'static [&'static str],
}
impl FieldSpec {
pub fn default_for(self, process: ProcessScope) -> Option<&'static str> {
match (self.env_name, process) {
("CRANK_BASE_URL", ProcessScope::AdminApi) => Some("http://localhost:3000"),
("CRANK_LOG_LEVEL", ProcessScope::AdminApi) => Some("admin_api=info,tower_http=info"),
("CRANK_LOG_LEVEL", ProcessScope::McpServer) => Some("mcp_server=info,tower_http=info"),
_ => self.default,
}
}
}
pub(crate) fn semantic_path_for(env_name: &str) -> &str {
field_registry()
.iter()
.find(|field| field.env_name == env_name)
.map_or(env_name, |field| field.semantic_path)
}
macro_rules! f {
($path:literal,$name:literal,$proc:ident,$type:literal,$unit:expr,$default:expr,$min:expr,$max:expr,$sensitivity:ident) => {
FieldSpec {
semantic_path: $path,
env_name: $name,
process: ProcessScope::$proc,
value_type: $type,
unit: $unit,
default: $default,
required: false,
minimum: $min,
maximum: $max,
sensitivity: Sensitivity::$sensitivity,
mode: FieldMode::Effective,
compatibility: None,
rules: &[],
}
};
}
static FIELDS: [FieldSpec; 57] = [
FieldSpec {
compatibility: Some("legacy URL form"),
rules: &[
"takes precedence over generated default-valued POSTGRES_HOST/PORT/DB/USER/PASSWORD",
"conflicts with any non-default decomposed database value",
],
..f!(
"database.url",
"CRANK_DATABASE_URL",
Shared,
"url",
None,
None,
None,
None,
Secret
)
},
f!(
"database.host",
"POSTGRES_HOST",
Shared,
"string",
None,
Some("postgres"),
None,
None,
Internal
),
f!(
"database.port",
"POSTGRES_PORT",
Shared,
"u16",
Some("port"),
Some("5432"),
Some(1),
Some(65535),
Public
),
f!(
"database.name",
"POSTGRES_DB",
Shared,
"string",
None,
Some("crank"),
None,
None,
Internal
),
f!(
"database.user",
"POSTGRES_USER",
Shared,
"string",
None,
Some("crank"),
None,
None,
Internal
),
f!(
"database.password",
"POSTGRES_PASSWORD",
Shared,
"secret",
None,
Some("configured"),
None,
None,
Secret
),
FieldSpec {
rules: &["must be >= min_connections"],
..f!(
"database.pool.max_connections",
"POSTGRES_MAX_CONNECTIONS",
Shared,
"u32",
Some("connections"),
Some("20"),
Some(1),
Some(1024),
Public
)
},
FieldSpec {
rules: &["must be <= max_connections"],
..f!(
"database.pool.min_connections",
"POSTGRES_MIN_CONNECTIONS",
Shared,
"u32",
Some("connections"),
Some("2"),
Some(0),
Some(1024),
Public
)
},
f!(
"database.pool.acquire_timeout_ms",
"POSTGRES_ACQUIRE_TIMEOUT_MS",
Shared,
"u64",
Some("milliseconds"),
Some("5000"),
Some(1),
Some(300000),
Public
),
f!(
"database.pool.idle_timeout_ms",
"POSTGRES_IDLE_TIMEOUT_MS",
Shared,
"u64",
Some("milliseconds"),
Some("600000"),
Some(1000),
Some(86400000),
Public
),
f!(
"database.pool.max_lifetime_ms",
"POSTGRES_MAX_LIFETIME_MS",
Shared,
"u64",
Some("milliseconds"),
Some("1800000"),
Some(1000),
Some(86400000),
Public
),
FieldSpec {
required: true,
..f!(
"runtime.master_key",
"CRANK_MASTER_KEY",
Shared,
"secret",
None,
None,
None,
None,
Secret
)
},
f!(
"runtime.base_url",
"CRANK_BASE_URL",
Shared,
"url",
None,
None,
None,
None,
Internal
),
f!(
"runtime.max_concurrent_unary",
"CRANK_RUNTIME_MAX_CONCURRENT_UNARY",
Shared,
"u32",
Some("requests"),
Some("64"),
Some(1),
Some(65535),
Public
),
FieldSpec {
compatibility: Some("redis value is deprecated in favor of valkey"),
rules: &["external backend requires cache.url"],
..f!(
"cache.backend",
"CRANK_CACHE_BACKEND",
Shared,
"enum",
None,
Some("memory"),
None,
None,
Public
)
},
FieldSpec {
rules: &["forbidden with memory backend"],
..f!(
"cache.url",
"CRANK_CACHE_URL",
Shared,
"url",
None,
None,
None,
None,
Secret
)
},
FieldSpec {
mode: FieldMode::DeprecatedNoEffect,
..f!(
"cache.default_ttl_ms",
"CRANK_CACHE_DEFAULT_TTL_MS",
Shared,
"u64",
Some("milliseconds"),
None,
Some(1),
Some(86400000),
Public
)
},
f!(
"outbound.allowed_hosts",
"CRANK_OUTBOUND_ALLOWED_HOSTS",
Shared,
"host_list",
None,
Some(""),
None,
None,
Internal
),
FieldSpec {
rules: &["deny entries override allow entries"],
..f!(
"outbound.denied_hosts",
"CRANK_OUTBOUND_DENIED_HOSTS",
Shared,
"host_list",
None,
Some(""),
None,
None,
Internal
)
},
f!(
"outbound.max_response_bytes",
"CRANK_OUTBOUND_MAX_RESPONSE_BYTES",
Shared,
"u64",
Some("bytes"),
Some("4194304"),
Some(1),
Some(67108864),
Public
),
f!(
"observability.environment",
"CRANK_ENVIRONMENT",
Shared,
"label",
None,
Some("development"),
None,
None,
Public
),
f!(
"observability.log_filter",
"CRANK_LOG_LEVEL",
Shared,
"string",
None,
None,
None,
None,
Public
),
f!(
"observability.sentry_dsn",
"CRANK_SENTRY_DSN",
Shared,
"url",
None,
None,
None,
None,
Secret
),
FieldSpec {
compatibility: Some("yes/no/on/off spellings are deprecated"),
..f!(
"observability.metrics.enabled",
"CRANK_METRICS_ENABLED",
Shared,
"bool",
None,
Some("true"),
None,
None,
Public
)
},
FieldSpec {
rules: &["required when an enabled metrics bind is non-loopback"],
..f!(
"observability.metrics.bearer_token",
"CRANK_METRICS_BEARER_TOKEN",
Shared,
"secret",
None,
None,
None,
None,
Secret
)
},
f!(
"observability.otlp.endpoint",
"OTEL_EXPORTER_OTLP_ENDPOINT",
Shared,
"url",
None,
None,
None,
None,
Internal
),
FieldSpec {
rules: &["overrides generic OTLP endpoint"],
..f!(
"observability.otlp.traces_endpoint",
"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
Shared,
"url",
None,
None,
None,
None,
Internal
)
},
f!(
"observability.otlp.protocol",
"OTEL_EXPORTER_OTLP_PROTOCOL",
Shared,
"enum",
None,
Some("http/protobuf"),
None,
None,
Public
),
f!(
"observability.otlp.traces_protocol",
"OTEL_EXPORTER_OTLP_TRACES_PROTOCOL",
Shared,
"enum",
None,
None,
None,
None,
Public
),
f!(
"observability.otlp.timeout",
"OTEL_EXPORTER_OTLP_TIMEOUT",
Shared,
"duration",
Some("milliseconds"),
Some("10000"),
Some(1),
Some(300000),
Public
),
f!(
"observability.otlp.traces_timeout",
"OTEL_EXPORTER_OTLP_TRACES_TIMEOUT",
Shared,
"duration",
Some("milliseconds"),
None,
Some(1),
Some(300000),
Public
),
f!(
"observability.otlp.headers",
"OTEL_EXPORTER_OTLP_HEADERS",
Shared,
"headers",
None,
None,
None,
None,
Secret
),
f!(
"observability.otlp.traces_headers",
"OTEL_EXPORTER_OTLP_TRACES_HEADERS",
Shared,
"headers",
None,
None,
None,
None,
Secret
),
f!(
"observability.otlp.max_queue_size",
"OTEL_BSP_MAX_QUEUE_SIZE",
Shared,
"u32",
Some("spans"),
Some("2048"),
Some(1),
Some(65536),
Public
),
FieldSpec {
rules: &["must be <= max_queue_size"],
..f!(
"observability.otlp.max_export_batch_size",
"OTEL_BSP_MAX_EXPORT_BATCH_SIZE",
Shared,
"u32",
Some("spans"),
Some("512"),
Some(1),
Some(65536),
Public
)
},
f!(
"observability.otlp.schedule_delay",
"OTEL_BSP_SCHEDULE_DELAY",
Shared,
"duration",
Some("milliseconds"),
Some("5000"),
Some(1),
Some(300000),
Public
),
f!(
"observability.otlp.export_timeout",
"OTEL_BSP_EXPORT_TIMEOUT",
Shared,
"duration",
Some("milliseconds"),
Some("30000"),
Some(1),
Some(300000),
Public
),
f!(
"admin.bind",
"CRANK_ADMIN_BIND",
AdminApi,
"socket",
None,
Some("0.0.0.0:3001"),
None,
None,
Internal
),
f!(
"admin.metrics_bind",
"CRANK_ADMIN_METRICS_BIND",
AdminApi,
"socket",
None,
Some("127.0.0.1:9464"),
None,
None,
Internal
),
f!(
"admin.storage_root",
"CRANK_STORAGE_ROOT",
AdminApi,
"absolute_path",
None,
Some("/var/lib/crank/storage"),
None,
None,
Internal
),
f!(
"admin.rate_limit.rps",
"CRANK_ADMIN_RATE_LIMIT_RPS",
AdminApi,
"u32",
Some("requests_per_second"),
Some("30"),
Some(1),
Some(100000),
Public
),
FieldSpec {
rules: &["must be >= admin rate RPS"],
..f!(
"admin.rate_limit.burst",
"CRANK_ADMIN_RATE_LIMIT_BURST",
AdminApi,
"u32",
Some("requests"),
Some("60"),
Some(1),
Some(1000000),
Public
)
},
f!(
"admin.invocation_log_retention_days",
"CRANK_INVOCATION_LOG_RETENTION_DAYS",
AdminApi,
"u32",
Some("days"),
Some("30"),
Some(1),
Some(36500),
Public
),
FieldSpec {
required: true,
..f!(
"admin.session.secret",
"CRANK_SESSION_SECRET",
AdminApi,
"secret",
None,
None,
None,
None,
Secret
)
},
FieldSpec {
required: true,
..f!(
"admin.password_pepper",
"CRANK_PASSWORD_PEPPER",
AdminApi,
"secret",
None,
None,
None,
None,
Secret
)
},
f!(
"admin.session.ttl_hours",
"CRANK_SESSION_TTL_HOURS",
AdminApi,
"u32",
Some("hours"),
Some("24"),
Some(1),
Some(8760),
Public
),
FieldSpec {
compatibility: Some("yes/no/on/off spellings are deprecated"),
..f!(
"admin.trust_forwarded_headers",
"CRANK_TRUST_FORWARDED_HEADERS",
AdminApi,
"bool",
None,
Some("false"),
None,
None,
Public
)
},
FieldSpec {
required: true,
..f!(
"admin.bootstrap.email",
"CRANK_BOOTSTRAP_ADMIN_EMAIL",
AdminApi,
"string",
None,
None,
None,
None,
Internal
)
},
FieldSpec {
required: true,
..f!(
"admin.bootstrap.password",
"CRANK_BOOTSTRAP_ADMIN_PASSWORD",
AdminApi,
"secret",
None,
None,
None,
None,
Secret
)
},
f!(
"admin.bootstrap.display_name",
"CRANK_BOOTSTRAP_ADMIN_DISPLAY_NAME",
AdminApi,
"string",
None,
Some("Crank Owner"),
None,
None,
Internal
),
FieldSpec {
compatibility: Some("yes/no/on/off spellings are deprecated"),
..f!(
"admin.demo_seed",
"CRANK_DEMO_SEED",
AdminApi,
"bool",
None,
Some("false"),
None,
None,
Public
)
},
f!(
"mcp.bind",
"CRANK_MCP_BIND",
McpServer,
"socket",
None,
Some("0.0.0.0:3002"),
None,
None,
Internal
),
f!(
"mcp.metrics_bind",
"CRANK_MCP_METRICS_BIND",
McpServer,
"socket",
None,
Some("127.0.0.1:9465"),
None,
None,
Internal
),
f!(
"mcp.refresh_ms",
"CRANK_MCP_REFRESH_MS",
McpServer,
"u64",
Some("milliseconds"),
Some("5000"),
Some(100),
Some(3600000),
Public
),
f!(
"mcp.rate_limit.rps",
"CRANK_MCP_RATE_LIMIT_RPS",
McpServer,
"u32",
Some("requests_per_second"),
Some("60"),
Some(1),
Some(100000),
Public
),
FieldSpec {
rules: &["must be >= MCP rate RPS"],
..f!(
"mcp.rate_limit.burst",
"CRANK_MCP_RATE_LIMIT_BURST",
McpServer,
"u32",
Some("requests"),
Some("120"),
Some(1),
Some(1000000),
Public
)
},
f!(
"runtime.max_concurrent_sessions",
"CRANK_RUNTIME_MAX_CONCURRENT_SESSIONS",
McpServer,
"u32",
Some("sessions"),
Some("16"),
Some(1),
Some(65535),
Public
),
];
pub fn field_registry() -> &'static [FieldSpec] {
&FIELDS
}
static DEPLOYMENT_FIELDS: [&str; 12] = [
"COMPOSE_PROJECT_NAME",
"POSTGRES_PUBLISH_BIND",
"POSTGRES_PUBLISH_PORT",
"CRANK_ADMIN_API_IMAGE",
"CRANK_MCP_SERVER_IMAGE",
"CRANK_UI_IMAGE",
"CRANK_PUBLISH_BIND",
"CRANK_ADMIN_PUBLISH_PORT",
"CRANK_MCP_PUBLISH_PORT",
"CRANK_UI_PUBLISH_PORT",
"VALKEY_PUBLISH_BIND",
"VALKEY_PUBLISH_PORT",
];
pub fn deployment_field_registry() -> &'static [&'static str] {
&DEPLOYMENT_FIELDS
}
crates/crank-config/src/source.rs
+85
View File
@@ -0,0 +1,85 @@
use std::{collections::BTreeMap, ffi::OsString};
use crate::{ConfigError, Diagnostic, DiagnosticCode, deployment_field_registry, field_registry};
#[derive(Clone, Debug, Default)]
pub struct ConfigSource {
values: BTreeMap<String, String>,
}
impl ConfigSource {
pub fn from_utf8(values: BTreeMap<String, String>) -> Self {
Self { values }
}
pub fn from_os() -> Result<Self, ConfigError> {
Self::from_os_iter(std::env::vars_os())
}
pub fn from_os_for_migrator() -> Result<Self, ConfigError> {
Self::from_os_iter_filtered(std::env::vars_os(), |name| {
name.starts_with("POSTGRES_") || name.starts_with("CRANK_DATABASE_")
})
}
pub fn from_os_iter<I>(values: I) -> Result<Self, ConfigError>
where
I: IntoIterator<Item = (OsString, OsString)>,
{
Self::from_os_iter_filtered(values, |_| true)
}
fn from_os_iter_filtered<I, F>(values: I, include: F) -> Result<Self, ConfigError>
where
I: IntoIterator<Item = (OsString, OsString)>,
F: Fn(&str) -> bool,
{
let mut parsed = BTreeMap::new();
let mut diagnostics = Vec::new();
for (name, value) in values {
let Ok(name) = name.into_string() else {
// Owned names are ASCII. A non-UTF-8 name therefore cannot belong
// to Crank and must not make startup depend on unrelated OS state.
continue;
};
if !include(&name) {
continue;
}
let owned = name.starts_with("CRANK_")
|| name.starts_with("POSTGRES_")
|| name.starts_with("OTEL_");
let known = field_registry().iter().any(|field| field.env_name == name)
|| deployment_field_registry().contains(&name.as_str());
if !owned && !known {
continue;
}
let value = match value.into_string() {
Ok(value) => value,
Err(_) => {
let field = field_registry()
.iter()
.find(|field| field.env_name == name)
.map_or("environment.unknown", |field| field.semantic_path);
diagnostics.push(Diagnostic::new(DiagnosticCode::InvalidEncoding, field));
continue;
}
};
parsed.insert(name, value);
}
if diagnostics.is_empty() {
Ok(Self { values: parsed })
} else {
Err(ConfigError::from_diagnostics(diagnostics))
}
}
pub(crate) fn values(&self) -> &BTreeMap<String, String> {
&self.values
}
pub(crate) fn retain_for_migrator(mut self) -> Self {
self.values
.retain(|name, _| name.starts_with("POSTGRES_") || name.starts_with("CRANK_DATABASE_"));
self
}
}
crates/crank-config/src/validation.rs
+42
View File
@@ -0,0 +1,42 @@
pub(crate) fn valid_percent_encoding(value: &str) -> bool {
let bytes = value.as_bytes();
let mut index = 0;
while index < bytes.len() {
if bytes[index] == b'%' {
if index + 2 >= bytes.len()
|| !bytes[index + 1].is_ascii_hexdigit()
|| !bytes[index + 2].is_ascii_hexdigit()
{
return false;
}
index += 3;
} else {
index += 1;
}
}
true
}
pub(crate) fn valid_database_host(value: &str) -> bool {
!value.is_empty()
&& value.len() <= 253
&& !value.chars().any(char::is_whitespace)
&& (value.parse::<std::net::IpAddr>().is_ok()
|| value.split('.').all(|label| {
!label.is_empty()
&& label.len() <= 63
&& label
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || byte == b'-')
&& !label.starts_with('-')
&& !label.ends_with('-')
}))
}
pub(crate) fn valid_database_identifier(value: &str) -> bool {
!value.is_empty()
&& value.len() <= 128
&& value
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-' | b'.'))
}
crates/crank-config/src/value.rs
+42
View File
@@ -0,0 +1,42 @@
use std::fmt;
#[derive(Clone, Eq, PartialEq)]
pub struct SecretString(String);
impl SecretString {
pub(crate) fn new(value: String) -> Self {
Self(value)
}
/// Deliberate composition boundary. Never use in diagnostics or fingerprints.
pub fn expose_secret(&self) -> &str {
&self.0
}
pub fn is_configured(&self) -> bool {
!self.0.is_empty()
}
}
impl fmt::Debug for SecretString {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_tuple("SecretString")
.field(&if self.is_configured() {
"configured"
} else {
"unconfigured"
})
.finish()
}
}
impl fmt::Display for SecretString {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(if self.is_configured() {
"configured"
} else {
"unconfigured"
})
}
}
crates/crank-config/tests/contract.rs
+558
View File
@@ -0,0 +1,558 @@
use std::collections::BTreeMap;
use crank_config::{
ConfigSource, DiagnosticCode, FieldMode, ProcessKind, ProcessScope, field_registry,
parse_migrator, parse_process,
};
fn required_admin() -> BTreeMap<String, String> {
[
("CRANK_MASTER_KEY", "master"),
("CRANK_SESSION_SECRET", "session"),
("CRANK_PASSWORD_PEPPER", "pepper"),
("CRANK_BOOTSTRAP_ADMIN_EMAIL", "owner@example.test"),
("CRANK_BOOTSTRAP_ADMIN_PASSWORD", "password"),
]
.into_iter()
.map(|(key, value)| (key.to_owned(), value.to_owned()))
.collect()
}
fn required_mcp() -> BTreeMap<String, String> {
[("CRANK_MASTER_KEY", "master")]
.into_iter()
.map(|(key, value)| (key.to_owned(), value.to_owned()))
.collect()
}
#[test]
fn migrator_projection_requires_only_database_configuration() {
let config = parse_migrator(ConfigSource::from_utf8(BTreeMap::new()))
.expect("database defaults are sufficient for the controlled migration job");
assert_eq!(config.database.host, "postgres");
assert_eq!(config.database.port, 5432);
assert_eq!(config.fingerprint().len(), 64);
let debug = format!("{config:?}");
assert!(
!debug.contains("crank"),
"database password must remain redacted"
);
}
#[test]
fn migrator_ignores_service_configuration_and_rejects_database_typos() {
let mut values = BTreeMap::from([
("CRANK_MASTER_KEY".to_owned(), "secret-canary".to_owned()),
(
"CRANK_SESSION_SECRET".to_owned(),
"secret-canary".to_owned(),
),
("CRANK_MCP_REFRESH_MS".to_owned(), "invalid".to_owned()),
]);
parse_migrator(ConfigSource::from_utf8(values.clone()))
.expect("service fields are outside the database-only projection");
values.insert("POSTGRES_PORRT".to_owned(), "5432".to_owned());
let error = parse_migrator(ConfigSource::from_utf8(values)).unwrap_err();
assert!(
error
.diagnostics()
.iter()
.any(|diagnostic| diagnostic.code == DiagnosticCode::UnknownField)
);
assert!(!error.to_string().contains("secret-canary"));
}
fn source_for(
field: &crank_config::FieldSpec,
value: String,
) -> (ProcessKind, BTreeMap<String, String>) {
let kind = match field.process {
ProcessScope::McpServer => ProcessKind::McpServer,
ProcessScope::Shared | ProcessScope::AdminApi => ProcessKind::AdminApi,
};
let mut vars = match kind {
ProcessKind::AdminApi => required_admin(),
ProcessKind::McpServer => required_mcp(),
};
vars.insert(field.env_name.to_owned(), value);
match field.env_name {
"POSTGRES_MAX_CONNECTIONS" => {
vars.insert("POSTGRES_MIN_CONNECTIONS".into(), "0".into());
}
"POSTGRES_MIN_CONNECTIONS" => {
vars.insert("POSTGRES_MAX_CONNECTIONS".into(), "1024".into());
}
"CRANK_ADMIN_RATE_LIMIT_RPS" => {
vars.insert("CRANK_ADMIN_RATE_LIMIT_BURST".into(), "1000000".into());
}
"CRANK_ADMIN_RATE_LIMIT_BURST" => {
vars.insert("CRANK_ADMIN_RATE_LIMIT_RPS".into(), "1".into());
}
"CRANK_MCP_RATE_LIMIT_RPS" => {
vars.insert("CRANK_MCP_RATE_LIMIT_BURST".into(), "1000000".into());
}
"CRANK_MCP_RATE_LIMIT_BURST" => {
vars.insert("CRANK_MCP_RATE_LIMIT_RPS".into(), "1".into());
}
"OTEL_BSP_MAX_QUEUE_SIZE" => {
vars.insert("OTEL_BSP_MAX_EXPORT_BATCH_SIZE".into(), "1".into());
}
"OTEL_BSP_MAX_EXPORT_BATCH_SIZE" => {
vars.insert("OTEL_BSP_MAX_QUEUE_SIZE".into(), "65536".into());
}
_ => {}
}
(kind, vars)
}
#[test]
fn registry_covers_exactly_the_57_observed_runtime_names() {
let registry = field_registry();
assert_eq!(registry.len(), 57);
let unique = registry
.iter()
.map(|field| field.env_name)
.collect::<std::collections::BTreeSet<_>>();
assert_eq!(unique.len(), registry.len());
assert!(!unique.contains("CRANK_RUNTIME_MAX_CONCURRENT_WINDOW"));
assert!(!unique.contains("CRANK_RUNTIME_MAX_CONCURRENT_JOBS"));
for field in registry {
assert!(!field.semantic_path.is_empty());
assert!(!field.env_name.is_empty());
assert!(!field.value_type.is_empty());
if let (Some(minimum), Some(maximum)) = (field.minimum, field.maximum) {
assert!(minimum <= maximum, "{}", field.env_name);
}
}
assert_eq!(
registry
.iter()
.find(|field| field.env_name == "CRANK_CACHE_DEFAULT_TTL_MS")
.unwrap()
.mode,
FieldMode::DeprecatedNoEffect
);
}
#[test]
fn defaults_are_preserved_and_invalid_values_never_fall_back() {
let valid = parse_process(
ProcessKind::AdminApi,
ConfigSource::from_utf8(required_admin()),
)
.expect("minimal admin config");
let admin = valid.admin().expect("admin projection");
assert_eq!(admin.database.port, 5432);
assert_eq!(admin.session_ttl_hours, 24);
assert_eq!(admin.rate_limit.requests_per_second, 30);
for (name, value) in [
("POSTGRES_PORT", "bad"),
("CRANK_SESSION_TTL_HOURS", "bad"),
("CRANK_ADMIN_RATE_LIMIT_RPS", "bad"),
("CRANK_TRUST_FORWARDED_HEADERS", "tru"),
] {
let mut vars = required_admin();
vars.insert(name.to_owned(), value.to_owned());
let error =
parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
let path = field_registry()
.iter()
.find(|field| field.env_name == name)
.unwrap()
.semantic_path;
assert!(error.diagnostics().iter().any(|item| item.field == path));
}
}
#[test]
fn database_forms_conflict_and_owned_typos_fail_closed() {
let mut vars = required_admin();
vars.insert(
"CRANK_DATABASE_URL".into(),
"postgres://user:secret@db/crank".into(),
);
vars.insert("POSTGRES_HOST".into(), "db".into());
let error = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
assert!(
error
.diagnostics()
.iter()
.any(|item| item.code == DiagnosticCode::Conflict)
);
let mut vars = required_admin();
vars.insert("CRANK_SESION_SECRET".into(), "canary".into());
let error = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
assert!(
error
.diagnostics()
.iter()
.any(|item| item.code == DiagnosticCode::UnknownField)
);
assert!(!error.to_string().contains("canary"));
for ghost in [
"CRANK_RUNTIME_MAX_CONCURRENT_WINDOW",
"CRANK_RUNTIME_MAX_CONCURRENT_JOBS",
] {
let mut vars = required_admin();
vars.insert(ghost.into(), "4".into());
let error =
parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
assert!(error.diagnostics().iter().any(|item| {
item.code == DiagnosticCode::UnknownField && item.field == "environment.unknown"
}));
}
}
#[test]
fn exact_deployment_only_names_are_known_but_never_runtime_fields() {
let mut vars = required_admin();
for name in crank_config::deployment_field_registry() {
vars.insert((*name).to_owned(), "deployment-value".to_owned());
}
let config = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap();
assert!(config.admin().is_some());
assert!(
field_registry()
.iter()
.all(|field| { !crank_config::deployment_field_registry().contains(&field.env_name) })
);
}
#[test]
fn parsed_but_unused_cache_ttl_is_an_explicit_non_pass_contract() {
let mut vars = required_admin();
vars.insert("CRANK_CACHE_DEFAULT_TTL_MS".into(), "5000".into());
let error = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
assert!(error.diagnostics().iter().any(|item| {
item.code == DiagnosticCode::DeprecatedNoEffect && item.field == "cache.default_ttl_ms"
}));
}
#[cfg(unix)]
#[test]
fn os_source_rejects_non_utf8_without_echoing_bytes() {
use std::{ffi::OsString, os::unix::ffi::OsStringExt};
let error = ConfigSource::from_os_iter([(
OsString::from("CRANK_MASTER_KEY"),
OsString::from_vec(vec![0xff, b'S', b'E', b'C', b'R', b'E', b'T']),
)])
.unwrap_err();
assert!(
error
.diagnostics()
.iter()
.any(|item| item.code == DiagnosticCode::InvalidEncoding)
);
assert!(!error.to_string().contains("SECRET"));
}
#[cfg(unix)]
#[test]
fn os_source_ignores_unrelated_invalid_or_unbounded_values() {
use std::{ffi::OsString, os::unix::ffi::OsStringExt};
ConfigSource::from_os_iter([
(
OsString::from_vec(vec![0xff]),
OsString::from_vec(vec![0xff]),
),
(
OsString::from("JAVA_TOOL_OPTIONS"),
OsString::from("x".repeat(20_000)),
),
(OsString::from("LANG"), OsString::from_vec(vec![0xff, b'x'])),
])
.expect("unrelated OS state is outside the runtime contract");
}
#[test]
fn process_specific_fields_and_zero_ports_fail_closed() {
let mut mcp = required_mcp();
mcp.insert("CRANK_SESSION_SECRET".into(), "wrong-process".into());
let error = parse_process(ProcessKind::McpServer, ConfigSource::from_utf8(mcp)).unwrap_err();
assert!(error.diagnostics().iter().any(|item| {
item.code == DiagnosticCode::UnknownField && item.field == "admin.session.secret"
}));
for (kind, name, required) in [
(ProcessKind::AdminApi, "CRANK_ADMIN_BIND", required_admin()),
(
ProcessKind::AdminApi,
"CRANK_ADMIN_METRICS_BIND",
required_admin(),
),
(ProcessKind::McpServer, "CRANK_MCP_BIND", required_mcp()),
(
ProcessKind::McpServer,
"CRANK_MCP_METRICS_BIND",
required_mcp(),
),
] {
let mut vars = required;
vars.insert(name.into(), "127.0.0.1:0".into());
let error = parse_process(kind, ConfigSource::from_utf8(vars)).unwrap_err();
let path = field_registry()
.iter()
.find(|field| field.env_name == name)
.unwrap()
.semantic_path;
assert!(
error
.diagnostics()
.iter()
.any(|item| { item.code == DiagnosticCode::OutOfRange && item.field == path })
);
}
}
#[test]
fn whitespace_secrets_and_consumer_invalid_values_fail_in_the_leaf_parser() {
for name in [
"CRANK_MASTER_KEY",
"CRANK_SESSION_SECRET",
"CRANK_PASSWORD_PEPPER",
"CRANK_BOOTSTRAP_ADMIN_PASSWORD",
] {
let mut vars = required_admin();
vars.insert(name.into(), " ".into());
assert!(
parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).is_err(),
"{name}"
);
}
for (name, value) in [
("CRANK_OUTBOUND_ALLOWED_HOSTS", "example.test:443"),
("CRANK_DATABASE_URL", "postgres://db/crank?sslmode=bogus"),
("CRANK_ENVIRONMENT", "bad environment"),
("CRANK_SENTRY_DSN", "not-a-dsn"),
("OTEL_EXPORTER_OTLP_HEADERS", "bad name=value"),
(
"CRANK_BASE_URL",
"https://user:secret@example.test/path?token=x",
),
] {
let mut vars = required_admin();
vars.insert(name.into(), value.into());
let error =
parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).expect_err(name);
assert!(
error
.diagnostics()
.iter()
.any(|item| item.code == DiagnosticCode::InvalidType),
"{name}: {error}"
);
}
}
#[test]
fn cross_field_and_typed_boundaries_fail_closed() {
let cases = [
("POSTGRES_MAX_CONNECTIONS", "1025"),
("CRANK_ADMIN_RATE_LIMIT_RPS", "100001"),
("CRANK_ADMIN_RATE_LIMIT_BURST", "0"),
("CRANK_OUTBOUND_MAX_RESPONSE_BYTES", "67108865"),
("OTEL_BSP_SCHEDULE_DELAY", "bad"),
("OTEL_BSP_EXPORT_TIMEOUT", "300001"),
("CRANK_BASE_URL", "file:///tmp/config"),
];
for (name, value) in cases {
let mut vars = required_admin();
vars.insert(name.to_owned(), value.to_owned());
let error =
parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).expect_err(name);
assert!(
error.diagnostics().iter().any(|item| item.field
== field_registry()
.iter()
.find(|field| field.env_name == name)
.unwrap()
.semantic_path),
"{name}: {error}"
);
}
let mut vars = required_admin();
vars.insert("POSTGRES_MIN_CONNECTIONS".into(), "21".into());
let error = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
assert!(
error
.diagnostics()
.iter()
.any(|item| item.code == DiagnosticCode::UnsafeCombination)
);
let mut vars = required_admin();
vars.insert("CRANK_CACHE_BACKEND".into(), "valkey".into());
vars.insert("CRANK_CACHE_URL".into(), "https://not-a-cache.test".into());
let error = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
assert!(
error
.diagnostics()
.iter()
.any(|item| item.field == "cache.url")
);
}
#[test]
fn inclusive_edges_and_legacy_boolean_spellings_are_explicit() {
let mut vars = required_admin();
vars.extend([
("POSTGRES_PORT".into(), "65535".into()),
("POSTGRES_MAX_CONNECTIONS".into(), "1024".into()),
("POSTGRES_MIN_CONNECTIONS".into(), "0".into()),
("CRANK_RUNTIME_MAX_CONCURRENT_UNARY".into(), "1".into()),
(
"CRANK_OUTBOUND_MAX_RESPONSE_BYTES".into(),
"67108864".into(),
),
("CRANK_TRUST_FORWARDED_HEADERS".into(), "yes".into()),
("CRANK_DEMO_SEED".into(), "off".into()),
]);
let config = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap();
let admin = config.admin().unwrap();
assert_eq!(admin.database.port, 65_535);
assert_eq!(admin.database.pool.max_connections, 1024);
assert_eq!(admin.database.pool.min_connections, 0);
assert_eq!(admin.runtime.max_concurrent_unary, 1);
assert!(admin.trust_forwarded_headers);
assert!(!admin.demo_seed);
}
#[test]
fn admin_and_mcp_share_one_normalized_foundation() {
let mut vars = required_admin();
vars.extend([
("CRANK_BASE_URL".into(), "https://crank.example.test".into()),
("CRANK_RUNTIME_MAX_CONCURRENT_UNARY".into(), "72".into()),
(
"CRANK_OUTBOUND_ALLOWED_HOSTS".into(),
"api.example.test".into(),
),
("POSTGRES_MAX_CONNECTIONS".into(), "24".into()),
]);
let admin =
parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars.clone())).unwrap();
let mut mcp_vars = vars;
for key in [
"CRANK_SESSION_SECRET",
"CRANK_PASSWORD_PEPPER",
"CRANK_BOOTSTRAP_ADMIN_EMAIL",
"CRANK_BOOTSTRAP_ADMIN_PASSWORD",
] {
mcp_vars.remove(key);
}
let mcp = parse_process(ProcessKind::McpServer, ConfigSource::from_utf8(mcp_vars)).unwrap();
let admin = admin.admin().unwrap();
let mcp = mcp.mcp().unwrap();
assert_eq!(admin.database.host, mcp.database.host);
assert_eq!(
admin.database.pool.max_connections,
mcp.database.pool.max_connections
);
assert_eq!(admin.runtime.base_url, mcp.runtime.base_url);
assert_eq!(
admin.runtime.max_concurrent_unary,
mcp.runtime.max_concurrent_unary
);
assert_eq!(
admin.runtime.outbound.allowed_hosts,
mcp.runtime.outbound.allowed_hosts
);
}
#[test]
fn every_bounded_numeric_field_accepts_edges_and_rejects_outside_values() {
for field in field_registry().iter().filter(|field| {
field.mode == FieldMode::Effective && field.minimum.is_some() && field.maximum.is_some()
}) {
let minimum = field.minimum.unwrap();
let maximum = field.maximum.unwrap();
for accepted in [minimum, maximum] {
let (kind, vars) = source_for(field, accepted.to_string());
parse_process(kind, ConfigSource::from_utf8(vars))
.unwrap_or_else(|error| panic!("{}={accepted}: {error}", field.env_name));
}
for rejected in [
if minimum == 0 {
"-1".to_owned()
} else {
(minimum - 1).to_string()
},
(maximum + 1).to_string(),
] {
let (kind, vars) = source_for(field, rejected);
let error =
parse_process(kind, ConfigSource::from_utf8(vars)).expect_err(field.env_name);
assert!(
error
.diagnostics()
.iter()
.any(|item| item.field == field.semantic_path),
"{}: {error}",
field.env_name
);
}
for malformed in ["-1", "184467440737095516160", "1.5", " 1", "1\n"] {
let (kind, vars) = source_for(field, malformed.to_owned());
let error =
parse_process(kind, ConfigSource::from_utf8(vars)).expect_err(field.env_name);
assert!(
error
.diagnostics()
.iter()
.any(|item| item.field == field.semantic_path),
"{}={malformed:?}: {error}",
field.env_name
);
}
}
}
#[test]
fn compatibility_values_and_otel_precedence_remain_explicit() {
let mut vars = required_admin();
vars.extend([
("CRANK_CACHE_BACKEND".into(), "redis".into()),
(
"CRANK_CACHE_URL".into(),
"redis://cache.example.test:6379".into(),
),
(
"OTEL_EXPORTER_OTLP_ENDPOINT".into(),
"https://generic.example.test".into(),
),
(
"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT".into(),
"https://traces.example.test".into(),
),
("OTEL_EXPORTER_OTLP_TIMEOUT".into(), "10000".into()),
("OTEL_EXPORTER_OTLP_TRACES_TIMEOUT".into(), "5000".into()),
]);
let config = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap();
let admin = config.admin().unwrap();
assert_eq!(
admin.runtime.cache.backend,
crank_config::CacheBackend::Redis
);
assert_eq!(
admin.observability.otlp.endpoint.as_deref(),
Some("https://generic.example.test")
);
assert_eq!(
admin.observability.otlp.traces_endpoint.as_deref(),
Some("https://traces.example.test")
);
assert_eq!(admin.observability.otlp.timeout.as_deref(), Some("10000"));
assert_eq!(
admin.observability.otlp.traces_timeout.as_deref(),
Some("5000")
);
assert_eq!(config.deprecations().len(), 1);
assert_eq!(config.deprecations()[0].field, "cache.backend");
}
crates/crank-config/tests/generation.rs
+48
View File
@@ -0,0 +1,48 @@
use crank_config::{field_registry, render};
#[test]
fn generated_contract_is_deterministic_complete_and_redacted() {
assert_eq!(render::schema_json(), render::schema_json());
let schema: serde_json::Value = serde_json::from_str(&render::schema_json()).unwrap();
assert_eq!(
schema["fields"].as_array().unwrap().len(),
field_registry().len()
);
for section in [render::env_section(false), render::env_section(true)] {
assert!(!section.contains("change-me"));
assert!(!section.contains("CRANK_RUNTIME_MAX_CONCURRENT_WINDOW"));
assert!(!section.contains("CRANK_RUNTIME_MAX_CONCURRENT_JOBS"));
assert!(!section.contains("CRANK_CACHE_DEFAULT_TTL_MS"));
}
}
#[test]
fn generated_reference_distinguishes_required_and_optional_fields() {
let reference = render::reference_section();
assert!(reference.contains(
"| `CRANK_MASTER_KEY` | `runtime.master_key` | `Shared` | `secret/-` | `required/blank` |"
));
assert!(
reference
.contains("| `CRANK_DATABASE_URL` | `database.url` | `Shared` | `url/-` | `blank` |")
);
assert!(reference.contains(
"| `CRANK_LOG_LEVEL` | `observability.log_filter` | `Shared` | `string/-` | `blank` |"
));
}
#[test]
fn marker_replacement_is_bounded_to_the_generated_region() {
let input = "before\n# BEGIN GENERATED CRANK RUNTIME CONFIG\nstale\n# END GENERATED CRANK RUNTIME CONFIG\nafter\n";
let output = render::replace_marked(
input,
render::BEGIN_MARKER,
render::END_MARKER,
&render::env_section(false),
)
.unwrap();
assert!(output.starts_with("before\n"));
assert!(output.ends_with("\nafter\n"));
assert!(!output.contains("stale"));
}
crates/crank-config/tests/redaction.rs
+178
View File
@@ -0,0 +1,178 @@
use std::collections::BTreeMap;
use crank_config::{ConfigSource, ProcessKind, parse_process};
fn config(secret: &str) -> crank_config::EffectiveConfig {
let vars = [
("CRANK_MASTER_KEY", secret),
("CRANK_SESSION_SECRET", secret),
("CRANK_PASSWORD_PEPPER", secret),
("CRANK_BOOTSTRAP_ADMIN_EMAIL", "owner@example.test"),
("CRANK_BOOTSTRAP_ADMIN_PASSWORD", secret),
]
.into_iter()
.map(|(key, value)| (key.to_owned(), value.to_owned()))
.collect::<BTreeMap<_, _>>();
parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap()
}
#[test]
fn secrets_are_absent_from_debug_display_and_fingerprint() {
let first = config("CANARY_ONE");
let second = config("CANARY_TWO");
let rendered = format!("{first:?}");
assert!(!rendered.contains("CANARY_ONE"));
assert_eq!(first.fingerprint(), second.fingerprint());
assert_eq!(first.fingerprint().len(), 64);
assert!(
first
.fingerprint()
.bytes()
.all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
);
}
#[test]
fn effective_semantics_not_input_spelling_drive_fingerprint() {
let mut canonical = [
("CRANK_MASTER_KEY", "master"),
("CRANK_SESSION_SECRET", "session"),
("CRANK_PASSWORD_PEPPER", "pepper"),
("CRANK_BOOTSTRAP_ADMIN_EMAIL", "owner@example.test"),
("CRANK_BOOTSTRAP_ADMIN_PASSWORD", "password"),
("CRANK_TRUST_FORWARDED_HEADERS", "true"),
]
.into_iter()
.map(|(key, value)| (key.to_owned(), value.to_owned()))
.collect::<BTreeMap<_, _>>();
let mut compatibility = canonical.clone();
compatibility.insert("CRANK_TRUST_FORWARDED_HEADERS".into(), "yes".into());
let canonical_config = parse_process(
ProcessKind::AdminApi,
ConfigSource::from_utf8(canonical.clone()),
)
.unwrap();
let compatibility_config = parse_process(
ProcessKind::AdminApi,
ConfigSource::from_utf8(compatibility),
)
.unwrap();
assert_eq!(
canonical_config.fingerprint(),
compatibility_config.fingerprint()
);
assert_eq!(compatibility_config.deprecations().len(), 1);
canonical.insert("CRANK_SESSION_TTL_HOURS".into(), "48".into());
let changed = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(canonical)).unwrap();
assert_ne!(changed.fingerprint(), compatibility_config.fingerprint());
}
#[test]
fn diagnostics_are_bounded_json_and_never_echo_secret_canaries() {
let canary = "CANARY_SECRET_VALUE";
let vars = [
("CRANK_MASTER_KEY", canary),
("CRANK_SESSION_SECRET", canary),
("CRANK_PASSWORD_PEPPER", canary),
("CRANK_BOOTSTRAP_ADMIN_EMAIL", "owner@example.test"),
("CRANK_BOOTSTRAP_ADMIN_PASSWORD", canary),
(
"CRANK_DATABASE_URL",
"postgres://owner:CANARY_SECRET_VALUE@db/crank",
),
("POSTGRES_PASSWORD", canary),
("CRANK_CACHE_BACKEND", "memory"),
("CRANK_CACHE_URL", "redis://:CANARY_SECRET_VALUE@cache:6379"),
(
"CRANK_SENTRY_DSN",
"https://CANARY_SECRET_VALUE@sentry.test/1",
),
("CRANK_METRICS_BEARER_TOKEN", canary),
(
"OTEL_EXPORTER_OTLP_HEADERS",
"authorization=CANARY_SECRET_VALUE",
),
]
.into_iter()
.map(|(key, value)| (key.to_owned(), value.to_owned()))
.collect::<BTreeMap<_, _>>();
let error = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
let display = error.to_string();
let json = error.to_json();
assert!(json.len() <= 65_536);
assert!(serde_json::from_str::<serde_json::Value>(&json).is_ok());
assert!(!display.contains(canary));
assert!(!json.contains(canary));
assert!(error.diagnostics().len() <= 100);
}
#[test]
fn public_projection_debug_omits_urls_hosts_paths_and_identity_values() {
let mut vars = [
("CRANK_MASTER_KEY", "master"),
("CRANK_SESSION_SECRET", "session"),
("CRANK_PASSWORD_PEPPER", "pepper"),
("CRANK_BOOTSTRAP_ADMIN_EMAIL", "owner@CANARY.test"),
("CRANK_BOOTSTRAP_ADMIN_PASSWORD", "password"),
("CRANK_STORAGE_ROOT", "/CANARY/private/storage"),
("POSTGRES_HOST", "CANARY-db.internal"),
("CRANK_OUTBOUND_ALLOWED_HOSTS", "CANARY-api.internal"),
]
.into_iter()
.map(|(k, v)| (k.to_owned(), v.to_owned()))
.collect::<BTreeMap<_, _>>();
vars.insert(
"CRANK_BASE_URL".into(),
"https://CANARY.example.test".into(),
);
let config = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap();
let rendered = format!("{:?}", config.admin().unwrap());
assert!(!rendered.contains("CANARY"), "{rendered}");
}
#[test]
fn normalized_database_and_admin_default_urls_drive_fingerprint() {
let base = [
("CRANK_MASTER_KEY", "master"),
("CRANK_SESSION_SECRET", "session"),
("CRANK_PASSWORD_PEPPER", "pepper"),
("CRANK_BOOTSTRAP_ADMIN_EMAIL", "owner@example.test"),
("CRANK_BOOTSTRAP_ADMIN_PASSWORD", "password"),
]
.into_iter()
.map(|(k, v)| (k.to_owned(), v.to_owned()))
.collect::<BTreeMap<_, _>>();
let implicit =
parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(base.clone())).unwrap();
let mut explicit = base.clone();
explicit.insert("CRANK_BASE_URL".into(), "http://localhost:3000".into());
let explicit = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(explicit)).unwrap();
assert_eq!(implicit.fingerprint(), explicit.fingerprint());
let mut url = base;
url.insert(
"CRANK_DATABASE_URL".into(),
"postgres://crank:rotated@postgres/crank".into(),
);
let url = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(url)).unwrap();
assert_eq!(implicit.fingerprint(), url.fingerprint());
let tls = [
("CRANK_MASTER_KEY", "master"),
("CRANK_SESSION_SECRET", "session"),
("CRANK_PASSWORD_PEPPER", "pepper"),
("CRANK_BOOTSTRAP_ADMIN_EMAIL", "owner@example.test"),
("CRANK_BOOTSTRAP_ADMIN_PASSWORD", "password"),
(
"CRANK_DATABASE_URL",
"postgres://crank:rotated@postgres/crank?sslmode=require",
),
]
.into_iter()
.map(|(k, v)| (k.to_owned(), v.to_owned()))
.collect::<BTreeMap<_, _>>();
let tls = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(tls)).unwrap();
assert_ne!(implicit.fingerprint(), tls.fingerprint());
}
crates/crank-core/Cargo.toml
+1
View File
@@ -12,6 +12,7 @@ serde.workspace = true
serde_json.workspace = true
thiserror.workspace = true
time.workspace = true
uuid.workspace = true
[dev-dependencies]
serde_yaml.workspace = true
crates/crank-core/src/correlation.rs
+275
View File
@@ -0,0 +1,275 @@
use serde::{Deserialize, Deserializer, Serialize, de};
use uuid::Uuid;
const TRACEPARENT_VERSION: &str = "00";
const ZERO_TRACE_ID: &str = "00000000000000000000000000000000";
const ZERO_PARENT_ID: &str = "0000000000000000";
#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize)]
#[serde(transparent)]
pub struct RequestId(String);
impl RequestId {
pub const MAX_LEN: usize = 128;
pub fn generate() -> Self {
Self(Uuid::now_v7().to_string())
}
pub fn resolve(candidate: Option<&str>) -> Self {
candidate
.filter(|value| Self::is_valid(value))
.map(|value| Self(value.to_owned()))
.unwrap_or_else(Self::generate)
}
pub fn parse(value: &str) -> Result<Self, CorrelationError> {
Self::is_valid(value)
.then(|| Self(value.to_owned()))
.ok_or(CorrelationError::InvalidRequestId)
}
pub fn is_valid(value: &str) -> bool {
!value.is_empty()
&& value.len() <= Self::MAX_LEN
&& value
.bytes()
.all(|byte| byte.is_ascii_graphic() && byte != b',' && byte != b';')
}
pub fn as_str(&self) -> &str {
&self.0
}
}
impl std::fmt::Display for RequestId {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str(&self.0)
}
}
impl<'de> Deserialize<'de> for RequestId {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
let value = String::deserialize(deserializer)?;
Self::parse(&value).map_err(de::Error::custom)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize)]
#[serde(transparent)]
pub struct TraceId(String);
impl TraceId {
pub const LEN: usize = 32;
pub fn generate() -> Self {
let value = Uuid::now_v7().simple().to_string();
debug_assert_ne!(value, ZERO_TRACE_ID);
Self(value)
}
pub fn parse(value: &str) -> Result<Self, CorrelationError> {
if is_lower_hex(value, Self::LEN) && value != ZERO_TRACE_ID {
Ok(Self(value.to_owned()))
} else {
Err(CorrelationError::InvalidTraceId)
}
}
pub fn as_str(&self) -> &str {
&self.0
}
}
impl std::fmt::Display for TraceId {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str(&self.0)
}
}
impl<'de> Deserialize<'de> for TraceId {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
let value = String::deserialize(deserializer)?;
Self::parse(&value).map_err(de::Error::custom)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
pub struct TraceContext {
trace_id: TraceId,
traceparent: String,
}
impl TraceContext {
pub const TRACEPARENT_LEN: usize = 55;
pub const TRACESTATE_MAX_BYTES: usize = 512;
pub const TRACESTATE_MAX_MEMBERS: usize = 32;
pub const BAGGAGE_MAX_BYTES: usize = 8_192;
pub const BAGGAGE_MAX_MEMBERS: usize = 64;
pub fn generate() -> Self {
let trace_id = TraceId::generate();
let mut parent_id = Uuid::now_v7().simple().to_string()[..16].to_owned();
if parent_id == ZERO_PARENT_ID {
parent_id.replace_range(15..16, "1");
}
// A context generated outside an SDK span must not claim that a sampler
// selected it. Ingress replaces this seed with the actual local span
// context before application code runs.
let traceparent = format!("{TRACEPARENT_VERSION}-{trace_id}-{parent_id}-00");
Self {
trace_id,
traceparent,
}
}
pub fn parse(value: &str) -> Result<Self, CorrelationError> {
if value.len() != Self::TRACEPARENT_LEN {
return Err(CorrelationError::InvalidTraceparent);
}
let bytes = value.as_bytes();
if bytes[2] != b'-' || bytes[35] != b'-' || bytes[52] != b'-' {
return Err(CorrelationError::InvalidTraceparent);
}
let version = &value[0..2];
let trace_id = &value[3..35];
let parent_id = &value[36..52];
let flags = &value[53..55];
if version != TRACEPARENT_VERSION
|| !is_lower_hex(parent_id, 16)
|| parent_id == ZERO_PARENT_ID
|| !matches!(flags, "00" | "01")
{
return Err(CorrelationError::InvalidTraceparent);
}
Ok(Self {
trace_id: TraceId::parse(trace_id).map_err(|_| CorrelationError::InvalidTraceparent)?,
traceparent: value.to_owned(),
})
}
pub fn from_span_parts(
trace_id: &str,
span_id: &str,
sampled: bool,
) -> Result<Self, CorrelationError> {
let flags = if sampled { "01" } else { "00" };
Self::parse(&format!(
"{TRACEPARENT_VERSION}-{trace_id}-{span_id}-{flags}"
))
}
pub fn continue_local(&self) -> Self {
let mut span_id = Uuid::now_v7().simple().to_string()[..16].to_owned();
if span_id == ZERO_PARENT_ID {
span_id.replace_range(15..16, "1");
}
let sampled = self.traceparent.ends_with("-01");
Self::from_span_parts(self.trace_id.as_str(), &span_id, sampled)
.expect("generated span identity is canonical")
}
pub fn trace_id(&self) -> &TraceId {
&self.trace_id
}
pub fn traceparent(&self) -> &str {
&self.traceparent
}
pub fn tracestate_within_budget(value: &str) -> bool {
header_list_within_budget(
value,
Self::TRACESTATE_MAX_BYTES,
Self::TRACESTATE_MAX_MEMBERS,
)
}
pub fn baggage_within_budget(value: &str) -> bool {
header_list_within_budget(value, Self::BAGGAGE_MAX_BYTES, Self::BAGGAGE_MAX_MEMBERS)
}
}
impl<'de> Deserialize<'de> for TraceContext {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct WireTraceContext {
trace_id: TraceId,
traceparent: String,
}
let wire = WireTraceContext::deserialize(deserializer)?;
let context = Self::parse(&wire.traceparent).map_err(de::Error::custom)?;
if context.trace_id != wire.trace_id {
return Err(de::Error::custom(CorrelationError::InvalidTraceparent));
}
Ok(context)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct CorrelationContext {
request_id: RequestId,
trace_context: TraceContext,
}
impl CorrelationContext {
pub fn new(request_id: RequestId, trace_context: TraceContext) -> Self {
Self {
request_id,
trace_context,
}
}
pub fn generate() -> Self {
Self::new(RequestId::generate(), TraceContext::generate())
}
pub fn request_id(&self) -> &RequestId {
&self.request_id
}
pub fn trace_context(&self) -> &TraceContext {
&self.trace_context
}
pub fn trace_id(&self) -> &TraceId {
self.trace_context.trace_id()
}
}
#[derive(Clone, Copy, Debug, thiserror::Error, PartialEq, Eq)]
pub enum CorrelationError {
#[error("invalid request identity")]
InvalidRequestId,
#[error("invalid trace identity")]
InvalidTraceId,
#[error("invalid trace parent")]
InvalidTraceparent,
}
fn is_lower_hex(value: &str, expected_len: usize) -> bool {
value.len() == expected_len
&& value
.bytes()
.all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
}
fn header_list_within_budget(value: &str, max_bytes: usize, max_members: usize) -> bool {
!value.is_empty()
&& value.len() <= max_bytes
&& value.is_ascii()
&& !value.bytes().any(|byte| byte.is_ascii_control())
&& value.split(',').count() <= max_members
&& value.split(',').all(|member| !member.trim().is_empty())
}
crates/crank-core/src/ext/protocol.rs
+32 -9
View File
@@ -4,7 +4,10 @@ use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use crate::{AgentId, InvocationSource, Protocol, Target, WorkspaceId};
use crate::{
AgentId, CorrelationContext, InvocationSource, Protocol, RequestId, Target, TraceContext,
WorkspaceId,
};
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
@@ -20,8 +23,8 @@ pub struct ResponseCacheScope {
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RuntimeRequestContext {
pub request_id: String,
pub correlation_id: String,
pub request_id: RequestId,
pub trace_context: TraceContext,
pub response_cache_scope: Option<ResponseCacheScope>,
pub metering_context: Option<MeteringContext>,
}
@@ -34,10 +37,10 @@ pub struct MeteringContext {
}
impl RuntimeRequestContext {
pub fn new(request_id: impl Into<String>, correlation_id: impl Into<String>) -> Self {
pub fn new(request_id: RequestId, trace_context: TraceContext) -> Self {
Self {
request_id: request_id.into(),
correlation_id: correlation_id.into(),
request_id,
trace_context,
response_cache_scope: None,
metering_context: None,
}
@@ -45,13 +48,33 @@ impl RuntimeRequestContext {
pub fn from_request_id(request_id: impl Into<String>) -> Self {
let request_id = request_id.into();
Self::new(request_id.clone(), request_id)
Self::new(
RequestId::resolve(Some(&request_id)),
TraceContext::generate(),
)
}
pub fn from_correlation(context: &CorrelationContext) -> Self {
Self::new(
context.request_id().clone(),
context.trace_context().clone(),
)
}
pub fn outbound_headers(&self) -> BTreeMap<String, String> {
BTreeMap::from([
("x-request-id".to_owned(), self.request_id.clone()),
("x-correlation-id".to_owned(), self.correlation_id.clone()),
("x-request-id".to_owned(), self.request_id.to_string()),
(
"x-trace-id".to_owned(),
self.trace_context.trace_id().to_string(),
),
(
"traceparent".to_owned(),
self.trace_context.traceparent().to_owned(),
),
// Compatibility alias only. It is intentionally the product Request ID,
// never the W3C Trace ID.
("x-correlation-id".to_owned(), self.request_id.to_string()),
])
}
crates/crank-core/src/lib.rs
+2
View File
@@ -3,6 +3,7 @@ pub mod agent;
pub mod approval;
pub mod auth;
pub mod cache;
pub mod correlation;
pub mod edition;
pub mod ext;
pub mod ids;
@@ -113,6 +114,7 @@ pub use cache::{
ParseCacheBackendError, RateLimitBucketState, RateLimitDecision, RateLimitStateStore,
ReplayGuardStatus, ReplayGuardStore, ResponseCacheStore,
};
pub use correlation::{CorrelationContext, CorrelationError, RequestId, TraceContext, TraceId};
pub use edition::{
EditionCapabilities, EditionLimits, MachineAccessMode, OperationSecurityLevel, ProductEdition,
};
crates/crank-core/src/observability.rs
+2
View File
@@ -118,6 +118,7 @@ pub struct InvocationLog {
pub tool_name: String,
pub message: String,
pub request_id: Option<String>,
pub trace_id: Option<String>,
pub status_code: Option<u16>,
pub duration_ms: u64,
pub error_kind: Option<String>,
@@ -169,6 +170,7 @@ mod tests {
tool_name: "create_lead".to_owned(),
message: "ok".to_owned(),
request_id: Some("req_01".to_owned()),
trace_id: Some("0af7651916cd43dd8448eb211c80319c".to_owned()),
status_code: Some(200),
duration_ms: 123,
error_kind: None,
crates/crank-core/tests/correlation.rs
+131
View File
@@ -0,0 +1,131 @@
use crank_core::{CorrelationContext, RequestId, TraceContext, TraceId};
use uuid::Version;
const VALID_TRACEPARENT: &str = "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01";
#[test]
fn generated_identities_are_distinct_and_canonical() {
let context = CorrelationContext::generate();
assert_eq!(
uuid::Uuid::parse_str(context.request_id().as_str())
.unwrap()
.get_version(),
Some(Version::SortRand)
);
assert_eq!(context.trace_id().as_str().len(), 32);
assert!(
context
.trace_id()
.as_str()
.bytes()
.all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
);
assert_ne!(
context.request_id().as_str().replace('-', ""),
context.trace_id().as_str()
);
}
#[test]
fn request_id_preserves_one_valid_opaque_value_and_replaces_invalid_values() {
assert_eq!(
RequestId::resolve(Some("gateway-request-42")).as_str(),
"gateway-request-42"
);
for invalid in ["", "bad value", "bad,value", "bad;value"] {
let replacement = RequestId::resolve(Some(invalid));
assert_ne!(replacement.as_str(), invalid);
assert_eq!(
uuid::Uuid::parse_str(replacement.as_str())
.unwrap()
.get_version(),
Some(Version::SortRand)
);
}
assert!(RequestId::is_valid(&"a".repeat(RequestId::MAX_LEN)));
assert!(!RequestId::is_valid(&"a".repeat(RequestId::MAX_LEN + 1)));
}
#[test]
fn traceparent_parser_is_strict_and_never_accepts_zero_ids() {
let context = TraceContext::parse(VALID_TRACEPARENT).unwrap();
assert_eq!(
context.trace_id().as_str(),
"0af7651916cd43dd8448eb211c80319c"
);
assert_eq!(context.traceparent(), VALID_TRACEPARENT);
for invalid in [
"00-00000000000000000000000000000000-b7ad6b7169203331-01",
"00-0af7651916cd43dd8448eb211c80319c-0000000000000000-01",
"00-0AF7651916CD43DD8448EB211C80319C-b7ad6b7169203331-01",
"00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-0z",
"00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-02",
"ff-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
"canary-invalid-traceparent",
] {
assert!(TraceContext::parse(invalid).is_err(), "accepted {invalid}");
}
assert!(TraceId::parse("00000000000000000000000000000000").is_err());
}
#[test]
fn durable_parent_envelope_roundtrips_without_conflating_ids() {
let context = CorrelationContext::new(
RequestId::resolve(Some("request-opaque-1")),
TraceContext::parse(VALID_TRACEPARENT).unwrap(),
);
let encoded = serde_json::to_vec(&context).unwrap();
let decoded: CorrelationContext = serde_json::from_slice(&encoded).unwrap();
assert_eq!(decoded, context);
assert_eq!(decoded.request_id().as_str(), "request-opaque-1");
assert_eq!(
decoded.trace_id().as_str(),
"0af7651916cd43dd8448eb211c80319c"
);
}
#[test]
fn durable_parent_envelope_rejects_invalid_or_inconsistent_identities() {
for candidate in [
serde_json::json!({
"request_id": "bad request",
"trace_context": {
"trace_id": "0af7651916cd43dd8448eb211c80319c",
"traceparent": VALID_TRACEPARENT,
}
}),
serde_json::json!({
"request_id": "request-1",
"trace_context": {
"trace_id": "00000000000000000000000000000000",
"traceparent": VALID_TRACEPARENT,
}
}),
serde_json::json!({
"request_id": "request-1",
"trace_context": {
"trace_id": "1af7651916cd43dd8448eb211c80319c",
"traceparent": VALID_TRACEPARENT,
}
}),
] {
assert!(serde_json::from_value::<CorrelationContext>(candidate).is_err());
}
}
#[test]
fn caller_state_and_baggage_budgets_are_closed_and_bounded() {
assert!(TraceContext::tracestate_within_budget("vendor=value"));
assert!(!TraceContext::tracestate_within_budget(&"x".repeat(513)));
assert!(!TraceContext::tracestate_within_budget(
&std::iter::repeat_n("a=b", 33).collect::<Vec<_>>().join(",")
));
assert!(TraceContext::baggage_within_budget("key=value"));
assert!(!TraceContext::baggage_within_budget(&"x".repeat(8_193)));
assert!(!TraceContext::baggage_within_budget(
&std::iter::repeat_n("a=b", 65).collect::<Vec<_>>().join(",")
));
}
crates/crank-observability/Cargo.toml
-1
View File
@@ -27,7 +27,6 @@ tracing.workspace = true
tracing-opentelemetry.workspace = true
tracing-subscriber.workspace = true
url.workspace = true
uuid.workspace = true
[dev-dependencies]
opentelemetry-proto.workspace = true
crates/crank-observability/src/config.rs
+18 -61
View File
@@ -1,10 +1,8 @@
use std::env;
use thiserror::Error;
use tracing_subscriber::EnvFilter;
use crate::RedactionLimits;
const DEFAULT_ENVIRONMENT: &str = "development";
const MAX_IDENTITY_LABEL_BYTES: usize = 64;
#[derive(Clone, Debug, Eq, PartialEq)]
@@ -52,6 +50,20 @@ pub struct ObservabilityConfig {
}
impl ObservabilityConfig {
pub fn try_new(
identity: ServiceIdentity,
filter: impl Into<String>,
redaction_limits: RedactionLimits,
) -> Result<Self, ObservabilityConfigError> {
let filter = filter.into();
EnvFilter::try_new(&filter).map_err(|_| ObservabilityConfigError::InvalidFilter)?;
Ok(Self {
identity,
filter,
redaction_limits,
})
}
pub fn new(
identity: ServiceIdentity,
filter: impl Into<String>,
@@ -64,26 +76,6 @@ impl ObservabilityConfig {
}
}
pub fn from_env(
service: &'static str,
version: &'static str,
default_filter: &'static str,
) -> Result<Self, ObservabilityConfigError> {
let environment = env_value_or_default(
"CRANK_ENVIRONMENT",
env::var("CRANK_ENVIRONMENT"),
DEFAULT_ENVIRONMENT,
)?;
let filter = env_value_or_default(
"CRANK_LOG_LEVEL",
env::var("CRANK_LOG_LEVEL"),
default_filter,
)?;
let identity = ServiceIdentity::try_new(service, version, environment)?;
Ok(Self::new(identity, filter, RedactionLimits::default()))
}
pub(crate) fn into_parts(self) -> (ServiceIdentity, String, RedactionLimits) {
(self.identity, self.filter, self.redaction_limits)
}
@@ -101,22 +93,8 @@ impl ObservabilityConfig {
pub enum ObservabilityConfigError {
#[error("invalid observability identity field: {field}")]
InvalidIdentity { field: &'static str },
#[error("observability environment variable is not valid UTF-8: {field}")]
InvalidEnvironmentEncoding { field: &'static str },
}
fn env_value_or_default(
field: &'static str,
value: Result<String, env::VarError>,
default: &'static str,
) -> Result<String, ObservabilityConfigError> {
match value {
Ok(value) => Ok(value),
Err(env::VarError::NotPresent) => Ok(default.to_owned()),
Err(env::VarError::NotUnicode(_)) => {
Err(ObservabilityConfigError::InvalidEnvironmentEncoding { field })
}
}
#[error("invalid observability log filter")]
InvalidFilter,
}
fn validate_label(field: &'static str, value: &str) -> Result<(), ObservabilityConfigError> {
@@ -135,9 +113,7 @@ fn validate_label(field: &'static str, value: &str) -> Result<(), ObservabilityC
#[cfg(test)]
mod tests {
use std::ffi::OsString;
use super::{ObservabilityConfigError, ServiceIdentity, env_value_or_default};
use super::ServiceIdentity;
#[test]
fn accepts_release_and_environment_labels() {
@@ -148,23 +124,4 @@ mod tests {
assert_eq!(identity.version(), "0.3.1+build.7");
assert_eq!(identity.environment(), "production");
}
#[test]
fn rejects_non_utf8_environment_values() {
let error = env_value_or_default(
"CRANK_ENVIRONMENT",
Err(std::env::VarError::NotUnicode(OsString::from(
"invalid-environment",
))),
"development",
)
.expect_err("non-UTF-8 values must not be replaced with defaults");
assert!(matches!(
error,
ObservabilityConfigError::InvalidEnvironmentEncoding {
field: "CRANK_ENVIRONMENT"
}
));
}
}
crates/crank-observability/src/correlation.rs
-51
View File
@@ -1,51 +0,0 @@
use std::fmt;
use axum::http::HeaderMap;
use uuid::Uuid;
#[derive(Clone, Debug, Eq, Hash, PartialEq)]
pub struct RequestId(String);
impl RequestId {
pub const MAX_LEN: usize = 128;
const HEADER_NAME: &'static str = "x-request-id";
pub fn resolve(candidate: Option<&str>) -> Self {
candidate
.filter(|value| Self::is_valid(value))
.map(|value| Self(value.to_owned()))
.unwrap_or_else(|| Self(Uuid::now_v7().to_string()))
}
pub fn resolve_from_headers(headers: &HeaderMap) -> Self {
let mut values = headers.get_all(Self::HEADER_NAME).iter();
let candidate = values.next();
if values.next().is_some() {
return Self::resolve(None);
}
Self::resolve(candidate.and_then(|value| value.to_str().ok()))
}
pub fn is_valid(value: &str) -> bool {
!value.is_empty()
&& value.len() <= Self::MAX_LEN
&& value
.bytes()
.all(|byte| matches!(byte, 0x21..=0x7e) && byte != b',' && byte != b';')
}
pub fn as_str(&self) -> &str {
&self.0
}
pub fn into_string(self) -> String {
self.0
}
}
impl fmt::Display for RequestId {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(self.as_str())
}
}
crates/crank-observability/src/error_reporting.rs
+57 -37
View File
@@ -1,7 +1,7 @@
use std::{
borrow::Cow,
collections::BTreeMap,
env, fmt,
fmt,
future::Future,
time::{Duration, SystemTime},
};
@@ -13,11 +13,8 @@ use sentry::{
};
use thiserror::Error;
use crate::{
RedactionLimits, ServiceIdentity, propagation::current_trace_id, redaction::truncate_string,
};
use crate::{RedactionLimits, ServiceIdentity, propagation::current_trace_id};
const SENTRY_DSN_ENV: &str = "CRANK_SENTRY_DSN";
const CRITICAL_ERROR_MESSAGE: &str = "critical error";
const SENTRY_SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(2);
// Sentry serializes SystemTime as a finite f64; this keeps conservative fixed headroom.
@@ -25,6 +22,7 @@ const MAX_SERIALIZED_TIMESTAMP_BYTES: usize = 32;
tokio::task_local! {
static REQUEST_ID: String;
static TRACE_ID: String;
}
pub struct SentryConfig {
@@ -43,14 +41,6 @@ impl SentryConfig {
Ok(Self { dsn: Some(dsn) })
}
pub fn from_env() -> Result<Self, SentryConfigError> {
match env::var(SENTRY_DSN_ENV) {
Ok(value) => Self::parse(Some(&value)),
Err(env::VarError::NotPresent) => Self::parse(None),
Err(env::VarError::NotUnicode(_)) => Err(SentryConfigError::InvalidEnvironmentEncoding),
}
}
pub fn enabled(&self) -> bool {
self.dsn.is_some()
}
@@ -69,8 +59,6 @@ impl fmt::Debug for SentryConfig {
pub enum SentryConfigError {
#[error("CRANK_SENTRY_DSN is not a valid Sentry DSN")]
InvalidDsn,
#[error("CRANK_SENTRY_DSN is not valid UTF-8")]
InvalidEnvironmentEncoding,
#[error("critical error event budget cannot hold the required fields")]
EventBudgetTooSmall,
}
@@ -123,11 +111,43 @@ pub fn capture_critical_error(category: CriticalErrorCategory) {
});
}
pub async fn with_request_correlation<F>(request_id: String, future: F) -> F::Output
pub async fn with_request_correlation<F>(
request_id: String,
trace_id: String,
future: F,
) -> F::Output
where
F: Future,
{
REQUEST_ID.scope(request_id, future).await
if !valid_request_id(&request_id) || !valid_trace_id(&trace_id) {
return future.await;
}
REQUEST_ID
.scope(request_id, TRACE_ID.scope(trace_id, future))
.await
}
fn valid_request_id(value: &str) -> bool {
!value.is_empty()
&& value.len() <= 128
&& value
.bytes()
.all(|byte| (0x21..=0x7e).contains(&byte) && byte != b',' && byte != b';')
}
fn valid_trace_id(value: &str) -> bool {
value.len() == 32
&& value != "00000000000000000000000000000000"
&& value
.bytes()
.all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
}
pub fn current_request_correlation() -> (Option<String>, Option<String>) {
(
REQUEST_ID.try_with(Clone::clone).ok(),
TRACE_ID.try_with(Clone::clone).ok(),
)
}
pub(crate) fn init_sentry(
@@ -184,16 +204,7 @@ fn sanitize_event(
CriticalErrorCategory::Panic
}
});
let mut tags = correlation_tags()
.into_iter()
.map(|(key, value)| (key, truncate_string(&value, limits.max_string_bytes)))
.collect::<BTreeMap<_, _>>();
for key in ["request_id", "trace_id"] {
if let Some(value) = event.tags.get(key) {
tags.entry(key.to_owned())
.or_insert_with(|| truncate_string(value, limits.max_string_bytes));
}
}
let mut tags = correlation_tags().into_iter().collect::<BTreeMap<_, _>>();
tags.insert("service".to_owned(), identity.service().to_owned());
tags.insert("category".to_owned(), category.as_str().to_owned());
@@ -222,19 +233,21 @@ fn correlation_tags() -> BTreeMap<String, String> {
if let Ok(request_id) = REQUEST_ID.try_with(Clone::clone) {
tags.insert("request_id".to_owned(), request_id);
}
if let Some(trace_id) = current_trace_id() {
if let Ok(trace_id) = TRACE_ID.try_with(Clone::clone) {
tags.insert("trace_id".to_owned(), trace_id);
} else if let Some(trace_id) = current_trace_id() {
tags.insert("trace_id".to_owned(), trace_id);
}
tags
}
fn enforce_event_budget(mut event: Event<'static>, max_event_bytes: usize) -> Event<'static> {
fn enforce_event_budget(event: Event<'static>, max_event_bytes: usize) -> Event<'static> {
if serialized_event_len(&event) <= max_event_bytes {
return event;
}
event.tags.remove("request_id");
event.tags.remove("trace_id");
// Startup validation reserves enough room for maximum canonical IDs. They
// are never evicted from a support event to satisfy a byte budget.
debug_assert!(serialized_event_len(&event) <= max_event_bytes);
event
}
@@ -257,7 +270,7 @@ fn required_critical_event_budget(identity: &ServiceIdentity, limits: RedactionL
CriticalErrorCategory::ALL
.into_iter()
.map(|category| {
let event = sanitize_event(
let mut event = sanitize_event(
Event {
tags: BTreeMap::from([("category".to_owned(), category.as_str().to_owned())]),
timestamp: SystemTime::UNIX_EPOCH,
@@ -266,6 +279,8 @@ fn required_critical_event_budget(identity: &ServiceIdentity, limits: RedactionL
identity,
unbounded_limits,
);
event.tags.insert("request_id".to_owned(), "r".repeat(128));
event.tags.insert("trace_id".to_owned(), "a".repeat(32));
serialized_event_len(&event)
.saturating_add(MAX_SERIALIZED_TIMESTAMP_BYTES.saturating_sub(1))
})
@@ -439,11 +454,15 @@ mod tests {
let events = sentry::test::with_captured_events_options(
|| {
tracing::dispatcher::with_default(&dispatch, || {
runtime.block_on(with_request_correlation("request-123".to_owned(), async {
let span = tracing::info_span!(target: "crank::trace", "http.request");
let _span_guard = span.enter();
capture_critical_error(CriticalErrorCategory::DataIntegrity);
}));
runtime.block_on(with_request_correlation(
"request-123".to_owned(),
"0af7651916cd43dd8448eb211c80319c".to_owned(),
async {
let span = tracing::info_span!(target: "crank::trace", "http.request");
let _span_guard = span.enter();
capture_critical_error(CriticalErrorCategory::DataIntegrity);
},
));
});
},
options,
@@ -496,6 +515,7 @@ mod tests {
tracing::dispatcher::with_default(&dispatch, || {
runtime.block_on(with_request_correlation(
"panic-request-123".to_owned(),
"0af7651916cd43dd8448eb211c80319c".to_owned(),
async {
let span =
tracing::info_span!(target: "crank::trace", "http.request");
crates/crank-observability/src/lib.rs
+1 -3
View File
@@ -1,5 +1,4 @@
mod config;
mod correlation;
mod error_reporting;
mod incidents;
mod instrumentation;
@@ -12,13 +11,12 @@ mod redaction;
mod schema;
pub use config::{ObservabilityConfig, ObservabilityConfigError, ServiceIdentity};
pub use correlation::RequestId;
pub use crank_metrics::{
DURATION_BUCKETS_SECONDS, MetricDefinition, MetricKind, MetricUnit, metric_schema,
};
pub use error_reporting::{
CriticalErrorCategory, SentryConfig, SentryConfigError, capture_critical_error,
with_request_correlation,
current_request_correlation, with_request_correlation,
};
pub use incidents::{OperationalIncident, operational_incident_total, record_operational_incident};
pub use instrumentation::{record_db_pool_connections, record_http_request};
crates/crank-observability/src/lifecycle.rs
+30 -11
View File
@@ -6,29 +6,45 @@ use tracing_subscriber::util::SubscriberInitExt;
use crate::{
MetricsConfig, MetricsSurface, MetricsSurfaceError, ObservabilityConfig,
ObservabilityConfigError, OtlpTraceConfig, OtlpTraceConfigError, OtlpTraceError,
RedactionLimitsError, SentryConfig, SentryConfigError, error_reporting::init_sentry,
instrumentation::register_metric_schema, logging::build_subscriber_with_tracer,
otlp::build_tracer_provider, prometheus::install_prometheus_recorder,
RedactionLimitsError, SentryConfig, SentryConfigError,
error_reporting::init_sentry,
instrumentation::register_metric_schema,
logging::build_subscriber_with_tracer,
otlp::{build_local_tracer_provider, build_tracer_provider},
prometheus::install_prometheus_recorder,
propagation::install_trace_context_propagator,
};
#[must_use = "observability resources must be retained until process shutdown"]
pub struct ObservabilityLifecycle {
metrics_handle: metrics_exporter_prometheus::PrometheusHandle,
tracer_provider: Option<opentelemetry_sdk::trace::SdkTracerProvider>,
_tracer_provider: opentelemetry_sdk::trace::SdkTracerProvider,
trace_export_enabled: bool,
sentry_guard: Option<sentry::ClientInitGuard>,
}
impl ObservabilityLifecycle {
pub fn init(config: ObservabilityConfig) -> Result<Self, ObservabilityInitError> {
Self::init_with_exporters(
config,
SentryConfig::parse(None)?,
OtlpTraceConfig::default(),
)
}
pub fn init_with_exporters(
config: ObservabilityConfig,
sentry_config: SentryConfig,
trace_config: OtlpTraceConfig,
) -> Result<Self, ObservabilityInitError> {
let identity = config.identity().clone();
let redaction_limits = config.redaction_limits();
let sentry_config = SentryConfig::from_env()?;
let trace_config = OtlpTraceConfig::from_env()?;
let tracing = build_tracer_provider(&identity, &trace_config)?;
let tracer = tracing.as_ref().map(|(_, tracer)| tracer.clone());
let exported_tracing = build_tracer_provider(&identity, &trace_config)?;
let trace_export_enabled = exported_tracing.is_some();
let (tracer_provider, tracer) =
exported_tracing.unwrap_or_else(|| build_local_tracer_provider(&identity));
install_trace_context_propagator();
build_subscriber_with_tracer(config, io::stdout, tracer)?
build_subscriber_with_tracer(config, io::stdout, Some(tracer))?
.try_init()
.map_err(|_| ObservabilityInitError::SubscriberAlreadyInitialized)?;
let metrics_handle = install_prometheus_recorder(&identity)?;
@@ -37,7 +53,8 @@ impl ObservabilityLifecycle {
Ok(Self {
metrics_handle,
tracer_provider: tracing.map(|(provider, _)| provider),
_tracer_provider: tracer_provider,
trace_export_enabled,
sentry_guard,
})
}
@@ -47,7 +64,7 @@ impl ObservabilityLifecycle {
}
pub fn traces_enabled(&self) -> bool {
self.tracer_provider.is_some()
self.trace_export_enabled
}
pub fn critical_errors_enabled(&self) -> bool {
@@ -77,6 +94,8 @@ pub enum ObservabilityInitError {
InvalidRedactionLimits(#[from] RedactionLimitsError),
#[error("invalid log filter")]
InvalidFilter,
#[error("log event budget cannot hold canonical correlation fields")]
LogEventBudgetTooSmall,
#[error("global tracing subscriber is already initialized")]
SubscriberAlreadyInitialized,
#[error(transparent)]
crates/crank-observability/src/logging.rs
+43 -18
View File
@@ -13,6 +13,7 @@ use tracing_subscriber::{
use crate::{
ObservabilityConfig, ObservabilityInitError, RedactionLimits, ServiceIdentity,
current_request_correlation,
propagation::current_trace_id,
redaction::{redact_value, truncate_string},
schema::LogEnvelope,
@@ -38,6 +39,9 @@ where
{
let (identity, filter, limits) = config.into_parts();
limits.validate()?;
if required_correlated_log_budget(&identity) > limits.max_event_bytes {
return Err(ObservabilityInitError::LogEventBudgetTooSmall);
}
let filter = EnvFilter::try_new(filter).map_err(|_| ObservabilityInitError::InvalidFilter)?;
let formatter = JsonEventFormatter::new(identity, limits);
let fmt_layer = tracing_subscriber::fmt::layer()
@@ -58,6 +62,22 @@ where
.with(otel_layer))
}
fn required_correlated_log_budget(identity: &ServiceIdentity) -> usize {
let envelope = LogEnvelope {
timestamp: "9999-12-31T23:59:59.999999999Z".to_owned(),
level: "ERROR".to_owned(),
service: identity.service().to_owned(),
version: identity.version().to_owned(),
environment: identity.environment().to_owned(),
target: "0123456789abcdef".to_owned(),
event: "0123456789abcdef".to_owned(),
request_id: Some("r".repeat(128)),
trace_id: Some("a".repeat(32)),
fields: Map::from_iter([("truncated".to_owned(), Value::Bool(true))]),
};
serde_json::to_vec(&envelope).map_or(usize::MAX, |value| value.len().saturating_add(1))
}
#[derive(Clone, Debug)]
struct JsonEventFormatter {
identity: ServiceIdentity,
@@ -75,10 +95,10 @@ impl JsonEventFormatter {
event.record(&mut visitor);
let mut raw_fields = visitor.fields;
let request_id = take_correlation_id(&mut raw_fields, "request_id")
.map(|value| truncate_string(&value, self.limits.max_string_bytes));
.or_else(|| current_request_correlation().0);
let trace_id = take_correlation_id(&mut raw_fields, "trace_id")
.or_else(current_trace_id)
.map(|value| truncate_string(&value, self.limits.max_string_bytes));
.or_else(|| current_request_correlation().1)
.or_else(current_trace_id);
let cleaned = redact_value(&Value::Object(raw_fields), self.limits);
let fields = cleaned.as_object().cloned().unwrap_or_default();
let timestamp = OffsetDateTime::now_utc()
@@ -110,19 +130,11 @@ impl JsonEventFormatter {
let fallback_string_limit = self.limits.max_string_bytes.min(64);
envelope.target = truncate_string(&envelope.target, fallback_string_limit);
envelope.event = truncate_string(&envelope.event, fallback_string_limit);
envelope.request_id = envelope
.request_id
.map(|value| truncate_string(&value, fallback_string_limit));
envelope.trace_id = envelope
.trace_id
.map(|value| truncate_string(&value, fallback_string_limit));
let serialized = serde_json::to_string(&envelope).map_err(|_| fmt::Error)?;
if serialized.len() <= line_budget {
return Ok(serialized);
}
envelope.request_id = None;
envelope.trace_id = None;
envelope.target = truncate_string(&envelope.target, 16);
envelope.event = truncate_string(&envelope.event, 16);
let serialized = serde_json::to_string(&envelope).map_err(|_| fmt::Error)?;
@@ -202,14 +214,27 @@ impl Visit for JsonFieldVisitor {
}
fn take_correlation_id(fields: &mut Map<String, Value>, name: &str) -> Option<String> {
let value = fields.remove(name)?;
let value = match value {
Value::String(value) => value,
Value::Number(value) => value.to_string(),
Value::Bool(value) => value.to_string(),
Value::Null | Value::Array(_) | Value::Object(_) => return None,
let Value::String(value) = fields.remove(name)? else {
return None;
};
(!value.is_empty()).then_some(value)
let valid = match name {
"trace_id" => {
value.len() == 32
&& value != "00000000000000000000000000000000"
&& value
.bytes()
.all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
}
"request_id" | "correlation_id" => {
!value.is_empty()
&& value.len() <= 128
&& value
.bytes()
.all(|byte| byte.is_ascii_graphic() && byte != b',' && byte != b';')
}
_ => false,
};
valid.then_some(value)
}
fn is_correlation_field(name: &str) -> bool {
crates/crank-observability/src/otlp.rs
+87 -42
View File
@@ -1,4 +1,4 @@
use std::{collections::HashMap, env, fmt, time::Duration};
use std::{collections::HashMap, fmt, time::Duration};
use axum::http::{HeaderName, HeaderValue};
use opentelemetry::{
@@ -118,8 +118,36 @@ impl fmt::Debug for OtlpTraceConfig {
}
impl OtlpTraceConfig {
pub fn from_env() -> Result<Self, OtlpTraceConfigError> {
OtlpEnvSettings::from_env()?.into_config()
#[allow(clippy::too_many_arguments)]
pub fn from_values(
generic_endpoint: Option<String>,
traces_endpoint: Option<String>,
generic_protocol: Option<String>,
traces_protocol: Option<String>,
generic_timeout: Option<String>,
traces_timeout: Option<String>,
generic_headers: Option<String>,
traces_headers: Option<String>,
max_queue_size: usize,
max_export_batch_size: usize,
scheduled_delay: String,
batch_export_timeout: String,
) -> Result<Self, OtlpTraceConfigError> {
OtlpEnvSettings {
traces_endpoint,
generic_endpoint,
traces_protocol,
generic_protocol,
traces_timeout,
generic_timeout,
traces_headers,
generic_headers,
max_queue_size: Some(max_queue_size.to_string()),
max_export_batch_size: Some(max_export_batch_size.to_string()),
scheduled_delay: Some(scheduled_delay),
batch_export_timeout: Some(batch_export_timeout),
}
.into_config()
}
fn from_settings(settings: OtlpEnvSettings) -> Result<Self, OtlpTraceConfigError> {
@@ -232,6 +260,17 @@ impl OtlpTraceConfig {
}
}
impl Default for OtlpTraceConfig {
fn default() -> Self {
Self {
endpoint: None,
export_timeout: DEFAULT_EXPORT_TIMEOUT,
batch: OtlpBatchConfig::default(),
headers: HashMap::new(),
}
}
}
#[derive(Default)]
struct OtlpEnvSettings {
traces_endpoint: Option<String>,
@@ -249,23 +288,6 @@ struct OtlpEnvSettings {
}
impl OtlpEnvSettings {
fn from_env() -> Result<Self, OtlpTraceConfigError> {
Ok(Self {
traces_endpoint: optional_env("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT")?,
generic_endpoint: optional_env("OTEL_EXPORTER_OTLP_ENDPOINT")?,
traces_protocol: optional_env("OTEL_EXPORTER_OTLP_TRACES_PROTOCOL")?,
generic_protocol: optional_env("OTEL_EXPORTER_OTLP_PROTOCOL")?,
traces_timeout: optional_env("OTEL_EXPORTER_OTLP_TRACES_TIMEOUT")?,
generic_timeout: optional_env("OTEL_EXPORTER_OTLP_TIMEOUT")?,
traces_headers: optional_env("OTEL_EXPORTER_OTLP_TRACES_HEADERS")?,
generic_headers: optional_env("OTEL_EXPORTER_OTLP_HEADERS")?,
max_queue_size: optional_env("OTEL_BSP_MAX_QUEUE_SIZE")?,
max_export_batch_size: optional_env("OTEL_BSP_MAX_EXPORT_BATCH_SIZE")?,
scheduled_delay: optional_env("OTEL_BSP_SCHEDULE_DELAY")?,
batch_export_timeout: optional_env("OTEL_BSP_EXPORT_TIMEOUT")?,
})
}
fn into_config(self) -> Result<OtlpTraceConfig, OtlpTraceConfigError> {
OtlpTraceConfig::from_settings(self)
}
@@ -313,7 +335,28 @@ pub fn build_tracer_provider(
let processor = BatchSpanProcessor::builder(ObservedSpanExporter(exporter))
.with_batch_config(config.batch.sdk_config())
.build();
let resource = Resource::builder_empty()
let resource = trace_resource(identity);
let provider = SdkTracerProvider::builder()
.with_span_processor(processor)
.with_resource(resource)
.build();
let tracer = provider.tracer("crank");
Ok(Some((provider, tracer)))
}
pub(crate) fn build_local_tracer_provider(
identity: &ServiceIdentity,
) -> (SdkTracerProvider, SdkTracer) {
let provider = SdkTracerProvider::builder()
.with_resource(trace_resource(identity))
.build();
let tracer = provider.tracer("crank");
(provider, tracer)
}
fn trace_resource(identity: &ServiceIdentity) -> Resource {
Resource::builder_empty()
.with_attributes([
KeyValue::new("service.name", identity.service().to_owned()),
KeyValue::new("service.version", identity.version().to_owned()),
@@ -322,14 +365,7 @@ pub fn build_tracer_provider(
identity.environment().to_owned(),
),
])
.build();
let provider = SdkTracerProvider::builder()
.with_span_processor(processor)
.with_resource(resource)
.build();
let tracer = provider.tracer("crank");
Ok(Some((provider, tracer)))
.build()
}
#[derive(Debug)]
@@ -405,7 +441,7 @@ fn is_allowed_span_attribute(attribute: &KeyValue) -> bool {
};
let value = value.as_str();
match attribute.key.as_str() {
"request_id" => crate::RequestId::is_valid(value),
"request_id" => is_valid_request_id(value),
"stage" => is_allowed_span_name(value),
"outcome" => matches!(
value,
@@ -453,6 +489,14 @@ fn is_allowed_span_attribute(attribute: &KeyValue) -> bool {
}
}
fn is_valid_request_id(value: &str) -> bool {
!value.is_empty()
&& value.len() <= 128
&& value
.bytes()
.all(|byte| byte.is_ascii_graphic() && byte != b',' && byte != b';')
}
#[derive(Clone, Copy)]
enum EndpointKind {
Trace,
@@ -514,17 +558,6 @@ fn parse_headers(value: &str) -> Result<HashMap<String, String>, OtlpTraceConfig
})
}
fn optional_env(field: &'static str) -> Result<Option<String>, OtlpTraceConfigError> {
match env::var(field) {
Ok(value) if value.is_empty() => Ok(None),
Ok(value) => Ok(Some(value)),
Err(env::VarError::NotPresent) => Ok(None),
Err(env::VarError::NotUnicode(_)) => {
Err(OtlpTraceConfigError::InvalidEnvironmentEncoding { field })
}
}
}
fn usize_env(
field: &'static str,
value: Option<String>,
@@ -586,7 +619,10 @@ mod tests {
use tracing::{Instrument, info_span};
use tracing_subscriber::layer::SubscriberExt;
use super::{OtlpBatchConfig, OtlpEnvSettings, OtlpTraceConfig, build_tracer_provider};
use super::{
OtlpBatchConfig, OtlpEnvSettings, OtlpTraceConfig, build_local_tracer_provider,
build_tracer_provider,
};
use crate::ServiceIdentity;
#[test]
@@ -708,6 +744,15 @@ mod tests {
assert!(build_tracer_provider(&identity, &config).unwrap().is_none());
}
#[test]
fn local_provider_creates_valid_context_without_an_exporter() {
let identity = ServiceIdentity::try_new("admin-api", "0.3.1", "test").unwrap();
let (provider, tracer) = build_local_tracer_provider(&identity);
let span = tracer.start("http.request");
assert!(span.span_context().is_valid());
provider.shutdown().unwrap();
}
#[test]
fn real_http_protobuf_export_contains_resource_and_trace() {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
crates/crank-observability/src/prometheus.rs
+1 -44
View File
@@ -1,4 +1,4 @@
use std::{env, net::SocketAddr};
use std::net::SocketAddr;
use axum::{
Router,
@@ -19,8 +19,6 @@ use tokio::net::TcpListener;
use crate::{DURATION_BUCKETS_SECONDS, ServiceIdentity};
const METRICS_ENABLED_ENV: &str = "CRANK_METRICS_ENABLED";
const METRICS_TOKEN_ENV: &str = "CRANK_METRICS_BEARER_TOKEN";
const PROMETHEUS_CONTENT_TYPE: &str = "text/plain; version=0.0.4; charset=utf-8";
#[derive(Clone)]
@@ -62,33 +60,6 @@ impl MetricsConfig {
})
}
pub fn from_env(
bind_env: &'static str,
default_bind: SocketAddr,
) -> Result<Self, MetricsConfigError> {
let enabled = parse_enabled(env::var(METRICS_ENABLED_ENV))?;
let bind_addr = match env::var(bind_env) {
Ok(raw) => raw
.parse()
.map_err(|_| MetricsConfigError::InvalidBindAddress { field: bind_env })?,
Err(env::VarError::NotPresent) => default_bind,
Err(env::VarError::NotUnicode(_)) => {
return Err(MetricsConfigError::InvalidEnvironmentEncoding { field: bind_env });
}
};
let bearer_token = match env::var(METRICS_TOKEN_ENV) {
Ok(token) => Some(token),
Err(env::VarError::NotPresent) => None,
Err(env::VarError::NotUnicode(_)) => {
return Err(MetricsConfigError::InvalidEnvironmentEncoding {
field: METRICS_TOKEN_ENV,
});
}
};
Self::new(enabled, bind_addr, bearer_token)
}
pub fn enabled(&self) -> bool {
self.enabled
}
@@ -280,17 +251,3 @@ fn bearer_token(headers: &HeaderMap) -> Option<&[u8]> {
fn token_digest(token: &[u8]) -> [u8; 32] {
Sha256::digest(token).into()
}
fn parse_enabled(value: Result<String, env::VarError>) -> Result<bool, MetricsConfigError> {
match value {
Ok(raw) => match raw.to_ascii_lowercase().as_str() {
"true" | "1" => Ok(true),
"false" | "0" => Ok(false),
_ => Err(MetricsConfigError::InvalidEnabledFlag),
},
Err(env::VarError::NotPresent) => Ok(true),
Err(env::VarError::NotUnicode(_)) => Err(MetricsConfigError::InvalidEnvironmentEncoding {
field: METRICS_ENABLED_ENV,
}),
}
}
crates/crank-observability/tests/correlation.rs
-74
View File
@@ -1,74 +0,0 @@
use axum::http::{HeaderMap, HeaderValue};
use crank_observability::RequestId;
use uuid::Version;
#[test]
fn preserves_valid_opaque_request_id() {
let request_id = RequestId::resolve(Some("req_test-123/abc"));
assert_eq!(request_id.as_str(), "req_test-123/abc");
}
#[test]
fn replaces_missing_and_invalid_values_with_uuid_v7() {
for candidate in [
None,
Some(""),
Some("bad value"),
Some(" leading"),
Some("trailing "),
Some("bad,value"),
Some("bad;value"),
Some("я"),
] {
let request_id = RequestId::resolve(candidate);
let parsed = uuid::Uuid::parse_str(request_id.as_str()).expect("generated UUID");
assert_eq!(parsed.get_version(), Some(Version::SortRand));
}
}
#[test]
fn rejects_values_over_the_shared_limit() {
let oversized = "x".repeat(RequestId::MAX_LEN + 1);
let request_id = RequestId::resolve(Some(&oversized));
assert_ne!(request_id.as_str(), oversized);
assert_eq!(
uuid::Uuid::parse_str(request_id.as_str())
.expect("generated UUID")
.get_version(),
Some(Version::SortRand)
);
}
#[test]
fn resolves_exactly_one_header_value_and_rejects_ambiguous_values() {
let mut single = HeaderMap::new();
single.insert(
"x-request-id",
HeaderValue::from_static("opaque-request-id"),
);
assert_eq!(
RequestId::resolve_from_headers(&single).as_str(),
"opaque-request-id"
);
let mut ambiguous = HeaderMap::new();
ambiguous.append("x-request-id", HeaderValue::from_static("first-request-id"));
ambiguous.append(
"x-request-id",
HeaderValue::from_static("second-request-id"),
);
let generated = RequestId::resolve_from_headers(&ambiguous);
assert_ne!(generated.as_str(), "first-request-id");
assert_ne!(generated.as_str(), "second-request-id");
assert_eq!(
uuid::Uuid::parse_str(generated.as_str())
.expect("generated UUID")
.get_version(),
Some(Version::SortRand)
);
}
crates/crank-observability/tests/json_logging.rs
+6 -19
View File
@@ -132,11 +132,11 @@ fn correlation_fields_are_distinct_and_only_present_when_recorded() {
tracing::info!(
name: "admin.request.completed",
request_id = "req-123",
trace_id = "trace-456"
trace_id = "0af7651916cd43dd8448eb211c80319c"
);
});
assert_eq!(present[0]["request_id"], "req-123");
assert_eq!(present[0]["trace_id"], "trace-456");
assert_eq!(present[0]["trace_id"], "0af7651916cd43dd8448eb211c80319c");
assert!(present[0]["fields"].get("request_id").is_none());
assert!(present[0]["fields"].get("trace_id").is_none());
@@ -148,7 +148,7 @@ fn correlation_fields_are_distinct_and_only_present_when_recorded() {
}
#[test]
fn correlation_fields_preserve_scalar_display_values_before_field_limits() {
fn correlation_fields_accept_valid_strings_and_reject_non_string_values() {
let limits = RedactionLimits {
max_object_fields: 1,
..RedactionLimits::default()
@@ -164,7 +164,7 @@ fn correlation_fields_preserve_scalar_display_values_before_field_limits() {
});
assert_eq!(events[0]["request_id"], "123");
assert_eq!(events[0]["trace_id"], "true");
assert!(events[0].get("trace_id").is_none());
}
#[test]
@@ -321,7 +321,7 @@ fn subscriber_rejects_limits_that_cannot_hold_an_event() {
}
#[test]
fn minimum_event_budget_handles_maximum_identity_labels() {
fn event_budget_rejects_maximum_identity_labels_when_correlation_cannot_fit() {
let writer = SharedWriter::default();
let config = ObservabilityConfig::new(
ServiceIdentity::try_new("s".repeat(64), "v".repeat(64), "e".repeat(64))
@@ -332,20 +332,7 @@ fn minimum_event_budget_handles_maximum_identity_labels() {
..RedactionLimits::default()
},
);
let subscriber =
build_subscriber(config, writer.clone()).expect("minimum valid budget must be usable");
tracing::subscriber::with_default(subscriber, || {
tracing::info!(
name: "event-name-that-is-intentionally-longer-than-the-fallback-limit",
description = %"x".repeat(4096),
);
});
let output = writer.output();
assert!(output.len() <= 512);
assert_eq!(output.lines().count(), 1);
serde_json::from_str::<Value>(output.trim_end()).expect("bounded line must remain valid JSON");
assert!(build_subscriber(config, writer).is_err());
}
#[test]
crates/crank-observability/tests/prometheus.rs
+2
View File
@@ -97,6 +97,8 @@ fn schema_is_closed_and_uses_fixed_duration_buckets() {
"agent_id",
"operation_id",
"request_id",
"trace_id",
"correlation_id",
"url",
"error_message",
"text",
crates/crank-observability/tests/request_correlation.rs
+60
View File
@@ -0,0 +1,60 @@
use std::sync::Arc;
use crank_observability::{current_request_correlation, with_request_correlation};
#[tokio::test]
async fn concurrent_request_correlation_is_task_local() {
let barrier = Arc::new(tokio::sync::Barrier::new(2));
let first = observe(
"request-first",
"0af7651916cd43dd8448eb211c80319c",
Arc::clone(&barrier),
);
let second = observe(
"request-second",
"1af7651916cd43dd8448eb211c80319c",
barrier,
);
let (first, second) = tokio::join!(first, second);
assert_eq!(
first,
(
Some("request-first".to_owned()),
Some("0af7651916cd43dd8448eb211c80319c".to_owned()),
)
);
assert_eq!(
second,
(
Some("request-second".to_owned()),
Some("1af7651916cd43dd8448eb211c80319c".to_owned()),
)
);
assert_eq!(current_request_correlation(), (None, None));
}
#[tokio::test]
async fn invalid_correlation_strings_never_enter_task_local_state() {
let observed = with_request_correlation(
"bad request id".to_owned(),
"CANARY-NOT-A-TRACE-ID".to_owned(),
async { current_request_correlation() },
)
.await;
assert_eq!(observed, (None, None));
}
async fn observe(
request_id: &str,
trace_id: &str,
barrier: Arc<tokio::sync::Barrier>,
) -> (Option<String>, Option<String>) {
with_request_correlation(request_id.to_owned(), trace_id.to_owned(), async move {
barrier.wait().await;
tokio::task::yield_now().await;
current_request_correlation()
})
.await
}
crates/crank-registry/src/error.rs
+4
View File
@@ -2,6 +2,8 @@ use thiserror::Error;
#[derive(Debug, Error)]
pub enum RegistryError {
#[error(transparent)]
Migration(#[from] crate::migrations::MigrationError),
#[error(transparent)]
Storage(#[from] sqlx::Error),
#[error(transparent)]
@@ -80,4 +82,6 @@ pub enum RegistryError {
InvalidEnumRepresentation { field: &'static str },
#[error("invalid numeric value for field {field}: {value}")]
InvalidNumericValue { field: &'static str, value: i64 },
#[error("invalid correlation identity for field {field}")]
InvalidCorrelationIdentity { field: &'static str },
}
crates/crank-registry/src/ext.rs
+5 -68
View File
@@ -1,77 +1,14 @@
use std::sync::Arc;
use sqlx::{PgPool, query};
use crate::RegistryError;
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ExtensionMigration {
pub version: u32,
pub sql: &'static str,
pub checksum: &'static str,
pub source_digest: &'static str,
pub phase: &'static str,
pub compatibility: &'static str,
pub owner: &'static str,
}
pub trait RegistryExtension: Send + Sync {
fn name(&self) -> &str;
fn migrations(&self) -> &[ExtensionMigration];
}
pub async fn apply_extension_migrations(
pool: &PgPool,
extensions: &[Arc<dyn RegistryExtension>],
) -> Result<(), RegistryError> {
query(
"create table if not exists __crank_ext_migrations (
extension_name text not null,
version integer not null,
applied_at timestamptz not null default now(),
primary key (extension_name, version)
)",
)
.execute(pool)
.await?;
for extension in extensions {
for migration in extension.migrations() {
let already_applied = query(
"select 1
from __crank_ext_migrations
where extension_name = $1 and version = $2",
)
.bind(extension.name())
.bind(i32::try_from(migration.version).map_err(|_| {
RegistryError::InvalidNumericValue {
field: "extension_migration.version",
value: migration.version as i64,
}
})?)
.fetch_optional(pool)
.await?
.is_some();
if already_applied {
continue;
}
let mut tx = pool.begin().await?;
query(migration.sql).execute(&mut *tx).await?;
query(
"insert into __crank_ext_migrations (extension_name, version)
values ($1, $2)",
)
.bind(extension.name())
.bind(i32::try_from(migration.version).map_err(|_| {
RegistryError::InvalidNumericValue {
field: "extension_migration.version",
value: migration.version as i64,
}
})?)
.execute(&mut *tx)
.await?;
tx.commit().await?;
}
}
Ok(())
}
crates/crank-registry/src/lib.rs
+10 -2
View File
@@ -5,7 +5,11 @@ mod model;
mod postgres;
pub use error::RegistryError;
pub use ext::{ExtensionMigration, RegistryExtension, apply_extension_migrations};
pub use ext::{ExtensionMigration, RegistryExtension};
pub use migrations::{
BackfillBatch, BackfillPolicy, MigrationApplyResult, MigrationAuthority, MigrationDescriptor,
MigrationError, MigrationPreflight,
};
pub mod records {
pub use crate::model::{
@@ -39,8 +43,12 @@ pub mod requests {
}
pub mod infrastructure {
pub use crate::ext::{ExtensionMigration, RegistryExtension, apply_extension_migrations};
pub use crate::ext::{ExtensionMigration, RegistryExtension};
pub use crate::postgres::{PostgresPoolConfig, PostgresPoolConfigError, PostgresRegistry};
pub use crate::{
BackfillBatch, BackfillPolicy, MigrationApplyResult, MigrationAuthority,
MigrationDescriptor, MigrationError, MigrationPreflight,
};
}
pub use model::{
crates/crank-registry/src/migrations.rs
+8 -719
View File
@@ -1,721 +1,10 @@
use sqlx::{PgPool, Postgres, Row, Transaction, query};
mod authority;
mod baseline_v1;
mod schema_guard;
const CORE_MIGRATION_LOCK_ID: i64 = 0x43_52_41_4E_4B;
const BASELINE_VERSION: i32 = 1;
const BASELINE_CHECKSUM: &str = "crank-community-baseline-v1";
pub use authority::{
BackfillBatch, BackfillPolicy, MigrationApplyResult, MigrationAuthority, MigrationDescriptor,
MigrationError, MigrationPreflight,
};
pub async fn apply_postgres(pool: &PgPool) -> Result<(), sqlx::Error> {
let mut transaction = pool.begin().await?;
query("select pg_advisory_xact_lock($1)")
.bind(CORE_MIGRATION_LOCK_ID)
.execute(&mut *transaction)
.await?;
query(
"create table if not exists __crank_core_migrations (
version integer primary key,
description text not null,
checksum text not null,
applied_at timestamptz not null default now()
)",
)
.execute(&mut *transaction)
.await?;
let applied = query(
"select version, checksum
from __crank_core_migrations
order by version",
)
.fetch_all(&mut *transaction)
.await?;
for row in &applied {
let version = row.try_get::<i32, _>("version")?;
let checksum = row.try_get::<String, _>("checksum")?;
if version != BASELINE_VERSION || checksum != BASELINE_CHECKSUM {
return Err(sqlx::Error::Protocol(format!(
"unsupported or modified core migration: version={version}, checksum={checksum}"
)));
}
}
if applied.is_empty() {
apply_baseline(&mut transaction).await?;
query(
"insert into __crank_core_migrations (version, description, checksum)
values ($1, $2, $3)",
)
.bind(BASELINE_VERSION)
.bind("community baseline")
.bind(BASELINE_CHECKSUM)
.execute(&mut *transaction)
.await?;
}
transaction.commit().await?;
Ok(())
}
async fn apply_baseline(transaction: &mut Transaction<'_, Postgres>) -> Result<(), sqlx::Error> {
query(
"create table if not exists workspaces (
id text primary key,
slug text not null unique,
display_name text not null,
status text not null,
settings_json jsonb not null default '{}'::jsonb,
created_at timestamptz not null,
updated_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists users (
id text primary key,
email text not null unique,
display_name text not null,
password_hash text null,
status text not null,
created_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query("alter table users add column if not exists password_hash text null")
.execute(&mut **transaction)
.await?;
query(
"insert into users (
id,
email,
display_name,
status,
created_at
) values (
'user_default_owner',
'owner@crank.local',
'Workspace Owner',
'active',
now()
)
on conflict (id) do nothing",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists memberships (
workspace_id text not null references workspaces(id) on delete cascade,
user_id text not null references users(id) on delete cascade,
role text not null,
created_at timestamptz not null,
primary key (workspace_id, user_id)
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists user_sessions (
id text primary key,
user_id text not null references users(id) on delete cascade,
current_workspace_id text null references workspaces(id) on delete set null,
secret_hash text not null,
status text not null,
expires_at timestamptz not null,
last_seen_at timestamptz null,
created_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query(
"alter table user_sessions
add column if not exists current_workspace_id text null references workspaces(id) on delete set null",
)
.execute(&mut **transaction)
.await?;
query(
"insert into workspaces (
id,
slug,
display_name,
status,
settings_json,
created_at,
updated_at
) values (
'ws_default',
'default',
'Default Workspace',
'active',
'{}'::jsonb,
now(),
now()
)
on conflict (id) do nothing",
)
.execute(&mut **transaction)
.await?;
query(
"insert into memberships (
workspace_id,
user_id,
role,
created_at
) values (
'ws_default',
'user_default_owner',
'owner',
now()
)
on conflict (workspace_id, user_id) do nothing",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists invitation_tokens (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
email text not null,
role text not null,
status text not null,
token_hash text not null,
expires_at timestamptz not null,
created_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists platform_api_keys (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
agent_id text null,
name text not null,
prefix text not null,
secret_hash text not null,
key_kind text not null default 'mcp_client',
scopes_json jsonb not null,
status text not null,
created_at timestamptz not null,
last_used_at timestamptz null,
revoked_at timestamptz null,
expires_at timestamptz null,
allowed_origins_json jsonb not null default '[]'::jsonb
)",
)
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists platform_api_keys_workspace_name_idx on platform_api_keys(workspace_id, name)",
)
.execute(&mut **transaction)
.await?;
query("alter table platform_api_keys add column if not exists agent_id text null")
.execute(&mut **transaction)
.await?;
query(
"alter table platform_api_keys add column if not exists key_kind text not null default 'mcp_client'",
)
.execute(&mut **transaction)
.await?;
query("alter table platform_api_keys add column if not exists expires_at timestamptz null")
.execute(&mut **transaction)
.await?;
query(
"alter table platform_api_keys add column if not exists allowed_origins_json jsonb not null default '[]'::jsonb",
)
.execute(&mut **transaction)
.await?;
query(
"insert into workspaces (
id,
slug,
display_name,
status,
settings_json,
created_at,
updated_at
) values (
'ws_default',
'default',
'Default Workspace',
'active',
'{}'::jsonb,
now(),
now()
)
on conflict (id) do nothing",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists operations (
id text primary key,
workspace_id text null references workspaces(id) on delete cascade,
name text not null,
display_name text not null,
category text not null default 'general',
protocol text not null,
security_level text not null default 'standard',
status text not null,
current_draft_version integer not null default 1,
latest_published_version integer null,
created_at timestamptz not null,
updated_at timestamptz not null,
published_at timestamptz null
)",
)
.execute(&mut **transaction)
.await?;
query("alter table operations add column if not exists workspace_id text null references workspaces(id) on delete cascade")
.execute(&mut **transaction)
.await?;
query(
"alter table operations add column if not exists category text not null default 'general'",
)
.execute(&mut **transaction)
.await?;
query(
"alter table operations add column if not exists security_level text not null default 'standard'",
)
.execute(&mut **transaction)
.await?;
query("update operations set workspace_id = 'ws_default' where workspace_id is null")
.execute(&mut **transaction)
.await?;
query("alter table operations alter column workspace_id set not null")
.execute(&mut **transaction)
.await?;
query("alter table operations drop constraint if exists operations_name_key")
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists operations_workspace_name_idx on operations(workspace_id, name)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists operation_versions (
operation_id text not null references operations(id) on delete cascade,
version integer not null,
status text not null,
target_json jsonb not null,
input_schema_json jsonb not null,
output_schema_json jsonb not null,
input_mapping_json jsonb not null,
output_mapping_json jsonb not null,
execution_config_json jsonb not null,
tool_description_json jsonb not null,
samples_json jsonb null,
generated_draft_json jsonb null,
config_export_json jsonb null,
wizard_state_json jsonb null,
change_note text null,
created_at timestamptz not null,
created_by text null,
primary key (operation_id, version)
)",
)
.execute(&mut **transaction)
.await?;
query("alter table operation_versions add column if not exists wizard_state_json jsonb null")
.execute(&mut **transaction)
.await?;
query(
"create table if not exists published_operations (
operation_id text primary key references operations(id) on delete cascade,
version integer not null,
published_at timestamptz not null,
published_by text null,
foreign key (operation_id, version) references operation_versions(operation_id, version) on delete cascade
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists operation_samples (
id text primary key,
operation_id text not null references operations(id) on delete cascade,
version integer not null,
sample_kind text not null,
storage_ref text not null,
content_type text not null,
file_name text null,
created_at timestamptz not null,
foreign key (operation_id, version) references operation_versions(operation_id, version) on delete cascade
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists descriptors (
id text primary key,
operation_id text null references operations(id) on delete cascade,
version integer null,
descriptor_kind text not null,
storage_ref text not null,
source_name text null,
package_index_json jsonb null,
created_at timestamptz not null,
foreign key (operation_id, version) references operation_versions(operation_id, version) on delete cascade
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists auth_profiles (
id text primary key,
workspace_id text null references workspaces(id) on delete cascade,
name text not null,
kind text not null,
config_json jsonb not null,
created_at timestamptz not null,
updated_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query("alter table auth_profiles add column if not exists workspace_id text null references workspaces(id) on delete cascade")
.execute(&mut **transaction)
.await?;
query("update auth_profiles set workspace_id = 'ws_default' where workspace_id is null")
.execute(&mut **transaction)
.await?;
query("alter table auth_profiles alter column workspace_id set not null")
.execute(&mut **transaction)
.await?;
query("alter table auth_profiles drop constraint if exists auth_profiles_name_key")
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists auth_profiles_workspace_name_idx on auth_profiles(workspace_id, name)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists workspace_upstreams (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
name text not null,
base_url text not null,
static_headers_json jsonb not null default '{}'::jsonb,
auth_profile_id text null references auth_profiles(id) on delete set null,
created_at timestamptz not null,
updated_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists workspace_upstreams_workspace_name_idx on workspace_upstreams(workspace_id, name)",
)
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists workspace_upstreams_workspace_base_auth_idx on workspace_upstreams(workspace_id, base_url, coalesce(auth_profile_id, ''))",
)
.execute(&mut **transaction)
.await?;
query(
"insert into workspace_upstreams (
id,
workspace_id,
name,
base_url,
static_headers_json,
auth_profile_id,
created_at,
updated_at
)
select
'upstream_frankfurter_' || w.id,
w.id,
'Frankfurter',
'https://api.frankfurter.dev',
'{}'::jsonb,
null,
now(),
now()
from workspaces w
where not exists (
select 1
from workspace_upstreams wu
where wu.workspace_id = w.id
and wu.name = 'Frankfurter'
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists secrets (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
name text not null,
kind text not null,
status text not null,
current_version integer not null,
last_used_at timestamptz null,
created_at timestamptz not null,
updated_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists secrets_workspace_name_idx on secrets(workspace_id, name)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists secret_versions (
secret_id text not null references secrets(id) on delete cascade,
version integer not null,
ciphertext text not null,
key_version text not null,
created_at timestamptz not null,
created_by text null references users(id) on delete set null,
primary key (secret_id, version)
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists yaml_import_jobs (
id text primary key,
source_sample_id text null references operation_samples(id) on delete set null,
status text not null,
format_version text not null,
mode text not null,
result_operation_id text null references operations(id) on delete set null,
result_version integer null,
error_text text null,
created_at timestamptz not null,
finished_at timestamptz null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists import_jobs (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
kind text not null,
source_format text not null,
source_version text null,
status text not null,
preview_payload jsonb not null,
created_operation_ids jsonb not null default '[]'::jsonb,
error_text text null,
created_at timestamptz not null,
expires_at timestamptz not null,
finished_at timestamptz null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists agents (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
slug text not null,
display_name text not null,
description text not null,
status text not null,
current_draft_version integer not null default 1,
latest_published_version integer null,
created_at timestamptz not null,
updated_at timestamptz not null,
published_at timestamptz null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists agents_workspace_slug_idx on agents(workspace_id, slug)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists agent_versions (
agent_id text not null references agents(id) on delete cascade,
version integer not null,
status text not null,
instructions_json jsonb not null,
tool_selection_policy_json jsonb not null,
created_at timestamptz not null,
primary key (agent_id, version)
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists agent_operation_bindings (
agent_id text not null references agents(id) on delete cascade,
agent_version integer not null,
operation_id text not null references operations(id) on delete cascade,
operation_version integer not null,
tool_name text not null,
tool_title text not null,
tool_description_override text null,
enabled boolean not null default true,
foreign key (agent_id, agent_version) references agent_versions(agent_id, version) on delete cascade,
foreign key (operation_id, operation_version) references operation_versions(operation_id, version) on delete cascade
)",
)
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists agent_bindings_tool_name_idx on agent_operation_bindings(agent_id, agent_version, tool_name)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists published_agents (
agent_id text primary key references agents(id) on delete cascade,
version integer not null,
published_at timestamptz not null,
published_by text null,
foreign key (agent_id, version) references agent_versions(agent_id, version) on delete cascade
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists approval_requests (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
agent_id text not null references agents(id) on delete cascade,
operation_id text not null references operations(id) on delete cascade,
operation_version integer not null,
status text not null,
risk_level text not null,
request_payload_json jsonb not null,
response_payload_json jsonb null,
created_at timestamptz not null,
expires_at timestamptz not null,
decided_at timestamptz null,
decided_by_key_id text null references platform_api_keys(id) on delete set null,
decision_note text null
)",
)
.execute(&mut **transaction)
.await?;
query("alter table approval_requests add column if not exists execution_started_at timestamptz null")
.execute(&mut **transaction)
.await?;
query("alter table approval_requests add column if not exists execution_attempts integer not null default 0")
.execute(&mut **transaction)
.await?;
query("alter table approval_requests add column if not exists request_fingerprint text null")
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists approval_requests_pending_fingerprint_idx
on approval_requests(agent_id, operation_id, operation_version, request_fingerprint)
where status = 'pending' and request_fingerprint is not null",
)
.execute(&mut **transaction)
.await?;
query(
"create index if not exists approval_requests_agent_status_idx
on approval_requests(workspace_id, agent_id, status, expires_at)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists invocation_logs (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
agent_id text null references agents(id) on delete set null,
operation_id text not null references operations(id) on delete cascade,
source text not null,
level text not null,
status text not null,
tool_name text not null,
message text not null,
request_id text null,
status_code integer null,
duration_ms bigint not null,
error_kind text null,
request_preview_json jsonb not null,
response_preview_json jsonb not null,
created_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create index if not exists invocation_logs_workspace_created_idx on invocation_logs(workspace_id, created_at desc)",
)
.execute(&mut **transaction)
.await?;
query(
"create index if not exists invocation_logs_workspace_operation_created_idx on invocation_logs(workspace_id, operation_id, created_at desc)",
)
.execute(&mut **transaction)
.await?;
query(
"create index if not exists invocation_logs_workspace_agent_created_idx on invocation_logs(workspace_id, agent_id, created_at desc)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists usage_rollups (
workspace_id text not null references workspaces(id) on delete cascade,
agent_id text null references agents(id) on delete cascade,
operation_id text null references operations(id) on delete cascade,
period text not null,
calls_total bigint not null,
calls_ok bigint not null,
calls_error bigint not null,
p50_ms bigint not null,
p95_ms bigint not null,
p99_ms bigint not null,
updated_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
Ok(())
}
use baseline_v1::{BASELINE_CHECKSUM, BASELINE_VERSION, apply_baseline};
crates/crank-registry/src/migrations/authority.rs
+926
View File
@@ -0,0 +1,926 @@
use std::fmt;
use sha2::{Digest, Sha256};
use sqlx::{PgConnection, PgPool, Row, Transaction, query};
use super::schema_guard::{
OWNED_RELATIONS, relation_exists, validate_required_relations, validate_schema_fingerprint,
};
use super::{BASELINE_CHECKSUM, BASELINE_VERSION, apply_baseline};
use crate::ext::ExtensionMigration;
const MIGRATION_LOCK_ID: i64 = 0x4352_414E_4B4D_4947;
const CURRENT_VERSION: i64 = 3;
const IMPLEMENTED_VERSIONS: &[i64] = &[1, 2, 3];
const BASELINE_SOURCE_SHA256: &str =
"eb1656fc5b4b5be9ee390d237d1d58e4b2274ae5ba9b7ba06a2f3f860dfda675";
const CONSOLIDATION_SOURCE: &str = include_str!("consolidation_v2.sql");
const CONSOLIDATION_SOURCE_SHA256: &str =
"1908b97ca7fe8a85d146b0eebf007d5018a9ff406cb099614270f3428ec1db48";
const REQUEST_TRACE_IDENTITY_SOURCE: &str = include_str!("request_trace_identity_v3.sql");
const REQUEST_TRACE_IDENTITY_SOURCE_SHA256: &str =
"36487625503a8d4d8f18d5771c3c9b6705f845e267acbfcb7244c330f640cd94";
const BASELINE_RELATIONS: &[&str] = &[
"workspaces",
"users",
"memberships",
"user_sessions",
"invitation_tokens",
"platform_api_keys",
"operations",
"operation_versions",
"published_operations",
"operation_samples",
"descriptors",
"agents",
"agent_versions",
"published_agents",
"agent_operation_bindings",
"secrets",
"secret_versions",
"auth_profiles",
"workspace_upstreams",
"yaml_import_jobs",
"import_jobs",
"approval_requests",
"invocation_logs",
"usage_rollups",
];
const CONSOLIDATION_RELATIONS: &[&str] = &[
"__crank_migrations",
"__crank_migration_legacy_audit",
"__crank_mcp_migrations",
"mcp_transport_sessions",
"__crank_ext_migrations",
];
const REGISTERED_EXTENSION_MIGRATIONS: &[(&str, ExtensionMigration)] = &[];
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct MigrationDescriptor {
pub version: i64,
pub name: &'static str,
pub checksum: String,
pub source_digest: String,
pub phase: &'static str,
pub compatibility: &'static str,
pub owner: &'static str,
pub transactional: bool,
pub backfill: BackfillPolicy,
pub readable_schema_min: i64,
pub readable_schema_max: i64,
pub contract_evidence: Option<&'static str>,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum BackfillPolicy {
None,
Bounded {
max_batch_rows: u32,
max_batch_ms: u32,
resumable: bool,
},
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct BackfillBatch {
pub cursor: Option<String>,
pub max_rows: u32,
pub max_ms: u32,
}
impl BackfillBatch {
pub fn validate(&self, policy: BackfillPolicy) -> Result<(), MigrationError> {
match policy {
BackfillPolicy::Bounded {
max_batch_rows,
max_batch_ms,
resumable: true,
} if (1..=max_batch_rows).contains(&self.max_rows)
&& (1..=max_batch_ms).contains(&self.max_ms)
&& self
.cursor
.as_ref()
.is_none_or(|cursor| cursor.len() <= 256) =>
{
Ok(())
}
_ => Err(MigrationError::new(
"invalid_contract",
"contract.backfill",
None,
"contact_operator",
)),
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum MigrationPreflight {
Current { version: i64 },
MigrationRequired { current: i64, target: i64 },
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum MigrationApplyResult {
Applied { from: i64, to: i64 },
AlreadyCurrent { version: i64 },
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct MigrationError {
code: &'static str,
stage: &'static str,
version: Option<i64>,
recovery: &'static str,
}
impl MigrationError {
pub(super) fn new(
code: &'static str,
stage: &'static str,
version: Option<i64>,
recovery: &'static str,
) -> Self {
Self {
code,
stage,
version,
recovery,
}
}
pub(super) fn storage(stage: &'static str) -> Self {
Self::new("storage_unavailable", stage, None, "contact_operator")
}
pub fn code(&self) -> &'static str {
self.code
}
pub fn stage(&self) -> &'static str {
self.stage
}
pub fn version(&self) -> Option<i64> {
self.version
}
pub fn recovery(&self) -> &'static str {
self.recovery
}
}
impl fmt::Display for MigrationError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
formatter,
"migration_error code={} stage={} version={} recovery={}",
self.code,
self.stage,
self.version
.map_or_else(|| "none".to_owned(), |value| value.to_string()),
self.recovery
)
}
}
impl std::error::Error for MigrationError {}
pub struct MigrationAuthority;
impl MigrationAuthority {
pub fn registered_extension_migrations() -> &'static [(&'static str, ExtensionMigration)] {
REGISTERED_EXTENSION_MIGRATIONS
}
pub fn sequence() -> Vec<MigrationDescriptor> {
vec![
MigrationDescriptor {
version: i64::from(BASELINE_VERSION),
name: "community-baseline-v1",
checksum: BASELINE_CHECKSUM.to_owned(),
source_digest: BASELINE_SOURCE_SHA256.to_owned(),
phase: "expand",
compatibility: "legacy-baseline",
owner: "crank-registry",
transactional: true,
backfill: BackfillPolicy::None,
readable_schema_min: 1,
readable_schema_max: 1,
contract_evidence: None,
},
MigrationDescriptor {
version: 2,
name: "legacy-consolidation-v2",
checksum: CONSOLIDATION_SOURCE_SHA256.to_owned(),
source_digest: CONSOLIDATION_SOURCE_SHA256.to_owned(),
phase: "expand",
compatibility: "n-minus-one-readable",
owner: "crank-registry",
transactional: true,
backfill: BackfillPolicy::None,
readable_schema_min: 1,
readable_schema_max: 2,
contract_evidence: None,
},
MigrationDescriptor {
version: 3,
name: "request-trace-identity-v3",
checksum: REQUEST_TRACE_IDENTITY_SOURCE_SHA256.to_owned(),
source_digest: REQUEST_TRACE_IDENTITY_SOURCE_SHA256.to_owned(),
phase: "expand",
compatibility: "n-minus-one-readable",
owner: "crank-registry",
transactional: true,
backfill: BackfillPolicy::None,
readable_schema_min: 2,
readable_schema_max: 3,
contract_evidence: None,
},
]
}
pub fn validate_sequence() -> Result<(), MigrationError> {
validate_descriptors(&Self::sequence())
}
pub async fn preflight(pool: &PgPool) -> Result<MigrationPreflight, MigrationError> {
Self::validate_sequence()?;
let mut connection = pool
.acquire()
.await
.map_err(|_| MigrationError::storage("preflight.connect"))?;
inspect(&mut connection).await
}
pub async fn require_current(pool: &PgPool) -> Result<(), MigrationError> {
match Self::preflight(pool).await? {
MigrationPreflight::Current { .. } => Ok(()),
MigrationPreflight::MigrationRequired { current: 0, .. } => Err(MigrationError::new(
"schema_missing",
"preflight.compatibility",
Some(0),
"run_controlled_migration",
)),
MigrationPreflight::MigrationRequired { current, .. } => Err(MigrationError::new(
"migration_required",
"preflight.compatibility",
Some(current),
"run_controlled_migration",
)),
}
}
pub async fn apply(pool: &PgPool) -> Result<MigrationApplyResult, MigrationError> {
Self::validate_sequence()?;
let mut transaction = pool
.begin()
.await
.map_err(|_| MigrationError::storage("apply.begin"))?;
query("set local lock_timeout = '30s'")
.execute(&mut *transaction)
.await
.map_err(|_| MigrationError::storage("apply.lock_policy"))?;
query("select pg_advisory_xact_lock($1)")
.bind(MIGRATION_LOCK_ID)
.execute(&mut *transaction)
.await
.map_err(|error| {
if error
.as_database_error()
.and_then(|database| database.code())
.is_some_and(|code| matches!(code.as_ref(), "55P03" | "57014"))
{
MigrationError::new("lock_timeout", "apply.lock", None, "run_preflight")
} else {
MigrationError::storage("apply.lock")
}
})?;
let before = inspect(&mut transaction).await?;
let from = match before {
MigrationPreflight::Current { version } => {
transaction
.commit()
.await
.map_err(|_| MigrationError::storage("apply.commit"))?;
return Ok(MigrationApplyResult::AlreadyCurrent { version });
}
MigrationPreflight::MigrationRequired { current, .. } => current,
};
if from == 0 {
create_core_ledger(&mut transaction).await?;
apply_baseline(&mut transaction).await.map_err(|_| {
MigrationError::new(
"apply_failed",
"apply.baseline",
Some(1),
"restore_known_good_backup",
)
})?;
query(
"insert into __crank_core_migrations (version, description, checksum)
values (1, 'community baseline', $1)",
)
.bind(BASELINE_CHECKSUM)
.execute(&mut *transaction)
.await
.map_err(|_| {
MigrationError::new(
"apply_failed",
"apply.baseline_ledger",
Some(1),
"restore_known_good_backup",
)
})?;
}
if from < 2 {
apply_consolidation(&mut transaction).await?;
}
if from < 3 {
apply_request_trace_identity(&mut transaction).await?;
}
transaction
.commit()
.await
.map_err(|_| MigrationError::storage("apply.commit"))?;
Ok(MigrationApplyResult::Applied {
from,
to: CURRENT_VERSION,
})
}
}
fn sha256_hex(bytes: &[u8]) -> String {
format!("{:x}", Sha256::digest(bytes))
}
#[cfg(test)]
fn baseline_source_digest() -> String {
let source = include_str!("baseline_v1.rs");
let (_, baseline) = source
.split_once("// baseline-v1:start\n")
.expect("baseline start marker must exist");
let (baseline, _) = baseline
.split_once("// baseline-v1:end")
.expect("baseline end marker must exist");
sha256_hex(baseline.as_bytes())
}
fn validate_descriptors(descriptors: &[MigrationDescriptor]) -> Result<(), MigrationError> {
if descriptors.is_empty() || descriptors.len() > 1_024 {
return Err(MigrationError::new(
"invalid_contract",
"contract.sequence",
None,
"contact_operator",
));
}
for (index, descriptor) in descriptors.iter().enumerate() {
let expected_version = i64::try_from(index + 1).unwrap_or(i64::MAX);
let valid_name = !descriptor.name.is_empty()
&& descriptor.name.len() <= 128
&& descriptor
.name
.bytes()
.all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
&& !descriptors[..index]
.iter()
.any(|prior| prior.name == descriptor.name);
let valid_source_digest = descriptor.source_digest.len() == 64
&& descriptor
.source_digest
.bytes()
.all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase());
let valid_checksum = if descriptor.version == 1 {
descriptor.checksum == BASELINE_CHECKSUM
} else {
descriptor.checksum == descriptor.source_digest
};
let valid_window = descriptor.readable_schema_min >= 1
&& descriptor.readable_schema_min <= descriptor.readable_schema_max
&& descriptor.readable_schema_max <= descriptor.version;
let valid_phase = match descriptor.phase {
"expand" => descriptor.backfill == BackfillPolicy::None,
"migrate" => matches!(
descriptor.backfill,
BackfillPolicy::Bounded {
max_batch_rows: 1..=10_000,
max_batch_ms: 1..=60_000,
resumable: true,
}
),
"contract" => {
descriptor.compatibility == "window-closed"
&& descriptor.contract_evidence.is_some_and(|evidence| {
!evidence.is_empty()
&& evidence.len() <= 256
&& !evidence.starts_with('/')
&& !evidence.contains("..")
})
&& descriptor.backfill == BackfillPolicy::None
}
_ => false,
};
let valid_compatibility = matches!(
descriptor.compatibility,
"legacy-baseline" | "n-minus-one-readable" | "window-open" | "window-closed"
);
let valid_owner = !descriptor.owner.is_empty()
&& descriptor.owner.len() <= 128
&& descriptor
.owner
.bytes()
.all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-');
if descriptor.version != expected_version
|| !valid_name
|| !valid_source_digest
|| !valid_checksum
|| !valid_phase
|| !valid_compatibility
|| !valid_owner
|| !valid_window
|| !descriptor.transactional
{
return Err(MigrationError::new(
"invalid_contract",
"contract.sequence",
Some(descriptor.version),
"contact_operator",
));
}
}
if descriptors.len() != usize::try_from(CURRENT_VERSION).unwrap_or_default()
|| descriptors
.iter()
.map(|descriptor| descriptor.version)
.ne(IMPLEMENTED_VERSIONS.iter().copied())
|| sha256_hex(CONSOLIDATION_SOURCE.as_bytes()) != CONSOLIDATION_SOURCE_SHA256
|| sha256_hex(REQUEST_TRACE_IDENTITY_SOURCE.as_bytes())
!= REQUEST_TRACE_IDENTITY_SOURCE_SHA256
{
return Err(MigrationError::new(
"invalid_contract",
"contract.implementation",
Some(CURRENT_VERSION),
"contact_operator",
));
}
Ok(())
}
async fn inspect(connection: &mut PgConnection) -> Result<MigrationPreflight, MigrationError> {
let core_exists = relation_exists(connection, "__crank_core_migrations").await?;
let canonical_exists = relation_exists(connection, "__crank_migrations").await?;
if !core_exists {
let mut owned_exists = canonical_exists;
for relation in OWNED_RELATIONS {
owned_exists |= relation_exists(connection, relation).await?;
}
if owned_exists {
return Err(MigrationError::new(
"partial_sequence",
"preflight.core",
None,
"restore_known_good_backup",
));
}
inspect_optional_legacy(connection).await?;
return Ok(MigrationPreflight::MigrationRequired {
current: 0,
target: CURRENT_VERSION,
});
}
validate_core_ledger(connection).await?;
validate_required_relations(connection, BASELINE_RELATIONS, 1).await?;
inspect_optional_legacy(connection).await?;
if !canonical_exists {
return Ok(MigrationPreflight::MigrationRequired {
current: 1,
target: CURRENT_VERSION,
});
}
let descriptors = MigrationAuthority::sequence();
let rows = query("select version, name, checksum, phase, compatibility from __crank_migrations order by version limit 1025")
.fetch_all(&mut *connection)
.await
.map_err(|_| MigrationError::storage("preflight.canonical"))?;
if rows.is_empty() {
return Err(MigrationError::new(
"partial_sequence",
"preflight.canonical",
None,
"restore_known_good_backup",
));
}
for (index, row) in rows.iter().enumerate() {
let version = row
.try_get::<i64, _>("version")
.map_err(|_| MigrationError::storage("preflight.canonical"))?;
if version > CURRENT_VERSION {
return Err(MigrationError::new(
"future_version",
"preflight.canonical",
Some(version),
"install_matching_application",
));
}
let Some(expected) = descriptors.get(index) else {
return Err(MigrationError::new(
"future_version",
"preflight.canonical",
Some(version),
"install_matching_application",
));
};
if version != expected.version {
return Err(MigrationError::new(
"partial_sequence",
"preflight.canonical",
Some(version),
"restore_known_good_backup",
));
}
let checksum = row
.try_get::<String, _>("checksum")
.map_err(|_| MigrationError::storage("preflight.canonical"))?;
if checksum != expected.checksum {
return Err(MigrationError::new(
"checksum_mismatch",
"preflight.canonical",
Some(version),
"restore_known_good_backup",
));
}
let name = row
.try_get::<String, _>("name")
.map_err(|_| MigrationError::storage("preflight.canonical"))?;
let phase = row
.try_get::<String, _>("phase")
.map_err(|_| MigrationError::storage("preflight.canonical"))?;
let compatibility = row
.try_get::<String, _>("compatibility")
.map_err(|_| MigrationError::storage("preflight.canonical"))?;
if name != expected.name
|| phase != expected.phase
|| compatibility != expected.compatibility
{
return Err(MigrationError::new(
"checksum_mismatch",
"preflight.metadata",
Some(version),
"restore_known_good_backup",
));
}
}
let current = rows
.last()
.and_then(|row| row.try_get::<i64, _>("version").ok())
.ok_or_else(|| MigrationError::storage("preflight.canonical"))?;
if rows.len() != usize::try_from(current).unwrap_or_default() {
return Err(MigrationError::new(
"partial_sequence",
"preflight.canonical",
Some(current),
"restore_known_good_backup",
));
}
validate_schema_fingerprint(connection, current).await?;
if current < CURRENT_VERSION {
Ok(MigrationPreflight::MigrationRequired {
current,
target: CURRENT_VERSION,
})
} else {
validate_required_relations(connection, CONSOLIDATION_RELATIONS, CURRENT_VERSION).await?;
validate_schema_fingerprint(connection, CURRENT_VERSION).await?;
validate_legacy_audit(connection).await?;
Ok(MigrationPreflight::Current { version: current })
}
}
async fn validate_core_ledger(connection: &mut PgConnection) -> Result<(), MigrationError> {
let rows = query("select version, description, checksum from __crank_core_migrations order by version limit 2")
.fetch_all(connection)
.await
.map_err(|_| MigrationError::storage("preflight.core"))?;
if rows.len() != 1 {
return Err(MigrationError::new(
"partial_sequence",
"preflight.core",
None,
"restore_known_good_backup",
));
}
let version = rows[0]
.try_get::<i32, _>("version")
.map_err(|_| MigrationError::storage("preflight.core"))?;
let checksum = rows[0]
.try_get::<String, _>("checksum")
.map_err(|_| MigrationError::storage("preflight.core"))?;
let description = rows[0]
.try_get::<String, _>("description")
.map_err(|_| MigrationError::storage("preflight.core"))?;
if version != BASELINE_VERSION
|| description != "community baseline"
|| checksum != BASELINE_CHECKSUM
{
return Err(MigrationError::new(
"checksum_mismatch",
"preflight.core",
Some(i64::from(version)),
"restore_known_good_backup",
));
}
Ok(())
}
async fn inspect_optional_legacy(connection: &mut PgConnection) -> Result<(), MigrationError> {
let mcp_ledger = relation_exists(connection, "__crank_mcp_migrations").await?;
let mcp_sessions = relation_exists(connection, "mcp_transport_sessions").await?;
if mcp_ledger != mcp_sessions {
return Err(MigrationError::new(
"legacy_conflict",
"preflight.legacy_mcp",
None,
"restore_known_good_backup",
));
}
if mcp_ledger {
let rows =
query("select version, checksum from __crank_mcp_migrations order by version limit 2")
.fetch_all(&mut *connection)
.await
.map_err(|_| MigrationError::storage("preflight.legacy_mcp"))?;
if rows.len() != 1
|| rows[0].try_get::<i32, _>("version").ok() != Some(1)
|| rows[0].try_get::<String, _>("checksum").ok().as_deref()
!= Some("mcp-transport-sessions-v1")
{
return Err(MigrationError::new(
"legacy_conflict",
"preflight.legacy_mcp",
None,
"restore_known_good_backup",
));
}
}
if relation_exists(connection, "__crank_ext_migrations").await? {
let count = query("select count(*)::bigint as count from __crank_ext_migrations")
.fetch_one(&mut *connection)
.await
.map_err(|_| MigrationError::storage("preflight.legacy_extension"))?
.try_get::<i64, _>("count")
.map_err(|_| MigrationError::storage("preflight.legacy_extension"))?;
if count > 1_000 {
return Err(MigrationError::new(
"legacy_conflict",
"preflight.legacy_extension",
None,
"contact_operator",
));
}
if count > 0 {
let checksum_column = query(
"select exists (
select 1 from information_schema.columns
where table_schema = current_schema()
and table_name = '__crank_ext_migrations'
and column_name = 'checksum'
) as present",
)
.fetch_one(&mut *connection)
.await
.map_err(|_| MigrationError::storage("preflight.legacy_extension"))?
.try_get::<bool, _>("present")
.map_err(|_| MigrationError::storage("preflight.legacy_extension"))?;
if !checksum_column {
return Err(MigrationError::new(
"legacy_conflict",
"preflight.legacy_extension",
None,
"contact_operator",
));
}
let rows = query(
"select extension_name, version, checksum
from __crank_ext_migrations
order by extension_name, version
limit 1001",
)
.fetch_all(&mut *connection)
.await
.map_err(|_| MigrationError::storage("preflight.legacy_extension"))?;
for row in rows {
let name = row
.try_get::<String, _>("extension_name")
.map_err(|_| MigrationError::storage("preflight.legacy_extension"))?;
let version = row
.try_get::<i32, _>("version")
.map_err(|_| MigrationError::storage("preflight.legacy_extension"))?;
let checksum = row
.try_get::<Option<String>, _>("checksum")
.map_err(|_| MigrationError::storage("preflight.legacy_extension"))?;
let registered = MigrationAuthority::registered_extension_migrations()
.iter()
.any(|(registered_name, descriptor)| {
*registered_name == name
&& descriptor.version == u32::try_from(version).unwrap_or_default()
&& checksum.as_deref() == Some(descriptor.checksum)
});
if !registered {
return Err(MigrationError::new(
"legacy_conflict",
"preflight.legacy_extension",
Some(i64::from(version)),
"contact_operator",
));
}
}
}
}
Ok(())
}
async fn validate_legacy_audit(connection: &mut PgConnection) -> Result<(), MigrationError> {
let rows = query(
"select source, source_version, source_checksum
from __crank_migration_legacy_audit
order by source, source_version
limit 1002",
)
.fetch_all(&mut *connection)
.await
.map_err(|_| MigrationError::storage("preflight.legacy_audit"))?;
if rows.len() > 1001 {
return Err(MigrationError::new(
"legacy_conflict",
"preflight.legacy_audit",
None,
"contact_operator",
));
}
for row in rows {
let source = row
.try_get::<String, _>("source")
.map_err(|_| MigrationError::storage("preflight.legacy_audit"))?;
let version = row
.try_get::<i64, _>("source_version")
.map_err(|_| MigrationError::storage("preflight.legacy_audit"))?;
let checksum = row
.try_get::<String, _>("source_checksum")
.map_err(|_| MigrationError::storage("preflight.legacy_audit"))?;
let valid = (source == "core" && version == 1 && checksum == BASELINE_CHECKSUM)
|| (source == "mcp-session" && version == 1 && checksum == "mcp-transport-sessions-v1")
|| source.strip_prefix("extension:").is_some_and(|name| {
MigrationAuthority::registered_extension_migrations()
.iter()
.any(|(registered_name, descriptor)| {
*registered_name == name
&& i64::from(descriptor.version) == version
&& descriptor.checksum == checksum
})
});
if !valid {
return Err(MigrationError::new(
"legacy_conflict",
"preflight.legacy_audit",
Some(version),
"restore_known_good_backup",
));
}
}
Ok(())
}
async fn create_core_ledger(
transaction: &mut Transaction<'_, sqlx::Postgres>,
) -> Result<(), MigrationError> {
query(
"create table __crank_core_migrations (
version integer primary key,
description text not null,
checksum text not null,
applied_at timestamptz not null default now()
)",
)
.execute(&mut **transaction)
.await
.map_err(|_| {
MigrationError::new(
"apply_failed",
"apply.core_ledger",
Some(1),
"restore_known_good_backup",
)
})?;
Ok(())
}
async fn apply_consolidation(
transaction: &mut Transaction<'_, sqlx::Postgres>,
) -> Result<(), MigrationError> {
sqlx::raw_sql(CONSOLIDATION_SOURCE)
.execute(&mut **transaction)
.await
.map_err(|_| {
MigrationError::new(
"apply_failed",
"apply.consolidation",
Some(2),
"restore_known_good_backup",
)
})?;
for (name, extension) in MigrationAuthority::registered_extension_migrations() {
query(
"insert into __crank_migration_legacy_audit
(source, source_version, source_checksum)
select 'extension:' || $1, $2, $3
from __crank_ext_migrations
where extension_name = $1 and version = $2 and checksum = $3",
)
.bind(name)
.bind(i64::from(extension.version))
.bind(extension.checksum)
.execute(&mut **transaction)
.await
.map_err(|_| {
MigrationError::new(
"apply_failed",
"apply.extension_audit",
Some(2),
"restore_known_good_backup",
)
})?;
}
let descriptor = &MigrationAuthority::sequence()[1];
query(
"insert into __crank_migrations (version, name, checksum, phase, compatibility)
values ($1, $2, $3, $4, $5)",
)
.bind(descriptor.version)
.bind(descriptor.name)
.bind(&descriptor.checksum)
.bind(descriptor.phase)
.bind(descriptor.compatibility)
.execute(&mut **transaction)
.await
.map_err(|_| {
MigrationError::new(
"apply_failed",
"apply.canonical_ledger",
Some(2),
"restore_known_good_backup",
)
})?;
Ok(())
}
async fn apply_request_trace_identity(
transaction: &mut Transaction<'_, sqlx::Postgres>,
) -> Result<(), MigrationError> {
sqlx::raw_sql(REQUEST_TRACE_IDENTITY_SOURCE)
.execute(&mut **transaction)
.await
.map_err(|_| {
MigrationError::new(
"apply_failed",
"apply.request_trace_identity",
Some(3),
"restore_known_good_backup",
)
})?;
let descriptor = &MigrationAuthority::sequence()[2];
query(
"insert into __crank_migrations (version, name, checksum, phase, compatibility)
values ($1, $2, $3, $4, $5)",
)
.bind(descriptor.version)
.bind(descriptor.name)
.bind(&descriptor.checksum)
.bind(descriptor.phase)
.bind(descriptor.compatibility)
.execute(&mut **transaction)
.await
.map_err(|_| {
MigrationError::new(
"apply_failed",
"apply.canonical_ledger",
Some(3),
"restore_known_good_backup",
)
})?;
Ok(())
}
#[cfg(test)]
#[path = "authority_tests.rs"]
mod tests;
crates/crank-registry/src/migrations/authority_tests.rs
+115
View File
@@ -0,0 +1,115 @@
use super::*;
#[test]
fn sequence_is_deterministic_and_append_only() {
let first = MigrationAuthority::sequence();
let second = MigrationAuthority::sequence();
assert_eq!(first, second);
MigrationAuthority::validate_sequence().unwrap();
assert_eq!(
first.iter().map(|item| item.version).collect::<Vec<_>>(),
vec![1, 2, 3]
);
assert_eq!(first[0].checksum, "crank-community-baseline-v1");
assert_eq!(first[0].source_digest, BASELINE_SOURCE_SHA256);
assert_eq!(
baseline_source_digest(),
BASELINE_SOURCE_SHA256,
"baseline v1 source changed; add a new migration instead"
);
assert_eq!(first[1].checksum.len(), 64);
assert!(
first[1]
.checksum
.bytes()
.all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
);
}
#[test]
fn invalid_gap_checksum_phase_and_unbounded_backfill_are_rejected() {
let base = MigrationAuthority::sequence();
for invalid in [
{
let mut value = base.clone();
value[1].version = 3;
value
},
{
let mut value = base.clone();
value[1].checksum = "0".repeat(64);
value
},
{
let mut value = base.clone();
value[1].phase = "unknown";
value
},
{
let mut value = base.clone();
value[1].name = value[0].name;
value
},
{
let mut value = base.clone();
value[1].transactional = false;
value
},
{
let mut value = base.clone();
value[1].phase = "migrate";
value[1].backfill = BackfillPolicy::Bounded {
max_batch_rows: 10_001,
max_batch_ms: 60_001,
resumable: false,
};
value
},
{
let mut value = base.clone();
value[1].phase = "contract";
value[1].compatibility = "window-closed";
value[1].contract_evidence = None;
value
},
] {
assert_eq!(
validate_descriptors(&invalid).unwrap_err().code(),
"invalid_contract"
);
}
}
#[test]
fn backfill_batches_are_bounded_and_resumable() {
let policy = BackfillPolicy::Bounded {
max_batch_rows: 100,
max_batch_ms: 1_000,
resumable: true,
};
BackfillBatch {
cursor: Some("next-100".to_owned()),
max_rows: 100,
max_ms: 1_000,
}
.validate(policy)
.unwrap();
assert!(
BackfillBatch {
cursor: None,
max_rows: 101,
max_ms: 1_000,
}
.validate(policy)
.is_err()
);
}
#[test]
fn diagnostic_is_bounded_and_does_not_echo_storage_details() {
let error = MigrationError::storage("preflight.connect");
let rendered = error.to_string();
assert!(rendered.len() < 512);
assert!(!rendered.contains("postgres://"));
assert_eq!(error.code(), "storage_unavailable");
}
crates/crank-registry/src/migrations/baseline_v1.rs
+673
View File
@@ -0,0 +1,673 @@
use sqlx::{Postgres, Transaction, query};
pub(super) const BASELINE_VERSION: i32 = 1;
pub(super) const BASELINE_CHECKSUM: &str = "crank-community-baseline-v1";
// baseline-v1:start
pub(super) async fn apply_baseline(
transaction: &mut Transaction<'_, Postgres>,
) -> Result<(), sqlx::Error> {
query(
"create table if not exists workspaces (
id text primary key,
slug text not null unique,
display_name text not null,
status text not null,
settings_json jsonb not null default '{}'::jsonb,
created_at timestamptz not null,
updated_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists users (
id text primary key,
email text not null unique,
display_name text not null,
password_hash text null,
status text not null,
created_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query("alter table users add column if not exists password_hash text null")
.execute(&mut **transaction)
.await?;
query(
"insert into users (
id,
email,
display_name,
status,
created_at
) values (
'user_default_owner',
'owner@crank.local',
'Workspace Owner',
'active',
now()
)
on conflict (id) do nothing",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists memberships (
workspace_id text not null references workspaces(id) on delete cascade,
user_id text not null references users(id) on delete cascade,
role text not null,
created_at timestamptz not null,
primary key (workspace_id, user_id)
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists user_sessions (
id text primary key,
user_id text not null references users(id) on delete cascade,
current_workspace_id text null references workspaces(id) on delete set null,
secret_hash text not null,
status text not null,
expires_at timestamptz not null,
last_seen_at timestamptz null,
created_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query(
"alter table user_sessions
add column if not exists current_workspace_id text null references workspaces(id) on delete set null",
)
.execute(&mut **transaction)
.await?;
query(
"insert into workspaces (
id,
slug,
display_name,
status,
settings_json,
created_at,
updated_at
) values (
'ws_default',
'default',
'Default Workspace',
'active',
'{}'::jsonb,
now(),
now()
)
on conflict (id) do nothing",
)
.execute(&mut **transaction)
.await?;
query(
"insert into memberships (
workspace_id,
user_id,
role,
created_at
) values (
'ws_default',
'user_default_owner',
'owner',
now()
)
on conflict (workspace_id, user_id) do nothing",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists invitation_tokens (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
email text not null,
role text not null,
status text not null,
token_hash text not null,
expires_at timestamptz not null,
created_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists platform_api_keys (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
agent_id text null,
name text not null,
prefix text not null,
secret_hash text not null,
key_kind text not null default 'mcp_client',
scopes_json jsonb not null,
status text not null,
created_at timestamptz not null,
last_used_at timestamptz null,
revoked_at timestamptz null,
expires_at timestamptz null,
allowed_origins_json jsonb not null default '[]'::jsonb
)",
)
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists platform_api_keys_workspace_name_idx on platform_api_keys(workspace_id, name)",
)
.execute(&mut **transaction)
.await?;
query("alter table platform_api_keys add column if not exists agent_id text null")
.execute(&mut **transaction)
.await?;
query(
"alter table platform_api_keys add column if not exists key_kind text not null default 'mcp_client'",
)
.execute(&mut **transaction)
.await?;
query("alter table platform_api_keys add column if not exists expires_at timestamptz null")
.execute(&mut **transaction)
.await?;
query(
"alter table platform_api_keys add column if not exists allowed_origins_json jsonb not null default '[]'::jsonb",
)
.execute(&mut **transaction)
.await?;
query(
"insert into workspaces (
id,
slug,
display_name,
status,
settings_json,
created_at,
updated_at
) values (
'ws_default',
'default',
'Default Workspace',
'active',
'{}'::jsonb,
now(),
now()
)
on conflict (id) do nothing",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists operations (
id text primary key,
workspace_id text null references workspaces(id) on delete cascade,
name text not null,
display_name text not null,
category text not null default 'general',
protocol text not null,
security_level text not null default 'standard',
status text not null,
current_draft_version integer not null default 1,
latest_published_version integer null,
created_at timestamptz not null,
updated_at timestamptz not null,
published_at timestamptz null
)",
)
.execute(&mut **transaction)
.await?;
query("alter table operations add column if not exists workspace_id text null references workspaces(id) on delete cascade")
.execute(&mut **transaction)
.await?;
query(
"alter table operations add column if not exists category text not null default 'general'",
)
.execute(&mut **transaction)
.await?;
query(
"alter table operations add column if not exists security_level text not null default 'standard'",
)
.execute(&mut **transaction)
.await?;
query("update operations set workspace_id = 'ws_default' where workspace_id is null")
.execute(&mut **transaction)
.await?;
query("alter table operations alter column workspace_id set not null")
.execute(&mut **transaction)
.await?;
query("alter table operations drop constraint if exists operations_name_key")
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists operations_workspace_name_idx on operations(workspace_id, name)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists operation_versions (
operation_id text not null references operations(id) on delete cascade,
version integer not null,
status text not null,
target_json jsonb not null,
input_schema_json jsonb not null,
output_schema_json jsonb not null,
input_mapping_json jsonb not null,
output_mapping_json jsonb not null,
execution_config_json jsonb not null,
tool_description_json jsonb not null,
samples_json jsonb null,
generated_draft_json jsonb null,
config_export_json jsonb null,
wizard_state_json jsonb null,
change_note text null,
created_at timestamptz not null,
created_by text null,
primary key (operation_id, version)
)",
)
.execute(&mut **transaction)
.await?;
query("alter table operation_versions add column if not exists wizard_state_json jsonb null")
.execute(&mut **transaction)
.await?;
query(
"create table if not exists published_operations (
operation_id text primary key references operations(id) on delete cascade,
version integer not null,
published_at timestamptz not null,
published_by text null,
foreign key (operation_id, version) references operation_versions(operation_id, version) on delete cascade
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists operation_samples (
id text primary key,
operation_id text not null references operations(id) on delete cascade,
version integer not null,
sample_kind text not null,
storage_ref text not null,
content_type text not null,
file_name text null,
created_at timestamptz not null,
foreign key (operation_id, version) references operation_versions(operation_id, version) on delete cascade
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists descriptors (
id text primary key,
operation_id text null references operations(id) on delete cascade,
version integer null,
descriptor_kind text not null,
storage_ref text not null,
source_name text null,
package_index_json jsonb null,
created_at timestamptz not null,
foreign key (operation_id, version) references operation_versions(operation_id, version) on delete cascade
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists auth_profiles (
id text primary key,
workspace_id text null references workspaces(id) on delete cascade,
name text not null,
kind text not null,
config_json jsonb not null,
created_at timestamptz not null,
updated_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query("alter table auth_profiles add column if not exists workspace_id text null references workspaces(id) on delete cascade")
.execute(&mut **transaction)
.await?;
query("update auth_profiles set workspace_id = 'ws_default' where workspace_id is null")
.execute(&mut **transaction)
.await?;
query("alter table auth_profiles alter column workspace_id set not null")
.execute(&mut **transaction)
.await?;
query("alter table auth_profiles drop constraint if exists auth_profiles_name_key")
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists auth_profiles_workspace_name_idx on auth_profiles(workspace_id, name)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists workspace_upstreams (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
name text not null,
base_url text not null,
static_headers_json jsonb not null default '{}'::jsonb,
auth_profile_id text null references auth_profiles(id) on delete set null,
created_at timestamptz not null,
updated_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists workspace_upstreams_workspace_name_idx on workspace_upstreams(workspace_id, name)",
)
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists workspace_upstreams_workspace_base_auth_idx on workspace_upstreams(workspace_id, base_url, coalesce(auth_profile_id, ''))",
)
.execute(&mut **transaction)
.await?;
query(
"insert into workspace_upstreams (
id,
workspace_id,
name,
base_url,
static_headers_json,
auth_profile_id,
created_at,
updated_at
)
select
'upstream_frankfurter_' || w.id,
w.id,
'Frankfurter',
'https://api.frankfurter.dev',
'{}'::jsonb,
null,
now(),
now()
from workspaces w
where not exists (
select 1
from workspace_upstreams wu
where wu.workspace_id = w.id
and wu.name = 'Frankfurter'
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists secrets (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
name text not null,
kind text not null,
status text not null,
current_version integer not null,
last_used_at timestamptz null,
created_at timestamptz not null,
updated_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists secrets_workspace_name_idx on secrets(workspace_id, name)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists secret_versions (
secret_id text not null references secrets(id) on delete cascade,
version integer not null,
ciphertext text not null,
key_version text not null,
created_at timestamptz not null,
created_by text null references users(id) on delete set null,
primary key (secret_id, version)
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists yaml_import_jobs (
id text primary key,
source_sample_id text null references operation_samples(id) on delete set null,
status text not null,
format_version text not null,
mode text not null,
result_operation_id text null references operations(id) on delete set null,
result_version integer null,
error_text text null,
created_at timestamptz not null,
finished_at timestamptz null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists import_jobs (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
kind text not null,
source_format text not null,
source_version text null,
status text not null,
preview_payload jsonb not null,
created_operation_ids jsonb not null default '[]'::jsonb,
error_text text null,
created_at timestamptz not null,
expires_at timestamptz not null,
finished_at timestamptz null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists agents (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
slug text not null,
display_name text not null,
description text not null,
status text not null,
current_draft_version integer not null default 1,
latest_published_version integer null,
created_at timestamptz not null,
updated_at timestamptz not null,
published_at timestamptz null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists agents_workspace_slug_idx on agents(workspace_id, slug)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists agent_versions (
agent_id text not null references agents(id) on delete cascade,
version integer not null,
status text not null,
instructions_json jsonb not null,
tool_selection_policy_json jsonb not null,
created_at timestamptz not null,
primary key (agent_id, version)
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists agent_operation_bindings (
agent_id text not null references agents(id) on delete cascade,
agent_version integer not null,
operation_id text not null references operations(id) on delete cascade,
operation_version integer not null,
tool_name text not null,
tool_title text not null,
tool_description_override text null,
enabled boolean not null default true,
foreign key (agent_id, agent_version) references agent_versions(agent_id, version) on delete cascade,
foreign key (operation_id, operation_version) references operation_versions(operation_id, version) on delete cascade
)",
)
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists agent_bindings_tool_name_idx on agent_operation_bindings(agent_id, agent_version, tool_name)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists published_agents (
agent_id text primary key references agents(id) on delete cascade,
version integer not null,
published_at timestamptz not null,
published_by text null,
foreign key (agent_id, version) references agent_versions(agent_id, version) on delete cascade
)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists approval_requests (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
agent_id text not null references agents(id) on delete cascade,
operation_id text not null references operations(id) on delete cascade,
operation_version integer not null,
status text not null,
risk_level text not null,
request_payload_json jsonb not null,
response_payload_json jsonb null,
created_at timestamptz not null,
expires_at timestamptz not null,
decided_at timestamptz null,
decided_by_key_id text null references platform_api_keys(id) on delete set null,
decision_note text null
)",
)
.execute(&mut **transaction)
.await?;
query("alter table approval_requests add column if not exists execution_started_at timestamptz null")
.execute(&mut **transaction)
.await?;
query("alter table approval_requests add column if not exists execution_attempts integer not null default 0")
.execute(&mut **transaction)
.await?;
query("alter table approval_requests add column if not exists request_fingerprint text null")
.execute(&mut **transaction)
.await?;
query(
"create unique index if not exists approval_requests_pending_fingerprint_idx
on approval_requests(agent_id, operation_id, operation_version, request_fingerprint)
where status = 'pending' and request_fingerprint is not null",
)
.execute(&mut **transaction)
.await?;
query(
"create index if not exists approval_requests_agent_status_idx
on approval_requests(workspace_id, agent_id, status, expires_at)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists invocation_logs (
id text primary key,
workspace_id text not null references workspaces(id) on delete cascade,
agent_id text null references agents(id) on delete set null,
operation_id text not null references operations(id) on delete cascade,
source text not null,
level text not null,
status text not null,
tool_name text not null,
message text not null,
request_id text null,
status_code integer null,
duration_ms bigint not null,
error_kind text null,
request_preview_json jsonb not null,
response_preview_json jsonb not null,
created_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
query(
"create index if not exists invocation_logs_workspace_created_idx on invocation_logs(workspace_id, created_at desc)",
)
.execute(&mut **transaction)
.await?;
query(
"create index if not exists invocation_logs_workspace_operation_created_idx on invocation_logs(workspace_id, operation_id, created_at desc)",
)
.execute(&mut **transaction)
.await?;
query(
"create index if not exists invocation_logs_workspace_agent_created_idx on invocation_logs(workspace_id, agent_id, created_at desc)",
)
.execute(&mut **transaction)
.await?;
query(
"create table if not exists usage_rollups (
workspace_id text not null references workspaces(id) on delete cascade,
agent_id text null references agents(id) on delete cascade,
operation_id text null references operations(id) on delete cascade,
period text not null,
calls_total bigint not null,
calls_ok bigint not null,
calls_error bigint not null,
p50_ms bigint not null,
p95_ms bigint not null,
p99_ms bigint not null,
updated_at timestamptz not null
)",
)
.execute(&mut **transaction)
.await?;
Ok(())
}
// baseline-v1:end
crates/crank-registry/src/migrations/consolidation_v2.sql
+84
View File
@@ -0,0 +1,84 @@
create temporary table __crank_v2_context (
had_mcp_ledger boolean not null
) on commit drop;
insert into __crank_v2_context (had_mcp_ledger)
values (to_regclass(format('%I.%I', current_schema(), '__crank_mcp_migrations')) is not null);
create table __crank_migrations (
version bigint primary key,
name text not null unique,
checksum text not null,
phase text not null,
compatibility text not null,
applied_at timestamptz not null default now()
);
create table __crank_migration_legacy_audit (
source text not null,
source_version bigint not null,
source_checksum text not null,
imported_at timestamptz not null default now(),
primary key (source, source_version)
);
insert into __crank_migrations (version, name, checksum, phase, compatibility)
values (
1,
'community-baseline-v1',
'crank-community-baseline-v1',
'expand',
'legacy-baseline'
);
insert into __crank_migration_legacy_audit (source, source_version, source_checksum)
values ('core', 1, 'crank-community-baseline-v1');
create table if not exists __crank_mcp_migrations (
version integer primary key,
checksum text not null,
applied_at timestamptz not null default now()
);
create table if not exists mcp_transport_sessions (
id text primary key,
protocol_version text not null,
initialized boolean not null default false,
supports_elicitation boolean not null default false,
workspace_slug text not null,
agent_slug text not null,
created_at timestamptz not null,
updated_at timestamptz not null,
expires_at timestamptz null
);
alter table mcp_transport_sessions
add column if not exists supports_elicitation boolean not null default false;
alter table mcp_transport_sessions
add column if not exists expires_at timestamptz null;
create index if not exists mcp_transport_sessions_workspace_agent_idx
on mcp_transport_sessions(workspace_slug, agent_slug, updated_at desc);
create index if not exists mcp_transport_sessions_expires_at_idx
on mcp_transport_sessions(expires_at)
where expires_at is not null;
insert into __crank_mcp_migrations (version, checksum)
values (1, 'mcp-transport-sessions-v1')
on conflict (version) do nothing;
insert into __crank_migration_legacy_audit (source, source_version, source_checksum)
select 'mcp-session', 1, 'mcp-transport-sessions-v1'
from __crank_v2_context
where had_mcp_ledger;
create table if not exists __crank_ext_migrations (
extension_name text not null,
version integer not null,
checksum text null,
applied_at timestamptz not null default now(),
primary key (extension_name, version)
);
alter table __crank_ext_migrations
add column if not exists checksum text null;
crates/crank-registry/src/migrations/request_trace_identity_v3.sql
+20
View File
@@ -0,0 +1,20 @@
alter table invocation_logs
add column trace_id text;
alter table invocation_logs
add constraint invocation_logs_trace_id_format_check
check (
trace_id is null
or (
trace_id ~ '^[0-9a-f]{32}$'
and trace_id <> '00000000000000000000000000000000'
)
) not valid;
create index invocation_logs_workspace_request_id_idx
on invocation_logs(workspace_id, request_id)
where request_id is not null and octet_length(request_id) <= 128;
create index invocation_logs_workspace_trace_id_idx
on invocation_logs(workspace_id, trace_id)
where trace_id is not null;
crates/crank-registry/src/migrations/schema_guard.rs
+451
View File
@@ -0,0 +1,451 @@
use sqlx::{PgConnection, Row, query};
use super::authority::MigrationError;
pub(super) const OWNED_RELATIONS: &[&str] = &[
"__crank_core_migrations",
"__crank_migrations",
"__crank_migration_legacy_audit",
"__crank_mcp_migrations",
"__crank_ext_migrations",
"mcp_transport_sessions",
"workspaces",
"users",
"memberships",
"user_sessions",
"invitation_tokens",
"platform_api_keys",
"operations",
"operation_versions",
"published_operations",
"operation_samples",
"descriptors",
"agents",
"agent_versions",
"published_agents",
"agent_operation_bindings",
"secrets",
"secret_versions",
"auth_profiles",
"workspace_upstreams",
"yaml_import_jobs",
"import_jobs",
"approval_requests",
"invocation_logs",
"usage_rollups",
];
const REQUIRED_COLUMNS: &[(&str, &[&str])] = &[
(
"__crank_core_migrations",
&["version", "description", "checksum", "applied_at"],
),
(
"__crank_migrations",
&[
"version",
"name",
"checksum",
"phase",
"compatibility",
"applied_at",
],
),
(
"__crank_migration_legacy_audit",
&["source", "source_version", "source_checksum", "imported_at"],
),
(
"__crank_mcp_migrations",
&["version", "checksum", "applied_at"],
),
(
"__crank_ext_migrations",
&["extension_name", "version", "checksum", "applied_at"],
),
(
"mcp_transport_sessions",
&[
"id",
"protocol_version",
"initialized",
"supports_elicitation",
"workspace_slug",
"agent_slug",
"created_at",
"updated_at",
"expires_at",
],
),
];
const REQUIRED_COLUMN_TYPES: &[(&str, &str, &str, bool)] = &[
("__crank_core_migrations", "version", "integer", false),
("__crank_core_migrations", "description", "text", false),
("__crank_core_migrations", "checksum", "text", false),
(
"__crank_core_migrations",
"applied_at",
"timestamp with time zone",
false,
),
("__crank_migrations", "version", "bigint", false),
("__crank_migrations", "name", "text", false),
("__crank_migrations", "checksum", "text", false),
("__crank_migrations", "phase", "text", false),
("__crank_migrations", "compatibility", "text", false),
(
"__crank_migrations",
"applied_at",
"timestamp with time zone",
false,
),
("__crank_migration_legacy_audit", "source", "text", false),
(
"__crank_migration_legacy_audit",
"source_version",
"bigint",
false,
),
(
"__crank_migration_legacy_audit",
"source_checksum",
"text",
false,
),
(
"__crank_migration_legacy_audit",
"imported_at",
"timestamp with time zone",
false,
),
("__crank_mcp_migrations", "version", "integer", false),
("__crank_mcp_migrations", "checksum", "text", false),
(
"__crank_mcp_migrations",
"applied_at",
"timestamp with time zone",
false,
),
("__crank_ext_migrations", "extension_name", "text", false),
("__crank_ext_migrations", "version", "integer", false),
("__crank_ext_migrations", "checksum", "text", true),
(
"__crank_ext_migrations",
"applied_at",
"timestamp with time zone",
false,
),
("mcp_transport_sessions", "id", "text", false),
("mcp_transport_sessions", "protocol_version", "text", false),
("mcp_transport_sessions", "initialized", "boolean", false),
(
"mcp_transport_sessions",
"supports_elicitation",
"boolean",
false,
),
("mcp_transport_sessions", "workspace_slug", "text", false),
("mcp_transport_sessions", "agent_slug", "text", false),
(
"mcp_transport_sessions",
"created_at",
"timestamp with time zone",
false,
),
(
"mcp_transport_sessions",
"updated_at",
"timestamp with time zone",
false,
),
(
"mcp_transport_sessions",
"expires_at",
"timestamp with time zone",
true,
),
];
pub(super) async fn relation_exists(
connection: &mut PgConnection,
relation: &str,
) -> Result<bool, MigrationError> {
query("select to_regclass(format('%I.%I', current_schema(), $1))::text is not null as present")
.bind(relation)
.fetch_one(connection)
.await
.map_err(|_| MigrationError::storage("preflight.inventory"))?
.try_get::<bool, _>("present")
.map_err(|_| MigrationError::storage("preflight.inventory"))
}
pub(super) async fn validate_required_relations(
connection: &mut PgConnection,
relations: &[&str],
version: i64,
) -> Result<(), MigrationError> {
for relation in relations {
if !relation_exists(connection, relation).await? {
return Err(schema_error(version));
}
let kind = query(
"select c.relkind::text as kind
from pg_catalog.pg_class c
join pg_catalog.pg_namespace n on n.oid = c.relnamespace
where n.nspname = current_schema() and c.relname = $1",
)
.bind(relation)
.fetch_one(&mut *connection)
.await
.map_err(|_| MigrationError::storage("preflight.schema"))?
.try_get::<String, _>("kind")
.map_err(|_| MigrationError::storage("preflight.schema"))?;
if !matches!(kind.as_str(), "r" | "p") {
return Err(schema_error(version));
}
}
Ok(())
}
pub(super) async fn validate_schema_fingerprint(
connection: &mut PgConnection,
current_version: i64,
) -> Result<(), MigrationError> {
for (table, required) in REQUIRED_COLUMNS {
if !relation_exists(connection, table).await? {
continue;
}
let rows = query(
"select column_name from information_schema.columns
where table_schema = current_schema() and table_name = $1
order by ordinal_position limit 257",
)
.bind(table)
.fetch_all(&mut *connection)
.await
.map_err(|_| MigrationError::storage("preflight.schema"))?;
let actual = rows
.iter()
.filter_map(|row| row.try_get::<String, _>("column_name").ok())
.collect::<Vec<_>>();
if actual.len() != required.len()
|| required
.iter()
.any(|column| !actual.iter().any(|actual| actual == column))
{
return Err(schema_error(current_version));
}
}
for (table, column, data_type, nullable) in REQUIRED_COLUMN_TYPES {
if !relation_exists(connection, table).await? {
continue;
}
let row = query(
"select data_type, is_nullable from information_schema.columns
where table_schema = current_schema() and table_name = $1 and column_name = $2",
)
.bind(table)
.bind(column)
.fetch_optional(&mut *connection)
.await
.map_err(|_| MigrationError::storage("preflight.schema"))?;
let valid = row.is_some_and(|row| {
row.try_get::<String, _>("data_type").ok().as_deref() == Some(*data_type)
&& row.try_get::<String, _>("is_nullable").ok().as_deref()
== Some(if *nullable { "YES" } else { "NO" })
});
if !valid {
return Err(schema_error(current_version));
}
}
if current_version < 3 {
let trace_column_present = query(
"select exists (
select 1 from information_schema.columns
where table_schema = current_schema()
and table_name = 'invocation_logs'
and column_name = 'trace_id'
) as present",
)
.fetch_one(&mut *connection)
.await
.map_err(|_| MigrationError::storage("preflight.schema"))?
.try_get::<bool, _>("present")
.map_err(|_| MigrationError::storage("preflight.schema"))?;
let trace_constraint_present = named_constraint_exists(
connection,
"invocation_logs",
"invocation_logs_trace_id_format_check",
)
.await?;
let v3_index_present =
relation_exists(connection, "invocation_logs_workspace_request_id_idx").await?
|| relation_exists(connection, "invocation_logs_workspace_trace_id_idx").await?;
if trace_column_present || trace_constraint_present || v3_index_present {
return Err(schema_error(current_version));
}
} else {
let trace_id = query(
"select data_type, is_nullable from information_schema.columns
where table_schema = current_schema()
and table_name = 'invocation_logs'
and column_name = 'trace_id'",
)
.fetch_optional(&mut *connection)
.await
.map_err(|_| MigrationError::storage("preflight.schema"))?;
let valid = trace_id.is_some_and(|row| {
row.try_get::<String, _>("data_type").ok().as_deref() == Some("text")
&& row.try_get::<String, _>("is_nullable").ok().as_deref() == Some("YES")
});
if !valid {
return Err(schema_error(current_version));
}
let constraint = query(
"select pg_get_expr(c.conbin, c.conrelid) as expression, c.convalidated
from pg_catalog.pg_constraint c
join pg_catalog.pg_class t on t.oid = c.conrelid
join pg_catalog.pg_namespace n on n.oid = t.relnamespace
where n.nspname = current_schema()
and t.relname = 'invocation_logs'
and c.conname = 'invocation_logs_trace_id_format_check'
and c.contype = 'c'",
)
.fetch_optional(&mut *connection)
.await
.map_err(|_| MigrationError::storage("preflight.schema"))?;
let constraint_valid = constraint.is_some_and(|row| {
row.try_get::<String, _>("expression")
.ok()
.is_some_and(|value| {
normalize_definition(&value)
== "trace_idisnullortrace_id~'^[0-9a-f]{32}$'::textandtrace_id<>'00000000000000000000000000000000'::text"
})
&& row.try_get::<bool, _>("convalidated").ok() == Some(false)
});
if !constraint_valid {
return Err(schema_error(current_version));
}
}
let required_indexes = [
"mcp_transport_sessions_workspace_agent_idx",
"mcp_transport_sessions_expires_at_idx",
];
for index in required_indexes {
let present = query(
"select exists (select 1 from pg_catalog.pg_indexes
where schemaname = current_schema() and indexname = $1) as present",
)
.bind(index)
.fetch_one(&mut *connection)
.await
.map_err(|_| MigrationError::storage("preflight.schema"))?
.try_get::<bool, _>("present")
.map_err(|_| MigrationError::storage("preflight.schema"))?;
if !present {
return Err(schema_error(current_version));
}
}
if current_version >= 3 {
validate_index(
connection,
"invocation_logs_workspace_request_id_idx",
"request_id",
"request_idisnotnullandoctet_lengthrequest_id<=128",
)
.await?;
validate_index(
connection,
"invocation_logs_workspace_trace_id_idx",
"trace_id",
"trace_idisnotnull",
)
.await?;
}
Ok(())
}
async fn named_constraint_exists(
connection: &mut PgConnection,
table: &str,
constraint: &str,
) -> Result<bool, MigrationError> {
query(
"select exists (
select 1 from pg_catalog.pg_constraint c
join pg_catalog.pg_class t on t.oid = c.conrelid
join pg_catalog.pg_namespace n on n.oid = t.relnamespace
where n.nspname = current_schema()
and t.relname = $1
and c.conname = $2
) as present",
)
.bind(table)
.bind(constraint)
.fetch_one(connection)
.await
.map_err(|_| MigrationError::storage("preflight.schema"))?
.try_get::<bool, _>("present")
.map_err(|_| MigrationError::storage("preflight.schema"))
}
async fn validate_index(
connection: &mut PgConnection,
index: &str,
second_column: &str,
expected_predicate: &str,
) -> Result<(), MigrationError> {
let row = query(
"select
t.relname as table_name,
am.amname as access_method,
i.indisvalid,
i.indisready,
i.indisunique,
pg_get_indexdef(i.indexrelid, 1, true) as first_column,
pg_get_indexdef(i.indexrelid, 2, true) as second_column,
pg_get_expr(i.indpred, i.indrelid) as predicate
from pg_catalog.pg_index i
join pg_catalog.pg_class idx on idx.oid = i.indexrelid
join pg_catalog.pg_class t on t.oid = i.indrelid
join pg_catalog.pg_namespace n on n.oid = t.relnamespace
join pg_catalog.pg_am am on am.oid = idx.relam
where n.nspname = current_schema() and idx.relname = $1",
)
.bind(index)
.fetch_optional(connection)
.await
.map_err(|_| MigrationError::storage("preflight.schema"))?;
let valid = row.is_some_and(|row| {
row.try_get::<String, _>("table_name").ok().as_deref() == Some("invocation_logs")
&& row.try_get::<String, _>("access_method").ok().as_deref() == Some("btree")
&& row.try_get::<bool, _>("indisvalid").ok() == Some(true)
&& row.try_get::<bool, _>("indisready").ok() == Some(true)
&& row.try_get::<bool, _>("indisunique").ok() == Some(false)
&& row.try_get::<String, _>("first_column").ok().as_deref() == Some("workspace_id")
&& row.try_get::<String, _>("second_column").ok().as_deref() == Some(second_column)
&& row
.try_get::<String, _>("predicate")
.ok()
.is_some_and(|value| normalize_definition(&value) == expected_predicate)
});
if valid { Ok(()) } else { Err(schema_error(3)) }
}
fn normalize_definition(value: &str) -> String {
value
.chars()
.filter(|character| !character.is_ascii_whitespace() && !matches!(character, '(' | ')'))
.flat_map(char::to_lowercase)
.collect()
}
fn schema_error(version: i64) -> MigrationError {
MigrationError::new(
"partial_sequence",
"preflight.schema",
Some(version),
"restore_known_good_backup",
)
}
crates/crank-registry/src/postgres/connection.rs
+3 -8
View File
@@ -5,7 +5,7 @@ use sqlx::{
postgres::{PgConnectOptions, PgPoolOptions},
};
use crate::{error::RegistryError, migrations};
use crate::{MigrationAuthority, error::RegistryError};
use super::{PostgresPoolConfig, PostgresRegistry};
@@ -33,7 +33,7 @@ impl PostgresRegistry {
.max_lifetime(Duration::from_millis(pool_config.max_lifetime_ms))
.connect_with(connect_options)
.await?;
migrations::apply_postgres(&pool).await?;
MigrationAuthority::require_current(&pool).await?;
Ok(Self { pool })
}
@@ -46,11 +46,6 @@ impl PostgresRegistry {
Ok(())
}
pub async fn migrate(&self) -> Result<(), RegistryError> {
migrations::apply_postgres(&self.pool).await?;
Ok(())
}
async fn connect_in_schema(
database_url: &str,
schema: Option<&str>,
@@ -69,7 +64,7 @@ impl PostgresRegistry {
}
let registry = Self { pool };
registry.migrate().await?;
MigrationAuthority::require_current(&registry.pool).await?;
Ok(registry)
}
}
crates/crank-registry/src/postgres/mod.rs
+1
View File
@@ -331,6 +331,7 @@ fn map_invocation_log_record(row: &PgRow) -> Result<InvocationLogRecord, Registr
tool_name: row.try_get("tool_name")?,
message: row.try_get("message")?,
request_id: row.try_get("request_id")?,
trace_id: row.try_get("trace_id")?,
status_code: match row.try_get::<Option<i32>, _>("status_code")? {
Some(value) => {
Some(
crates/crank-registry/src/postgres/observability.rs
+25 -1
View File
@@ -43,6 +43,26 @@ impl PostgresRegistry {
&self,
request: CreateInvocationLogRequest<'_>,
) -> Result<(), RegistryError> {
let request_id =
request
.log
.request_id
.as_deref()
.ok_or(RegistryError::InvalidCorrelationIdentity {
field: "request_id",
})?;
crank_core::RequestId::parse(request_id).map_err(|_| {
RegistryError::InvalidCorrelationIdentity {
field: "request_id",
}
})?;
let trace_id = request
.log
.trace_id
.as_deref()
.ok_or(RegistryError::InvalidCorrelationIdentity { field: "trace_id" })?;
crank_core::TraceId::parse(trace_id)
.map_err(|_| RegistryError::InvalidCorrelationIdentity { field: "trace_id" })?;
let request_preview = crank_core::sanitize_invocation_preview(&request.log.request_preview);
let response_preview =
crank_core::sanitize_invocation_preview(&request.log.response_preview);
@@ -58,6 +78,7 @@ impl PostgresRegistry {
tool_name,
message,
request_id,
trace_id,
status_code,
duration_ms,
error_kind,
@@ -65,7 +86,7 @@ impl PostgresRegistry {
response_preview_json,
created_at
) values (
$1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16::timestamptz
$1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17::timestamptz
)",
)
.bind(request.log.id.as_str())
@@ -78,6 +99,7 @@ impl PostgresRegistry {
.bind(&request.log.tool_name)
.bind(&request.log.message)
.bind(&request.log.request_id)
.bind(&request.log.trace_id)
.bind(request.log.status_code.map(i32::from))
.bind(i64::try_from(request.log.duration_ms).map_err(|_| {
RegistryError::InvalidNumericValue {
@@ -111,6 +133,7 @@ impl PostgresRegistry {
l.tool_name,
l.message,
l.request_id,
l.trace_id,
l.status_code,
l.duration_ms,
l.error_kind,
@@ -183,6 +206,7 @@ impl PostgresRegistry {
l.tool_name,
l.message,
l.request_id,
l.trace_id,
l.status_code,
l.duration_ms,
l.error_kind,
crates/crank-registry/src/postgres/pool_config.rs
+38 -155
View File
@@ -1,5 +1,3 @@
use std::{collections::BTreeMap, env};
use thiserror::Error;
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
@@ -13,11 +11,9 @@ pub struct PostgresPoolConfig {
#[derive(Debug, Error, PartialEq, Eq)]
pub enum PostgresPoolConfigError {
#[error("invalid postgres pool setting {name}={value}")]
InvalidValue { name: &'static str, value: String },
#[error("POSTGRES_MAX_CONNECTIONS must be greater than zero")]
ZeroMaxConnections,
#[error("POSTGRES_MIN_CONNECTIONS must not exceed POSTGRES_MAX_CONNECTIONS")]
#[error("postgres pool setting is outside its allowed bounds: {field}")]
OutOfRange { field: &'static str },
#[error("minimum connections must not exceed maximum connections")]
MinConnectionsExceedMax,
}
@@ -34,173 +30,60 @@ impl Default for PostgresPoolConfig {
}
impl PostgresPoolConfig {
pub fn from_env() -> Result<Self, PostgresPoolConfigError> {
Self::from_vars(env::vars())
}
fn from_vars<I, K, V>(vars: I) -> Result<Self, PostgresPoolConfigError>
where
I: IntoIterator<Item = (K, V)>,
K: AsRef<str>,
V: AsRef<str>,
{
let vars = vars
.into_iter()
.map(|(name, value)| (name.as_ref().to_owned(), value.as_ref().to_owned()))
.collect::<BTreeMap<_, _>>();
let defaults = Self::default();
let config = Self {
max_connections: parse_u32_setting(
&vars,
"POSTGRES_MAX_CONNECTIONS",
defaults.max_connections,
)?,
min_connections: parse_u32_setting(
&vars,
"POSTGRES_MIN_CONNECTIONS",
defaults.min_connections,
)?,
acquire_timeout_ms: parse_u64_setting(
&vars,
"POSTGRES_ACQUIRE_TIMEOUT_MS",
defaults.acquire_timeout_ms,
)?,
idle_timeout_ms: parse_u64_setting(
&vars,
"POSTGRES_IDLE_TIMEOUT_MS",
defaults.idle_timeout_ms,
)?,
max_lifetime_ms: parse_u64_setting(
&vars,
"POSTGRES_MAX_LIFETIME_MS",
defaults.max_lifetime_ms,
)?,
};
config.validate()?;
Ok(config)
}
fn validate(self) -> Result<Self, PostgresPoolConfigError> {
if self.max_connections == 0 {
return Err(PostgresPoolConfigError::ZeroMaxConnections);
pub fn try_new(
max_connections: u32,
min_connections: u32,
acquire_timeout_ms: u64,
idle_timeout_ms: u64,
max_lifetime_ms: u64,
) -> Result<Self, PostgresPoolConfigError> {
for (field, value, minimum, maximum) in [
("max_connections", u64::from(max_connections), 1, 1024),
("min_connections", u64::from(min_connections), 0, 1024),
("acquire_timeout_ms", acquire_timeout_ms, 1, 300_000),
("idle_timeout_ms", idle_timeout_ms, 1_000, 86_400_000),
("max_lifetime_ms", max_lifetime_ms, 1_000, 86_400_000),
] {
if !(minimum..=maximum).contains(&value) {
return Err(PostgresPoolConfigError::OutOfRange { field });
}
}
if self.min_connections > self.max_connections {
if min_connections > max_connections {
return Err(PostgresPoolConfigError::MinConnectionsExceedMax);
}
Ok(self)
Ok(Self {
max_connections,
min_connections,
acquire_timeout_ms,
idle_timeout_ms,
max_lifetime_ms,
})
}
}
fn parse_u32_setting(
vars: &BTreeMap<String, String>,
name: &'static str,
default: u32,
) -> Result<u32, PostgresPoolConfigError> {
vars.get(name)
.map(|value| {
value
.parse::<u32>()
.map_err(|_| PostgresPoolConfigError::InvalidValue {
name,
value: value.clone(),
})
})
.transpose()
.map(|value| value.unwrap_or(default))
}
fn parse_u64_setting(
vars: &BTreeMap<String, String>,
name: &'static str,
default: u64,
) -> Result<u64, PostgresPoolConfigError> {
vars.get(name)
.map(|value| {
value
.parse::<u64>()
.map_err(|_| PostgresPoolConfigError::InvalidValue {
name,
value: value.clone(),
})
})
.transpose()
.map(|value| value.unwrap_or(default))
}
#[cfg(test)]
mod pool_config_tests {
mod tests {
use super::{PostgresPoolConfig, PostgresPoolConfigError};
#[test]
fn pool_config_uses_explicit_defaults() {
let config = PostgresPoolConfig::from_vars(std::iter::empty::<(&str, &str)>()).unwrap();
fn explicit_defaults_remain_valid() {
assert_eq!(
config,
PostgresPoolConfig {
max_connections: 20,
min_connections: 2,
acquire_timeout_ms: 5_000,
idle_timeout_ms: 600_000,
max_lifetime_ms: 1_800_000,
}
PostgresPoolConfig::try_new(20, 2, 5_000, 600_000, 1_800_000).unwrap(),
PostgresPoolConfig::default()
);
}
#[test]
fn pool_config_parses_overrides() {
let config = PostgresPoolConfig::from_vars([
("POSTGRES_MAX_CONNECTIONS", "32"),
("POSTGRES_MIN_CONNECTIONS", "4"),
("POSTGRES_ACQUIRE_TIMEOUT_MS", "7000"),
("POSTGRES_IDLE_TIMEOUT_MS", "900000"),
("POSTGRES_MAX_LIFETIME_MS", "3600000"),
])
.unwrap();
fn rejects_invalid_bounds_and_cross_fields() {
assert_eq!(
config,
PostgresPoolConfig {
max_connections: 32,
min_connections: 4,
acquire_timeout_ms: 7_000,
idle_timeout_ms: 900_000,
max_lifetime_ms: 3_600_000,
PostgresPoolConfig::try_new(0, 0, 5_000, 600_000, 1_800_000).unwrap_err(),
PostgresPoolConfigError::OutOfRange {
field: "max_connections"
}
);
}
#[test]
fn pool_config_rejects_invalid_numeric_value() {
let error =
PostgresPoolConfig::from_vars([("POSTGRES_MAX_CONNECTIONS", "abc")]).unwrap_err();
assert_eq!(
error,
PostgresPoolConfigError::InvalidValue {
name: "POSTGRES_MAX_CONNECTIONS",
value: "abc".to_owned(),
}
PostgresPoolConfig::try_new(2, 3, 5_000, 600_000, 1_800_000).unwrap_err(),
PostgresPoolConfigError::MinConnectionsExceedMax
);
}
#[test]
fn pool_config_rejects_zero_max_connections() {
let error = PostgresPoolConfig::from_vars([("POSTGRES_MAX_CONNECTIONS", "0")]).unwrap_err();
assert_eq!(error, PostgresPoolConfigError::ZeroMaxConnections);
}
#[test]
fn pool_config_rejects_min_connections_above_max() {
let error = PostgresPoolConfig::from_vars([
("POSTGRES_MAX_CONNECTIONS", "2"),
("POSTGRES_MIN_CONNECTIONS", "3"),
])
.unwrap_err();
assert_eq!(error, PostgresPoolConfigError::MinConnectionsExceedMax);
}
}
crates/crank-registry/tests/integration/common.rs
+8 -4
View File
@@ -216,6 +216,7 @@ pub(super) fn test_invocation_log(
tool_name: "create_lead".to_owned(),
message: "invocation".to_owned(),
request_id: Some(format!("req_{id}")),
trace_id: Some("0af7651916cd43dd8448eb211c80319c".to_owned()),
status_code: Some(200),
duration_ms,
error_kind: None,
@@ -256,12 +257,15 @@ impl TestDatabase {
}
pub(super) async fn registry(&self) -> PostgresRegistry {
PostgresRegistry::connect(&format!(
let database_url = format!(
"{}?options=-csearch_path%3D{}",
self.database_url, self.schema
))
.await
.unwrap()
);
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
crank_registry::MigrationAuthority::apply(&pool)
.await
.unwrap();
PostgresRegistry::connect(&database_url).await.unwrap()
}
pub(super) async fn cleanup(&self) {
crates/crank-registry/tests/integration/migrations.rs
+683 -18
View File
@@ -1,34 +1,46 @@
use crank_registry::PostgresRegistry;
use crank_registry::{MigrationAuthority, MigrationPreflight, PostgresRegistry};
use sqlx::Row;
static EVENT_TRIGGER_TEST_LOCK: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
#[tokio::test]
async fn core_migration_is_versioned_and_safe_under_concurrent_startup() {
async fn controlled_authority_is_versioned_and_safe_under_concurrent_apply() {
let database_url = crank_test_support::postgres_schema_url("test_core_migration").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
let (first, second) = tokio::join!(
PostgresRegistry::connect(&database_url),
PostgresRegistry::connect(&database_url),
MigrationAuthority::apply(&pool),
MigrationAuthority::apply(&pool),
);
let first = first.expect("first service startup must apply the migration");
second.expect("second service startup must observe the applied migration");
first.expect("first controlled runner must apply the sequence");
second.expect("second controlled runner must observe the applied sequence");
let rows = sqlx::query(
"select version, description, checksum from __crank_core_migrations order by version",
)
.fetch_all(first.pool())
.await
.expect("migration ledger must be readable");
let first = PostgresRegistry::connect(&database_url)
.await
.expect("service startup must verify the migrated schema");
assert_eq!(rows.len(), 1);
assert_eq!(rows[0].get::<i32, _>("version"), 1);
assert_eq!(
rows[0].get::<String, _>("description"),
"community baseline"
);
let rows =
sqlx::query("select version, name, checksum from __crank_migrations order by version")
.fetch_all(first.pool())
.await
.expect("migration ledger must be readable");
assert_eq!(rows.len(), 3);
assert_eq!(rows[0].get::<i64, _>("version"), 1);
assert_eq!(rows[0].get::<String, _>("name"), "community-baseline-v1");
assert_eq!(
rows[0].get::<String, _>("checksum"),
"crank-community-baseline-v1"
);
assert_eq!(rows[1].get::<i64, _>("version"), 2);
assert_eq!(rows[1].get::<String, _>("name"), "legacy-consolidation-v2");
assert_eq!(rows[1].get::<String, _>("checksum").len(), 64);
assert_eq!(rows[2].get::<i64, _>("version"), 3);
assert_eq!(
rows[2].get::<String, _>("name"),
"request-trace-identity-v3"
);
assert_eq!(rows[2].get::<String, _>("checksum").len(), 64);
let approval_columns = sqlx::query(
"select column_name
@@ -41,4 +53,657 @@ async fn core_migration_is_versioned_and_safe_under_concurrent_startup() {
.await
.expect("approval schema must be readable");
assert_eq!(approval_columns.len(), 3);
assert_eq!(
MigrationAuthority::preflight(first.pool()).await.unwrap(),
MigrationPreflight::Current { version: 3 }
);
}
#[tokio::test]
async fn service_connect_is_read_only_on_fresh_database() {
let database_url = crank_test_support::postgres_schema_url("test_read_only_startup").await;
let error = PostgresRegistry::connect(&database_url)
.await
.expect_err("fresh schema must require the controlled migration command");
assert!(error.to_string().contains("schema_missing"));
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
let ledger = sqlx::query("select to_regclass('__crank_migrations')::text as name")
.fetch_one(&pool)
.await
.unwrap()
.try_get::<Option<String>, _>("name")
.unwrap();
assert_eq!(
ledger, None,
"startup compatibility check must not create DDL"
);
}
#[tokio::test]
async fn changed_checksum_fails_closed_without_repair() {
let database_url = crank_test_support::postgres_schema_url("test_changed_checksum").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
sqlx::query("update __crank_migrations set checksum = 'changed' where version = 1")
.execute(&pool)
.await
.unwrap();
let error = MigrationAuthority::apply(&pool)
.await
.expect_err("published checksum mismatch must fail closed");
assert_eq!(error.code(), "checksum_mismatch");
let checksum = sqlx::query("select checksum from __crank_migrations where version = 1")
.fetch_one(&pool)
.await
.unwrap()
.get::<String, _>("checksum");
assert_eq!(
checksum, "changed",
"authority must not rewrite corrupt history"
);
}
#[tokio::test]
async fn legacy_core_baseline_is_consolidated_without_data_loss() {
let database_url = crank_test_support::postgres_schema_url("test_legacy_core").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
sqlx::query(
"insert into workspaces (id, slug, display_name, status, settings_json, created_at, updated_at)
values ('ws_preserved', 'preserved', 'Preserved', 'active', '{}'::jsonb, now(), now())",
)
.execute(&pool)
.await
.unwrap();
sqlx::raw_sql(
"insert into operations
(id, workspace_id, name, display_name, protocol, status, created_at, updated_at)
values ('op_preserved', 'ws_default', 'preserved', 'Preserved', 'rest', 'draft', now(), now());
insert into operation_versions
(operation_id, version, status, target_json, input_schema_json, output_schema_json,
input_mapping_json, output_mapping_json, execution_config_json,
tool_description_json, created_at)
values ('op_preserved', 1, 'draft', '{}'::jsonb, '{}'::jsonb, '{}'::jsonb,
'{}'::jsonb, '{}'::jsonb, '{}'::jsonb, '{}'::jsonb, now());
insert into agents
(id, workspace_id, slug, display_name, description, status, created_at, updated_at)
values ('agent_preserved', 'ws_default', 'preserved', 'Preserved', '', 'draft', now(), now());
insert into agent_versions
(agent_id, version, status, instructions_json, tool_selection_policy_json, created_at)
values ('agent_preserved', 1, 'draft', '{}'::jsonb, '{}'::jsonb, now());
insert into platform_api_keys
(id, workspace_id, agent_id, name, prefix, secret_hash, scopes_json, status, created_at)
values ('key_preserved', 'ws_default', 'agent_preserved', 'Preserved', 'cp_', 'hash', '[]'::jsonb, 'active', now());
insert into approval_requests
(id, workspace_id, agent_id, operation_id, operation_version, status, risk_level,
request_payload_json, created_at, expires_at)
values ('approval_preserved', 'ws_default', 'agent_preserved', 'op_preserved', 1,
'pending', 'high', '{}'::jsonb, now(), now() + interval '1 hour');
insert into invocation_logs
(id, workspace_id, agent_id, operation_id, source, level, status, tool_name,
message, duration_ms, request_preview_json, response_preview_json, created_at)
values ('log_preserved', 'ws_default', 'agent_preserved', 'op_preserved', 'mcp',
'info', 'success', 'preserved', 'safe', 1, '{}'::jsonb, '{}'::jsonb, now());",
)
.execute(&pool)
.await
.unwrap();
remove_v3_schema(&pool).await;
let tables = [
"operations",
"operation_versions",
"agents",
"agent_versions",
"platform_api_keys",
"approval_requests",
"invocation_logs",
];
let mut before = Vec::new();
for table in tables {
let row = if table == "invocation_logs" {
"to_jsonb(t) - 'trace_id'"
} else {
"to_jsonb(t)"
};
let sql = format!("select jsonb_agg({row} order by {row}::text)::text from {table} t");
before.push(
sqlx::query_scalar::<_, Option<String>>(sqlx::AssertSqlSafe(sql))
.fetch_one(&pool)
.await
.unwrap(),
);
}
sqlx::query(
"drop table __crank_migrations, __crank_migration_legacy_audit,
__crank_mcp_migrations, mcp_transport_sessions, __crank_ext_migrations",
)
.execute(&pool)
.await
.unwrap();
assert_eq!(
MigrationAuthority::preflight(&pool).await.unwrap(),
MigrationPreflight::MigrationRequired {
current: 1,
target: 3,
}
);
MigrationAuthority::apply(&pool).await.unwrap();
let display_name = sqlx::query("select display_name from workspaces where id = 'ws_preserved'")
.fetch_one(&pool)
.await
.unwrap()
.get::<String, _>("display_name");
assert_eq!(display_name, "Preserved");
let mut after = Vec::new();
for table in tables {
let row = if table == "invocation_logs" {
"to_jsonb(t) - 'trace_id'"
} else {
"to_jsonb(t)"
};
let sql = format!("select jsonb_agg({row} order by {row}::text)::text from {table} t");
after.push(
sqlx::query_scalar::<_, Option<String>>(sqlx::AssertSqlSafe(sql))
.fetch_one(&pool)
.await
.unwrap(),
);
}
assert_eq!(before, after, "brownfield rows must remain byte-equivalent");
}
#[tokio::test]
async fn legacy_mcp_sessions_survive_consolidation() {
let database_url = crank_test_support::postgres_schema_url("test_legacy_mcp").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
sqlx::query(
"insert into mcp_transport_sessions (
id, protocol_version, initialized, supports_elicitation,
workspace_slug, agent_slug, created_at, updated_at, expires_at
) values ('session_preserved', '2025-11-25', true, false,
'default', 'agent', now(), now(), null)",
)
.execute(&pool)
.await
.unwrap();
remove_v3_schema(&pool).await;
sqlx::query("drop table __crank_migrations, __crank_migration_legacy_audit")
.execute(&pool)
.await
.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
let count = sqlx::query("select count(*)::bigint as count from mcp_transport_sessions where id = 'session_preserved'")
.fetch_one(&pool)
.await
.unwrap()
.get::<i64, _>("count");
assert_eq!(count, 1);
}
#[tokio::test]
async fn repeated_apply_does_not_rewrite_audit_timestamps() {
let database_url = crank_test_support::postgres_schema_url("test_repeat_apply").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
let before = sqlx::query("select applied_at from __crank_migrations order by version")
.fetch_all(&pool)
.await
.unwrap()
.into_iter()
.map(|row| row.get::<time::OffsetDateTime, _>("applied_at"))
.collect::<Vec<_>>();
MigrationAuthority::apply(&pool).await.unwrap();
let after = sqlx::query("select applied_at from __crank_migrations order by version")
.fetch_all(&pool)
.await
.unwrap()
.into_iter()
.map(|row| row.get::<time::OffsetDateTime, _>("applied_at"))
.collect::<Vec<_>>();
assert_eq!(before, after);
}
#[tokio::test]
async fn future_sequence_fails_closed() {
let database_url = crank_test_support::postgres_schema_url("test_future_sequence").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
sqlx::query("update __crank_migrations set version = 4 where version = 3")
.execute(&pool)
.await
.unwrap();
assert_eq!(
MigrationAuthority::preflight(&pool)
.await
.unwrap_err()
.code(),
"future_version"
);
}
#[tokio::test]
async fn healthy_v2_is_reported_as_migration_required_and_upgrades_to_v3() {
let database_url = crank_test_support::postgres_schema_url("test_v2_to_v3_identity").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
sqlx::query("delete from __crank_migrations where version = 3")
.execute(&pool)
.await
.unwrap();
remove_v3_schema(&pool).await;
assert_eq!(
MigrationAuthority::preflight(&pool).await.unwrap(),
MigrationPreflight::MigrationRequired {
current: 2,
target: 3,
}
);
MigrationAuthority::apply(&pool).await.unwrap();
assert_eq!(
MigrationAuthority::preflight(&pool).await.unwrap(),
MigrationPreflight::Current { version: 3 }
);
let trace_column: bool = sqlx::query_scalar(
"select exists (
select 1 from information_schema.columns
where table_schema = current_schema()
and table_name = 'invocation_logs'
and column_name = 'trace_id'
)",
)
.fetch_one(&pool)
.await
.unwrap();
assert!(trace_column);
}
#[tokio::test]
async fn v2_with_partial_v3_objects_fails_before_apply() {
let database_url = crank_test_support::postgres_schema_url("test_v2_partial_v3").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
sqlx::query("delete from __crank_migrations where version = 3")
.execute(&pool)
.await
.unwrap();
sqlx::raw_sql(
"drop index invocation_logs_workspace_request_id_idx;
drop index invocation_logs_workspace_trace_id_idx;
alter table invocation_logs drop constraint invocation_logs_trace_id_format_check;",
)
.execute(&pool)
.await
.unwrap();
let error = MigrationAuthority::preflight(&pool).await.unwrap_err();
assert_eq!(error.code(), "partial_sequence");
assert_eq!(error.stage(), "preflight.schema");
}
#[tokio::test]
async fn v3_rejects_same_named_constraint_or_index_with_wrong_definition() {
let database_url = crank_test_support::postgres_schema_url("test_v3_named_drift").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
sqlx::raw_sql(
"alter table invocation_logs drop constraint invocation_logs_trace_id_format_check;
alter table invocation_logs add constraint invocation_logs_trace_id_format_check
check (true) not valid;",
)
.execute(&pool)
.await
.unwrap();
assert_eq!(
MigrationAuthority::preflight(&pool)
.await
.unwrap_err()
.code(),
"partial_sequence"
);
sqlx::raw_sql(
"alter table invocation_logs drop constraint invocation_logs_trace_id_format_check;
alter table invocation_logs add constraint invocation_logs_trace_id_format_check
check (
trace_id is null or (
trace_id ~ '^[0-9a-f]{32}$'
and trace_id <> '00000000000000000000000000000000'
)
) not valid;
drop index invocation_logs_workspace_trace_id_idx;
create index invocation_logs_workspace_trace_id_idx on invocation_logs(trace_id);",
)
.execute(&pool)
.await
.unwrap();
assert_eq!(
MigrationAuthority::preflight(&pool)
.await
.unwrap_err()
.code(),
"partial_sequence"
);
}
#[tokio::test]
async fn v3_upgrade_ignores_oversized_legacy_request_ids_in_partial_index() {
let database_url = crank_test_support::postgres_schema_url("test_v3_legacy_request_id").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
sqlx::raw_sql(
"insert into operations
(id, workspace_id, name, display_name, protocol, status, created_at, updated_at)
values ('op_legacy_request', 'ws_default', 'legacy-request', 'Legacy Request',
'rest', 'draft', now(), now());",
)
.execute(&pool)
.await
.unwrap();
sqlx::query(
"insert into invocation_logs
(id, workspace_id, operation_id, source, level, status, tool_name, message,
request_id, duration_ms, request_preview_json, response_preview_json, created_at)
values ('legacy_request_log', 'ws_default', 'op_legacy_request', 'admin', 'info',
'success', 'legacy_request', 'safe', $1, 1, '{}'::jsonb, '{}'::jsonb, now())",
)
.bind("x".repeat(10_000))
.execute(&pool)
.await
.unwrap();
sqlx::query("delete from __crank_migrations where version = 3")
.execute(&pool)
.await
.unwrap();
remove_v3_schema(&pool).await;
MigrationAuthority::apply(&pool).await.unwrap();
assert_eq!(
MigrationAuthority::preflight(&pool).await.unwrap(),
MigrationPreflight::Current { version: 3 }
);
}
async fn remove_v3_schema(pool: &sqlx::PgPool) {
sqlx::raw_sql(
"drop index if exists invocation_logs_workspace_request_id_idx;
alter table invocation_logs drop column if exists trace_id;",
)
.execute(pool)
.await
.unwrap();
}
#[tokio::test]
async fn partial_sequence_fails_closed() {
let database_url = crank_test_support::postgres_schema_url("test_partial_sequence").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
sqlx::query("delete from __crank_migrations where version = 1")
.execute(&pool)
.await
.unwrap();
assert_eq!(
MigrationAuthority::preflight(&pool)
.await
.unwrap_err()
.code(),
"partial_sequence"
);
}
#[tokio::test]
async fn missing_relation_with_current_ledger_fails_closed() {
let database_url = crank_test_support::postgres_schema_url("test_missing_relation").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
sqlx::query("drop table usage_rollups")
.execute(&pool)
.await
.unwrap();
let error = MigrationAuthority::preflight(&pool).await.unwrap_err();
assert_eq!(error.code(), "partial_sequence");
assert_eq!(error.stage(), "preflight.schema");
}
#[tokio::test]
async fn unregistered_legacy_extension_provenance_is_rejected() {
let database_url = crank_test_support::postgres_schema_url("test_legacy_extension").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
sqlx::query("drop table __crank_migrations, __crank_migration_legacy_audit")
.execute(&pool)
.await
.unwrap();
let checksum = "a".repeat(64);
sqlx::query(
"insert into __crank_ext_migrations (extension_name, version, checksum)
values ('known-extension', 1, $1)",
)
.bind(&checksum)
.execute(&pool)
.await
.unwrap();
let error = MigrationAuthority::apply(&pool).await.unwrap_err();
assert_eq!(error.code(), "legacy_conflict");
}
#[tokio::test]
async fn any_owned_relation_without_core_ledger_is_partial() {
let database_url = crank_test_support::postgres_schema_url("test_owned_partial").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
sqlx::query("create table users (id text primary key)")
.execute(&pool)
.await
.unwrap();
let error = MigrationAuthority::preflight(&pool).await.unwrap_err();
assert_eq!(error.code(), "partial_sequence");
}
#[tokio::test]
async fn current_ledger_with_structural_drift_fails_closed() {
let database_url = crank_test_support::postgres_schema_url("test_structural_drift").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
sqlx::query("alter table mcp_transport_sessions drop column supports_elicitation")
.execute(&pool)
.await
.unwrap();
let error = MigrationAuthority::preflight(&pool).await.unwrap_err();
assert_eq!(error.code(), "partial_sequence");
assert_eq!(error.stage(), "preflight.schema");
}
#[tokio::test]
async fn tampered_legacy_audit_fails_closed() {
let database_url = crank_test_support::postgres_schema_url("test_tampered_audit").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
sqlx::query(
"update __crank_migration_legacy_audit set source_checksum = 'tampered' where source = 'core'",
)
.execute(&pool)
.await
.unwrap();
let error = MigrationAuthority::preflight(&pool).await.unwrap_err();
assert_eq!(error.code(), "legacy_conflict");
}
#[tokio::test]
async fn failed_consolidation_rolls_back_all_changes() {
let _event_trigger_guard = EVENT_TRIGGER_TEST_LOCK.lock().await;
let database_url = crank_test_support::postgres_schema_url("test_apply_rollback").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
sqlx::query(
"insert into workspaces (id, slug, display_name, status, settings_json, created_at, updated_at)
values ('rollback_preserved', 'rollback-preserved', 'Rollback Preserved', 'active', '{}'::jsonb, now(), now())",
)
.execute(&pool)
.await
.unwrap();
sqlx::query(
"drop table __crank_migrations, __crank_migration_legacy_audit,
__crank_mcp_migrations, mcp_transport_sessions, __crank_ext_migrations",
)
.execute(&pool)
.await
.unwrap();
let schema: String = sqlx::query_scalar("select current_schema()")
.fetch_one(&pool)
.await
.unwrap();
let failure_trigger = format!(
"create function reject_story14_v2() returns event_trigger language plpgsql as $$
begin
if current_schema() = '{schema}' and current_query() like '%__crank_migrations%' then
raise exception 'injected v2 ddl failure';
end if;
end $$;
create event trigger reject_story14_v2 on ddl_command_start
execute function reject_story14_v2();"
);
sqlx::raw_sql(sqlx::AssertSqlSafe(failure_trigger))
.execute(&pool)
.await
.unwrap();
let error = MigrationAuthority::apply(&pool).await.unwrap_err();
sqlx::raw_sql(
"drop event trigger reject_story14_v2;
drop function reject_story14_v2();",
)
.execute(&pool)
.await
.unwrap();
assert_eq!(error.code(), "apply_failed");
for relation in [
"__crank_migrations",
"__crank_migration_legacy_audit",
"__crank_mcp_migrations",
"mcp_transport_sessions",
"__crank_ext_migrations",
] {
let present: bool = sqlx::query_scalar(
"select to_regclass(format('%I.%I', current_schema(), $1)) is not null",
)
.bind(relation)
.fetch_one(&pool)
.await
.unwrap();
assert!(!present, "{relation} must roll back with failed v2 DDL");
}
let preserved: String =
sqlx::query_scalar("select display_name from workspaces where id = 'rollback_preserved'")
.fetch_one(&pool)
.await
.unwrap();
assert_eq!(preserved, "Rollback Preserved");
}
#[tokio::test]
async fn failed_request_trace_identity_migration_rolls_back_all_changes() {
let _event_trigger_guard = EVENT_TRIGGER_TEST_LOCK.lock().await;
let database_url =
crank_test_support::postgres_schema_url("test_trace_identity_rollback").await;
let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
MigrationAuthority::apply(&pool).await.unwrap();
sqlx::raw_sql(
"insert into operations
(id, workspace_id, name, display_name, protocol, status, created_at, updated_at)
values ('op_trace_rollback', 'ws_default', 'trace-rollback', 'Trace rollback',
'rest', 'draft', now(), now());
insert into invocation_logs
(id, workspace_id, operation_id, source, level, status, tool_name, message,
duration_ms, request_preview_json, response_preview_json, created_at)
values ('trace_rollback_preserved', 'ws_default', 'op_trace_rollback', 'admin',
'info', 'success', 'trace_rollback', 'safe preserved row', 1,
'{}'::jsonb, '{}'::jsonb, now());",
)
.execute(&pool)
.await
.unwrap();
sqlx::query("delete from __crank_migrations where version = 3")
.execute(&pool)
.await
.unwrap();
remove_v3_schema(&pool).await;
let schema: String = sqlx::query_scalar("select current_schema()")
.fetch_one(&pool)
.await
.unwrap();
let failure_trigger = format!(
"create function reject_story15_v3() returns event_trigger language plpgsql as $$
begin
if current_schema() = '{schema}' and current_query() like '%invocation_logs_workspace_trace_id_idx%' then
raise exception 'injected v3 ddl failure';
end if;
end $$;
create event trigger reject_story15_v3 on ddl_command_start
execute function reject_story15_v3();"
);
sqlx::raw_sql(sqlx::AssertSqlSafe(failure_trigger))
.execute(&pool)
.await
.unwrap();
let error = MigrationAuthority::apply(&pool).await.unwrap_err();
sqlx::raw_sql(
"drop event trigger reject_story15_v3;
drop function reject_story15_v3();",
)
.execute(&pool)
.await
.unwrap();
assert_eq!(error.code(), "apply_failed");
assert_eq!(error.version(), Some(3));
let trace_column: bool = sqlx::query_scalar(
"select exists (
select 1 from information_schema.columns
where table_schema = current_schema()
and table_name = 'invocation_logs'
and column_name = 'trace_id'
)",
)
.fetch_one(&pool)
.await
.unwrap();
assert!(!trace_column, "trace_id column must roll back with v3");
for index in [
"invocation_logs_workspace_request_id_idx",
"invocation_logs_workspace_trace_id_idx",
] {
let present: bool = sqlx::query_scalar(
"select to_regclass(format('%I.%I', current_schema(), $1)) is not null",
)
.bind(index)
.fetch_one(&pool)
.await
.unwrap();
assert!(!present, "{index} must roll back with failed v3 DDL");
}
let ledger_v3: i64 =
sqlx::query_scalar("select count(*) from __crank_migrations where version = 3")
.fetch_one(&pool)
.await
.unwrap();
assert_eq!(ledger_v3, 0, "failed v3 must not be recorded as applied");
let preserved: String = sqlx::query_scalar(
"select message from invocation_logs where id = 'trace_rollback_preserved'",
)
.fetch_one(&pool)
.await
.unwrap();
assert_eq!(preserved, "safe preserved row");
}
crates/crank-runtime/src/cache.rs
+19 -98
View File
@@ -1,7 +1,5 @@
use std::{
collections::HashMap,
env,
num::ParseIntError,
sync::Arc,
time::{Duration, Instant},
};
@@ -21,7 +19,6 @@ use tokio::sync::RwLock;
pub struct RuntimeCacheConfig {
pub backend: CacheBackend,
pub url: Option<String>,
pub default_ttl_ms: Option<u64>,
}
impl Default for RuntimeCacheConfig {
@@ -29,26 +26,22 @@ impl Default for RuntimeCacheConfig {
Self {
backend: CacheBackend::Memory,
url: None,
default_ttl_ms: None,
}
}
}
impl RuntimeCacheConfig {
pub fn from_env() -> Result<Self, RuntimeCacheConfigError> {
let backend = parse_backend()?;
let url = parse_optional_string("CRANK_CACHE_URL")?;
let default_ttl_ms = parse_optional_u64("CRANK_CACHE_DEFAULT_TTL_MS")?;
pub fn try_new(
backend: CacheBackend,
url: Option<String>,
) -> Result<Self, RuntimeCacheConfigError> {
if backend.is_external() && url.is_none() {
return Err(RuntimeCacheConfigError::MissingUrl { backend });
}
Ok(Self {
backend,
url,
default_ttl_ms,
})
if !backend.is_external() && url.is_some() {
return Err(RuntimeCacheConfigError::UnexpectedUrl);
}
Ok(Self { backend, url })
}
}
@@ -137,17 +130,11 @@ impl RedisCacheStore {
url: &str,
) -> Result<Self, RuntimeCacheStoreInitError> {
let client =
Client::open(url).map_err(|source| RuntimeCacheStoreInitError::InvalidUrl {
backend,
url: url.to_owned(),
details: source.to_string(),
})?;
let connection_manager = client.get_connection_manager().await.map_err(|source| {
RuntimeCacheStoreInitError::ConnectFailed {
backend,
details: source.to_string(),
}
})?;
Client::open(url).map_err(|_| RuntimeCacheStoreInitError::InvalidUrl { backend })?;
let connection_manager = client
.get_connection_manager()
.await
.map_err(|_| RuntimeCacheStoreInitError::ConnectFailed { backend })?;
Ok(Self {
backend,
connection_manager,
@@ -774,86 +761,20 @@ fn scoped_key(scope: CacheScope, key: &str) -> String {
format!("{scope:?}:{key}")
}
fn parse_backend() -> Result<CacheBackend, RuntimeCacheConfigError> {
match env::var("CRANK_CACHE_BACKEND") {
Ok(raw) => raw
.parse::<CacheBackend>()
.map_err(|source| RuntimeCacheConfigError::InvalidBackend { value: raw, source }),
Err(env::VarError::NotPresent) => Ok(CacheBackend::Memory),
Err(env::VarError::NotUnicode(_)) => Err(RuntimeCacheConfigError::InvalidUnicode {
name: "CRANK_CACHE_BACKEND",
}),
}
}
fn parse_optional_string(name: &'static str) -> Result<Option<String>, RuntimeCacheConfigError> {
match env::var(name) {
Ok(raw) => {
let trimmed = raw.trim();
if trimmed.is_empty() {
Ok(None)
} else {
Ok(Some(trimmed.to_owned()))
}
}
Err(env::VarError::NotPresent) => Ok(None),
Err(env::VarError::NotUnicode(_)) => Err(RuntimeCacheConfigError::InvalidUnicode { name }),
}
}
fn parse_optional_u64(name: &'static str) -> Result<Option<u64>, RuntimeCacheConfigError> {
match env::var(name) {
Ok(raw) => {
let trimmed = raw.trim();
if trimmed.is_empty() {
return Ok(None);
}
let value = trimmed
.parse::<u64>()
.map_err(|source| RuntimeCacheConfigError::InvalidTtl { value: raw, source })?;
if value == 0 {
return Err(RuntimeCacheConfigError::ZeroTtl { name });
}
Ok(Some(value))
}
Err(env::VarError::NotPresent) => Ok(None),
Err(env::VarError::NotUnicode(_)) => Err(RuntimeCacheConfigError::InvalidUnicode { name }),
}
}
#[derive(Debug, Error)]
pub enum RuntimeCacheConfigError {
#[error("{name} must contain valid UTF-8")]
InvalidUnicode { name: &'static str },
#[error("CRANK_CACHE_BACKEND must be one of memory, valkey, redis, got {value}")]
InvalidBackend {
value: String,
source: crank_core::ParseCacheBackendError,
},
#[error("CRANK_CACHE_DEFAULT_TTL_MS must be a positive integer, got {value}")]
InvalidTtl {
value: String,
source: ParseIntError,
},
#[error("{name} must be greater than zero")]
ZeroTtl { name: &'static str },
#[error("{backend} backend requires CRANK_CACHE_URL")]
MissingUrl { backend: CacheBackend },
#[error("memory cache backend does not accept CRANK_CACHE_URL")]
UnexpectedUrl,
}
#[derive(Debug, Error, PartialEq, Eq)]
pub enum RuntimeCacheStoreInitError {
#[error("{backend} backend requires CRANK_CACHE_URL")]
MissingUrl { backend: CacheBackend },
#[error("invalid {backend} cache url {url}: {details}")]
InvalidUrl {
backend: CacheBackend,
url: String,
details: String,
},
#[error("failed to connect to {backend} cache backend: {details}")]
ConnectFailed {
backend: CacheBackend,
details: String,
},
#[error("invalid {backend} cache url")]
InvalidUrl { backend: CacheBackend },
#[error("failed to connect to {backend} cache backend")]
ConnectFailed { backend: CacheBackend },
}
crates/crank-runtime/src/executor.rs
+21 -13
View File
@@ -11,7 +11,9 @@ use crank_metrics::{
ToolOutcome, record_cache_outcome, record_confirmation_outcome, record_idempotency_outcome,
record_limit_rejection,
};
use crank_trace::{ErrorCategory, Stage, StageOutcome};
use crank_trace::{
ErrorCategory, Stage, StageOutcome, set_parent_from_trace_context, trace_context_for_span,
};
use serde_json::{Map, Value, json};
use time::OffsetDateTime;
use tokio::sync::{OwnedSemaphorePermit, Semaphore};
@@ -242,11 +244,22 @@ impl RuntimeExecutor {
&self,
request: RuntimeExecutionRequest<'_>,
) -> Result<Value, RuntimeError> {
log_runtime_event("unary.execute", request.operation, request.request_context);
let runtime_span = Stage::RuntimeExecute.span();
if let Some(context) = request.request_context {
set_parent_from_trace_context(&runtime_span, &context.trace_context);
}
let generated_context = request.request_context.is_none().then(|| {
RuntimeRequestContext::new(
crank_core::RequestId::generate(),
trace_context_for_span(&runtime_span)
.unwrap_or_else(crank_core::TraceContext::generate),
)
});
let request_context = request.request_context.or(generated_context.as_ref());
log_runtime_event("unary.execute", request.operation, request_context);
let started_at = Instant::now();
let invocation_metrics =
ToolInvocationMetrics::start(metric_invocation_source(request.request_context));
let runtime_span = Stage::RuntimeExecute.span();
ToolInvocationMetrics::start(metric_invocation_source(request_context));
let result = async {
let _permit = self.acquire_unary_permit(request.operation)?;
let _inflight = InFlightGuard::runtime();
@@ -261,7 +274,7 @@ impl RuntimeExecutor {
request.operation,
request.input,
prepared_request,
request.request_context,
request_context,
)
.await
}
@@ -274,13 +287,8 @@ impl RuntimeExecutor {
Err(error) => (ToolOutcome::Error, runtime_error_kind(error)),
};
invocation_metrics.complete(outcome, error_kind);
self.record_metering(
request.operation,
request.request_context,
&result,
started_at,
)
.await;
self.record_metering(request.operation, request_context, &result, started_at)
.await;
result
}
@@ -829,7 +837,7 @@ fn log_runtime_event(
operation_id = operation.operation_id.as_str(),
protocol,
request_id = context.request_id.as_str(),
correlation_id = context.correlation_id.as_str(),
trace_id = context.trace_context.trace_id().as_str(),
"runtime execution"
);
} else {
crates/crank-runtime/src/executor_builder.rs
+1 -6
View File
@@ -1,6 +1,6 @@
use std::sync::Arc;
use crank_adapter_rest::{OutboundHttpPolicy, RestAdapter, RestAdapterError};
use crank_adapter_rest::{OutboundHttpPolicy, RestAdapter};
use crank_core::{
AdapterRegistry, CoordinationStateStore, MeteringSink, NoopMeteringSink, ResponseCacheStore,
SharedMeteringSink, SharedProtocolAdapter,
@@ -74,11 +74,6 @@ pub fn community_default() -> RuntimeExecutorBuilder {
.register_adapter(Arc::new(RestAdapter::new()) as SharedProtocolAdapter)
}
pub fn community_from_env() -> Result<RuntimeExecutorBuilder, RestAdapterError> {
Ok(RuntimeExecutorBuilder::new()
.register_adapter(Arc::new(RestAdapter::from_env()?) as SharedProtocolAdapter))
}
pub fn community_with_outbound_policy(policy: OutboundHttpPolicy) -> RuntimeExecutorBuilder {
RuntimeExecutorBuilder::new()
.register_adapter(Arc::new(RestAdapter::with_policy(policy)) as SharedProtocolAdapter)
crates/crank-runtime/src/lib.rs
+1 -1
View File
@@ -27,7 +27,7 @@ pub use crank_adapter_rest::OutboundHttpPolicy;
pub use error::RuntimeError;
pub use executor::{RuntimeExecutionRequest, RuntimeExecutor};
pub use executor_builder::{
RuntimeExecutorBuilder, community_default, community_from_env, community_with_outbound_policy,
RuntimeExecutorBuilder, community_default, community_with_outbound_policy,
};
pub use limits::{RuntimeLimits, RuntimeLimitsConfigError};
pub use model::{AdapterResponse, PreparedRequest, RuntimeOperation};
crates/crank-runtime/src/limits.rs
+26 -59
View File
@@ -1,9 +1,8 @@
use std::{env, num::ParseIntError};
use thiserror::Error;
const DEFAULT_MAX_CONCURRENT_UNARY: usize = 64;
const DEFAULT_MAX_CONCURRENT_SESSIONS: usize = 16;
const MAX_CONCURRENCY: usize = 65_535;
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct RuntimeLimits {
@@ -21,52 +20,31 @@ impl Default for RuntimeLimits {
}
impl RuntimeLimits {
pub fn from_env() -> Result<Self, RuntimeLimitsConfigError> {
pub fn try_new(
max_concurrent_unary: usize,
max_concurrent_sessions: usize,
) -> Result<Self, RuntimeLimitsConfigError> {
if !(1..=MAX_CONCURRENCY).contains(&max_concurrent_unary) {
return Err(RuntimeLimitsConfigError::OutOfRange {
field: "runtime.max_concurrent_unary",
});
}
if !(1..=MAX_CONCURRENCY).contains(&max_concurrent_sessions) {
return Err(RuntimeLimitsConfigError::OutOfRange {
field: "runtime.max_concurrent_sessions",
});
}
Ok(Self {
max_concurrent_unary: parse_limit(
"CRANK_RUNTIME_MAX_CONCURRENT_UNARY",
DEFAULT_MAX_CONCURRENT_UNARY,
)?,
max_concurrent_sessions: parse_limit(
"CRANK_RUNTIME_MAX_CONCURRENT_SESSIONS",
DEFAULT_MAX_CONCURRENT_SESSIONS,
)?,
max_concurrent_unary,
max_concurrent_sessions,
})
}
}
fn parse_limit(name: &'static str, default: usize) -> Result<usize, RuntimeLimitsConfigError> {
match env::var(name) {
Ok(raw) => {
let value =
raw.parse::<usize>()
.map_err(|source| RuntimeLimitsConfigError::InvalidValue {
name,
value: raw,
source,
})?;
if value == 0 {
return Err(RuntimeLimitsConfigError::ZeroValue { name });
}
Ok(value)
}
Err(env::VarError::NotPresent) => Ok(default),
Err(env::VarError::NotUnicode(_)) => Err(RuntimeLimitsConfigError::InvalidUnicode { name }),
}
}
#[derive(Debug, Error)]
#[derive(Debug, Error, Eq, PartialEq)]
pub enum RuntimeLimitsConfigError {
#[error("{name} must contain valid UTF-8")]
InvalidUnicode { name: &'static str },
#[error("{name} must be a positive integer, got {value}")]
InvalidValue {
name: &'static str,
value: String,
source: ParseIntError,
},
#[error("{name} must be greater than zero")]
ZeroValue { name: &'static str },
#[error("runtime limit is outside its allowed bounds: {field}")]
OutOfRange { field: &'static str },
}
#[cfg(test)]
@@ -76,28 +54,17 @@ mod tests {
#[test]
fn defaults_are_positive() {
let limits = RuntimeLimits::default();
assert!(limits.max_concurrent_unary > 0);
assert!(limits.max_concurrent_sessions > 0);
}
#[test]
fn rejects_zero_limit_values() {
unsafe {
std::env::set_var("CRANK_RUNTIME_MAX_CONCURRENT_UNARY", "0");
}
let error = RuntimeLimits::from_env().unwrap_err();
assert!(matches!(
error,
RuntimeLimitsConfigError::ZeroValue {
name: "CRANK_RUNTIME_MAX_CONCURRENT_UNARY"
fn value_constructor_rejects_zero() {
assert_eq!(
RuntimeLimits::try_new(0, 1).unwrap_err(),
RuntimeLimitsConfigError::OutOfRange {
field: "runtime.max_concurrent_unary"
}
));
unsafe {
std::env::remove_var("CRANK_RUNTIME_MAX_CONCURRENT_UNARY");
}
);
}
}
crates/crank-runtime/src/request_context.rs
+33 -13
View File
@@ -1,6 +1,8 @@
use std::collections::BTreeMap;
use crank_core::{AgentId, InvocationSource, WorkspaceId};
use crank_core::{
AgentId, CorrelationContext, InvocationSource, RequestId, TraceContext, WorkspaceId,
};
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ResponseCacheScope {
@@ -10,8 +12,8 @@ pub struct ResponseCacheScope {
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RuntimeRequestContext {
pub request_id: String,
pub correlation_id: String,
pub request_id: RequestId,
pub trace_context: TraceContext,
pub response_cache_scope: Option<ResponseCacheScope>,
pub metering_context: Option<MeteringContext>,
pub confirmation_token: Option<String>,
@@ -26,10 +28,10 @@ pub struct MeteringContext {
}
impl RuntimeRequestContext {
pub fn new(request_id: impl Into<String>, correlation_id: impl Into<String>) -> Self {
pub fn new(request_id: RequestId, trace_context: TraceContext) -> Self {
Self {
request_id: request_id.into(),
correlation_id: correlation_id.into(),
request_id,
trace_context,
response_cache_scope: None,
metering_context: None,
confirmation_token: None,
@@ -39,13 +41,31 @@ impl RuntimeRequestContext {
pub fn from_request_id(request_id: impl Into<String>) -> Self {
let request_id = request_id.into();
Self::new(request_id.clone(), request_id)
Self::new(
RequestId::resolve(Some(&request_id)),
TraceContext::generate(),
)
}
pub fn from_correlation(context: &CorrelationContext) -> Self {
Self::new(
context.request_id().clone(),
context.trace_context().clone(),
)
}
pub fn outbound_headers(&self) -> BTreeMap<String, String> {
BTreeMap::from([
("x-request-id".to_owned(), self.request_id.clone()),
("x-correlation-id".to_owned(), self.correlation_id.clone()),
("x-request-id".to_owned(), self.request_id.to_string()),
(
"x-trace-id".to_owned(),
self.trace_context.trace_id().to_string(),
),
(
"traceparent".to_owned(),
self.trace_context.traceparent().to_owned(),
),
("x-correlation-id".to_owned(), self.request_id.to_string()),
])
}
@@ -124,7 +144,7 @@ impl From<&RuntimeRequestContext> for crank_core::RuntimeRequestContext {
fn from(value: &RuntimeRequestContext) -> Self {
Self {
request_id: value.request_id.clone(),
correlation_id: value.correlation_id.clone(),
trace_context: value.trace_context.clone(),
response_cache_scope: value.response_cache_scope.as_ref().map(Into::into),
metering_context: value.metering_context.as_ref().map(Into::into),
}
@@ -158,11 +178,11 @@ mod tests {
use super::RuntimeRequestContext;
#[test]
fn uses_request_id_for_default_correlation_id() {
fn generates_a_separate_default_trace_identity() {
let context = RuntimeRequestContext::from_request_id("req_123");
assert_eq!(context.request_id, "req_123");
assert_eq!(context.correlation_id, "req_123");
assert_eq!(context.request_id.as_str(), "req_123");
assert_ne!(context.trace_context.trace_id().as_str(), "req_123");
assert!(context.response_cache_scope.is_none());
assert!(context.confirmation_token.is_none());
assert!(!context.approval_granted());
crates/crank-runtime/tests/unit/cache.rs
+13 -99
View File
@@ -1,8 +1,4 @@
use std::{
ffi::OsString,
sync::{Mutex, MutexGuard},
time::Duration,
};
use std::time::Duration;
use crank_core::{
CacheBackend, CacheScope, CacheStoreError, CachedHeader, CachedResponse,
@@ -17,62 +13,29 @@ use crank_runtime::{
};
use serde_json::json;
const CACHE_ENV_NAMES: [&str; 3] = [
"CRANK_CACHE_BACKEND",
"CRANK_CACHE_URL",
"CRANK_CACHE_DEFAULT_TTL_MS",
];
static CACHE_ENV_LOCK: Mutex<()> = Mutex::new(());
#[test]
fn defaults_to_in_memory_cache_without_url() {
let config = RuntimeCacheConfig::default();
assert_eq!(config.backend, CacheBackend::Memory);
assert_eq!(config.url, None);
assert_eq!(config.default_ttl_ms, None);
}
#[test]
fn treats_blank_optional_cache_values_as_unset() {
let _env = IsolatedCacheEnv::new();
unsafe {
std::env::set_var("CRANK_CACHE_URL", " ");
std::env::set_var("CRANK_CACHE_DEFAULT_TTL_MS", " ");
}
let config = RuntimeCacheConfig::from_env().unwrap();
assert_eq!(config.backend, CacheBackend::Memory);
assert_eq!(config.url, None);
assert_eq!(config.default_ttl_ms, None);
}
#[test]
fn loads_valkey_config_from_env() {
let _env = IsolatedCacheEnv::new();
unsafe {
std::env::set_var("CRANK_CACHE_BACKEND", "valkey");
std::env::set_var("CRANK_CACHE_URL", "redis://cache:6379/0");
std::env::set_var("CRANK_CACHE_DEFAULT_TTL_MS", "15000");
}
let config = RuntimeCacheConfig::from_env().unwrap();
fn accepts_validated_valkey_values() {
let config = RuntimeCacheConfig::try_new(
CacheBackend::Valkey,
Some("redis://cache:6379/0".to_owned()),
)
.unwrap();
assert_eq!(config.backend, CacheBackend::Valkey);
assert_eq!(config.url.as_deref(), Some("redis://cache:6379/0"));
assert_eq!(config.default_ttl_ms, Some(15_000));
}
#[test]
fn rejects_external_backend_without_url() {
let _env = IsolatedCacheEnv::new();
unsafe {
std::env::set_var("CRANK_CACHE_BACKEND", "redis");
std::env::remove_var("CRANK_CACHE_URL");
}
let error = RuntimeCacheConfig::from_env().unwrap_err();
let error = RuntimeCacheConfig::try_new(CacheBackend::Redis, None).unwrap_err();
assert!(matches!(
error,
@@ -83,59 +46,11 @@ fn rejects_external_backend_without_url() {
}
#[test]
fn rejects_zero_ttl() {
let _env = IsolatedCacheEnv::new();
unsafe {
std::env::set_var("CRANK_CACHE_DEFAULT_TTL_MS", "0");
}
let error = RuntimeCacheConfig::from_env().unwrap_err();
assert!(matches!(
error,
RuntimeCacheConfigError::ZeroTtl {
name: "CRANK_CACHE_DEFAULT_TTL_MS"
}
));
}
struct IsolatedCacheEnv {
_lock: MutexGuard<'static, ()>,
previous: Vec<(&'static str, Option<OsString>)>,
}
impl IsolatedCacheEnv {
fn new() -> Self {
let lock = CACHE_ENV_LOCK
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner);
let previous = CACHE_ENV_NAMES
.iter()
.map(|name| (*name, std::env::var_os(name)))
.collect();
for name in CACHE_ENV_NAMES {
unsafe {
std::env::remove_var(name);
}
}
Self {
_lock: lock,
previous,
}
}
}
impl Drop for IsolatedCacheEnv {
fn drop(&mut self) {
for (name, value) in &self.previous {
unsafe {
match value {
Some(value) => std::env::set_var(name, value),
None => std::env::remove_var(name),
}
}
}
}
fn rejects_url_for_memory_backend() {
let error =
RuntimeCacheConfig::try_new(CacheBackend::Memory, Some("redis://cache:6379".to_owned()))
.unwrap_err();
assert!(matches!(error, RuntimeCacheConfigError::UnexpectedUrl));
}
#[tokio::test]
@@ -410,7 +325,6 @@ fn runtime_cache_stores_report_missing_external_url() {
let future = RuntimeCacheStores::from_config(&RuntimeCacheConfig {
backend: CacheBackend::Valkey,
url: None,
default_ttl_ms: None,
});
let runtime = tokio::runtime::Runtime::new().unwrap();
crates/crank-trace/Cargo.toml
+3
View File
@@ -10,7 +10,10 @@ version.workspace = true
path = "src/lib.rs"
[dependencies]
crank-core = { path = "../crank-core" }
opentelemetry.workspace = true
tracing.workspace = true
tracing-opentelemetry.workspace = true
[dev-dependencies]
tracing-subscriber.workspace = true
crates/crank-trace/src/lib.rs
+43
View File
@@ -6,7 +6,50 @@
use std::future::Future;
use opentelemetry::{
Context,
trace::{SpanContext, SpanId, TraceContextExt, TraceFlags, TraceId, TraceState},
};
use tracing::{Instrument, Span, field::Empty, info_span};
use tracing_opentelemetry::OpenTelemetrySpanExt;
pub fn set_parent_from_trace_context(span: &Span, context: &crank_core::TraceContext) -> bool {
let mut parts = context.traceparent().split('-');
let (Some("00"), Some(trace_id), Some(parent_id), Some(flags), None) = (
parts.next(),
parts.next(),
parts.next(),
parts.next(),
parts.next(),
) else {
return false;
};
let (Ok(trace_id), Ok(parent_id)) = (TraceId::from_hex(trace_id), SpanId::from_hex(parent_id))
else {
return false;
};
let flags = match flags {
"00" => TraceFlags::default(),
"01" => TraceFlags::SAMPLED,
_ => return false,
};
let parent = SpanContext::new(trace_id, parent_id, flags, true, TraceState::default());
span.set_parent(Context::new().with_remote_span_context(parent))
.is_ok()
}
pub fn trace_context_for_span(span: &Span) -> Option<crank_core::TraceContext> {
let context = span.context();
let span_context = context.span().span_context().clone();
span_context.is_valid().then(|| {
crank_core::TraceContext::from_span_parts(
&span_context.trace_id().to_string(),
&span_context.span_id().to_string(),
span_context.is_sampled(),
)
.ok()
})?
}
macro_rules! stage_span {
($name:literal) => {