alba_engine/
lib.rs

1//! Orchestration engine that schedules and runs beams.
2//!
3//! `alba-engine` sits between the model and the machine: it takes the
4//! validated [`alba_core::Project`] the loader produced, extracts the union
5//! of the target beams' execution subgraphs, and runs it with bounded
6//! parallelism through an [`alba_executors::Executor`] — which it only ever
7//! sees as that trait, so a future docker or plugin executor drops in
8//! without this crate changing. See the `scheduler` module for the
9//! scheduling rules themselves.
10//!
11//! Everything a caller needs is [`run`]: give it a project, [`Targets`],
12//! [`RunOptions`], the [`Executors`] to dispatch each beam's declared kind
13//! to, a channel to receive [`RunEvent`]s on, and a cancellation token, and
14//! it reports back a [`RunSummary`]. [`watch`] wraps that same call in a
15//! session that re-runs the target whenever the files its `inputs` declare
16//! change; see the `session` module for the loop's shape.
17
18mod affected;
19mod cache;
20mod event;
21mod scheduler;
22mod session;
23mod watch;
24
25pub use affected::{Selection, affected, select};
26pub use cache::CacheOptions;
27pub use event::{BeamStatus, RunEvent, RunSummary};
28pub use scheduler::{Executors, RunOptions, Targets, run};
29pub use session::{SessionCommand, session};
30pub use watch::{NotifyWatcher, SessionError, WatchBatch, WatchExit, Watcher, beamfile_dir, watch};
31
32use alba_core::{BeamId, CoreError};
33
34/// Something that stopped Alba from running the beams as asked.
35///
36/// Deliberately *not* how a failing beam is reported: a command that exits
37/// non-zero — or that could not be spawned at all — is an expected outcome
38/// of a run and lands in [`RunSummary::failed`]. An `EngineError` means the
39/// run could not be carried out at all, and is what the CLI turns into its
40/// exit code 2.
41#[derive(Debug, thiserror::Error)]
42pub enum EngineError {
43    /// The project could not answer a question the engine asked of it:
44    /// today, only an unknown target beam. Carries the span and source
45    /// file the CLI needs to point at the offending Beamfile. A `run`/`env`
46    /// template that fails to render at schedule time is deliberately not
47    /// one of these — it is the failure of the beam that declared it.
48    #[error(transparent)]
49    Core(#[from] CoreError),
50    /// The run cannot be scheduled as requested: a beam using an executor
51    /// Alba does not implement yet, or parameters that do not match what
52    /// the target beam declares. Detected before any beam starts.
53    #[error("{0}")]
54    Unschedulable(String),
55    /// A beam's task panicked, which can only be a bug in the engine or in
56    /// an `Executor` implementation. Reported rather than unwrapped, so
57    /// one broken beam cannot take the whole run down silently.
58    #[error("beam `{}` panicked while running", beam.0)]
59    Panicked { beam: BeamId },
60    /// Git could not answer the question an affected run asked it: git is
61    /// missing, this is not a repository, the reference does not exist.
62    #[error("{0}")]
63    Git(#[from] alba_core::git::GitError),
64}
alba_engine/lib.rs

alba_engine/
lib.rs
