lightshuttle_spec/lib.rs
1//! Manifest-to-container specification resolution for LightShuttle.
2//!
3//! # Position in the layer graph
4//!
5//! `lightshuttle-spec` sits between the manifest parsing layer and the
6//! execution/export layer:
7//!
8//! ```text
9//! lightshuttle-manifest (parsing, typed resource declarations)
10//! |
11//! v
12//! lightshuttle-spec (THIS CRATE - resolution, defaults, outputs)
13//! |
14//! +-----+------+
15//! v v
16//! runtime export
17//! ```
18//!
19//! It depends on `lightshuttle-manifest` and is consumed by
20//! `lightshuttle-runtime` and `lightshuttle-export`. It does not depend
21//! on any container daemon, so both consumers share a single, consistent
22//! resolution without drift.
23//!
24//! # What resolution does
25//!
26//! The entry point is [`from_resource`]. Given a project name, a
27//! resource name, and a [`lightshuttle_manifest::ResourceKind`], it
28//! returns a [`ResolvedResource`] that bundles:
29//!
30//! - A [`ContainerSpec`]: the complete, self-contained description of
31//! the container to launch (image, env vars, ports, volumes,
32//! healthcheck).
33//! - A [`ResourceOutputs`] map: the key/value pairs exposed to
34//! dependent resources via `${resources.<name>.<key>}` interpolation
35//! and `LSH_*` environment variables.
36//!
37//! # Resolved outputs by resource kind
38//!
39//! | Kind | Keys |
40//! |---|---|
41//! | `postgres` | `host`, `port`, `database`, `user`, `password`, `url` |
42//! | `redis` | `host`, `port`, `password`, `url` |
43//! | `container` / `dockerfile` | `host`, `ports` (comma-separated) |
44//!
45//! # Errors
46//!
47//! Resolution fails with a [`SpecError`] when a port mapping, volume
48//! string, or healthcheck duration in the manifest is structurally
49//! invalid.
50
51#![deny(missing_docs)]
52
53mod error;
54mod spec;
55
56pub use crate::error::{Result, SpecError};
57pub use crate::spec::{
58 ContainerSpec, HealthcheckSpec, ImageSource, PortBinding, ResolvedResource, ResourceOutputs,
59 VolumeBinding, VolumeSource, from_resource,
60};