tatara_process/
lib.rs

1//! Process CRD — the K8s-as-Unix-processes wire format.
2//!
3//! A `Process` is one element of the tatara convergence lattice.
4//! Clusters, HelmReleases, migrations, tests — all are Processes.
5//! The reconciliation loop *is* Unix: fork → exec → wait → exit → reap.
6
7pub mod allocation;
8pub mod attestation;
9pub mod boundary;
10pub mod classification;
11pub mod compliance;
12pub mod crd;
13pub mod encapsulates;
14pub mod env;
15pub mod ephemeral;
16pub mod export;
17pub mod hostname;
18pub mod identity;
19pub mod intent;
20pub mod lifetime;
21pub mod lifetime_clock;
22pub mod matrix;
23pub mod phase;
24pub mod pool;
25pub mod receipt;
26pub mod routing;
27pub mod signal;
28pub mod spec;
29pub mod status;
30pub mod table;
31pub mod tagged_union;
32
33pub mod prelude {
34    pub use crate::allocation::{
35        AllocationCondition, AllocationPhase, AllocationSpec, AllocationStatus,
36        EphemeralAllocation, Requestor,
37    };
38    pub use crate::attestation::ProcessAttestation;
39    pub use crate::boundary::{Boundary, Condition, ConditionKind, UnknownConditionKind};
40    pub use crate::classification::{
41        Arity, CalmClassification, Classification, ConvergencePointType, DataClassification,
42        Horizon, HorizonKind, OptimizationDirection, SubstrateType, UnknownCalmClassification,
43        UnknownConvergencePointType, UnknownDataClassification, UnknownHorizonKind,
44        UnknownOptimizationDirection, UnknownSubstrateType,
45    };
46    pub use crate::compliance::{
47        ComplianceBinding, ComplianceSpec, UnknownVerificationPhase, VerificationPhase,
48    };
49    pub use crate::crd::{Process, ProcessSpec, ProcessStatus};
50    pub use crate::encapsulates::{
51        BareWorkload, EncapsulatesSpec, EncapsulationKind, EncapsulationKindError,
52        EncapsulationKindVariant, EncapsulationMode, EncapsulationTarget, ExistingHelmRelease,
53        ExistingKustomization, UnknownEncapsulationMode, UnknownEncapsulationTarget,
54    };
55    pub use crate::ephemeral::{compile_ephemeral_source, EphemeralSpec};
56    pub use crate::export::{
57        ArtifactError, ArtifactKind, ArtifactSource, ArtifactVariant, ChannelError, ChannelKind,
58        ChannelVariant, ExportSpec, ExportTrigger, HttpEventChannel, NatsSubjectChannel,
59        ProcessSnapshotSource, ReceiptsSource, ReportFormat, ReportPayloadShape, RunMarkerSource,
60        StdoutChannel, TestReportSource, UnknownArtifactKind, UnknownChannelKind,
61        UnknownExportTrigger, UnknownReportFormat, VectorChannel, DEFAULT_NATS_URL,
62        DEFAULT_VECTOR_INGEST,
63    };
64    pub use crate::hostname::{
65        ephemeral_id_from_spec, fmt_fqdn, fmt_fqdn_stable, resolve_ephemeral_id, HostnameError,
66        EPHEMERAL_ID_HASH_LEN,
67    };
68    pub use crate::identity::{content_hash, derive_identity, format_process_address, Identity};
69    pub use crate::intent::{
70        AplicacaoIntent, ContainerIntent, FluxIntent, GuestIntent, Intent, IntentError, IntentKind,
71        IntentVariant, LispIntent, NixIntent, UnknownWorkloadKind, WorkloadKind,
72    };
73    pub use crate::lifetime::{
74        EphemeralLifetime, Lifetime, LifetimeError, LifetimeKind, LifetimeVariant,
75        PermanentLifetime, TeardownPolicy, UnknownTeardownPolicy,
76    };
77    pub use crate::lifetime_clock::{
78        evaluate as lifetime_clock_evaluate, AutoTerminate, AutoTerminateKind, TerminateReason,
79        TerminateReasonKind, UnknownAutoTerminateKind, UnknownTerminateReasonKind,
80    };
81    pub use crate::matrix::{
82        compile_env_matrix_source, EnvMatrixSpec, MatrixAxis, MatrixBudget, NamedEphemeral,
83        SelectStrategy, SelectStrategyKind, UnknownSelectStrategyKind,
84    };
85    pub use crate::phase::{ProcessPhase, UnknownPhase};
86    pub use crate::pool::{
87        AllocationRef, EphemeralPool, MatchKey, MemberState, PoolCondition, PoolMember, PoolPhase,
88        PoolSelector, PoolSpec, PoolStatus, ReplacementPolicy, ReturnPolicy, UnknownMemberState,
89        UnknownPoolPhase, UnknownReplacementPolicy,
90    };
91    pub use crate::receipt::{
92        default_receipt_config_map_name, ReceiptEnvelope, ReceiptError, ReceiptKind,
93        RECEIPT_CM_SUFFIX, RECEIPT_VERSION,
94    };
95    pub use crate::routing::{RoutingBackend, RoutingHostname, RoutingSpec};
96    pub use crate::signal::{ProcessSignal, SighupStrategy, UnknownSighupStrategy};
97    pub use crate::spec::{
98        DependsOn, IdentitySpec, MustReachPhase, SignalPolicy, UnknownMustReachPhase,
99    };
100    pub use crate::status::{
101        BoundaryStatus, CheckedCondition, ComplianceStatus, FluxResourceRef, ProcessCondition,
102    };
103    pub use crate::table::{
104        ClaimRecord, ProcessEntry, ProcessTable, ProcessTableSpec, ProcessTableStatus,
105    };
106}
107
108/// CRD API group for every tatara CRD.
109pub const GROUP: &str = "tatara.pleme.io";
110/// CRD version for this module.
111pub const VERSION: &str = "v1alpha1";
112
113/// Annotation keys the reconciler reads/writes on owned FluxCD resources.
114pub mod annotations {
115    pub const MANAGED_BY: &str = "tatara.pleme.io/managed-by";
116    pub const PROCESS: &str = "tatara.pleme.io/process";
117    pub const PID: &str = "tatara.pleme.io/pid";
118    pub const CONTENT_HASH: &str = "tatara.pleme.io/content-hash";
119    pub const ATTESTATION_ROOT: &str = "tatara.pleme.io/attestation-root";
120    pub const GENERATION: &str = "tatara.pleme.io/generation";
121    pub const SIGNAL: &str = "tatara.pleme.io/signal";
122    /// Stamped by the reconciler when transitioning into `Releasing`
123    /// — records which terminal-reached gate the Process came from
124    /// (`Attested` or `Failed`) so `handle_releasing` can pick the
125    /// matching `ExportTrigger` set + the correct post-Releasing
126    /// destination (`Exiting` from Attested, `Zombie` from Failed).
127    pub const RELEASED_FROM: &str = "tatara.pleme.io/released-from";
128    /// Labels the export-worker Jobs the reconciler emits during
129    /// `Releasing`. Selector: `tatara.pleme.io/role=export`.
130    pub const ROLE: &str = "tatara.pleme.io/role";
131    /// Index of an export inside `lifetime.ephemeral.exports`.
132    /// Stamped on the corresponding tatara-export-worker Job + its
133    /// receipt ConfigMap so the reconciler can correlate them
134    /// without re-parsing the spec JSON.
135    pub const EXPORT_INDEX: &str = "tatara.pleme.io/export-index";
136}
137
138/// Standard finalizer for the Process reconciler.
139pub const PROCESS_FINALIZER: &str = "tatara.pleme.io/process-finalizer";
140
141/// Shared schemars helpers — emit OpenAPI schemas Kubernetes accepts.
142/// Free-form `serde_json::Value` fields default to an *empty* schema
143/// in schemars, which the K8s API server rejects with "type: Required
144/// value: must not be empty for specified object fields". The typed
145/// workaround is to emit `{type: object, x-kubernetes-preserve-unknown-
146/// fields: true}` — same shape kube-rs's own helpers produce.
147pub mod schema_helpers {
148    use schemars::{gen::SchemaGenerator, schema::Schema};
149    /// Schema for a free-form JSON object field. Apply via
150    /// `#[schemars(schema_with = "tatara_process::schema_helpers::preserve_unknown_object")]`
151    /// on any `serde_json::Value` / `BTreeMap<String, serde_json::Value>`
152    /// field exposed through a CRD.
153    pub fn preserve_unknown_object(_g: &mut SchemaGenerator) -> Schema {
154        serde_json::from_value(serde_json::json!({
155            "type": "object",
156            "x-kubernetes-preserve-unknown-fields": true
157        }))
158        .expect("static JSON literal parses as Schema")
159    }
160}
161
162// ── Lisp → ProcessSpec compile bridge ──────────────────────────────────
163//
164// `(defpoint NAME :k v …)` compiles to a `NamedDefinition<ProcessSpec>`.
165// The derive on ProcessSpec handles every field via the serde Deserialize
166// fallthrough — no hand-rolled keyword parsing needed.
167
168/// A named ProcessSpec as produced by `compile_source`.
169pub type Definition = tatara_lisp::NamedDefinition<crate::crd::ProcessSpec>;
170
171/// Compile a Lisp source string into a list of named ProcessSpecs.
172/// Each top-level `(defpoint NAME …)` form becomes one `Definition`.
173pub fn compile_source(src: &str) -> tatara_lisp::Result<Vec<Definition>> {
174    tatara_lisp::compile_named::<crate::crd::ProcessSpec>(src)
175}
176
177/// Register every domain owned by this crate with the global Lisp
178/// dispatcher. Call once per binary, typically near the top of `main`.
179/// After this call, `tatara_lisp::domain::lookup("defpoint")` and
180/// `lookup("defephemeral")` both resolve to the right typed compiler.
181///
182/// Idempotent — registering the same type twice is a no-op.
183pub fn register_all() {
184    tatara_lisp::domain::register::<crate::crd::ProcessSpec>();
185    tatara_lisp::domain::register::<crate::ephemeral::EphemeralSpec>();
186}
187
188#[cfg(test)]
189mod compile_tests {
190    use super::compile_source;
191    use crate::classification::{ConvergencePointType, SubstrateType};
192    use crate::compliance::VerificationPhase;
193    use crate::spec::MustReachPhase;
194
195    /// The full derive-powered pipeline — no hand-rolled parsing anywhere.
196    /// Every field travels: Lisp → Sexp → serde_json → typed ProcessSpec.
197    #[test]
198    fn full_processspec_round_trip_via_derive() {
199        let src = r#"
200            (defpoint observability-stack
201              :identity       (:parent "seph.1")
202              :classification (:point-type Gate
203                               :substrate Observability
204                               :horizon (:kind Bounded)
205                               :calm Monotone
206                               :data-classification Internal)
207              :intent         (:nix (:flake-ref "github:pleme-io/k8s"
208                                     :attribute "observability"
209                                     :attic-cache "main"))
210              :boundary       (:postconditions
211                                 ((:kind KustomizationHealthy
212                                   :params (:name "observability-stack"
213                                            :namespace "flux-system"))
214                                  (:kind PromQL
215                                   :params (:query "up == 1")))
216                               :timeout "15m")
217              :compliance     (:baseline "fedramp-moderate"
218                               :bindings ((:framework "nist-800-53"
219                                           :control-id "SC-7"
220                                           :phase AtBoundary)))
221              :depends-on     ((:name "secret-injection" :must-reach Attested))
222              :signals        (:sigterm-grace-seconds 480
223                               :sighup-strategy Reconverge))
224        "#;
225        let defs = compile_source(src).expect("compile");
226        assert_eq!(defs.len(), 1);
227        let d = &defs[0];
228        assert_eq!(d.name, "observability-stack");
229
230        // identity
231        assert_eq!(d.spec.identity.parent.as_deref(), Some("seph.1"));
232
233        // classification (enums deserialized via symbol → string)
234        assert_eq!(d.spec.classification.point_type, ConvergencePointType::Gate);
235        assert_eq!(
236            d.spec.classification.substrate,
237            SubstrateType::Observability
238        );
239
240        // intent (tagged-union with one of four options)
241        let nix = d.spec.intent.nix.as_ref().expect("nix intent");
242        assert_eq!(nix.flake_ref, "github:pleme-io/k8s");
243        assert_eq!(nix.attribute, "observability");
244        assert_eq!(nix.attic_cache.as_deref(), Some("main"));
245
246        // boundary (Vec<nested struct with params object>)
247        assert_eq!(d.spec.boundary.postconditions.len(), 2);
248        assert_eq!(d.spec.boundary.timeout.as_deref(), Some("15m"));
249
250        // compliance (Vec<binding with enum phase>)
251        assert_eq!(
252            d.spec.compliance.baseline.as_deref(),
253            Some("fedramp-moderate")
254        );
255        assert_eq!(d.spec.compliance.bindings.len(), 1);
256        assert_eq!(
257            d.spec.compliance.bindings[0].phase,
258            VerificationPhase::AtBoundary
259        );
260
261        // depends_on (Vec<struct with enum>)
262        assert_eq!(d.spec.depends_on.len(), 1);
263        assert_eq!(d.spec.depends_on[0].must_reach, MustReachPhase::Attested);
264
265        // signals (numeric + enum defaults)
266        assert_eq!(d.spec.signals.sigterm_grace_seconds, 480);
267    }
268
269    #[test]
270    fn missing_required_field_errors() {
271        // `:classification` has no #[serde(default)] — omit it and compile must fail.
272        let src = r#"(defpoint x :intent (:nix (:flake-ref "f" :attribute "a")))"#;
273        assert!(compile_source(src).is_err());
274    }
275
276    #[test]
277    fn serde_default_fields_are_optional() {
278        // Omit every #[serde(default)] field — compile must succeed because
279        // the derive honors serde defaults.
280        let src = r#"
281            (defpoint x
282              :classification (:point-type Transform :substrate Compute)
283              :intent (:flux (:git-repository "g" :path ".")))
284        "#;
285        let defs = compile_source(src).expect("compile");
286        assert_eq!(defs.len(), 1);
287        let d = &defs[0];
288        assert!(d.spec.depends_on.is_empty());
289        assert!(d.spec.boundary.postconditions.is_empty());
290        assert!(d.spec.compliance.bindings.is_empty());
291        assert!(!d.spec.suspended);
292        // Lifetime defaults to Permanent (no variant set, resolver still works).
293        assert!(d.spec.lifetime.is_default());
294        assert!(!d.spec.lifetime.is_ephemeral());
295    }
296
297    /// Registering all process-owned domains is idempotent and resolves
298    /// both `defpoint` (ProcessSpec) and `defephemeral` (EphemeralSpec).
299    #[test]
300    fn register_all_resolves_defpoint_and_defephemeral() {
301        use tatara_lisp::domain::lookup;
302        super::register_all();
303        super::register_all(); // idempotent
304        assert!(lookup("defpoint").is_some(), "defpoint must resolve");
305        assert!(
306            lookup("defephemeral").is_some(),
307            "defephemeral must resolve"
308        );
309    }
310
311    /// End-to-end: a `(defpoint …)` form may carry the full ephemeral
312    /// shape directly — `:intent (:aplicacao …)` + `:lifetime (:ephemeral …)`.
313    /// This is what the `(defephemeral …)` sugar lowers to via `From`.
314    #[test]
315    fn defpoint_with_aplicacao_intent_and_ephemeral_lifetime() {
316        use crate::intent::IntentVariant;
317        use crate::lifetime::{LifetimeVariant, TeardownPolicy};
318        let src = r#"
319            (defpoint closed-loop-attest
320              :classification (:point-type Gate :substrate Compute)
321              :intent (:aplicacao
322                        (:chart-ref "oci://ghcr.io/pleme-io/charts/lareira-demo-app"
323                         :version "0.5.5"
324                         :profile "all-in-one"
325                         :values-overlay (:cluster (:name "ephemeral-test-01"))
326                         :target-namespace "demo-test"))
327              :boundary (:postconditions
328                          ((:kind HelmReleaseReleased
329                            :params (:name "demo-app-consolidated"
330                                     :namespace "demo-test"))
331                           (:kind ClosedLoopAuth
332                            :params (:issuer (:service "demo-app-issuer" :port 8080)
333                                     :consumer (:service "demo-app-gateway" :port 8000)
334                                     :probeImage "ghcr.io/pleme-io/closed-loop-probe:0.1.0"))))
335              :lifetime (:ephemeral (:ttl "1h"
336                                     :teardown-policy OnAttested
337                                     :max-concurrent 1)))
338        "#;
339        let defs = compile_source(src).expect("compile");
340        assert_eq!(defs.len(), 1);
341        let d = &defs[0];
342
343        // Aplicacao intent landed.
344        match d.spec.intent.variant().unwrap() {
345            IntentVariant::Aplicacao(a) => {
346                assert_eq!(a.profile, "all-in-one");
347                assert_eq!(a.version, "0.5.5");
348                assert_eq!(a.target_namespace.as_deref(), Some("demo-test"));
349                assert_eq!(a.values_overlay["cluster"]["name"], "ephemeral-test-01");
350            }
351            other => panic!("expected Aplicacao, got {other:?}"),
352        }
353
354        // Ephemeral lifetime landed with the right teardown policy.
355        match d.spec.lifetime.variant().unwrap() {
356            LifetimeVariant::Ephemeral(e) => {
357                assert_eq!(e.ttl, "1h");
358                assert_eq!(e.teardown_policy, TeardownPolicy::OnAttested);
359                assert_eq!(e.max_concurrent, 1);
360            }
361            other => panic!("expected ephemeral, got {other:?}"),
362        }
363
364        // Two typed postconditions including ClosedLoopAuth.
365        assert_eq!(d.spec.boundary.postconditions.len(), 2);
366        assert_eq!(
367            d.spec.boundary.postconditions[1].kind,
368            crate::boundary::ConditionKind::ClosedLoopAuth
369        );
370    }
371}
tatara_process/lib.rs

tatara_process/
lib.rs
