1mod anchor_retry;
9mod apply;
10mod approval;
11pub mod capture;
12pub(crate) mod program;
13pub mod project_registry;
14pub(crate) mod review;
15mod reviewed_build;
16pub mod runtime;
17mod snapshot;
18mod strict_json;
19
20pub use approval::*;
21pub use snapshot::{CapturedInput, GateSnapshot, InputKey};
22
23use std::collections::{BTreeMap, BTreeSet};
24
25use subc_config::{Changeset, Digest, Generation, Plan};
26use subc_control::config::ConfigPlanView;
27
28use crate::config_store::{CommitKind, ConfigStore, HistoryEntry, StoreError, StoreState, Tuple};
29
30#[derive(Clone, Debug, PartialEq, Eq)]
31pub struct GateError {
32 pub code: String,
33 pub detail: String,
34}
35type Result<T> = std::result::Result<T, GateError>;
36
37impl GateError {
38 pub fn new(code: &str, detail: impl ToString) -> Self {
39 Self {
40 code: code.into(),
41 detail: detail.to_string(),
42 }
43 }
44 fn invalid(detail: impl ToString) -> Self {
45 Self::new("value_invalid", detail)
46 }
47 fn stale() -> Self {
48 Self::new(
49 "plan_stale",
50 "reviewed inputs or generation changed; plan again",
51 )
52 }
53
54 pub(crate) fn commit_timeout() -> Self {
55 Self::new("config_commit_timeout", "the post-answer commit window expired before durable publication; plan remains unapproved")
56 }
57}
58impl std::fmt::Display for GateError {
59 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
60 write!(f, "{}: {}", self.code, self.detail)
61 }
62}
63impl std::error::Error for GateError {}
64impl From<StoreError> for GateError {
65 fn from(error: StoreError) -> Self {
66 use crate::config_store::StoreErrorCode as Code;
67 let code = match error.code {
68 Code::StoreUnverified => "store_unverified",
69 Code::StoreMissing => "store_missing",
70 Code::StoreTampered => "store_tampered",
71 Code::StoreTooLarge => "store_too_large",
72 Code::AnchorPending => "anchor_pending",
73 Code::GenerationPruned => "generation_pruned",
74 Code::GenerationMissing => "generation_missing",
75 Code::RevisionExhausted => "revision_exhausted",
76 Code::InvalidState => "config_gated",
77 Code::Io => "config_store_io",
78 };
79 Self::new(code, error.detail)
80 }
81}
82
83pub trait ReviewAdmission: Send + Sync {
86 fn check(&self, registration: &crate::registry::ModuleRegistration) -> Result<()>;
87}
88
89pub(crate) struct MissingReviewAdmission;
90impl ReviewAdmission for MissingReviewAdmission {
91 fn check(&self, registration: &crate::registry::ModuleRegistration) -> Result<()> {
92 Err(GateError::new(
93 "program_admission_unavailable",
94 format!(
95 "{}: running program review admission is not connected",
96 registration.manifest.module_id
97 ),
98 ))
99 }
100}
101
102pub(crate) enum ReviewRecord<'a> {
105 Absent,
108 Reviewed(&'a BTreeSet<String>),
112 Copied(Option<serde_json::Value>),
115}
116
117#[derive(Clone, Copy, Debug, PartialEq, Eq)]
118pub enum PlanKind {
119 Change,
120 Stamp,
121 Unstamp,
122 Rollback(u64),
123}
124impl PlanKind {
125 fn commit_kind(self) -> CommitKind {
126 match self {
127 Self::Change => CommitKind::Approved,
128 Self::Stamp => CommitKind::Stamp,
129 Self::Unstamp => CommitKind::Unstamp,
130 Self::Rollback(_) => CommitKind::Rollback,
131 }
132 }
133}
134
135struct PendingPlan {
136 development_approval: Option<crate::program_origin::DevelopmentApproval>,
137 view: ConfigPlanView,
138 kind: PlanKind,
139 snapshot: GateSnapshot,
140 modules: BTreeSet<String>,
141 changed: BTreeSet<InputKey>,
142 callosum_entry_changed: bool,
143 recovery: bool,
144 delivery: Option<crate::config_store::DeliverySnapshot>,
145}
146
147pub struct ConfigGate {
150 incarnation: String,
151 plans: BTreeMap<Digest, PendingPlan>,
152 attempts: BTreeMap<u64, approval::Attempt>,
153 next_attempt: u64,
154}
155
156impl ConfigGate {
157 pub(crate) fn plan_modules(&self, digest: &Digest) -> Result<BTreeSet<String>> {
158 self.plans
159 .get(digest)
160 .map(|plan| plan.modules.clone())
161 .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))
162 }
163
164 pub(crate) fn cancel_attempt(&mut self, attempt: u64) {
165 self.attempts.remove(&attempt);
166 }
167
168 pub(crate) fn expire_plan(&mut self, digest: &Digest) -> bool {
169 self.plans.remove(digest).is_some()
170 }
171 pub fn new(incarnation: String) -> Self {
172 Self {
173 incarnation,
174 plans: BTreeMap::new(),
175 attempts: BTreeMap::new(),
176 next_attempt: 0,
177 }
178 }
179
180 pub fn plan(
183 &mut self,
184 store: &mut ConfigStore,
185 kind: PlanKind,
186 candidate: GateSnapshot,
187 observed: &GateSnapshot,
188 review: impl FnOnce(&GateSnapshot, &GateSnapshot) -> Result<Changeset>,
189 ) -> Result<ConfigPlanView> {
190 self.plan_reviewed(
191 store,
192 kind,
193 candidate,
194 observed,
195 ReviewRecord::Absent,
196 review,
197 )
198 }
199
200 pub(crate) fn plan_reviewed(
205 &mut self,
206 store: &mut ConfigStore,
207 kind: PlanKind,
208 candidate: GateSnapshot,
209 observed: &GateSnapshot,
210 record: ReviewRecord<'_>,
211 review: impl FnOnce(&GateSnapshot, &GateSnapshot) -> Result<Changeset>,
212 ) -> Result<ConfigPlanView> {
213 let status = store.status();
214 let recovery = matches!(
215 status.state,
216 StoreState::StoreUnverified | StoreState::StoreMissing
217 );
218 if (recovery && !matches!(kind, PlanKind::Stamp | PlanKind::Unstamp))
219 || (status.state == StoreState::Unstamped && kind != PlanKind::Stamp)
220 {
221 return Err(GateError::new(
222 "config_gated",
223 "stamp is required before planning changes",
224 ));
225 }
226 if self.plans.len() >= 64 {
227 return Err(GateError::new("config_busy", "too many pending plans"));
228 }
229 let mut rollback_programs = Vec::new();
230 if let PlanKind::Rollback(id) = kind {
231 let target = GateSnapshot::from_store(&store.rollback_configuration(id)?)?;
232 if target
233 .inputs
234 .iter()
235 .filter(|(key, _)| !key.is_program())
236 .ne(candidate.inputs.iter().filter(|(key, _)| !key.is_program()))
237 {
238 return Err(GateError::invalid(
239 "rollback must reverse the target configuration",
240 ));
241 }
242 for (key, now) in candidate.inputs.iter().filter(|(key, _)| key.is_program()) {
243 if target.inputs.get(key) != Some(now) {
244 rollback_programs.push(serde_json::json!({
245 "module_id":key.module(),
246 "input":key,
247 "reason":"program changed since that version",
248 "approved_then":target.inputs.get(key),
249 "on_disk_now":now,
250 }));
251 }
252 }
253 }
254 let (base_revision, base_generation, approved, active) = if recovery {
255 (0, 0, GateSnapshot::default(), BTreeMap::new())
256 } else {
257 store.delivery_ready()?;
258 let body = store.body()?;
259 let active = body
260 .versions
261 .iter()
262 .filter_map(|(tuple, versions)| {
263 versions
264 .active
265 .map(|id| (serde_json::to_string(tuple).expect("tuple"), id))
266 })
267 .collect();
268 (
269 body.base_revision,
270 body.last_generation,
271 GateSnapshot::from_store(&body.approved)?,
272 active,
273 )
274 };
275 let changed: BTreeSet<InputKey> = approved
276 .changed_keys(&candidate)
277 .into_iter()
278 .cloned()
279 .collect();
280 let callosum_entry_changed = if changed.contains(&InputKey::Daemon) {
281 match (
282 approved.inputs.get(&InputKey::Daemon),
283 candidate.inputs.get(&InputKey::Daemon),
284 ) {
285 (
286 Some(CapturedInput {
287 value: subc_config::RecordedValue::Value { value: old },
288 ..
289 }),
290 Some(CapturedInput {
291 value: subc_config::RecordedValue::Value { value: new },
292 ..
293 }),
294 ) => old.pointer("/modules/callosum") != new.pointer("/modules/callosum"),
295 _ => true,
296 }
297 } else {
298 false
299 };
300 let mut modules: BTreeSet<String> = changed
301 .iter()
302 .filter_map(|key| key.module().map(str::to_owned))
303 .collect();
304 let mut changeset = review(&approved, &candidate)?;
305 for difference in &rollback_programs {
306 if let Some(module) = difference["module_id"].as_str() {
307 modules.insert(module.to_owned());
308 changeset
309 .launch_manifests
310 .entry(module.to_owned())
311 .or_insert_with(|| serde_json::json!({}))
312 .as_object_mut()
313 .ok_or_else(|| GateError::invalid("launch manifest must be an object"))?
314 .insert(
315 "program_changed_since_target".into(),
316 serde_json::Value::Bool(true),
317 );
318 }
319 }
320 modules.extend(changeset.fields.iter().map(|field| field.module_id.clone()));
321 modules.extend(changeset.launch_manifests.keys().cloned());
322 if matches!(kind, PlanKind::Stamp | PlanKind::Unstamp) {
323 modules.extend(observed.modules());
324 modules.extend(approved.modules());
325 }
326 let transitions = changeset
333 .apply_plan
334 .as_object_mut()
335 .and_then(|review| review.remove("module_transitions"));
336 if transitions.is_some()
337 && changeset
338 .apply_plan
339 .as_object()
340 .is_some_and(|review| review.is_empty())
341 {
342 changeset.apply_plan = serde_json::Value::Null;
343 }
344 changeset.apply_plan = serde_json::json!({
345 "operation": match kind { PlanKind::Change => "change", PlanKind::Stamp => "stamp", PlanKind::Unstamp => "unstamp", PlanKind::Rollback(_) => "rollback" },
346 "rollback_to": if let PlanKind::Rollback(id) = kind { Some(id) } else { None },
347 "review": changeset.apply_plan,
348 "previous": approved.to_store()?,
349 "snapshot": candidate.to_store()?,
350 });
351 if let Some(transitions) = transitions {
352 if let Some(table) = transitions.as_object() {
353 modules.extend(table.keys().cloned());
354 }
355 changeset.apply_plan["module_transitions"] = transitions;
356 }
357 if matches!(kind, PlanKind::Rollback(_)) {
358 changeset.apply_plan["rollback_programs"] = serde_json::Value::Array(rollback_programs);
359 }
360 let replaces_programs =
361 !recovery && matches!(kind, PlanKind::Change | PlanKind::Rollback(_));
362 if replaces_programs {
363 let body = store.body()?;
369 for module in &modules {
370 if reviewed_build::active(body, module)?
371 .is_some_and(|active| active != reviewed_build::identity(&candidate, module))
372 {
373 changeset
374 .launch_manifests
375 .entry(module.clone())
376 .or_insert_with(|| serde_json::json!({}))
377 .as_object_mut()
378 .ok_or_else(|| GateError::invalid("launch manifest must be an object"))?
379 .insert(
380 "program_changed_since_active".into(),
381 serde_json::Value::Bool(true),
382 );
383 }
384 }
385 }
386 let reviewed = match record {
387 ReviewRecord::Absent | ReviewRecord::Copied(None) => None,
388 ReviewRecord::Copied(Some(copied)) => {
389 changeset.apply_plan[reviewed_build::REVIEWED_PROGRAMS] = copied;
390 None
391 }
392 ReviewRecord::Reviewed(reviewed) => Some(reviewed),
393 };
394 if let Some(reviewed) = reviewed {
395 let mut record = if replaces_programs {
396 reviewed_build::recorded(store.body()?)?
397 } else {
398 BTreeMap::new()
399 };
400 let present = candidate.modules();
401 record.retain(|module, _| present.contains(module));
402 for module in reviewed {
403 let program = if replaces_programs {
408 match reviewed_build::active(store.body()?, module)? {
409 Some(active) => active,
410 None => reviewed_build::identity(&approved, module),
411 }
412 } else {
413 reviewed_build::identity(&candidate, module)
414 };
415 if let Some(previous) = record.get(module).filter(|previous| **previous != program)
416 {
417 changeset.policy_changes.push(serde_json::json!({
418 "module_id": module,
419 "path": "reviewed_program",
420 "old": previous,
421 "new": program,
422 "reason": "approved configuration re-reviewed by the module's newly approved program",
423 }));
424 }
425 record.insert(module.clone(), program);
426 }
427 changeset.apply_plan[reviewed_build::REVIEWED_PROGRAMS] = serde_json::json!(record);
428 }
429 apply::bind_plan(&mut changeset)?;
430 let mut plan = Plan::new(
431 base_revision,
432 base_generation,
433 &self.incarnation,
434 observed.read_set(&modules)?,
435 changeset,
436 );
437 plan.active_generations = active;
438 let view = ConfigPlanView::new(plan).map_err(GateError::invalid)?;
439 self.plans.insert(
440 view.digest.clone(),
441 PendingPlan {
442 development_approval: None,
443 view: view.clone(),
444 kind,
445 snapshot: candidate,
446 modules,
447 changed,
448 callosum_entry_changed,
449 recovery,
450 delivery: None,
451 },
452 );
453 Ok(view)
454 }
455
456 fn plan_program_keys(&self, digest: &Digest) -> Result<Vec<InputKey>> {
457 let plan = self
458 .plans
459 .get(digest)
460 .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?;
461 Ok(plan
462 .snapshot
463 .inputs
464 .keys()
465 .filter(|key| {
466 key.is_program()
467 && key
468 .module()
469 .is_some_and(|module| plan.modules.contains(module))
470 })
471 .cloned()
472 .collect())
473 }
474
475 pub(crate) fn bind_delivery(
479 &mut self,
480 digest: &Digest,
481 delivery: crate::config_store::DeliverySnapshot,
482 ) -> Result<()> {
483 self.plans
484 .get_mut(digest)
485 .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?
486 .delivery = Some(delivery);
487 Ok(())
488 }
489
490 pub fn rollback(
496 &mut self,
497 store: &mut ConfigStore,
498 generation: u64,
499 observed: &GateSnapshot,
500 current_programs: &GateSnapshot,
501 review: impl FnOnce(&GateSnapshot, &GateSnapshot) -> Result<Changeset>,
502 ) -> Result<ConfigPlanView> {
503 let mut target = GateSnapshot::from_store(&store.rollback_configuration(generation)?)?;
504 target.restore_programs_from(current_programs)?;
505 let copied = store
506 .body()?
507 .generations
508 .get(&generation)
509 .and_then(|entry| {
510 entry
511 .generation
512 .changeset
513 .apply_plan
514 .get(reviewed_build::REVIEWED_PROGRAMS)
515 })
516 .cloned();
517 self.plan_reviewed(
518 store,
519 PlanKind::Rollback(generation),
520 target,
521 observed,
522 ReviewRecord::Copied(copied),
523 review,
524 )
525 }
526
527 fn fresh(plan: &PendingPlan, store: &mut ConfigStore, current: &GateSnapshot) -> Result<()> {
528 let status = store.status();
529 let recovery = matches!(
530 status.state,
531 StoreState::StoreUnverified | StoreState::StoreMissing
532 );
533 if recovery != plan.recovery {
534 return Err(GateError::stale());
535 }
536 let base = if recovery {
537 0
538 } else {
539 store.delivery_ready()?;
540 store.body()?.base_revision
541 };
542 plan.view
543 .plan
544 .check_fresh(base, ¤t.read_set(&plan.modules)?)
545 .map_err(|_| GateError::stale())
546 }
547
548 #[allow(clippy::too_many_arguments)]
549 fn commit(
550 &mut self,
551 digest: &Digest,
552 approval_channel: subc_config::ApprovalChannel,
553 store: &mut ConfigStore,
554 current: &GateSnapshot,
555 now_ms: u64,
556 before_publication: impl FnOnce() -> Result<()>,
557 ) -> Result<u64> {
558 let plan = self
559 .plans
560 .get(digest)
561 .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?;
562 Self::fresh(plan, store, current)?;
563 let mut generation = Generation::new(
564 0,
565 approval_channel,
566 digest.clone(),
567 plan.view.plan.input_vector.clone(),
568 plan.view.plan.changeset.clone(),
569 );
570 let declarations_only = plan.development_approval.is_some();
571 generation.active_generations = plan.view.plan.active_generations.clone();
572 for module in plan.modules.iter().filter(|_| !declarations_only) {
573 generation
574 .module_states
575 .insert(module.clone(), subc_config::GenerationState::Pending);
576 if let Some(CapturedInput {
577 state: subc_config::InputState::Present { digest },
578 ..
579 }) = plan
580 .snapshot
581 .inputs
582 .get(&InputKey::Declaration(module.clone()))
583 {
584 generation
585 .declaration_digests
586 .insert(module.clone(), digest.clone());
587 }
588 }
589 let mut tuples: BTreeSet<Tuple> = plan
590 .modules
591 .iter()
592 .map(|module| Tuple {
593 module: module.clone(),
594 project: None,
595 })
596 .chain(plan.view.plan.changeset.fields.iter().map(|field| Tuple {
597 module: field.module_id.clone(),
598 project: field.project_id.clone(),
599 }))
600 .chain(plan.modules.iter().flat_map(|module| {
601 plan.view
602 .plan
603 .changeset
604 .affected_projects
605 .iter()
606 .map(move |project| Tuple {
607 module: module.clone(),
608 project: Some(project.clone()),
609 })
610 }))
611 .collect();
612 if declarations_only {
613 tuples.clear();
614 }
615 let snapshot = plan.snapshot.to_store()?;
616 let entry = HistoryEntry {
617 generation,
618 kind: if declarations_only {
619 CommitKind::DeclarationApproval
620 } else {
621 plan.kind.commit_kind()
622 },
623 approval_id: digest.to_string(),
624 outcome: "approved".into(),
625 tuples,
626 configuration: snapshot.clone(),
627 delivery: plan.delivery.clone(),
628 };
629 let base_before = store.status().base_revision;
630 let observed = current.to_store()?;
631 before_publication()?;
632 let result = if plan.recovery {
633 store.recovery_exit(entry, snapshot, now_ms)
634 } else {
635 store.commit_generation(entry, snapshot, observed, now_ms)
636 };
637 if result.is_ok() || store.status().base_revision != base_before {
641 self.plans.remove(digest);
642 }
643 let id = result?;
644 store.delivery_ready()?;
645 Ok(id)
646 }
647}
648
649mod registration;
650#[cfg(test)]
651mod tests;