solti/lib.rs
1//! # solti
2//!
3//! Feature and namespace façade for the modular Solti SDK.
4//! It contains no runtime logic.
5//! Features select component crates and expose them under stable namespaces.
6//!
7//! Use this crate when an agent binary needs several SDK components.
8//! Depend on a component crate directly when one component is enough.
9//!
10//! ## Start Here
11//!
12//! 1. Choose the capabilities required by the binary.
13//! 2. Enable their `solti` features.
14//! 3. Import each component through its namespace.
15//! 4. Build and own the application runtime.
16//!
17//! All features are disabled by default.
18//! Higher-level features enable their required lower layers.
19//!
20//! ## Feature Flow
21//!
22//! ```text
23//! application features
24//! ▼
25//! solti
26//! ├── model ─────────────► solti-model + JSON Schema
27//! ├── runner ────────────► solti-runner + model + taskvisor
28//! ├── core ──────────────► solti-core + runner + taskvisor/controller
29//! ├── exec-* ────────────► solti-exec integrations
30//! ├── api-* ─────────────► solti-api transports and adapters
31//! ├── discover-* ────────► solti-discover transports
32//! ├── observe-* ─────────► solti-observe integrations
33//! ├── prometheus-* ──────► solti-prometheus integrations
34//! └── tls ───────────────► solti-tls
35//! ```
36//!
37//! Component crates never depend on this façade.
38//! The façade preserves their ownership boundaries.
39//!
40//! ## Choose Features
41//!
42//! | Need | Feature family |
43//! |------------------------------|-------------------------|
44//! | Resource types and schemas | `model` |
45//! | Runner registration | `runner` |
46//! | Desired-state supervision | `core` |
47//! | Host process controls | `exec-host-process` |
48//! | Subprocess execution | `exec-subprocess` |
49//! | Container engine boundary | `exec-container` |
50//! | Native containerd 2.x | `exec-containerd` |
51//! | Seccomp host process filter | `exec-seccomp` |
52//! | HTTP task API | `api-http` |
53//! | gRPC task API | `api-grpc` |
54//! | Core API adapter | `api-core-adapter` |
55//! | gRPC server TLS | `api-grpc-tls` |
56//! | HTTP discovery | `discover-http` |
57//! | gRPC discovery | `discover-grpc` |
58//! | Discovery TLS | `discover-tls` |
59//! | Logging integrations | `observe-*` |
60//! | Prometheus integrations | `prometheus-*` |
61//! | Shared TLS types | `tls` |
62//! | Taskvisor integrations | `taskvisor-*` |
63//!
64//! `exec-seccomp` enables the low-level host process filter.
65//! Combine it with `exec-subprocess` to filter subprocess attempts.
66//! `exec-container` exposes the engine-neutral container runner.
67//! `exec-containerd` adds the native containerd 2.x adapter.
68//!
69//! `api-http` and `api-grpc` expose transports.
70//! They do not enable `solti-core`.
71//! Add `api-core-adapter` when the API delegates to `core::SupervisorApi`.
72//!
73//! `discover-http` and `discover-grpc` select the outbound discovery transport.
74//! They do not select the task API exposed by the agent.
75//!
76//! `model` includes the `solti-model/schema` feature.
77//! The `full` feature enables the complete standard integration set.
78//!
79//! ## Namespaces
80//!
81//! | Namespace | Component crate |
82//! |----------------|-----------------------|
83//! | `api` | `solti-api` |
84//! | `core` | `solti-core` |
85//! | `discover` | `solti-discover` |
86//! | `exec` | `solti-exec` |
87//! | `model` | `solti-model` |
88//! | `observe` | `solti-observe` |
89//! | `prometheus` | `solti-prometheus` |
90//! | `runner` | `solti-runner` |
91//! | `taskvisor` | `taskvisor` |
92//! | `tls` | `solti-tls` |
93//!
94//! A namespace exists only when its owning feature is enabled.
95//! Re-exported APIs keep their component-crate paths below that namespace.
96//!
97//! ## Quick Start
98//!
99//! Enable only the components used by the binary:
100//!
101//! ```toml
102//! [dependencies]
103//! solti = { version = "0.0.3", features = [
104//! "api-core-adapter",
105//! "api-http",
106//! "exec-subprocess",
107//! ] }
108//! ```
109//!
110//! Use the canonical namespaces:
111//!
112//! ```rust,no_run
113//! # #[cfg(all(feature = "core", feature = "exec-subprocess"))]
114//! # async fn build() -> Result<solti::core::SupervisorApi, Box<dyn std::error::Error>> {
115//! use solti::core::SupervisorApi;
116//! use solti::exec::subprocess::register_subprocess_runner;
117//! use solti::runner::RunnerRouter;
118//!
119//! let mut router = RunnerRouter::new();
120//! register_subprocess_runner(&mut router, "default")?;
121//!
122//! let supervisor = SupervisorApi::builder(router).start().await?;
123//! # Ok(supervisor)
124//! # }
125//! ```
126
127#![forbid(unsafe_code)]
128#![warn(missing_docs)]
129#![cfg_attr(docsrs, feature(doc_cfg))]
130
131/// Compiles the runnable Rust code blocks in `README.md` as doctests.
132#[cfg(doctest)]
133#[doc = include_str!("../README.md")]
134struct ReadmeDoctests;
135
136/// Task API types from `solti-api`.
137#[cfg(feature = "api")]
138#[cfg_attr(docsrs, doc(cfg(feature = "api")))]
139pub use solti_api as api;
140
141/// Desired-state supervisor types from `solti-core`.
142#[cfg(feature = "core")]
143#[cfg_attr(docsrs, doc(cfg(feature = "core")))]
144pub use solti_core as core;
145
146/// Agent discovery types from `solti-discover`.
147#[cfg(feature = "discover")]
148#[cfg_attr(docsrs, doc(cfg(feature = "discover")))]
149pub use solti_discover as discover;
150
151/// Execution integrations from `solti-exec`.
152#[cfg(feature = "exec")]
153#[cfg_attr(docsrs, doc(cfg(feature = "exec")))]
154pub use solti_exec as exec;
155
156/// Resource and domain types from `solti-model`.
157#[cfg(feature = "model")]
158#[cfg_attr(docsrs, doc(cfg(feature = "model")))]
159pub use solti_model as model;
160
161/// Observability integrations from `solti-observe`.
162#[cfg(feature = "observe")]
163#[cfg_attr(docsrs, doc(cfg(feature = "observe")))]
164pub use solti_observe as observe;
165
166/// Prometheus integrations from `solti-prometheus`.
167#[cfg(feature = "prometheus-base")]
168#[cfg_attr(docsrs, doc(cfg(feature = "prometheus-base")))]
169pub use solti_prometheus as prometheus;
170
171/// Runner contracts and routing from `solti-runner`.
172#[cfg(feature = "runner")]
173#[cfg_attr(docsrs, doc(cfg(feature = "runner")))]
174pub use solti_runner as runner;
175
176/// Task supervision types from `taskvisor`.
177#[cfg(feature = "taskvisor")]
178#[cfg_attr(docsrs, doc(cfg(feature = "taskvisor")))]
179pub use taskvisor;
180
181/// TLS and mTLS configuration types from `solti-tls`.
182#[cfg(feature = "tls")]
183#[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
184pub use solti_tls as tls;