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

tatara_process/
lib.rs
