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";
25
26#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
27#[serde(rename_all = "snake_case")]
28pub enum HealthStatus {
29 Ok,
30 Degraded,
31 Failing,
32}
33
34#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
35pub struct HealthReport {
36 pub status: HealthStatus,
37 #[serde(default, skip_serializing_if = "Option::is_none")]
38 pub detail: Option<String>,
39 #[serde(default, skip_serializing_if = "Option::is_none")]
40 pub metrics: Option<Value>,
41}
42
43impl HealthReport {
44 pub fn ok() -> Self {
45 Self {
46 status: HealthStatus::Ok,
47 detail: None,
48 metrics: None,
49 }
50 }
51}
52
53#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
55#[serde(tag = "op")]
56#[allow(clippy::large_enum_variant)]
59pub enum ModuleControlRequest {
60 #[serde(rename = "route.bind")]
61 RouteBind {
62 route_channel: u16,
63 epoch: u32,
64 target: RouteTarget,
65 identity: BindIdentity,
66 #[serde(default, skip_serializing_if = "Option::is_none")]
80 principal: Option<Principal>,
81 #[serde(default, skip_serializing_if = "Option::is_none")]
90 consumer_capabilities: Option<Vec<String>>,
91 #[serde(default, skip_serializing_if = "Option::is_none")]
100 role_versions: Option<BTreeMap<String, String>>,
101 #[serde(default, skip_serializing_if = "Option::is_none")]
103 admission_facts: Option<Value>,
104 #[serde(default, skip_serializing_if = "Option::is_none")]
114 scope: Option<ScopeStamp>,
115 #[serde(default, skip_serializing_if = "Option::is_none")]
120 call_mode: Option<CallMode>,
121 },
122 #[serde(rename = "health.check")]
123 HealthCheck {},
124}
125
126#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
128#[serde(tag = "op")]
129pub enum ModuleControlCommand {
130 #[serde(rename = "module.draining")]
131 Draining {
132 reason: RouteCloseReason,
133 deadline_ms: u64,
149 },
150}
151
152#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
154#[serde(tag = "op")]
155pub enum ModuleControlResponse {
156 #[serde(rename = "route.bind")]
158 RouteBindAck {},
159 #[serde(rename = "health.check")]
160 HealthCheck {
161 status: HealthStatus,
162 #[serde(default, skip_serializing_if = "Option::is_none")]
163 detail: Option<String>,
164 #[serde(default, skip_serializing_if = "Option::is_none")]
165 metrics: Option<Value>,
166 },
167}
168
169#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
175#[serde(tag = "op")]
176#[non_exhaustive]
177pub enum ModuleControlRequestFromModule {
178 #[serde(rename = "route.authorize")]
180 RouteAuthorize {
181 principal: Principal,
182 scope: crate::scope::RouteAuthorizeScope,
183 target: String,
184 expected: crate::scope::RouteAuthorizeExpected,
185 },
186 #[serde(rename = "catalog.update")]
187 CatalogUpdate {
188 provides: Vec<ProviderRole>,
189 #[serde(default, skip_serializing_if = "Option::is_none")]
193 capabilities: Option<CapabilityDeclarations>,
194 #[serde(default, skip_serializing_if = "Option::is_none")]
199 ready: Option<bool>,
200 },
201 #[serde(rename = "supervisor.live_roots")]
202 LiveRoots {},
203 #[serde(rename = "supervisor.agent_commands")]
208 AgentCommands {
209 started: Vec<AgentCommandRoot>,
210 finished: Vec<AgentCommandFinished>,
211 #[serde(default, skip_serializing_if = "Option::is_none")]
212 known: Option<Vec<AgentCommandRoot>>,
213 },
214 #[serde(rename = "scope.sync")]
220 ScopeSync {
221 generation: u64,
222 scopes: Vec<ScopeRecord>,
223 },
224 #[serde(rename = "scope.apply")]
229 ScopeApply {
230 generation: u64,
231 upsert: Vec<ScopeRecord>,
232 end: Vec<ScopeEnd>,
233 },
234 #[serde(rename = "scope.describe")]
236 ScopeDescribe {
237 owner: Principal,
238 #[serde(rename = "ref")]
239 scope_ref: String,
240 },
241}
242
243#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord)]
246pub struct AgentCommandRoot {
247 pub pid: u32,
248 pub start_time_ms: u64,
249}
250
251#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
253pub struct AgentCommandFinished {
254 pub pid: u32,
255 pub start_time_ms: u64,
256 #[serde(default, skip_serializing_if = "Option::is_none")]
257 pub cpu_ms: Option<u64>,
258}
259
260#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
262pub struct LiveRoot {
263 pub project_root: std::path::PathBuf,
264 pub bound: u64,
265 pub pending: u64,
266}
267
268#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
270#[serde(tag = "op")]
271#[allow(clippy::large_enum_variant)]
274pub enum ModuleControlResponseToModule {
275 #[serde(rename = "catalog.update")]
276 CatalogUpdate {},
277 #[serde(rename = "supervisor.live_roots")]
278 LiveRoots {
279 roots: Vec<LiveRoot>,
280 unknown_root_bindings: u64,
281 total_bindings: u64,
282 },
283 #[serde(rename = "scope.sync")]
284 ScopeSync {
285 generation: u64,
286 results: Vec<ScopeRecordResult>,
287 #[serde(default, skip_serializing_if = "Vec::is_empty")]
288 ended: Vec<ScopeEnded>,
289 },
290 #[serde(rename = "scope.apply")]
291 ScopeApply {
292 generation: u64,
293 results: Vec<ScopeRecordResult>,
294 end_results: Vec<ScopeEndResult>,
295 #[serde(default, skip_serializing_if = "Vec::is_empty")]
296 ended: Vec<ScopeEnded>,
297 },
298 #[serde(rename = "scope.describe")]
299 ScopeDescribe {
300 status: ScopeStatus,
301 #[serde(default, skip_serializing_if = "Option::is_none")]
303 scope_epoch: Option<u64>,
304 daemon_incarnation: String,
305 owner_synced: bool,
307 owner_configured: bool,
309 #[serde(default, skip_serializing_if = "Option::is_none")]
311 scope: Option<ScopeStamp>,
312 },
313}
314
315#[non_exhaustive]
321#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
322pub struct OperatorConfirmRequest {
323 op: OperatorConfirmOp,
324 pub summary: String,
325 pub route_channel: u16,
327 pub route_epoch: u32,
329 #[serde(default, skip_serializing_if = "Option::is_none")]
334 pub kind: Option<OperatorConfirmKind>,
335 #[serde(default, skip_serializing_if = "Option::is_none")]
339 pub operation: Option<String>,
340}
341
342impl OperatorConfirmRequest {
343 pub fn new(summary: impl Into<String>, route_channel: u16, route_epoch: u32) -> Self {
346 Self {
347 op: OperatorConfirmOp::Confirm,
348 summary: summary.into(),
349 route_channel,
350 route_epoch,
351 kind: None,
352 operation: None,
353 }
354 }
355
356 #[must_use]
358 pub fn with_kind(mut self, kind: Option<OperatorConfirmKind>) -> Self {
359 self.kind = kind;
360 self
361 }
362
363 #[must_use]
365 pub fn with_operation(mut self, operation: Option<String>) -> Self {
366 self.operation = operation;
367 self
368 }
369}
370
371#[derive(Debug, Clone, PartialEq, Eq)]
377pub enum OperatorConfirmKind {
378 Operation,
380 Enrollment,
382 Unknown(String),
383}
384
385impl Serialize for OperatorConfirmKind {
386 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
387 serializer.serialize_str(match self {
388 Self::Operation => "operation",
389 Self::Enrollment => "enrollment",
390 Self::Unknown(value) => value,
391 })
392 }
393}
394
395impl<'de> Deserialize<'de> for OperatorConfirmKind {
396 fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
397 Ok(match String::deserialize(deserializer)?.as_str() {
398 "operation" => Self::Operation,
399 "enrollment" => Self::Enrollment,
400 value => Self::Unknown(value.to_owned()),
401 })
402 }
403}
404
405#[non_exhaustive]
410#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
411pub struct OperatorConfirmReply {
412 op: OperatorConfirmOp,
413 pub outcome: String,
414}
415
416impl OperatorConfirmReply {
417 pub fn confirmed() -> Self {
418 Self {
419 op: OperatorConfirmOp::Confirm,
420 outcome: "confirmed".to_string(),
421 }
422 }
423}
424
425#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
428enum OperatorConfirmOp {
429 #[serde(rename = "operator.confirm")]
430 Confirm,
431}
432
433impl From<HealthReport> for ModuleControlResponse {
434 fn from(report: HealthReport) -> Self {
435 Self::HealthCheck {
436 status: report.status,
437 detail: report.detail,
438 metrics: report.metrics,
439 }
440 }
441}
442
443impl ModuleControlResponse {
444 pub fn health_report(&self) -> Option<HealthReport> {
445 match self {
446 Self::HealthCheck {
447 status,
448 detail,
449 metrics,
450 } => Some(HealthReport {
451 status: *status,
452 detail: detail.clone(),
453 metrics: metrics.clone(),
454 }),
455 Self::RouteBindAck {} => None,
456 }
457 }
458}
459
460#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
462#[serde(tag = "op")]
463pub enum ModuleControlPush {
464 #[serde(rename = "route.status")]
465 RouteStatus {
466 route_channel: u16,
467 route_epoch: u32,
468 status: String,
469 },
470}
471
472pub const ROLE_VERSIONS_FIELD: &str = "role_versions";
476
477pub const MAX_ROLE_VERSIONS: usize = 8;
479
480pub const MAX_ROLE_NAME_LEN: usize = 64;
482
483#[derive(Clone, Debug, PartialEq, Eq)]
485#[non_exhaustive]
486pub enum RoleVersionsError {
487 TooMany { count: usize },
489 InvalidRole { role: String },
493 InvalidVersion { role: String, version: String },
496}
497
498impl RoleVersionsError {
499 pub fn field(&self) -> &'static str {
501 ROLE_VERSIONS_FIELD
502 }
503}
504
505impl std::fmt::Display for RoleVersionsError {
506 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
507 match self {
508 Self::TooMany { count } => write!(
509 f,
510 "{ROLE_VERSIONS_FIELD} has {count} entries; at most {MAX_ROLE_VERSIONS} are allowed"
511 ),
512 Self::InvalidRole { role } => write!(
513 f,
514 "{ROLE_VERSIONS_FIELD} names role {role:?}, which is not lowercase letters and \
515 digits in words joined by '-', at most {MAX_ROLE_NAME_LEN} bytes"
516 ),
517 Self::InvalidVersion { role, version } => write!(
518 f,
519 "{ROLE_VERSIONS_FIELD} gives role {role:?} version {version:?}, which is not 'v' \
520 followed by a positive integer without leading zeros"
521 ),
522 }
523 }
524}
525
526impl std::error::Error for RoleVersionsError {}
527
528pub fn validate_role_versions(
536 role_versions: &BTreeMap<String, String>,
537) -> Result<(), RoleVersionsError> {
538 if role_versions.len() > MAX_ROLE_VERSIONS {
539 return Err(RoleVersionsError::TooMany {
540 count: role_versions.len(),
541 });
542 }
543 for (role, version) in role_versions {
544 if !is_role_name(role) {
545 return Err(RoleVersionsError::InvalidRole { role: role.clone() });
546 }
547 if !is_role_version(version) {
548 return Err(RoleVersionsError::InvalidVersion {
549 role: role.clone(),
550 version: version.clone(),
551 });
552 }
553 }
554 Ok(())
555}
556
557fn is_role_name(role: &str) -> bool {
558 !role.is_empty()
559 && role.len() <= MAX_ROLE_NAME_LEN
560 && role.split('-').all(|word| {
561 !word.is_empty()
562 && word
563 .bytes()
564 .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit())
565 })
566}
567
568fn is_role_version(version: &str) -> bool {
569 let bytes = version.as_bytes();
570 bytes.len() >= 2
571 && bytes[0] == b'v'
572 && (b'1'..=b'9').contains(&bytes[1])
573 && bytes[2..].iter().all(u8::is_ascii_digit)
574}
575
576#[cfg(test)]
577mod tests {
578 use super::*;
579
580 fn map(entries: &[(&str, &str)]) -> BTreeMap<String, String> {
581 entries
582 .iter()
583 .map(|(role, version)| (role.to_string(), version.to_string()))
584 .collect()
585 }
586
587 #[test]
588 fn role_versions_accept_role_names_and_positive_versions() {
589 for entries in [
590 vec![],
591 vec![("tool-provider", "v1")],
592 vec![("a", "v9"), ("b2", "v10"), ("x-1-y", "v1203")],
593 ] {
594 assert_eq!(
595 validate_role_versions(&map(&entries)),
596 Ok(()),
597 "{entries:?}"
598 );
599 }
600 let longest = "a".repeat(MAX_ROLE_NAME_LEN);
601 assert_eq!(validate_role_versions(&map(&[(&longest, "v1")])), Ok(()));
602 let full: BTreeMap<String, String> = (0..MAX_ROLE_VERSIONS)
603 .map(|index| (format!("role-{index}"), "v1".to_string()))
604 .collect();
605 assert_eq!(validate_role_versions(&full), Ok(()));
606 }
607
608 #[test]
609 fn role_versions_refuse_malformed_role_names() {
610 let too_long = "a".repeat(MAX_ROLE_NAME_LEN + 1);
611 for role in [
612 "",
613 "Tool-provider",
614 "tool_provider",
615 "tool provider",
616 "-tool",
617 "tool-",
618 "tool--provider",
619 "tool.provider",
620 "outil-é",
621 too_long.as_str(),
622 ] {
623 let error = validate_role_versions(&map(&[(role, "v1")])).unwrap_err();
624 assert_eq!(
625 error,
626 RoleVersionsError::InvalidRole {
627 role: role.to_string()
628 },
629 "{role:?}"
630 );
631 assert_eq!(error.field(), "role_versions");
632 }
633 }
634
635 #[test]
636 fn role_versions_refuse_malformed_versions() {
637 for version in [
638 "", "v", "v0", "v01", "1", "V1", "v1.0", "v-1", "v1 ", " v1", "vx",
639 ] {
640 let error = validate_role_versions(&map(&[("tool-provider", version)])).unwrap_err();
641 assert_eq!(
642 error,
643 RoleVersionsError::InvalidVersion {
644 role: "tool-provider".to_string(),
645 version: version.to_string(),
646 },
647 "{version:?}"
648 );
649 assert_eq!(error.field(), "role_versions");
650 }
651 }
652
653 #[test]
654 fn role_versions_refuse_more_than_eight_entries() {
655 let nine: BTreeMap<String, String> = (0..=MAX_ROLE_VERSIONS)
656 .map(|index| (format!("role-{index}"), "v1".to_string()))
657 .collect();
658 let error = validate_role_versions(&nine).unwrap_err();
659 assert_eq!(error, RoleVersionsError::TooMany { count: 9 });
660 assert_eq!(error.field(), "role_versions");
661 assert!(error.to_string().starts_with("role_versions"), "{error}");
662 }
663
664 #[test]
665 fn route_bind_omits_absent_role_versions_and_carries_present_ones_verbatim() {
666 let bind = |role_versions| ModuleControlRequest::RouteBind {
667 route_channel: 1,
668 epoch: 1,
669 target: crate::RouteTarget::ToolProvider {
670 module_id: "aft".to_string(),
671 },
672 identity: crate::BindIdentity::new("h", "s"),
673 principal: None,
674 consumer_capabilities: None,
675 role_versions,
676 admission_facts: None,
677 scope: None,
678 call_mode: None,
679 };
680 let absent = serde_json::to_value(bind(None)).unwrap();
681 assert!(absent.get("role_versions").is_none(), "{absent}");
682 let present = bind(Some(map(&[("tool-provider", "v1")])));
683 let encoded = serde_json::to_value(&present).unwrap();
684 assert_eq!(
685 encoded["role_versions"],
686 serde_json::json!({ "tool-provider": "v1" })
687 );
688 let decoded: ModuleControlRequest = serde_json::from_value(encoded).unwrap();
689 assert_eq!(decoded, present);
690 }
691}
692
693#[cfg(test)]
694mod agent_command_tests {
695 use super::*;
696
697 #[test]
698 fn agent_commands_round_trip_start_finish_and_known_snapshot() {
699 let root = AgentCommandRoot {
700 pid: 42,
701 start_time_ms: 1_700_000_000_123,
702 };
703 let request = ModuleControlRequestFromModule::AgentCommands {
704 started: vec![root],
705 finished: vec![AgentCommandFinished {
706 pid: 43,
707 start_time_ms: root.start_time_ms,
708 cpu_ms: Some(100),
709 }],
710 known: Some(vec![root]),
711 };
712 let value = serde_json::to_value(&request).unwrap();
713 assert_eq!(
714 value,
715 serde_json::json!({"op":"supervisor.agent_commands",
716 "started":[{"pid":42,"start_time_ms":1_700_000_000_123_u64}],
717 "finished":[{"pid":43,"start_time_ms":1_700_000_000_123_u64,"cpu_ms":100}],
718 "known":[{"pid":42,"start_time_ms":1_700_000_000_123_u64}]})
719 );
720 assert_eq!(
721 serde_json::from_value::<ModuleControlRequestFromModule>(value).unwrap(),
722 request
723 );
724 let absent = ModuleControlRequestFromModule::AgentCommands {
725 started: Vec::new(),
726 finished: vec![AgentCommandFinished {
727 pid: 1,
728 start_time_ms: 2,
729 cpu_ms: None,
730 }],
731 known: None,
732 };
733 assert_eq!(
734 serde_json::to_value(absent).unwrap(),
735 serde_json::json!({"op":"supervisor.agent_commands",
736 "started":[],"finished":[{"pid":1,"start_time_ms":2}]})
737 );
738 }
739}