cloacina_macros/

lib.rs

/*
 *  Copyright 2025-2026 Colliery Software
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

#![allow(unexpected_cfgs)]
//! # Cloacina Macros
//!
//! Procedural macros for defining tasks and workflows in the Cloacina framework.
//!
//! ## Key Features
//!
//! - `#[task]` — define tasks with retry policies and trigger rules
//! - `#[workflow]` — define workflows as modules containing `#[task]` functions
//! - Compile-time validation of task dependencies and workflow structure
//! - Automatic task and workflow registration
//! - Code fingerprinting for task versioning
//!
//! ## Example
//!
//! ```rust,ignore
//! use cloacina::{task, workflow, Context, TaskError};
//!
//! #[workflow(name = "my_pipeline", description = "Process data")]
//! pub mod my_pipeline {
//!     use super::*;
//!
//!     #[task(id = "fetch", dependencies = [])]
//!     pub async fn fetch(ctx: &mut Context<Value>) -> Result<(), TaskError> { Ok(()) }
//!
//!     #[task(id = "process", dependencies = ["fetch"])]
//!     pub async fn process(ctx: &mut Context<Value>) -> Result<(), TaskError> { Ok(()) }
//! }
//! ```

pub(crate) mod computation_graph;
mod constructor_attr;
mod constructor_provider;
pub(crate) mod packaged_workflow;
mod reactor_attr;
mod registry;
pub(crate) mod tasks;
mod trigger_attr;
mod workflow_attr;

use proc_macro::TokenStream;

/// Define a task with retry policies and trigger rules.
#[proc_macro_attribute]
pub fn task(args: TokenStream, input: TokenStream) -> TokenStream {
    tasks::task(args, input)
}

/// Define a workflow as a module containing `#[task]` functions.
///
/// Applied to a `pub mod` containing `#[task]` functions. Auto-discovers tasks,
/// validates dependencies, and generates registration code based on delivery mode:
///
/// - **Embedded** (default): `inventory::submit!` auto-registration consumed by
///   `cloacina::Runtime::seed_from_inventory`
/// - **Packaged** (`features = ["packaged"]`): FFI exports for `.cloacina` packages
///
/// # Example
///
/// ```rust,ignore
/// #[workflow(name = "my_pipeline", description = "Process data")]
/// pub mod my_pipeline {
///     use super::*;
///
///     #[task(id = "fetch", dependencies = [])]
///     pub async fn fetch(ctx: &mut Context<Value>) -> Result<(), TaskError> { Ok(()) }
///
///     #[task(id = "process", dependencies = ["fetch"])]
///     pub async fn process(ctx: &mut Context<Value>) -> Result<(), TaskError> { Ok(()) }
/// }
/// ```
#[proc_macro_attribute]
pub fn workflow(args: TokenStream, input: TokenStream) -> TokenStream {
    workflow_attr::workflow_attr(args, input)
}

/// Define a trigger that fires a workflow on a schedule or condition.
///
/// # Custom poll trigger
///
/// ```rust,ignore
/// #[trigger(on = "my_workflow", poll_interval = "5s")]
/// pub async fn check_inbox() -> Result<TriggerResult, TriggerError> {
///     // check condition, return Fire(ctx) or Skip
/// }
/// ```
///
/// # Cron trigger (T-0305)
///
/// ```rust,ignore
/// #[trigger(on = "my_workflow", cron = "0 2 * * *", timezone = "UTC")]
/// ```
#[proc_macro_attribute]
pub fn trigger(args: TokenStream, input: TokenStream) -> TokenStream {
    trigger_attr::trigger_attr(args, input)
}

/// Define a computation graph as a module containing async node functions.
///
/// The topology is declared in the macro attribute. Nodes are pure async functions
/// within the module. The macro compiles the topology into a single async function
/// with nested match arms for enum routing.
///
/// # Example
///
/// ```rust,ignore
/// #[computation_graph(
///     react = when_any(alpha, beta),
///     graph = {
///         decision(alpha, beta) => {
///             Signal -> output_handler,
///             NoAction -> audit_logger,
///         },
///     }
/// )]
/// mod my_strategy {
///     async fn decision(alpha: Option<&AlphaData>, beta: Option<&BetaData>) -> DecisionOutcome { ... }
///     async fn output_handler(signal: &Signal) -> OutputConfirmation { ... }
///     async fn audit_logger(reason: &NoActionReason) -> AuditRecord { ... }
/// }
/// ```
#[proc_macro_attribute]
pub fn computation_graph(args: TokenStream, input: TokenStream) -> TokenStream {
    computation_graph::computation_graph_attr(args, input)
}

/// Declare a reactor as a unit struct.
///
/// The reactor bundles accumulators + firing criteria and publishes an
/// `InputCache` whenever its criteria are met. Graphs declared with
/// `#[computation_graph(trigger = reactor(ReactorType), ...)]` bind to it
/// by type path.
///
/// ```rust,ignore
/// #[reactor(
///     name = "risk_signals",
///     accumulators = [alpha, beta],
///     criteria = when_any(alpha, beta),
/// )]
/// pub struct RiskSignals;
/// ```
#[proc_macro_attribute]
pub fn reactor(args: TokenStream, input: TokenStream) -> TokenStream {
    reactor_attr::reactor_attr(args, input)
}

/// Author a WASM **constructor** member in clean form (CLOACI-T-0826 / T-0837).
///
/// A constructor is one MEMBER of a provider *suite*: the macro generates the
/// member's config struct, its object-safe `<Kind>Object` impl (the `JSON`-wire
/// body), and the associated metadata fns (`__constructor_name`,
/// `__constructor_manifest`, `__constructor_make`) the crate-level
/// [`macro@constructor_provider`] shell aggregates. The macro does NOT emit fidius
/// `#[plugin_interface]` / `#[plugin_impl]` glue — that is the shell's job, so N
/// constructors can coexist in one crate behind one component (CLOACI-A-0011).
///
/// Applied to a struct whose fields are `#[config]` (bound once per instance at
/// load) or `#[param(required)]` / `#[param(optional)]` (declared inputs pulled
/// from the task context — `task` kind only). The author writes ONLY the body
/// method (`execute` for `kind = task`).
///
/// ```rust,ignore
/// #[constructor(kind = task, name = "prefix", version = "0.1.0")]
/// struct Prefix {
///     #[config] prefix: String,
///     #[param(required)] name: String,
/// }
/// impl Prefix {
///     fn execute(&self) -> Result<(), ConstructorError> {
///         self.set("result", format!("{}{}", self.prefix, self.name));
///         Ok(())
///     }
/// }
///
/// // One provider = a suite of members behind one component:
/// constructor_provider!(name = "cloacina-provider-text", version = "0.1.0", task = [Prefix]);
/// ```
///
/// All four kinds are code-generated: `task` (T-0826), `trigger` (T-0829), and
/// `accumulator` / `reactor` (T-0828). `trigger`'s author body returns a fire
/// decision (`Result<bool, ConstructorError>`) and uses `set`/`get` to build the
/// fired context.
#[proc_macro_attribute]
pub fn constructor(args: TokenStream, input: TokenStream) -> TokenStream {
    constructor_attr::constructor_attr(args, input)
}

/// Declare a constructor **provider** — a *suite* of `#[constructor]` members
/// compiled into one WASM component (CLOACI-A-0011 / T-0837).
///
/// Aggregates the explicitly-listed members (by struct name, grouped by kind) into
/// the per-kind fidius `#[plugin_interface]` + `#[plugin_impl]` shell with a
/// name-dispatched `configure` (the consumer's `constructor = "<name>"` selects
/// the member; the name travels in the `configure` payload), and emits a crate-level
/// `pub fn __provider_manifest() -> ProviderManifest` listing every member. A
/// single-constructor provider is just a suite of one.
///
/// ```rust,ignore
/// #[constructor(kind = task, name = "read_file", version = "0.1.0")]
/// struct ReadFile { #[config] path: String }
/// // ... impl ReadFile { fn execute(&self) -> Result<(), ConstructorError> { ... } }
///
/// #[constructor(kind = task, name = "write_file", version = "0.1.0")]
/// struct WriteFile { #[config] path: String, #[param(required)] contents: String }
/// // ... impl WriteFile { fn execute(&self) -> Result<(), ConstructorError> { ... } }
///
/// constructor_provider!(
///     name = "cloacina-provider-fs",
///     version = "0.1.0",
///     task = [ReadFile, WriteFile],
/// );
/// ```
#[proc_macro]
pub fn constructor_provider(input: TokenStream) -> TokenStream {
    constructor_provider::constructor_provider(input)
}

/// Define a passthrough accumulator (socket-only, no event loop).
///
/// ```rust,ignore
/// #[passthrough_accumulator]
/// fn beta(event: PricingUpdate) -> BetaData {
///     BetaData { estimate: event.mid_price }
/// }
/// ```
#[proc_macro_attribute]
pub fn passthrough_accumulator(args: TokenStream, input: TokenStream) -> TokenStream {
    match computation_graph::accumulator_macros::passthrough_accumulator_impl(
        args.into(),
        input.into(),
    ) {
        Ok(output) => output.into(),
        Err(err) => err.to_compile_error().into(),
    }
}

/// Define a stream-backed accumulator.
///
/// ```rust,ignore
/// #[stream_accumulator(type = "kafka", topic = "market.orderbook")]
/// fn alpha(event: OrderBookUpdate) -> AlphaData {
///     AlphaData { top_high: event.best_ask, top_low: event.best_bid }
/// }
/// ```
#[proc_macro_attribute]
pub fn stream_accumulator(args: TokenStream, input: TokenStream) -> TokenStream {
    match computation_graph::accumulator_macros::stream_accumulator_impl(args.into(), input.into())
    {
        Ok(output) => output.into(),
        Err(err) => err.to_compile_error().into(),
    }
}

/// Define a batch accumulator (buffers events, flushes on timer or size threshold).
///
/// ```rust,ignore
/// #[batch_accumulator(flush_interval = "1s", max_buffer_size = 100)]
/// fn aggregate_fills(events: Vec<FillEvent>) -> Option<AggregatedFills> {
///     if events.is_empty() { return None; }
///     Some(AggregatedFills { total: events.len(), volume: events.iter().map(|e| e.qty).sum() })
/// }
/// ```
#[proc_macro_attribute]
pub fn batch_accumulator(args: TokenStream, input: TokenStream) -> TokenStream {
    match computation_graph::accumulator_macros::batch_accumulator_impl(args.into(), input.into()) {
        Ok(output) => output.into(),
        Err(err) => err.to_compile_error().into(),
    }
}

/// Define a polling accumulator (timer-based, queries pull-based sources).
///
/// ```rust,ignore
/// #[polling_accumulator(interval = "5s")]
/// async fn config_source() -> Option<ConfigData> {
///     let data = fetch_config().await;
///     if data.changed() { Some(data) } else { None }
/// }
/// ```
#[proc_macro_attribute]
pub fn polling_accumulator(args: TokenStream, input: TokenStream) -> TokenStream {
    match computation_graph::accumulator_macros::polling_accumulator_impl(args.into(), input.into())
    {
        Ok(output) => output.into(),
        Err(err) => err.to_compile_error().into(),
    }
}

/// Define a state accumulator (bounded history buffer with DAL persistence).
///
/// ```rust,ignore
/// #[state_accumulator(capacity = 10)]
/// fn previous_outputs() -> VecDeque<DecisionOutput>;
/// ```
#[proc_macro_attribute]
pub fn state_accumulator(args: TokenStream, input: TokenStream) -> TokenStream {
    match computation_graph::accumulator_macros::state_accumulator_impl(args.into(), input.into()) {
        Ok(output) => output.into(),
        Err(err) => err.to_compile_error().into(),
    }
}