1use std::collections::BTreeMap;
9
10use serde::{Deserialize, Serialize};
11use serde_json::Value;
12
13use crate::{
14 call_mode::CallMode,
15 manifest::{CapabilityDeclarations, ProviderRole},
16 scope::{
17 ScopeEnd, ScopeEndResult, ScopeEnded, ScopeRecord, ScopeRecordResult, ScopeStamp,
18 ScopeStatus,
19 },
20 BindIdentity, Principal, RouteCloseReason, RouteTarget,
21};
22
23pub const MODULE_CONTROL_OP_HEALTH_CHECK: &str = "health.check";
24pub const MODULE_TO_SUBC_OP_CATALOG_UPDATE: &str = "catalog.update";
25pub const MODULE_TO_SUBC_OP_CATALOG_UPDATE_ROLE_DECLARATIONS: &str =
26 "catalog.update_role_declarations";
27
28#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
29#[serde(rename_all = "snake_case")]
30pub enum HealthStatus {
31 Ok,
32 Degraded,
33 Failing,
34}
35
36#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
37pub struct HealthReport {
38 pub status: HealthStatus,
39 #[serde(default, skip_serializing_if = "Option::is_none")]
40 pub detail: Option<String>,
41 #[serde(default, skip_serializing_if = "Option::is_none")]
42 pub metrics: Option<Value>,
43}
44
45impl HealthReport {
46 pub fn ok() -> Self {
47 Self {
48 status: HealthStatus::Ok,
49 detail: None,
50 metrics: None,
51 }
52 }
53}
54
55#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
57#[serde(tag = "op")]
58#[allow(clippy::large_enum_variant)]
61pub enum ModuleControlRequest {
62 #[serde(rename = "route.bind")]
63 RouteBind {
64 route_channel: u16,
65 epoch: u32,
66 target: RouteTarget,
67 identity: BindIdentity,
68 #[serde(default, skip_serializing_if = "Option::is_none")]
82 principal: Option<Principal>,
83 #[serde(default, skip_serializing_if = "Option::is_none")]
92 consumer_capabilities: Option<Vec<String>>,
93 #[serde(default, skip_serializing_if = "Option::is_none")]
102 role_versions: Option<BTreeMap<String, String>>,
103 #[serde(default, skip_serializing_if = "Option::is_none")]
105 admission_facts: Option<Value>,
106 #[serde(default, skip_serializing_if = "Option::is_none")]
116 scope: Option<ScopeStamp>,
117 #[serde(default, skip_serializing_if = "Option::is_none")]
122 call_mode: Option<CallMode>,
123 },
124 #[serde(rename = "health.check")]
125 HealthCheck {},
126}
127
128#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
130#[serde(tag = "op")]
131pub enum ModuleControlCommand {
132 #[serde(rename = "module.draining")]
133 Draining {
134 reason: RouteCloseReason,
135 deadline_ms: u64,
151 },
152}
153
154#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
156#[serde(tag = "op")]
157pub enum ModuleControlResponse {
158 #[serde(rename = "route.bind")]
160 RouteBindAck {},
161 #[serde(rename = "health.check")]
162 HealthCheck {
163 status: HealthStatus,
164 #[serde(default, skip_serializing_if = "Option::is_none")]
165 detail: Option<String>,
166 #[serde(default, skip_serializing_if = "Option::is_none")]
167 metrics: Option<Value>,
168 },
169}
170
171#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
177#[serde(tag = "op")]
178#[non_exhaustive]
179pub enum ModuleControlRequestFromModule {
180 #[serde(rename = "route.authorize")]
182 RouteAuthorize {
183 principal: Principal,
184 scope: crate::scope::RouteAuthorizeScope,
185 target: String,
186 expected: crate::scope::RouteAuthorizeExpected,
187 },
188 #[serde(rename = "catalog.update")]
189 CatalogUpdate {
190 provides: Vec<ProviderRole>,
191 #[serde(default, skip_serializing_if = "Option::is_none")]
195 capabilities: Option<CapabilityDeclarations>,
196 #[serde(default, skip_serializing_if = "Option::is_none")]
201 ready: Option<bool>,
202 },
203 #[serde(rename = "catalog.update_role_declarations")]
205 CatalogUpdateRoleDeclarations {
206 #[serde(deserialize_with = "Value::deserialize")]
209 role_declarations: Value,
210 },
211 #[serde(rename = "supervisor.live_roots")]
212 LiveRoots {},
213 #[serde(rename = "policy_root.get")]
214 PolicyRoot(crate::policy_root::GetPolicyRoot),
215 #[serde(rename = "policy_root.rotate")]
216 PolicyRootRotate(crate::policy_root::RotatePolicyRoot),
217 #[serde(rename = "supervisor.agent_commands")]
222 AgentCommands {
223 started: Vec<AgentCommandRoot>,
224 finished: Vec<AgentCommandFinished>,
225 #[serde(default, skip_serializing_if = "Option::is_none")]
226 known: Option<Vec<AgentCommandRoot>>,
227 },
228 #[serde(rename = "scope.sync")]
234 ScopeSync {
235 generation: u64,
236 scopes: Vec<ScopeRecord>,
237 },
238 #[serde(rename = "scope.apply")]
243 ScopeApply {
244 generation: u64,
245 upsert: Vec<ScopeRecord>,
246 end: Vec<ScopeEnd>,
247 },
248 #[serde(rename = "scope.describe")]
250 ScopeDescribe {
251 owner: Principal,
252 #[serde(rename = "ref")]
253 scope_ref: String,
254 },
255}
256
257#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord)]
260pub struct AgentCommandRoot {
261 pub pid: u32,
262 pub start_time_ms: u64,
263}
264
265#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
267pub struct AgentCommandFinished {
268 pub pid: u32,
269 pub start_time_ms: u64,
270 #[serde(default, skip_serializing_if = "Option::is_none")]
271 pub cpu_ms: Option<u64>,
272}
273
274#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
276pub struct LiveRoot {
277 pub project_root: std::path::PathBuf,
278 pub bound: u64,
279 pub pending: u64,
280}
281
282#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
284#[serde(tag = "op")]
285#[allow(clippy::large_enum_variant)]
288pub enum ModuleControlResponseToModule {
289 #[serde(rename = "catalog.update")]
290 CatalogUpdate {},
291 #[serde(rename = "catalog.update_role_declarations")]
292 CatalogUpdateRoleDeclarations {},
293 #[serde(rename = "supervisor.live_roots")]
294 LiveRoots {
295 roots: Vec<LiveRoot>,
296 unknown_root_bindings: u64,
297 total_bindings: u64,
298 },
299 #[serde(rename = "policy_root.get")]
300 PolicyRoot(crate::policy_root::PolicyRoot),
301 #[serde(rename = "policy_root.rotate")]
302 PolicyRootRotate(crate::policy_root::PolicyRootChange),
303 #[serde(rename = "scope.sync")]
304 ScopeSync {
305 generation: u64,
306 results: Vec<ScopeRecordResult>,
307 #[serde(default, skip_serializing_if = "Vec::is_empty")]
308 ended: Vec<ScopeEnded>,
309 },
310 #[serde(rename = "scope.apply")]
311 ScopeApply {
312 generation: u64,
313 results: Vec<ScopeRecordResult>,
314 end_results: Vec<ScopeEndResult>,
315 #[serde(default, skip_serializing_if = "Vec::is_empty")]
316 ended: Vec<ScopeEnded>,
317 },
318 #[serde(rename = "scope.describe")]
319 ScopeDescribe {
320 status: ScopeStatus,
321 #[serde(default, skip_serializing_if = "Option::is_none")]
323 scope_epoch: Option<u64>,
324 daemon_incarnation: String,
325 owner_synced: bool,
327 owner_configured: bool,
329 #[serde(default, skip_serializing_if = "Option::is_none")]
331 scope: Option<ScopeStamp>,
332 },
333}
334
335#[non_exhaustive]
341#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
342pub struct OperatorConfirmRequest {
343 op: OperatorConfirmOp,
344 pub summary: String,
345 pub route_channel: u16,
347 pub route_epoch: u32,
349 #[serde(default, skip_serializing_if = "Option::is_none")]
354 pub kind: Option<OperatorConfirmKind>,
355 #[serde(default, skip_serializing_if = "Option::is_none")]
359 pub operation: Option<String>,
360}
361
362impl OperatorConfirmRequest {
363 pub fn new(summary: impl Into<String>, route_channel: u16, route_epoch: u32) -> Self {
366 Self {
367 op: OperatorConfirmOp::Confirm,
368 summary: summary.into(),
369 route_channel,
370 route_epoch,
371 kind: None,
372 operation: None,
373 }
374 }
375
376 #[must_use]
378 pub fn with_kind(mut self, kind: Option<OperatorConfirmKind>) -> Self {
379 self.kind = kind;
380 self
381 }
382
383 #[must_use]
385 pub fn with_operation(mut self, operation: Option<String>) -> Self {
386 self.operation = operation;
387 self
388 }
389}
390
391#[derive(Debug, Clone, PartialEq, Eq)]
397pub enum OperatorConfirmKind {
398 Operation,
400 Enrollment,
402 Unknown(String),
403}
404
405impl Serialize for OperatorConfirmKind {
406 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
407 serializer.serialize_str(match self {
408 Self::Operation => "operation",
409 Self::Enrollment => "enrollment",
410 Self::Unknown(value) => value,
411 })
412 }
413}
414
415impl<'de> Deserialize<'de> for OperatorConfirmKind {
416 fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
417 Ok(match String::deserialize(deserializer)?.as_str() {
418 "operation" => Self::Operation,
419 "enrollment" => Self::Enrollment,
420 value => Self::Unknown(value.to_owned()),
421 })
422 }
423}
424
425#[non_exhaustive]
430#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
431pub struct OperatorConfirmReply {
432 op: OperatorConfirmOp,
433 pub outcome: String,
434}
435
436impl OperatorConfirmReply {
437 pub fn confirmed() -> Self {
438 Self {
439 op: OperatorConfirmOp::Confirm,
440 outcome: "confirmed".to_string(),
441 }
442 }
443}
444
445#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
448enum OperatorConfirmOp {
449 #[serde(rename = "operator.confirm")]
450 Confirm,
451}
452
453impl From<HealthReport> for ModuleControlResponse {
454 fn from(report: HealthReport) -> Self {
455 Self::HealthCheck {
456 status: report.status,
457 detail: report.detail,
458 metrics: report.metrics,
459 }
460 }
461}
462
463impl ModuleControlResponse {
464 pub fn health_report(&self) -> Option<HealthReport> {
465 match self {
466 Self::HealthCheck {
467 status,
468 detail,
469 metrics,
470 } => Some(HealthReport {
471 status: *status,
472 detail: detail.clone(),
473 metrics: metrics.clone(),
474 }),
475 Self::RouteBindAck {} => None,
476 }
477 }
478}
479
480#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
482#[serde(tag = "op")]
483pub enum ModuleControlPush {
484 #[serde(rename = "route.status")]
485 RouteStatus {
486 route_channel: u16,
487 route_epoch: u32,
488 status: String,
489 },
490}
491
492pub const ROLE_VERSIONS_FIELD: &str = "role_versions";
496
497pub const MAX_ROLE_VERSIONS: usize = 8;
499
500pub const MAX_ROLE_NAME_LEN: usize = 64;
502
503#[derive(Clone, Debug, PartialEq, Eq)]
505#[non_exhaustive]
506pub enum RoleVersionsError {
507 TooMany { count: usize },
509 InvalidRole { role: String },
513 InvalidVersion { role: String, version: String },
516}
517
518impl RoleVersionsError {
519 pub fn field(&self) -> &'static str {
521 ROLE_VERSIONS_FIELD
522 }
523}
524
525impl std::fmt::Display for RoleVersionsError {
526 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
527 match self {
528 Self::TooMany { count } => write!(
529 f,
530 "{ROLE_VERSIONS_FIELD} has {count} entries; at most {MAX_ROLE_VERSIONS} are allowed"
531 ),
532 Self::InvalidRole { role } => write!(
533 f,
534 "{ROLE_VERSIONS_FIELD} names role {role:?}, which is not lowercase letters and \
535 digits in words joined by '-', at most {MAX_ROLE_NAME_LEN} bytes"
536 ),
537 Self::InvalidVersion { role, version } => write!(
538 f,
539 "{ROLE_VERSIONS_FIELD} gives role {role:?} version {version:?}, which is not 'v' \
540 followed by a positive integer without leading zeros"
541 ),
542 }
543 }
544}
545
546impl std::error::Error for RoleVersionsError {}
547
548pub fn validate_role_versions(
556 role_versions: &BTreeMap<String, String>,
557) -> Result<(), RoleVersionsError> {
558 if role_versions.len() > MAX_ROLE_VERSIONS {
559 return Err(RoleVersionsError::TooMany {
560 count: role_versions.len(),
561 });
562 }
563 for (role, version) in role_versions {
564 if !is_role_name(role) {
565 return Err(RoleVersionsError::InvalidRole { role: role.clone() });
566 }
567 if !is_role_version(version) {
568 return Err(RoleVersionsError::InvalidVersion {
569 role: role.clone(),
570 version: version.clone(),
571 });
572 }
573 }
574 Ok(())
575}
576
577fn is_role_name(role: &str) -> bool {
578 !role.is_empty()
579 && role.len() <= MAX_ROLE_NAME_LEN
580 && role.split('-').all(|word| {
581 !word.is_empty()
582 && word
583 .bytes()
584 .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit())
585 })
586}
587
588fn is_role_version(version: &str) -> bool {
589 let bytes = version.as_bytes();
590 bytes.len() >= 2
591 && bytes[0] == b'v'
592 && (b'1'..=b'9').contains(&bytes[1])
593 && bytes[2..].iter().all(u8::is_ascii_digit)
594}
595
596#[cfg(test)]
597mod tests {
598 use super::*;
599
600 #[test]
601 fn catalog_update_role_declarations_wire_round_trip() {
602 for declarations in [
603 serde_json::json!({"media-provider/v1": {"engines": ["image"]}}),
604 serde_json::json!({}),
605 ] {
606 let body = serde_json::json!({
607 "op": "catalog.update_role_declarations",
608 "role_declarations": declarations,
609 });
610 let request: ModuleControlRequestFromModule =
611 serde_json::from_value(body.clone()).unwrap();
612 assert_eq!(serde_json::to_value(request).unwrap(), body);
613 }
614 let body = serde_json::json!({"op": "catalog.update_role_declarations"});
615 let response: ModuleControlResponseToModule = serde_json::from_value(body.clone()).unwrap();
616 assert_eq!(serde_json::to_value(response).unwrap(), body);
617 assert!(serde_json::from_value::<ModuleControlRequestFromModule>(body).is_err());
618 }
619
620 fn map(entries: &[(&str, &str)]) -> BTreeMap<String, String> {
621 entries
622 .iter()
623 .map(|(role, version)| (role.to_string(), version.to_string()))
624 .collect()
625 }
626
627 #[test]
628 fn role_versions_accept_role_names_and_positive_versions() {
629 for entries in [
630 vec![],
631 vec![("tool-provider", "v1")],
632 vec![("a", "v9"), ("b2", "v10"), ("x-1-y", "v1203")],
633 ] {
634 assert_eq!(
635 validate_role_versions(&map(&entries)),
636 Ok(()),
637 "{entries:?}"
638 );
639 }
640 let longest = "a".repeat(MAX_ROLE_NAME_LEN);
641 assert_eq!(validate_role_versions(&map(&[(&longest, "v1")])), Ok(()));
642 let full: BTreeMap<String, String> = (0..MAX_ROLE_VERSIONS)
643 .map(|index| (format!("role-{index}"), "v1".to_string()))
644 .collect();
645 assert_eq!(validate_role_versions(&full), Ok(()));
646 }
647
648 #[test]
649 fn role_versions_refuse_malformed_role_names() {
650 let too_long = "a".repeat(MAX_ROLE_NAME_LEN + 1);
651 for role in [
652 "",
653 "Tool-provider",
654 "tool_provider",
655 "tool provider",
656 "-tool",
657 "tool-",
658 "tool--provider",
659 "tool.provider",
660 "outil-é",
661 too_long.as_str(),
662 ] {
663 let error = validate_role_versions(&map(&[(role, "v1")])).unwrap_err();
664 assert_eq!(
665 error,
666 RoleVersionsError::InvalidRole {
667 role: role.to_string()
668 },
669 "{role:?}"
670 );
671 assert_eq!(error.field(), "role_versions");
672 }
673 }
674
675 #[test]
676 fn role_versions_refuse_malformed_versions() {
677 for version in [
678 "", "v", "v0", "v01", "1", "V1", "v1.0", "v-1", "v1 ", " v1", "vx",
679 ] {
680 let error = validate_role_versions(&map(&[("tool-provider", version)])).unwrap_err();
681 assert_eq!(
682 error,
683 RoleVersionsError::InvalidVersion {
684 role: "tool-provider".to_string(),
685 version: version.to_string(),
686 },
687 "{version:?}"
688 );
689 assert_eq!(error.field(), "role_versions");
690 }
691 }
692
693 #[test]
694 fn role_versions_refuse_more_than_eight_entries() {
695 let nine: BTreeMap<String, String> = (0..=MAX_ROLE_VERSIONS)
696 .map(|index| (format!("role-{index}"), "v1".to_string()))
697 .collect();
698 let error = validate_role_versions(&nine).unwrap_err();
699 assert_eq!(error, RoleVersionsError::TooMany { count: 9 });
700 assert_eq!(error.field(), "role_versions");
701 assert!(error.to_string().starts_with("role_versions"), "{error}");
702 }
703
704 #[test]
705 fn route_bind_omits_absent_role_versions_and_carries_present_ones_verbatim() {
706 let bind = |role_versions| ModuleControlRequest::RouteBind {
707 route_channel: 1,
708 epoch: 1,
709 target: crate::RouteTarget::ToolProvider {
710 module_id: "aft".to_string(),
711 },
712 identity: crate::BindIdentity::new("h", "s"),
713 principal: None,
714 consumer_capabilities: None,
715 role_versions,
716 admission_facts: None,
717 scope: None,
718 call_mode: None,
719 };
720 let absent = serde_json::to_value(bind(None)).unwrap();
721 assert!(absent.get("role_versions").is_none(), "{absent}");
722 let present = bind(Some(map(&[("tool-provider", "v1")])));
723 let encoded = serde_json::to_value(&present).unwrap();
724 assert_eq!(
725 encoded["role_versions"],
726 serde_json::json!({ "tool-provider": "v1" })
727 );
728 let decoded: ModuleControlRequest = serde_json::from_value(encoded).unwrap();
729 assert_eq!(decoded, present);
730 }
731}
732
733#[cfg(test)]
734mod agent_command_tests {
735 use super::*;
736
737 #[test]
738 fn agent_commands_round_trip_start_finish_and_known_snapshot() {
739 let root = AgentCommandRoot {
740 pid: 42,
741 start_time_ms: 1_700_000_000_123,
742 };
743 let request = ModuleControlRequestFromModule::AgentCommands {
744 started: vec![root],
745 finished: vec![AgentCommandFinished {
746 pid: 43,
747 start_time_ms: root.start_time_ms,
748 cpu_ms: Some(100),
749 }],
750 known: Some(vec![root]),
751 };
752 let value = serde_json::to_value(&request).unwrap();
753 assert_eq!(
754 value,
755 serde_json::json!({"op":"supervisor.agent_commands",
756 "started":[{"pid":42,"start_time_ms":1_700_000_000_123_u64}],
757 "finished":[{"pid":43,"start_time_ms":1_700_000_000_123_u64,"cpu_ms":100}],
758 "known":[{"pid":42,"start_time_ms":1_700_000_000_123_u64}]})
759 );
760 assert_eq!(
761 serde_json::from_value::<ModuleControlRequestFromModule>(value).unwrap(),
762 request
763 );
764 let absent = ModuleControlRequestFromModule::AgentCommands {
765 started: Vec::new(),
766 finished: vec![AgentCommandFinished {
767 pid: 1,
768 start_time_ms: 2,
769 cpu_ms: None,
770 }],
771 known: None,
772 };
773 assert_eq!(
774 serde_json::to_value(absent).unwrap(),
775 serde_json::json!({"op":"supervisor.agent_commands",
776 "started":[],"finished":[{"pid":1,"start_time_ms":2}]})
777 );
778 }
779}