Module component_builders

Expand description

DSL runtime component builders: instantiate runtime components from validated specs. This module will host builders for multiple component types (Channel, Endpoint, Adapter, etc.). Each builder converts a spec (format-agnostic, already validated) into a concrete runtime type.

§Purpose

Bridge the gap between a format-specific parsed spec (e.g. YAML -> ChannelSpec) and the actual runtime component (e.g. QueueChannel). Parsing & validation happen elsewhere (under spec/ parsers). Builders assume the spec is structurally valid and focus solely on instantiation and enforcing runtime constraints (like non-empty IDs).

§Design Principles

One builder per component type (not per serialization format).
Builders accept only strongly typed specs (no raw YAML/JSON here).
Fail fast on remaining invariants (e.g. empty string ID) that are easier to check post-parse.
Keep side-effects minimal: no I/O, no global state modifications.

§Usage Example

use allora_runtime::spec::ChannelSpec;
use allora_runtime::dsl::component_builders::build_channel_from_spec;
use allora_core::Channel; // bring trait into scope for channel.id()
let spec = ChannelSpec::queue().id("example-channel");
let channel = build_channel_from_spec(spec).unwrap();
assert_eq!(channel.id(), "example-channel");

§Auto-generated IDs (Single vs Multi Build)

Single channel (build_channel_from_spec when spec.channel_id() is None): underlying QueueChannel::with_random_id() assigns a UUID-based id (queue:<uuid>).
Multi-channel (build_channels_from_spec) with missing ids: this module generates deterministic sequential ids of the form channel:auto.<N> starting at 1 and incrementing for each missing id within that build invocation. The sequence resets each time you call build_channels_from_spec (no global counter).

Rationale: deterministic ids in multi-build scenarios improve testability and reproducibility without leaking global mutable state.

§Uniqueness Enforcement

Duplicate provided ids (two specs supplying the same non-empty id) -> Error::Serialization("duplicate channel.id '<id>'").
Empty id string -> Error::Serialization("channel.id must not be empty").
Generated ids are checked against previously used ids in the same build to avoid collisions.

§Extending Channel Kinds

When additional kinds (e.g. Kafka, Amqp) are introduced, extend ChannelKindSpec and add match arms inside build_channel_spec_internal. Keep generation & uniqueness logic centralized so tests remain stable.

§Internal Helper

build_channel_spec_internal encapsulates ID resolution (provided vs generated), uniqueness checks, and final builder dispatch. It is intentionally private so external callers use only the stable public functions.

§Error Semantics

Error::Serialization – structural or invariant violation (empty id, duplicate id).
Error::Other – reserved for future runtime construction failures.

§Future Improvements

Shared trait for all component specs (e.g. ComponentSpec with fn kind(&self) + fn id(&self)) enabling generic multi-component builders.
Pluggable id generation strategy (configure prefix / starting counter).
Metrics hooks (time to build, count of auto-generated ids) gated behind a feature flag.

This documentation focuses on current behavior while outlining evolution points to minimize refactors as new component types are added.

Functions§

build_channel_from_spec: Build a concrete channel from a validated ChannelSpec. Delegates to internal helper without uniqueness / auto-ID tracking (builder handles UUID auto-id).
build_channels_from_spec: Build multiple concrete channels from a validated ChannelsSpec. Enforces uniqueness across provided IDs and generates deterministic auto IDs for missing ones.
build_filter_from_spec: Build a Filter from a validated FilterSpec.
build_filters_from_spec: Build multiple Filters from FiltersSpec (collection). Returns Vec preserving order. ID Strategy (mirrors channels):
build_http_inbound_adapter_from_spec: Build a single HTTP inbound adapter from a validated HttpInboundAdapterSpec.
build_http_inbound_adapters_from_spec: Build multiple HTTP inbound adapters from a validated HttpInboundAdaptersSpec.
build_http_outbound_adapter_from_spec: Build a single HTTP outbound adapter from a validated HttpOutboundAdapterSpec.
build_http_outbound_adapters_from_spec: Build multiple HTTP outbound adapters from a validated HttpOutboundAdaptersSpec.
build_service_activators_from_spec: Build multiple services from ServicesSpec preserving order. Auto-ID Strategy:
build_service_from_spec: Build a single Service from a validated ServiceSpec. Currently materializes as a ClosureProcessor placeholder executing no-op logic. Future: compile & load user-provided implementation from ref_name.

Type Aliases§

ServiceProcessor