Module dsl

allora_runtime

Module dsl 

Source
Expand description

DSL Facade: multi-format (YAML today; JSON/XML forthcoming) configuration entry points.

This module orchestrates conversion of external textual configuration into runtime components by coordinating three layers:

  1. Parsers (in spec/): format-specific translation into strongly typed specs.
  2. Builders (in dsl/component_builders.rs): spec -> concrete runtime objects.
  3. Facade (this file): public ergonomic API + format inference.

§Goals

  • Provide a minimal, stable surface (build, build_channel, build_channel_from_str, build_filter, DslFormat).
  • Keep parsing & instantiation decoupled so additional formats/components add minimal code.
  • Fail fast with clear, categorized errors (Error::Serialization vs Error::Other).

§Supported Components (v1)

  • Channel (InMemory kind)
  • Filter (single filter spec via build_filter AND aggregated when present in top-level allora.yml into AlloraRuntime)
  • Service (single service spec via build_service; aggregation forthcoming when services spec collection is added)

§Supported Formats

  • YAML (DslFormat::Yaml)
  • JSON / XML reserved (emit explicit unsupported errors)

§Building a Single Channel

use allora_core::Channel;
use allora_runtime::build_channel;
let ch = build_channel("tests/fixtures/channel.yml").unwrap();
println!("channel id={}", ch.id());

§Building a Single Filter

use allora_runtime::build_filter;
// Requires tests/fixtures/filter.yml present.
let f = build_filter("tests/fixtures/filter.yml").unwrap();
// apply using f.accepts(exchange)

§Building a Single Service

use allora_runtime::build_service;
// Requires tests/fixtures/service.yml present.
let svc = build_service("tests/fixtures/service.yml").unwrap();
// invoke via svc.process_sync(&mut exchange)

§Building Multiple Filters (collection spec)

use allora_runtime::spec::FiltersSpecYamlParser;
use allora_runtime::dsl::component_builders::build_filters_from_spec;
let raw = std::fs::read_to_string("tests/fixtures/filters.yml").unwrap();
let spec = FiltersSpecYamlParser::parse_str(&raw).unwrap();
let filters = build_filters_from_spec(spec).unwrap();
assert!(!filters.is_empty());

§Building the Full Runtime (AlloraRuntime)

use allora_runtime::{build, Channel, Filter};
let rt = build("tests/fixtures/allora.yml").unwrap();
assert!(rt.channel_by_id("inbound.orders").is_some());
assert!(rt.filters().len() >= 1);

Runtime accessors now: channels(), channel_by_id(), channel_count(), filters(), filter_count(), plus ownership via into_channels() / into_filters().

§Access Patterns

  • Borrow: rt.channels(), rt.filters()
  • Lookup: rt.channel_by_id("inbound.orders")
  • Counts: rt.channel_count(), rt.filter_count()
  • Consume: rt.into_channels(), rt.into_filters()

§Error Semantics

  • Error::Other – I/O failures (e.g. unreadable file path)
  • Error::Serialization – structural issues (missing fields / invalid values / unsupported version / unsupported format)

§Extension Guide (Adding New Components)

  1. Define data model spec (*_spec.rs)
  2. Add parser (*_spec_yaml.rs) validating version + fields
  3. Extend AlloraSpec to hold new spec collection (e.g. filters, endpoints)
  4. Add builder in component_builders.rs
  5. Augment build_runtime_from_str to assemble new runtime objects
  6. Add accessors on AlloraRuntime

§Format Addition (JSON Outline)

  • Introduce *_json_parser implementing parse_str
  • Branch in build_*_from_str and build_runtime_from_str
  • Reuse existing builders (format-agnostic)

§Testing Strategy

  • Parser edge cases near parser modules (*_spec_yaml.rs)
  • Builder invariants in dedicated tests (channels, filters)
  • Facade behavior & runtime aggregation in runtime-focused tests

§Versioning

  • Each spec parser validates an explicit integer version
  • Breaking changes add parallel parser modules (*_v2_yaml.rs) preserving old behavior

§Internal Helpers (Non-Public)

  • build_runtime_from_str – dispatcher from raw text + format (now aggregates filters when present)
  • build_filter_from_str – kept private

§Roadmap

  • Multiple channel kinds (kafka, amqp)
  • Additional pattern components (routers, splitters) aggregated in runtime
  • Endpoints & adapters (HTTP, file, custom transport)
  • JSON/XML DSL formats
  • Expanded expression language (parentheses, negation, path navigation)

This documentation focuses on architecture & extensibility; see component modules for specifics.

Modules§

component_builders
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.
runtime
AlloraRuntime: aggregate of built runtime components (extensible).

Enums§

DslFormat
Supported DSL input formats.

Functions§

build
Public: build full runtime from a file path (future: endpoints, filters, etc.).
build_channel
Convenience: build channel from a file path (auto-detect format via extension).
build_channel_from_str
Build channel from raw string + specified format.
build_filter
Convenience: build filter from a file path (auto-detect format via extension).
build_service
Convenience: build service from a file path (auto-detect format via extension).