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 view: ConfigPlanView,
136 kind: PlanKind,
137 snapshot: GateSnapshot,
138 modules: BTreeSet<String>,
139 changed: BTreeSet<InputKey>,
140 callosum_entry_changed: bool,
141 recovery: bool,
142 delivery: Option<crate::config_store::DeliverySnapshot>,
143}
144
145pub struct ConfigGate {
148 incarnation: String,
149 plans: BTreeMap<Digest, PendingPlan>,
150 attempts: BTreeMap<u64, approval::Attempt>,
151 next_attempt: u64,
152}
153
154impl ConfigGate {
155 pub(crate) fn plan_modules(&self, digest: &Digest) -> Result<BTreeSet<String>> {
156 self.plans
157 .get(digest)
158 .map(|plan| plan.modules.clone())
159 .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))
160 }
161
162 pub(crate) fn cancel_attempt(&mut self, attempt: u64) {
163 self.attempts.remove(&attempt);
164 }
165
166 pub(crate) fn expire_plan(&mut self, digest: &Digest) -> bool {
167 self.plans.remove(digest).is_some()
168 }
169 pub fn new(incarnation: String) -> Self {
170 Self {
171 incarnation,
172 plans: BTreeMap::new(),
173 attempts: BTreeMap::new(),
174 next_attempt: 0,
175 }
176 }
177
178 pub fn plan(
181 &mut self,
182 store: &mut ConfigStore,
183 kind: PlanKind,
184 candidate: GateSnapshot,
185 observed: &GateSnapshot,
186 review: impl FnOnce(&GateSnapshot, &GateSnapshot) -> Result<Changeset>,
187 ) -> Result<ConfigPlanView> {
188 self.plan_reviewed(
189 store,
190 kind,
191 candidate,
192 observed,
193 ReviewRecord::Absent,
194 review,
195 )
196 }
197
198 pub(crate) fn plan_reviewed(
203 &mut self,
204 store: &mut ConfigStore,
205 kind: PlanKind,
206 candidate: GateSnapshot,
207 observed: &GateSnapshot,
208 record: ReviewRecord<'_>,
209 review: impl FnOnce(&GateSnapshot, &GateSnapshot) -> Result<Changeset>,
210 ) -> Result<ConfigPlanView> {
211 let status = store.status();
212 let recovery = matches!(
213 status.state,
214 StoreState::StoreUnverified | StoreState::StoreMissing
215 );
216 if (recovery && !matches!(kind, PlanKind::Stamp | PlanKind::Unstamp))
217 || (status.state == StoreState::Unstamped && kind != PlanKind::Stamp)
218 {
219 return Err(GateError::new(
220 "config_gated",
221 "stamp is required before planning changes",
222 ));
223 }
224 if self.plans.len() >= 64 {
225 return Err(GateError::new("config_busy", "too many pending plans"));
226 }
227 let mut rollback_programs = Vec::new();
228 if let PlanKind::Rollback(id) = kind {
229 let target = GateSnapshot::from_store(&store.rollback_configuration(id)?)?;
230 if target
231 .inputs
232 .iter()
233 .filter(|(key, _)| !key.is_program())
234 .ne(candidate.inputs.iter().filter(|(key, _)| !key.is_program()))
235 {
236 return Err(GateError::invalid(
237 "rollback must reverse the target configuration",
238 ));
239 }
240 for (key, now) in candidate.inputs.iter().filter(|(key, _)| key.is_program()) {
241 if target.inputs.get(key) != Some(now) {
242 rollback_programs.push(serde_json::json!({
243 "module_id":key.module(),
244 "input":key,
245 "reason":"program changed since that version",
246 "approved_then":target.inputs.get(key),
247 "on_disk_now":now,
248 }));
249 }
250 }
251 }
252 let (base_revision, base_generation, approved, active) = if recovery {
253 (0, 0, GateSnapshot::default(), BTreeMap::new())
254 } else {
255 store.delivery_ready()?;
256 let body = store.body()?;
257 let active = body
258 .versions
259 .iter()
260 .filter_map(|(tuple, versions)| {
261 versions
262 .active
263 .map(|id| (serde_json::to_string(tuple).expect("tuple"), id))
264 })
265 .collect();
266 (
267 body.base_revision,
268 body.last_generation,
269 GateSnapshot::from_store(&body.approved)?,
270 active,
271 )
272 };
273 let changed: BTreeSet<InputKey> = approved
274 .changed_keys(&candidate)
275 .into_iter()
276 .cloned()
277 .collect();
278 let callosum_entry_changed = if changed.contains(&InputKey::Daemon) {
279 match (
280 approved.inputs.get(&InputKey::Daemon),
281 candidate.inputs.get(&InputKey::Daemon),
282 ) {
283 (
284 Some(CapturedInput {
285 value: subc_config::RecordedValue::Value { value: old },
286 ..
287 }),
288 Some(CapturedInput {
289 value: subc_config::RecordedValue::Value { value: new },
290 ..
291 }),
292 ) => old.pointer("/modules/callosum") != new.pointer("/modules/callosum"),
293 _ => true,
294 }
295 } else {
296 false
297 };
298 let mut modules: BTreeSet<String> = changed
299 .iter()
300 .filter_map(|key| key.module().map(str::to_owned))
301 .collect();
302 let mut changeset = review(&approved, &candidate)?;
303 for difference in &rollback_programs {
304 if let Some(module) = difference["module_id"].as_str() {
305 modules.insert(module.to_owned());
306 changeset
307 .launch_manifests
308 .entry(module.to_owned())
309 .or_insert_with(|| serde_json::json!({}))
310 .as_object_mut()
311 .ok_or_else(|| GateError::invalid("launch manifest must be an object"))?
312 .insert(
313 "program_changed_since_target".into(),
314 serde_json::Value::Bool(true),
315 );
316 }
317 }
318 modules.extend(changeset.fields.iter().map(|field| field.module_id.clone()));
319 modules.extend(changeset.launch_manifests.keys().cloned());
320 if matches!(kind, PlanKind::Stamp | PlanKind::Unstamp) {
321 modules.extend(observed.modules());
322 modules.extend(approved.modules());
323 }
324 changeset.apply_plan = serde_json::json!({
327 "operation": match kind { PlanKind::Change => "change", PlanKind::Stamp => "stamp", PlanKind::Unstamp => "unstamp", PlanKind::Rollback(_) => "rollback" },
328 "rollback_to": if let PlanKind::Rollback(id) = kind { Some(id) } else { None },
329 "review": changeset.apply_plan,
330 "previous": approved.to_store()?,
331 "snapshot": candidate.to_store()?,
332 });
333 if matches!(kind, PlanKind::Rollback(_)) {
334 changeset.apply_plan["rollback_programs"] = serde_json::Value::Array(rollback_programs);
335 }
336 let replaces_programs =
337 !recovery && matches!(kind, PlanKind::Change | PlanKind::Rollback(_));
338 if replaces_programs {
339 let body = store.body()?;
345 for module in &modules {
346 if reviewed_build::active(body, module)?
347 .is_some_and(|active| active != reviewed_build::identity(&candidate, module))
348 {
349 changeset
350 .launch_manifests
351 .entry(module.clone())
352 .or_insert_with(|| serde_json::json!({}))
353 .as_object_mut()
354 .ok_or_else(|| GateError::invalid("launch manifest must be an object"))?
355 .insert(
356 "program_changed_since_active".into(),
357 serde_json::Value::Bool(true),
358 );
359 }
360 }
361 }
362 let reviewed = match record {
363 ReviewRecord::Absent | ReviewRecord::Copied(None) => None,
364 ReviewRecord::Copied(Some(copied)) => {
365 changeset.apply_plan[reviewed_build::REVIEWED_PROGRAMS] = copied;
366 None
367 }
368 ReviewRecord::Reviewed(reviewed) => Some(reviewed),
369 };
370 if let Some(reviewed) = reviewed {
371 let mut record = if replaces_programs {
372 reviewed_build::recorded(store.body()?)?
373 } else {
374 BTreeMap::new()
375 };
376 let present = candidate.modules();
377 record.retain(|module, _| present.contains(module));
378 for module in reviewed {
379 let program = if replaces_programs {
384 match reviewed_build::active(store.body()?, module)? {
385 Some(active) => active,
386 None => reviewed_build::identity(&approved, module),
387 }
388 } else {
389 reviewed_build::identity(&candidate, module)
390 };
391 if let Some(previous) = record.get(module).filter(|previous| **previous != program)
392 {
393 changeset.policy_changes.push(serde_json::json!({
394 "module_id": module,
395 "path": "reviewed_program",
396 "old": previous,
397 "new": program,
398 "reason": "approved configuration re-reviewed by the module's newly approved program",
399 }));
400 }
401 record.insert(module.clone(), program);
402 }
403 changeset.apply_plan[reviewed_build::REVIEWED_PROGRAMS] = serde_json::json!(record);
404 }
405 apply::bind_plan(&mut changeset)?;
406 let mut plan = Plan::new(
407 base_revision,
408 base_generation,
409 &self.incarnation,
410 observed.read_set(&modules)?,
411 changeset,
412 );
413 plan.active_generations = active;
414 let view = ConfigPlanView::new(plan).map_err(GateError::invalid)?;
415 self.plans.insert(
416 view.digest.clone(),
417 PendingPlan {
418 view: view.clone(),
419 kind,
420 snapshot: candidate,
421 modules,
422 changed,
423 callosum_entry_changed,
424 recovery,
425 delivery: None,
426 },
427 );
428 Ok(view)
429 }
430
431 fn plan_program_keys(&self, digest: &Digest) -> Result<Vec<InputKey>> {
432 let plan = self
433 .plans
434 .get(digest)
435 .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?;
436 Ok(plan
437 .snapshot
438 .inputs
439 .keys()
440 .filter(|key| {
441 key.is_program()
442 && key
443 .module()
444 .is_some_and(|module| plan.modules.contains(module))
445 })
446 .cloned()
447 .collect())
448 }
449
450 pub(crate) fn bind_delivery(
454 &mut self,
455 digest: &Digest,
456 delivery: crate::config_store::DeliverySnapshot,
457 ) -> Result<()> {
458 self.plans
459 .get_mut(digest)
460 .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?
461 .delivery = Some(delivery);
462 Ok(())
463 }
464
465 pub fn rollback(
471 &mut self,
472 store: &mut ConfigStore,
473 generation: u64,
474 observed: &GateSnapshot,
475 current_programs: &GateSnapshot,
476 review: impl FnOnce(&GateSnapshot, &GateSnapshot) -> Result<Changeset>,
477 ) -> Result<ConfigPlanView> {
478 let mut target = GateSnapshot::from_store(&store.rollback_configuration(generation)?)?;
479 target.restore_programs_from(current_programs)?;
480 let copied = store
481 .body()?
482 .generations
483 .get(&generation)
484 .and_then(|entry| {
485 entry
486 .generation
487 .changeset
488 .apply_plan
489 .get(reviewed_build::REVIEWED_PROGRAMS)
490 })
491 .cloned();
492 self.plan_reviewed(
493 store,
494 PlanKind::Rollback(generation),
495 target,
496 observed,
497 ReviewRecord::Copied(copied),
498 review,
499 )
500 }
501
502 fn fresh(plan: &PendingPlan, store: &mut ConfigStore, current: &GateSnapshot) -> Result<()> {
503 let status = store.status();
504 let recovery = matches!(
505 status.state,
506 StoreState::StoreUnverified | StoreState::StoreMissing
507 );
508 if recovery != plan.recovery {
509 return Err(GateError::stale());
510 }
511 let base = if recovery {
512 0
513 } else {
514 store.delivery_ready()?;
515 store.body()?.base_revision
516 };
517 plan.view
518 .plan
519 .check_fresh(base, ¤t.read_set(&plan.modules)?)
520 .map_err(|_| GateError::stale())
521 }
522
523 #[allow(clippy::too_many_arguments)]
524 fn commit(
525 &mut self,
526 digest: &Digest,
527 approval_channel: subc_config::ApprovalChannel,
528 store: &mut ConfigStore,
529 current: &GateSnapshot,
530 now_ms: u64,
531 before_publication: impl FnOnce() -> Result<()>,
532 ) -> Result<u64> {
533 let plan = self
534 .plans
535 .get(digest)
536 .ok_or_else(|| GateError::new("plan_unknown", "plan is absent or already applied"))?;
537 Self::fresh(plan, store, current)?;
538 let mut generation = Generation::new(
539 0,
540 approval_channel,
541 digest.clone(),
542 plan.view.plan.input_vector.clone(),
543 plan.view.plan.changeset.clone(),
544 );
545 generation.active_generations = plan.view.plan.active_generations.clone();
546 for module in &plan.modules {
547 generation
548 .module_states
549 .insert(module.clone(), subc_config::GenerationState::Pending);
550 if let Some(CapturedInput {
551 state: subc_config::InputState::Present { digest },
552 ..
553 }) = plan
554 .snapshot
555 .inputs
556 .get(&InputKey::Declaration(module.clone()))
557 {
558 generation
559 .declaration_digests
560 .insert(module.clone(), digest.clone());
561 }
562 }
563 let tuples: BTreeSet<Tuple> = plan
564 .modules
565 .iter()
566 .map(|module| Tuple {
567 module: module.clone(),
568 project: None,
569 })
570 .chain(plan.view.plan.changeset.fields.iter().map(|field| Tuple {
571 module: field.module_id.clone(),
572 project: field.project_id.clone(),
573 }))
574 .chain(plan.modules.iter().flat_map(|module| {
575 plan.view
576 .plan
577 .changeset
578 .affected_projects
579 .iter()
580 .map(move |project| Tuple {
581 module: module.clone(),
582 project: Some(project.clone()),
583 })
584 }))
585 .collect();
586 let snapshot = plan.snapshot.to_store()?;
587 let entry = HistoryEntry {
588 generation,
589 kind: plan.kind.commit_kind(),
590 approval_id: digest.to_string(),
591 outcome: "approved".into(),
592 tuples,
593 configuration: snapshot.clone(),
594 delivery: plan.delivery.clone(),
595 };
596 let base_before = store.status().base_revision;
597 let observed = current.to_store()?;
598 before_publication()?;
599 let result = if plan.recovery {
600 store.recovery_exit(entry, snapshot, now_ms)
601 } else {
602 store.commit_generation(entry, snapshot, observed, now_ms)
603 };
604 if result.is_ok() || store.status().base_revision != base_before {
608 self.plans.remove(digest);
609 }
610 let id = result?;
611 store.delivery_ready()?;
612 Ok(id)
613 }
614}
615
616mod registration;
617#[cfg(test)]
618mod tests;