squib_api/lib.rs
1//! Firecracker-compatible HTTP API server for squib.
2//!
3//! `squib-api` exposes the same `OpenAPI` surface that upstream Firecracker speaks over
4//! a Unix domain socket: same paths, same JSON shapes, same status codes, same
5//! `{"fault_message": "..."}` error body, same `Server: Firecracker API` response
6//! header. Per-endpoint compatibility lives in
7//! [21-api-compat-matrix.md](../../specs/21-api-compat-matrix.md); the machinery is
8//! pinned in [20-firecracker-api.md](../../specs/20-firecracker-api.md).
9//!
10//! # Architecture
11//!
12//! - [`schemas`] — `Raw*` request/response shapes plus validated newtypes whose only construction
13//! path is via `TryFrom`. Per [10-data-model.md §
14//! 2.3](../../specs/10-data-model.md#23-schema-layer), validation is the constructor;
15//! "unvalidated `DriveConfig`" is unrepresentable.
16//! - [`action`] — the `ApiAction` / `ApiResponse` enum the API thread posts onto the bounded mpsc
17//! channel into the VMM event loop.
18//! - [`controller`] — the `RuntimeApiController` with `ArcSwap` read-mirror, lock-free read fast
19//! path, and per-action-class `tokio::time::timeout` (D26).
20//! - [`error`] — the wire-shape `FaultMessage`, `ApiError` (incl. squib-only 504), and the
21//! `IntoResponse` impl that translates everything into the upstream wire shape.
22//! - [`handlers`] — axum endpoint handlers for every Firecracker route.
23//! - [`server`] — axum router on `tokio::net::UnixListener` plus the `serve` entry.
24//! - [`replay`] — `--config-file` static-config replay path; deterministic order, identical
25//! validation/dispatch as the HTTP layer.
26
27#![forbid(unsafe_code)]
28#![warn(missing_docs)]
29
30pub mod action;
31pub mod controller;
32pub mod error;
33pub mod handlers;
34pub mod replay;
35pub mod schemas;
36pub mod server;
37
38pub use action::{ActionClass, ApiAction, ApiResponse};
39pub use controller::{
40 ActionReceiver, ActionSender, ControllerSnapshot, RuntimeApiController, TimeoutTable,
41};
42pub use error::{ApiError, FaultMessage, Result};
43pub use replay::{ReplayError, parse_config_file, replay_config};
44pub use schemas::{InstanceInfo, VersionResponse, VmState};
45pub use server::{
46 DEFAULT_MAX_PAYLOAD, FIRECRACKER_SERVER_HEADER, MAX_MAX_PAYLOAD, MIN_MAX_PAYLOAD, ServeOptions,
47 bind_listener, router, serve, serve_bound, unlink_socket_if_exists,
48};