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