aion/
lib.rs

1//! Transport-agnostic Aion workflow engine with durability, replay, timers, and supervision.
2//!
3//! The engine embeds beamr, loads `.aion` packages, owns workflow lifecycle and
4//! process residency, records and replays durable history, and exposes seams for
5//! activities, events, signals, queries, and server transports.
6//!
7//! # Example
8//!
9//! ```no_run
10//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
11//! use std::sync::Arc;
12//!
13//! use aion::EngineBuilder;
14//! use aion_store::{EventStore, InMemoryStore};
15//!
16//! let store: Arc<dyn EventStore> = Arc::new(InMemoryStore::default());
17//! let engine = EngineBuilder::new()
18//!     .store_arc(store)
19//!     .in_memory_visibility()
20//!     .build()
21//!     .await?;
22//! # let _ = engine;
23//! # Ok(())
24//! # }
25//! ```
26//!
27//! # Cargo features
28//!
29//! - `beamr_query_reentry_fixed` (off by default): compiles the
30//!   batch-orchestrator example e2e tests (`tests/example_query_reentry.rs`)
31//!   that drive live queries through the Gleam SDK's query pump while a
32//!   parent is parked in `child.await`. The engine-side query protocol is
33//!   fully functional, but the example's child-result decode path hit
34//!   beamr 0.4.9 VM gaps in `gleam_json`/`gleam_stdlib`; enable the feature
35//!   once the upstream beamr fixes land and the pin is bumped.
36//!
37//!   NOTE: the crate is now pinned to beamr 0.6.4. The gap this gate guards
38//!   against was identified on 0.4.9 and may have been fixed upstream, so the
39//!   gate needs re-validation against 0.6.4 and may now be stale.
40
41#![deny(unsafe_code)]
42
43/// Activity dispatch bridge and error propagation helpers.
44pub mod activity;
45/// Child-workflow spawn support.
46pub mod child;
47/// Durable command recording, replay, and recovery support.
48pub mod durability;
49/// Engine builder, runtime APIs, and delegated seams.
50pub mod engine;
51/// Handle type exposed by embedded engine seams.
52pub mod engine_seam;
53/// Engine and routing error types.
54pub mod error;
55/// Workflow lifecycle start, transition, visibility, and termination helpers.
56pub mod lifecycle;
57/// `.aion` package loading into runtime modules.
58pub mod loader;
59/// Live event publication: publish-after-commit store wrapper and publisher.
60pub mod publish;
61/// Query dispatch services and mailbox support.
62pub mod query;
63/// Active workflow registry and handle residency tracking.
64pub mod registry;
65/// BEAM runtime configuration, handles, NIFs, and workflow process support.
66pub mod runtime;
67/// Schedule evaluation and cron parsing support.
68pub mod schedule;
69/// Signal routing and resume handoff support.
70pub mod signal;
71/// Supervision tree models for engines, workflow types, and workflow instances.
72pub mod supervision;
73
74/// Thread-scoped tracing capture shared by the crate's operator-visibility
75/// proofs.
76#[cfg(test)]
77pub(crate) mod log_capture;
78/// Fault-injecting stores shared by the crate's durable-refusal proofs — not
79/// all of their consumers are retry paths, and the module's own doc says why.
80#[cfg(test)]
81pub(crate) mod store_faults;
82/// Timer creation, recovery, and wake-up services.
83pub mod time;
84/// Workloop engine services: cadence dead-man, tolerance sweep, iteration
85/// boundary, hatch (workloop design brief, Leg 2).
86pub mod workloop;
87
88pub use activity::{
89    ActivityDispatch, ActivityDispatcher, dispatch_activity, propagate_activity_outcome,
90    surface_activity_error,
91};
92pub use durability::ActiveWorkflowRecoverySeamImpl;
93pub use engine::{
94    AdmissionReason, DeferredEventPublisher, DeferredQueryService, DeferredSignalRouter,
95    DelegatedSeams, Engine, EngineBuilder, EventFamily, EventFilter, EventPublisher,
96    EventStreamLagged, QueryService, QueueAdmission, ReasonCensus, RequiredContract, SignalRouter,
97    UnreachableContract, schedule_coordinator_workflow_id,
98};
99pub use engine_seam::EngineHandle;
100// Both appear in the public signature of `EngineError` — `ContentHash` in the
101// `version` field of `StartInputRefused`, `SignalRefused` and
102// `NoQueueDeclaration`, and `ContractIdentityError` as the `source` of
103// `ContractIdentity` — so a consumer of this crate cannot construct,
104// destructure, or exhaustively match those variants without them. Re-exported
105// here rather than leaving every downstream to take its own `aion-package`
106// dependency to reach types this crate's own API already hands them.
107//
108// Not speculative surface: `aion-client` declares no `aion-package` dependency
109// at all and its `transport::embedded` error-mapping tests construct
110// `aion::ContentHash` and `aion::ContractIdentityError` directly. Without these
111// two lines that crate cannot build the very `EngineError` values it exists to
112// translate — the hole is older than this change, and this is where it surfaced.
113pub use aion_package::{ContentHash, ContractIdentityError};
114pub use error::{EngineError, PinHolder, SignalRouterError};
115pub use loader::{
116    ActivityServing, DeployedWorkerContract, LoadOutcome, LoadedWorkflow, SignalRefusalReason,
117    WorkflowCatalog, WorkflowVersionInfo,
118};
119pub use publish::{BroadcastEventPublisher, PublishError, PublishingEventStore};
120pub use query::{ConcreteQueryService, QueryError};
121pub use registry::{
122    CompletionNotifier, HandleResidency, Registry, Residency, TerminalOutcome, WorkflowHandle,
123    WorkflowHandleParts,
124};
125pub use runtime::{
126    CompletionRetryConfig, InvalidCompletionRetryLadder, PARKED_ACTIVITY_REASON, Pid,
127    RuntimeConfig, RuntimeHandle, RuntimeInput, SignalDeliveryConfig, activity_timeout_from_config,
128    activity_timeout_reason, is_parked_reason,
129};
130pub use schedule::{ScheduleError, next_fire_time, parse_cron_expression};
131pub use supervision::{
132    EngineSupervisorId, SupervisionTree, TypeSupervisorId, TypeSupervisorNode, WorkflowNode,
133};
aion/lib.rs

aion/
lib.rs
