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 = "supervisor.agent_commands")]
218 AgentCommands {
219 started: Vec<AgentCommandRoot>,
220 finished: Vec<AgentCommandFinished>,
221 #[serde(default, skip_serializing_if = "Option::is_none")]
222 known: Option<Vec<AgentCommandRoot>>,
223 },
224 #[serde(rename = "scope.sync")]
230 ScopeSync {
231 generation: u64,
232 scopes: Vec<ScopeRecord>,
233 },
234 #[serde(rename = "scope.apply")]
239 ScopeApply {
240 generation: u64,
241 upsert: Vec<ScopeRecord>,
242 end: Vec<ScopeEnd>,
243 },
244 #[serde(rename = "scope.describe")]
246 ScopeDescribe {
247 owner: Principal,
248 #[serde(rename = "ref")]
249 scope_ref: String,
250 },
251}
252
253#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord)]
256pub struct AgentCommandRoot {
257 pub pid: u32,
258 pub start_time_ms: u64,
259}
260
261#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
263pub struct AgentCommandFinished {
264 pub pid: u32,
265 pub start_time_ms: u64,
266 #[serde(default, skip_serializing_if = "Option::is_none")]
267 pub cpu_ms: Option<u64>,
268}
269
270#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
272pub struct LiveRoot {
273 pub project_root: std::path::PathBuf,
274 pub bound: u64,
275 pub pending: u64,
276}
277
278#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
280#[serde(tag = "op")]
281#[allow(clippy::large_enum_variant)]
284pub enum ModuleControlResponseToModule {
285 #[serde(rename = "catalog.update")]
286 CatalogUpdate {},
287 #[serde(rename = "catalog.update_role_declarations")]
288 CatalogUpdateRoleDeclarations {},
289 #[serde(rename = "supervisor.live_roots")]
290 LiveRoots {
291 roots: Vec<LiveRoot>,
292 unknown_root_bindings: u64,
293 total_bindings: u64,
294 },
295 #[serde(rename = "scope.sync")]
296 ScopeSync {
297 generation: u64,
298 results: Vec<ScopeRecordResult>,
299 #[serde(default, skip_serializing_if = "Vec::is_empty")]
300 ended: Vec<ScopeEnded>,
301 },
302 #[serde(rename = "scope.apply")]
303 ScopeApply {
304 generation: u64,
305 results: Vec<ScopeRecordResult>,
306 end_results: Vec<ScopeEndResult>,
307 #[serde(default, skip_serializing_if = "Vec::is_empty")]
308 ended: Vec<ScopeEnded>,
309 },
310 #[serde(rename = "scope.describe")]
311 ScopeDescribe {
312 status: ScopeStatus,
313 #[serde(default, skip_serializing_if = "Option::is_none")]
315 scope_epoch: Option<u64>,
316 daemon_incarnation: String,
317 owner_synced: bool,
319 owner_configured: bool,
321 #[serde(default, skip_serializing_if = "Option::is_none")]
323 scope: Option<ScopeStamp>,
324 },
325}
326
327#[non_exhaustive]
333#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
334pub struct OperatorConfirmRequest {
335 op: OperatorConfirmOp,
336 pub summary: String,
337 pub route_channel: u16,
339 pub route_epoch: u32,
341 #[serde(default, skip_serializing_if = "Option::is_none")]
346 pub kind: Option<OperatorConfirmKind>,
347 #[serde(default, skip_serializing_if = "Option::is_none")]
351 pub operation: Option<String>,
352}
353
354impl OperatorConfirmRequest {
355 pub fn new(summary: impl Into<String>, route_channel: u16, route_epoch: u32) -> Self {
358 Self {
359 op: OperatorConfirmOp::Confirm,
360 summary: summary.into(),
361 route_channel,
362 route_epoch,
363 kind: None,
364 operation: None,
365 }
366 }
367
368 #[must_use]
370 pub fn with_kind(mut self, kind: Option<OperatorConfirmKind>) -> Self {
371 self.kind = kind;
372 self
373 }
374
375 #[must_use]
377 pub fn with_operation(mut self, operation: Option<String>) -> Self {
378 self.operation = operation;
379 self
380 }
381}
382
383#[derive(Debug, Clone, PartialEq, Eq)]
389pub enum OperatorConfirmKind {
390 Operation,
392 Enrollment,
394 Unknown(String),
395}
396
397impl Serialize for OperatorConfirmKind {
398 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
399 serializer.serialize_str(match self {
400 Self::Operation => "operation",
401 Self::Enrollment => "enrollment",
402 Self::Unknown(value) => value,
403 })
404 }
405}
406
407impl<'de> Deserialize<'de> for OperatorConfirmKind {
408 fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
409 Ok(match String::deserialize(deserializer)?.as_str() {
410 "operation" => Self::Operation,
411 "enrollment" => Self::Enrollment,
412 value => Self::Unknown(value.to_owned()),
413 })
414 }
415}
416
417#[non_exhaustive]
422#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
423pub struct OperatorConfirmReply {
424 op: OperatorConfirmOp,
425 pub outcome: String,
426}
427
428impl OperatorConfirmReply {
429 pub fn confirmed() -> Self {
430 Self {
431 op: OperatorConfirmOp::Confirm,
432 outcome: "confirmed".to_string(),
433 }
434 }
435}
436
437#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
440enum OperatorConfirmOp {
441 #[serde(rename = "operator.confirm")]
442 Confirm,
443}
444
445impl From<HealthReport> for ModuleControlResponse {
446 fn from(report: HealthReport) -> Self {
447 Self::HealthCheck {
448 status: report.status,
449 detail: report.detail,
450 metrics: report.metrics,
451 }
452 }
453}
454
455impl ModuleControlResponse {
456 pub fn health_report(&self) -> Option<HealthReport> {
457 match self {
458 Self::HealthCheck {
459 status,
460 detail,
461 metrics,
462 } => Some(HealthReport {
463 status: *status,
464 detail: detail.clone(),
465 metrics: metrics.clone(),
466 }),
467 Self::RouteBindAck {} => None,
468 }
469 }
470}
471
472#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
474#[serde(tag = "op")]
475pub enum ModuleControlPush {
476 #[serde(rename = "route.status")]
477 RouteStatus {
478 route_channel: u16,
479 route_epoch: u32,
480 status: String,
481 },
482}
483
484pub const ROLE_VERSIONS_FIELD: &str = "role_versions";
488
489pub const MAX_ROLE_VERSIONS: usize = 8;
491
492pub const MAX_ROLE_NAME_LEN: usize = 64;
494
495#[derive(Clone, Debug, PartialEq, Eq)]
497#[non_exhaustive]
498pub enum RoleVersionsError {
499 TooMany { count: usize },
501 InvalidRole { role: String },
505 InvalidVersion { role: String, version: String },
508}
509
510impl RoleVersionsError {
511 pub fn field(&self) -> &'static str {
513 ROLE_VERSIONS_FIELD
514 }
515}
516
517impl std::fmt::Display for RoleVersionsError {
518 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
519 match self {
520 Self::TooMany { count } => write!(
521 f,
522 "{ROLE_VERSIONS_FIELD} has {count} entries; at most {MAX_ROLE_VERSIONS} are allowed"
523 ),
524 Self::InvalidRole { role } => write!(
525 f,
526 "{ROLE_VERSIONS_FIELD} names role {role:?}, which is not lowercase letters and \
527 digits in words joined by '-', at most {MAX_ROLE_NAME_LEN} bytes"
528 ),
529 Self::InvalidVersion { role, version } => write!(
530 f,
531 "{ROLE_VERSIONS_FIELD} gives role {role:?} version {version:?}, which is not 'v' \
532 followed by a positive integer without leading zeros"
533 ),
534 }
535 }
536}
537
538impl std::error::Error for RoleVersionsError {}
539
540pub fn validate_role_versions(
548 role_versions: &BTreeMap<String, String>,
549) -> Result<(), RoleVersionsError> {
550 if role_versions.len() > MAX_ROLE_VERSIONS {
551 return Err(RoleVersionsError::TooMany {
552 count: role_versions.len(),
553 });
554 }
555 for (role, version) in role_versions {
556 if !is_role_name(role) {
557 return Err(RoleVersionsError::InvalidRole { role: role.clone() });
558 }
559 if !is_role_version(version) {
560 return Err(RoleVersionsError::InvalidVersion {
561 role: role.clone(),
562 version: version.clone(),
563 });
564 }
565 }
566 Ok(())
567}
568
569fn is_role_name(role: &str) -> bool {
570 !role.is_empty()
571 && role.len() <= MAX_ROLE_NAME_LEN
572 && role.split('-').all(|word| {
573 !word.is_empty()
574 && word
575 .bytes()
576 .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit())
577 })
578}
579
580fn is_role_version(version: &str) -> bool {
581 let bytes = version.as_bytes();
582 bytes.len() >= 2
583 && bytes[0] == b'v'
584 && (b'1'..=b'9').contains(&bytes[1])
585 && bytes[2..].iter().all(u8::is_ascii_digit)
586}
587
588#[cfg(test)]
589mod tests {
590 use super::*;
591
592 #[test]
593 fn catalog_update_role_declarations_wire_round_trip() {
594 for declarations in [
595 serde_json::json!({"media-provider/v1": {"engines": ["image"]}}),
596 serde_json::json!({}),
597 ] {
598 let body = serde_json::json!({
599 "op": "catalog.update_role_declarations",
600 "role_declarations": declarations,
601 });
602 let request: ModuleControlRequestFromModule =
603 serde_json::from_value(body.clone()).unwrap();
604 assert_eq!(serde_json::to_value(request).unwrap(), body);
605 }
606 let body = serde_json::json!({"op": "catalog.update_role_declarations"});
607 let response: ModuleControlResponseToModule = serde_json::from_value(body.clone()).unwrap();
608 assert_eq!(serde_json::to_value(response).unwrap(), body);
609 assert!(serde_json::from_value::<ModuleControlRequestFromModule>(body).is_err());
610 }
611
612 fn map(entries: &[(&str, &str)]) -> BTreeMap<String, String> {
613 entries
614 .iter()
615 .map(|(role, version)| (role.to_string(), version.to_string()))
616 .collect()
617 }
618
619 #[test]
620 fn role_versions_accept_role_names_and_positive_versions() {
621 for entries in [
622 vec![],
623 vec![("tool-provider", "v1")],
624 vec![("a", "v9"), ("b2", "v10"), ("x-1-y", "v1203")],
625 ] {
626 assert_eq!(
627 validate_role_versions(&map(&entries)),
628 Ok(()),
629 "{entries:?}"
630 );
631 }
632 let longest = "a".repeat(MAX_ROLE_NAME_LEN);
633 assert_eq!(validate_role_versions(&map(&[(&longest, "v1")])), Ok(()));
634 let full: BTreeMap<String, String> = (0..MAX_ROLE_VERSIONS)
635 .map(|index| (format!("role-{index}"), "v1".to_string()))
636 .collect();
637 assert_eq!(validate_role_versions(&full), Ok(()));
638 }
639
640 #[test]
641 fn role_versions_refuse_malformed_role_names() {
642 let too_long = "a".repeat(MAX_ROLE_NAME_LEN + 1);
643 for role in [
644 "",
645 "Tool-provider",
646 "tool_provider",
647 "tool provider",
648 "-tool",
649 "tool-",
650 "tool--provider",
651 "tool.provider",
652 "outil-é",
653 too_long.as_str(),
654 ] {
655 let error = validate_role_versions(&map(&[(role, "v1")])).unwrap_err();
656 assert_eq!(
657 error,
658 RoleVersionsError::InvalidRole {
659 role: role.to_string()
660 },
661 "{role:?}"
662 );
663 assert_eq!(error.field(), "role_versions");
664 }
665 }
666
667 #[test]
668 fn role_versions_refuse_malformed_versions() {
669 for version in [
670 "", "v", "v0", "v01", "1", "V1", "v1.0", "v-1", "v1 ", " v1", "vx",
671 ] {
672 let error = validate_role_versions(&map(&[("tool-provider", version)])).unwrap_err();
673 assert_eq!(
674 error,
675 RoleVersionsError::InvalidVersion {
676 role: "tool-provider".to_string(),
677 version: version.to_string(),
678 },
679 "{version:?}"
680 );
681 assert_eq!(error.field(), "role_versions");
682 }
683 }
684
685 #[test]
686 fn role_versions_refuse_more_than_eight_entries() {
687 let nine: BTreeMap<String, String> = (0..=MAX_ROLE_VERSIONS)
688 .map(|index| (format!("role-{index}"), "v1".to_string()))
689 .collect();
690 let error = validate_role_versions(&nine).unwrap_err();
691 assert_eq!(error, RoleVersionsError::TooMany { count: 9 });
692 assert_eq!(error.field(), "role_versions");
693 assert!(error.to_string().starts_with("role_versions"), "{error}");
694 }
695
696 #[test]
697 fn route_bind_omits_absent_role_versions_and_carries_present_ones_verbatim() {
698 let bind = |role_versions| ModuleControlRequest::RouteBind {
699 route_channel: 1,
700 epoch: 1,
701 target: crate::RouteTarget::ToolProvider {
702 module_id: "aft".to_string(),
703 },
704 identity: crate::BindIdentity::new("h", "s"),
705 principal: None,
706 consumer_capabilities: None,
707 role_versions,
708 admission_facts: None,
709 scope: None,
710 call_mode: None,
711 };
712 let absent = serde_json::to_value(bind(None)).unwrap();
713 assert!(absent.get("role_versions").is_none(), "{absent}");
714 let present = bind(Some(map(&[("tool-provider", "v1")])));
715 let encoded = serde_json::to_value(&present).unwrap();
716 assert_eq!(
717 encoded["role_versions"],
718 serde_json::json!({ "tool-provider": "v1" })
719 );
720 let decoded: ModuleControlRequest = serde_json::from_value(encoded).unwrap();
721 assert_eq!(decoded, present);
722 }
723}
724
725#[cfg(test)]
726mod agent_command_tests {
727 use super::*;
728
729 #[test]
730 fn agent_commands_round_trip_start_finish_and_known_snapshot() {
731 let root = AgentCommandRoot {
732 pid: 42,
733 start_time_ms: 1_700_000_000_123,
734 };
735 let request = ModuleControlRequestFromModule::AgentCommands {
736 started: vec![root],
737 finished: vec![AgentCommandFinished {
738 pid: 43,
739 start_time_ms: root.start_time_ms,
740 cpu_ms: Some(100),
741 }],
742 known: Some(vec![root]),
743 };
744 let value = serde_json::to_value(&request).unwrap();
745 assert_eq!(
746 value,
747 serde_json::json!({"op":"supervisor.agent_commands",
748 "started":[{"pid":42,"start_time_ms":1_700_000_000_123_u64}],
749 "finished":[{"pid":43,"start_time_ms":1_700_000_000_123_u64,"cpu_ms":100}],
750 "known":[{"pid":42,"start_time_ms":1_700_000_000_123_u64}]})
751 );
752 assert_eq!(
753 serde_json::from_value::<ModuleControlRequestFromModule>(value).unwrap(),
754 request
755 );
756 let absent = ModuleControlRequestFromModule::AgentCommands {
757 started: Vec::new(),
758 finished: vec![AgentCommandFinished {
759 pid: 1,
760 start_time_ms: 2,
761 cpu_ms: None,
762 }],
763 known: None,
764 };
765 assert_eq!(
766 serde_json::to_value(absent).unwrap(),
767 serde_json::json!({"op":"supervisor.agent_commands",
768 "started":[],"finished":[{"pid":1,"start_time_ms":2}]})
769 );
770 }
771}