allora_runtime/spec/
mod.rs

1//! Spec module: programmatic component specification data models and format parsers.
2//!
3//! Provides strongly typed specification builders ("Spec") for components. Parsing of external
4//! configuration (YAML today) is isolated in `*_spec_yaml.rs` modules that yield these pure data
5//! structs. Runtime instantiation is handled separately by DSL builders (`dsl/component_builders.rs`).
6//!
7//! # Current Specs
8//! * `ChannelSpec` / `ChannelKindSpec` – single channel intent.
9//! * `ChannelsSpec` – collection of channel specs sharing a version.
10//! * `AlloraSpec` – top-level aggregate (currently only channels; future: endpoints, filters, adapters).
11//!
12//! # Layering
13//! 1. Spec data models (`*_spec.rs`) – no parsing, no IO, no instantiation.
14//! 2. Parsers (`*_spec_yaml.rs`) – YAML Value -> Spec (+ structural validation, version checks).
15//! 3. DSL builders (`dsl/component_builders.rs`) – Spec -> runtime (assign ids, enforce uniqueness).
16//! 4. Facade (`dsl/mod.rs`) – format inference + `build()` returning `AlloraRuntime`.
17//!
18//! # Goals
19//! * Clear separation between parsing, specification, and instantiation.
20//! * Programmatic construction (e.g. `ChannelSpec::queue().id("orders")`) without YAML.
21//! * Non-breaking extension path for new components (add new spec + parser; do not alter existing semantics).
22//!
23//! # Versioning Strategy
24//! * Each parser validates an integer `version` field (currently must equal 1) via shared helper `version::validate_version`.
25//! * Breaking changes introduce new versioned parser modules (e.g. `channel_spec_yaml_v2.rs`).
26//! * Older parsers remain for backward compatibility.
27//!
28//! # Uniqueness & IDs
29//! * Parsers allow duplicate / missing `id` values (structural validation only).
30//! * Builders enforce uniqueness (error on duplicates) and generate deterministic auto IDs (`channel:auto.N`) for missing channel ids in multi-builds; single channel builds use a UUID-based id.
31//!
32//! # Example (Programmatic + YAML)
33//! ```rust
34//! use allora_core::Channel;
35//! use allora_runtime::{build_channel_from_str, spec::ChannelSpec, DslFormat};
36//! // Programmatic spec
37//! let spec = ChannelSpec::queue().id("prog-demo");
38//! assert_eq!(spec.channel_id(), Some("prog-demo"));
39//! // YAML parsed via facade (no need to construct spec manually)
40//! let raw = "version: 1\nchannel:\n  kind: direct\n  id: parsed-demo";
41//! let chan = build_channel_from_str(raw, DslFormat::Yaml).unwrap();
42//! assert_eq!(chan.id(), "parsed-demo");
43//! ```
44//!
45//! # Specification Modules
46//! * `AlloraSpec`: top-level aggregate; future extension point.
47//! * `ChannelSpec`: single channel intent.
48//! * `ChannelsSpec`: ordered collection of channel specs sharing a version.
49//!
50//! # YAML Parser Modules
51//! Each spec type has a corresponding YAML parser module translating YAML values into the spec.
52//! Parsers perform structural + version validation; they defer uniqueness to builders.
53//!
54//! # DSL Builders
55//! Builders instantiate runtime components from specs (ID generation, uniqueness checks).
56//!
57//! # Facade
58//! `dsl/mod.rs` exposes user-facing build APIs (`build()`, `build_channel()`), performing format inference.
59//!
60//! This documentation intentionally avoids redundancy; for architecture-wide details see crate root docs.
61pub mod allora_spec;
62pub mod allora_spec_yaml;
63pub mod channel_spec;
64pub mod channel_spec_yaml;
65pub mod channels_spec;
66pub mod channels_spec_yaml;
67pub mod filter_spec;
68pub mod filter_spec_yaml;
69pub mod filters_spec;
70pub mod filters_spec_yaml;
71pub mod http_inbound_adapter_spec;
72pub mod http_inbound_adapter_spec_yaml;
73pub mod http_inbound_adapters_spec;
74pub mod http_inbound_adapters_spec_yaml;
75pub mod http_outbound_adapter_spec;
76pub mod http_outbound_adapter_spec_yaml;
77pub mod http_outbound_adapters_spec;
78pub mod http_outbound_adapters_spec_yaml;
79pub mod service_spec;
80pub mod service_spec_yaml;
81pub mod services_spec;
82pub mod version;
83
84pub use allora_spec::AlloraSpec;
85pub use allora_spec_yaml::AlloraSpecYamlParser;
86pub use channel_spec::{ChannelKindSpec, ChannelSpec};
87pub use channel_spec_yaml::ChannelSpecYamlParser;
88pub use channels_spec::ChannelsSpec;
89pub use channels_spec_yaml::ChannelsSpecYamlParser;
90pub use filter_spec::FilterSpec;
91pub use filter_spec_yaml::FilterSpecYamlParser;
92pub use filters_spec::FiltersSpec;
93pub use filters_spec_yaml::FiltersSpecYamlParser;
94pub use http_inbound_adapter_spec::HttpInboundAdapterSpec;
95pub use http_inbound_adapter_spec_yaml::HttpInboundAdapterSpecYamlParser;
96pub use http_inbound_adapters_spec::HttpInboundAdaptersSpec;
97pub use http_inbound_adapters_spec_yaml::HttpInboundAdaptersSpecYamlParser;
98pub use http_outbound_adapter_spec::HttpOutboundAdapterSpec;
99pub use http_outbound_adapter_spec_yaml::HttpOutboundAdapterSpecYamlParser;
100pub use http_outbound_adapters_spec::HttpOutboundAdaptersSpec;
101pub use http_outbound_adapters_spec_yaml::HttpOutboundAdaptersSpecYamlParser;
102pub use service_spec::ServiceActivatorSpec;
103pub use service_spec_yaml::ServiceSpecYamlParser;
104pub use services_spec::ServiceActivatorsSpec;
allora_runtime/spec/mod.rs

allora_runtime/spec/
mod.rs
