Module spec 

Spec module: programmatic component specification data models and format parsers.

Provides strongly typed specification builders (“Spec”) for components. Parsing of external configuration (YAML today) is isolated in *_spec_yaml.rs modules that yield these pure data structs. Runtime instantiation is handled separately by DSL builders (dsl/component_builders.rs).

Current Specs

• ChannelSpec / ChannelKindSpec – single channel intent.
• ChannelsSpec – collection of channel specs sharing a version.
• AlloraSpec – top-level aggregate (currently only channels; future: endpoints, filters, adapters).

Layering

1. Spec data models (*_spec.rs) – no parsing, no IO, no instantiation.
2. Parsers (*_spec_yaml.rs) – YAML Value -> Spec (+ structural validation, version checks).
3. DSL builders (dsl/component_builders.rs) – Spec -> runtime (assign ids, enforce uniqueness).
4. Facade (dsl/mod.rs) – format inference + build() returning AlloraRuntime.

Goals

• Clear separation between parsing, specification, and instantiation.
• Programmatic construction (e.g. ChannelSpec::queue().id("orders")) without YAML.
• Non-breaking extension path for new components (add new spec + parser; do not alter existing semantics).

Versioning Strategy

• Each parser validates an integer version field (currently must equal 1) via shared helper version::validate_version.
• Breaking changes introduce new versioned parser modules (e.g. channel_spec_yaml_v2.rs).
• Older parsers remain for backward compatibility.

Uniqueness & IDs

• Parsers allow duplicate / missing id values (structural validation only).
• 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.

Example (Programmatic + YAML)

use allora_core::Channel;
use allora_runtime::{build_channel_from_str, spec::ChannelSpec, DslFormat};
// Programmatic spec
let spec = ChannelSpec::queue().id("prog-demo");
assert_eq!(spec.channel_id(), Some("prog-demo"));
// YAML parsed via facade (no need to construct spec manually)
let raw = "version: 1\nchannel:\n  kind: direct\n  id: parsed-demo";
let chan = build_channel_from_str(raw, DslFormat::Yaml).unwrap();
assert_eq!(chan.id(), "parsed-demo");

Specification Modules

• AlloraSpec: top-level aggregate; future extension point.
• ChannelSpec: single channel intent.
• ChannelsSpec: ordered collection of channel specs sharing a version.

YAML Parser Modules

Each spec type has a corresponding YAML parser module translating YAML values into the spec. Parsers perform structural + version validation; they defer uniqueness to builders.

DSL Builders

Builders instantiate runtime components from specs (ID generation, uniqueness checks).

Facade

dsl/mod.rs exposes user-facing build APIs (build(), build_channel()), performing format inference.

This documentation intentionally avoids redundancy; for architecture-wide details see crate root docs.

Re-exports

pub use allora_spec::AlloraSpec;

pub use allora_spec_yaml::AlloraSpecYamlParser;

pub use channel_spec::ChannelKindSpec;

pub use channel_spec::ChannelSpec;

pub use channel_spec_yaml::ChannelSpecYamlParser;

pub use channels_spec::ChannelsSpec;

pub use channels_spec_yaml::ChannelsSpecYamlParser;

pub use filter_spec::FilterSpec;

pub use filter_spec_yaml::FilterSpecYamlParser;

pub use filters_spec::FiltersSpec;

pub use filters_spec_yaml::FiltersSpecYamlParser;

pub use http_inbound_adapter_spec::HttpInboundAdapterSpec;

pub use http_inbound_adapter_spec_yaml::HttpInboundAdapterSpecYamlParser;

pub use http_inbound_adapters_spec::HttpInboundAdaptersSpec;

pub use http_inbound_adapters_spec_yaml::HttpInboundAdaptersSpecYamlParser;

pub use http_outbound_adapter_spec::HttpOutboundAdapterSpec;

pub use http_outbound_adapter_spec_yaml::HttpOutboundAdapterSpecYamlParser;

pub use http_outbound_adapters_spec::HttpOutboundAdaptersSpec;

pub use http_outbound_adapters_spec_yaml::HttpOutboundAdaptersSpecYamlParser;

pub use service_spec::ServiceActivatorSpec;

pub use service_spec_yaml::ServiceSpecYamlParser;

pub use services_spec::ServiceActivatorsSpec;

Modules

allora_spec

AlloraSpec: top-level configuration spec aggregating inner component specs (currently channels only).

allora_spec_yaml

YAML parser for AlloraSpec (top-level, v1) reusing ChannelsSpec parser logic.

channel_spec

ChannelSpec: immutable, format-agnostic description of a Channel (pure pipe).

channel_spec_yaml

YAML parser/loader for ChannelSpec (schema v1). Focus: translate a YAML document into a validated ChannelSpec; no component instantiation.

channels_spec

ChannelsSpec: collection of ChannelSpec entries under one version (schema v1).

channels_spec_yaml

YAML parser for ChannelsSpec (v1 collection).

filter_spec

FilterSpec: specification for a single message filter (EIP Message Filter). Captures source channel id (from), optional target channel id (to), predicate expression (when), and optional identifier (id).

filter_spec_yaml

YAML parser for FilterSpec (v1). Expects structure defined in schema/v1/filter.schema.yml. Performs structural validation only (no expression grammar validation yet) and now recognizes optional id for uniqueness enforcement at build time.

filters_spec

FiltersSpec: collection of FilterSpec entries (v1) sharing a version. Provides ordered aggregation prior to runtime building; does not perform uniqueness checks.

filters_spec_yaml

YAML parser for FiltersSpec (collection v1). Delegates per-entry parsing to FilterSpecYamlParser and focuses on sequence + version validation.

http_inbound_adapter_spec

HttpInboundAdapterSpec: specification for a single HTTP inbound adapter binding an HTTP endpoint to messaging channels.

http_inbound_adapter_spec_yaml

YAML parser for HttpInboundAdapterSpec (v1). Expects structure defined in schema/v1/http-inbound-adapter.schema.yml. Performs structural validation: required non-empty host, path, methods (non-empty list), request-channel; numeric range for port; optional non-empty id, reply-channel.

http_inbound_adapters_spec

HttpInboundAdaptersSpec: collection of HttpInboundAdapterSpec entries sharing a single version.

http_inbound_adapters_spec_yaml

YAML parser for HttpInboundAdaptersSpec (collection v1). Expects structure defined in schema/v1/http-inbound-adapters.schema.yml. Delegates per-entry parsing to HttpInboundAdapterSpecYamlParser and focuses on sequence + version validation.

http_outbound_adapter_spec

http_outbound_adapter_spec_yaml

http_outbound_adapters_spec

http_outbound_adapters_spec_yaml

service_spec

ServiceActivatorSpec: specification for a single processing service (activator) binding logic between channels.

service_spec_yaml

YAML parser for ServiceActivatorSpec (v1). Expects structure defined in schema/v1/service-activator.schema.yml. Performs structural validation: required non-empty ref-name, from, to; optional non-empty id.

services_spec

ServiceActivatorsSpec: collection of ServiceActivatorSpec entries (v1) sharing a version. Mirrors FiltersSpec semantics for ordered aggregation and deferred uniqueness enforcement.

version

Shared YAML spec version validation helper. Ensures presence of integer version field and equality to expected version. Centralizes error message strings to keep parser modules consistent.