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 changeset.apply_plan = serde_json::json!({
328 "operation": match kind { PlanKind::Change => "change", PlanKind::Stamp => "stamp", PlanKind::Unstamp => "unstamp", PlanKind::Rollback(_) => "rollback" },
329 "rollback_to": if let PlanKind::Rollback(id) = kind { Some(id) } else { None },
330 "review": changeset.apply_plan,
331 "previous": approved.to_store()?,
332 "snapshot": candidate.to_store()?,
333 });
334 if matches!(kind, PlanKind::Rollback(_)) {
335 changeset.apply_plan["rollback_programs"] = serde_json::Value::Array(rollback_programs);
336 }
337 let replaces_programs =
338 !recovery && matches!(kind, PlanKind::Change | PlanKind::Rollback(_));
339 if replaces_programs {
340 let body = store.body()?;
346 for module in &modules {
347 if reviewed_build::active(body, module)?
348 .is_some_and(|active| active != reviewed_build::identity(&candidate, module))
349 {
350 changeset
351 .launch_manifests
352 .entry(module.clone())
353 .or_insert_with(|| serde_json::json!({}))
354 .as_object_mut()
355 .ok_or_else(|| GateError::invalid("launch manifest must be an object"))?
356 .insert(
357 "program_changed_since_active".into(),
358 serde_json::Value::Bool(true),
359 );
360 }
361 }
362 }
363 let reviewed = match record {
364 ReviewRecord::Absent | ReviewRecord::Copied(None) => None,
365 ReviewRecord::Copied(Some(copied)) => {
366 changeset.apply_plan[reviewed_build::REVIEWED_PROGRAMS] = copied;
367 None
368 }
369 ReviewRecord::Reviewed(reviewed) => Some(reviewed),
370 };
371 if let Some(reviewed) = reviewed {
372 let mut record = if replaces_programs {
373 reviewed_build::recorded(store.body()?)?
374 } else {
375 BTreeMap::new()
376 };
377 let present = candidate.modules();
378 record.retain(|module, _| present.contains(module));
379 for module in reviewed {
380 let program = if replaces_programs {
385 match reviewed_build::active(store.body()?, module)? {
386 Some(active) => active,
387 None => reviewed_build::identity(&approved, module),
388 }
389 } else {
390 reviewed_build::identity(&candidate, module)
391 };
392 if let Some(previous) = record.get(module).filter(|previous| **previous != program)
393 {
394 changeset.policy_changes.push(serde_json::json!({
395 "module_id": module,
396 "path": "reviewed_program",
397 "old": previous,
398 "new": program,
399 "reason": "approved configuration re-reviewed by the module's newly approved program",
400 }));
401 }
402 record.insert(module.clone(), program);
403 }
404 changeset.apply_plan[reviewed_build::REVIEWED_PROGRAMS] = serde_json::json!(record);
405 }
406 apply::bind_plan(&mut changeset)?;
407 let mut plan = Plan::new(
408 base_revision,
409 base_generation,
410 &self.incarnation,
411 observed.read_set(&modules)?,
412 changeset,
413 );
414 plan.active_generations = active;
415 let view = ConfigPlanView::new(plan).map_err(GateError::invalid)?;
416 self.plans.insert(
417 view.digest.clone(),
418 PendingPlan {
419 development_approval: None,
420 view: view.clone(),
421 kind,
422 snapshot: candidate,
423 modules,
424 changed,
425 callosum_entry_changed,
426 recovery,
427 delivery: None,
428 },
429 );
430 Ok(view)
431 }
432
433 fn plan_program_keys(&self, digest: &Digest) -> Result<Vec<InputKey>> {
434 let plan = self
435 .plans
436 .get(digest)
437 .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?;
438 Ok(plan
439 .snapshot
440 .inputs
441 .keys()
442 .filter(|key| {
443 key.is_program()
444 && key
445 .module()
446 .is_some_and(|module| plan.modules.contains(module))
447 })
448 .cloned()
449 .collect())
450 }
451
452 pub(crate) fn bind_delivery(
456 &mut self,
457 digest: &Digest,
458 delivery: crate::config_store::DeliverySnapshot,
459 ) -> Result<()> {
460 self.plans
461 .get_mut(digest)
462 .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?
463 .delivery = Some(delivery);
464 Ok(())
465 }
466
467 pub fn rollback(
473 &mut self,
474 store: &mut ConfigStore,
475 generation: u64,
476 observed: &GateSnapshot,
477 current_programs: &GateSnapshot,
478 review: impl FnOnce(&GateSnapshot, &GateSnapshot) -> Result<Changeset>,
479 ) -> Result<ConfigPlanView> {
480 let mut target = GateSnapshot::from_store(&store.rollback_configuration(generation)?)?;
481 target.restore_programs_from(current_programs)?;
482 let copied = store
483 .body()?
484 .generations
485 .get(&generation)
486 .and_then(|entry| {
487 entry
488 .generation
489 .changeset
490 .apply_plan
491 .get(reviewed_build::REVIEWED_PROGRAMS)
492 })
493 .cloned();
494 self.plan_reviewed(
495 store,
496 PlanKind::Rollback(generation),
497 target,
498 observed,
499 ReviewRecord::Copied(copied),
500 review,
501 )
502 }
503
504 fn fresh(plan: &PendingPlan, store: &mut ConfigStore, current: &GateSnapshot) -> Result<()> {
505 let status = store.status();
506 let recovery = matches!(
507 status.state,
508 StoreState::StoreUnverified | StoreState::StoreMissing
509 );
510 if recovery != plan.recovery {
511 return Err(GateError::stale());
512 }
513 let base = if recovery {
514 0
515 } else {
516 store.delivery_ready()?;
517 store.body()?.base_revision
518 };
519 plan.view
520 .plan
521 .check_fresh(base, ¤t.read_set(&plan.modules)?)
522 .map_err(|_| GateError::stale())
523 }
524
525 #[allow(clippy::too_many_arguments)]
526 fn commit(
527 &mut self,
528 digest: &Digest,
529 approval_channel: subc_config::ApprovalChannel,
530 store: &mut ConfigStore,
531 current: &GateSnapshot,
532 now_ms: u64,
533 before_publication: impl FnOnce() -> Result<()>,
534 ) -> Result<u64> {
535 let plan = self
536 .plans
537 .get(digest)
538 .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?;
539 Self::fresh(plan, store, current)?;
540 let mut generation = Generation::new(
541 0,
542 approval_channel,
543 digest.clone(),
544 plan.view.plan.input_vector.clone(),
545 plan.view.plan.changeset.clone(),
546 );
547 let declarations_only = plan.development_approval.is_some();
548 generation.active_generations = plan.view.plan.active_generations.clone();
549 for module in plan.modules.iter().filter(|_| !declarations_only) {
550 generation
551 .module_states
552 .insert(module.clone(), subc_config::GenerationState::Pending);
553 if let Some(CapturedInput {
554 state: subc_config::InputState::Present { digest },
555 ..
556 }) = plan
557 .snapshot
558 .inputs
559 .get(&InputKey::Declaration(module.clone()))
560 {
561 generation
562 .declaration_digests
563 .insert(module.clone(), digest.clone());
564 }
565 }
566 let mut tuples: BTreeSet<Tuple> = plan
567 .modules
568 .iter()
569 .map(|module| Tuple {
570 module: module.clone(),
571 project: None,
572 })
573 .chain(plan.view.plan.changeset.fields.iter().map(|field| Tuple {
574 module: field.module_id.clone(),
575 project: field.project_id.clone(),
576 }))
577 .chain(plan.modules.iter().flat_map(|module| {
578 plan.view
579 .plan
580 .changeset
581 .affected_projects
582 .iter()
583 .map(move |project| Tuple {
584 module: module.clone(),
585 project: Some(project.clone()),
586 })
587 }))
588 .collect();
589 if declarations_only {
590 tuples.clear();
591 }
592 let snapshot = plan.snapshot.to_store()?;
593 let entry = HistoryEntry {
594 generation,
595 kind: if declarations_only {
596 CommitKind::DeclarationApproval
597 } else {
598 plan.kind.commit_kind()
599 },
600 approval_id: digest.to_string(),
601 outcome: "approved".into(),
602 tuples,
603 configuration: snapshot.clone(),
604 delivery: plan.delivery.clone(),
605 };
606 let base_before = store.status().base_revision;
607 let observed = current.to_store()?;
608 before_publication()?;
609 let result = if plan.recovery {
610 store.recovery_exit(entry, snapshot, now_ms)
611 } else {
612 store.commit_generation(entry, snapshot, observed, now_ms)
613 };
614 if result.is_ok() || store.status().base_revision != base_before {
618 self.plans.remove(digest);
619 }
620 let id = result?;
621 store.delivery_ready()?;
622 Ok(id)
623 }
624}
625
626mod registration;
627#[cfg(test)]
628mod tests;