aion_toolchain/lib.rs
1//! Server-side Gleam authoring toolchain.
2//!
3//! This crate turns a running Aion engine into a Gleam authoring loop: it
4//! takes submitted workflow source, compiles and type-checks it, and — on
5//! success — packages a verified `.aion` archive ready to hot-load.
6//!
7//! # No embedded compiler (CN7 / C12 / C15)
8//!
9//! The toolchain embeds **no** Gleam compiler. It only ever spawns the
10//! external `gleam` binary (the caller supplies its path) and captures the
11//! compiler's output. Its entire dependency set is [`aion_package`] (the
12//! `.aion` format) plus `thiserror`; there is no Gleam compiler crate and no
13//! `beamr` in the tree. The `no_gleam_compiler_in_dependency_tree` integration
14//! test asserts this guarantee mechanically. Without the toolchain there is no
15//! way to compile Gleam on the server, which is exactly why the server-side
16//! authoring endpoints are gated on an explicit `gleam_path`.
17//!
18//! # Per-submission isolation
19//!
20//! [`compile_source`] treats the configured project root as a **read-only
21//! template**: each call stages its own throwaway working copy (a
22//! [`workspace::Workspace`]), writes and builds entirely within it, and removes
23//! it on drop. Concurrent submissions never share an entry-file, a `build/`
24//! directory, or a `.aion` output — no global lock and no pool-size cap.
25//!
26//! # Blocking
27//!
28//! [`compile_source`] is synchronous and blocks on staging the working copy,
29//! `gleam build`, and packaging, all of which can run for seconds. Async
30//! callers MUST wrap it in a blocking task (for example
31//! `tokio::task::spawn_blocking`).
32
33/// Core compile/type-check/package loop over the external `gleam` binary.
34pub mod compile;
35/// Toolchain error taxonomy.
36pub mod error;
37/// Project-root validation and entry-module source resolution.
38pub mod project;
39/// Per-submission isolated build workspace (RAII working copy of the template).
40pub mod workspace;
41
42pub use compile::{
43 CompileRequest, CompiledWorkflow, build_project, compile_source, compile_source_for_entry,
44};
45pub use error::ToolchainError;
46pub use workspace::Workspace;