Crate lightshuttle_runtime 

Container runtime backends and lifecycle manager for LightShuttle.

Crate placement in the stack

lightshuttle-spec      (domain types, ContainerSpec)
lightshuttle-manifest  (YAML parsing, interpolation)
        |
lightshuttle-runtime   <-- this crate
        |
lightshuttle-control   (REST/HTTP control plane)
lightshuttle-otel      (OpenTelemetry instrumentation)

This crate depends on lightshuttle-spec (for ContainerSpec and related domain types) and lightshuttle-manifest (for parsed manifests fed into LifecyclePlan::from_manifest). It is consumed by lightshuttle-control (the control plane) and lightshuttle-otel.

Core abstractions

ContainerRuntime trait

The narrow abstraction that hides every daemon-specific detail. The lifecycle manager calls only the methods declared by this trait. DockerRuntime is the first concrete implementation, backed by the bollard crate. Tests and downstream crates use testkit::MockRuntime as a drop-in replacement that requires no Docker daemon.

LifecyclePlan

Computed from a parsed manifest by LifecyclePlan::from_manifest. Performs a topological sort (Kahn’s algorithm) over the declared depends_on graph so the manager can start independent branches in parallel and block each resource until its dependencies are ready.

LifecycleManager

Orchestrates the full up and down lifecycle:

1. Starts every resource in topological order, independent branches in parallel, via tokio::spawn.
2. Waits for each container to pass its healthcheck (or to reach ContainerStatus::Running when no healthcheck is declared).
3. Publishes LifecycleEvent on a broadcast channel so the CLI, dashboard, and REST layer can observe progress.
4. On SIGINT or SIGTERM (see LifecycleManager::run_until_signal), stops all resources in reverse topological order, sends SIGTERM and then SIGKILL after the configured grace window, and tears down the per-project bridge network.

Quick start (no Docker daemon)

use std::collections::HashMap;
use std::time::Duration;

use lightshuttle_manifest::Manifest;
use lightshuttle_runtime::{LifecyclePlan, LifecycleManager, DockerRuntime};

let yaml = r#"
project:
  name: myapp
resources:
  db:
    postgres:
      version: "16"
"#;

let manifest = Manifest::parse(yaml)?;
let plan = LifecyclePlan::from_manifest(&manifest)?;
let runtime = DockerRuntime::connect()?;
let (manager, _events) = LifecycleManager::new(plan, runtime);

// Blocks until SIGINT/SIGTERM, then tears the stack down cleanly.
manager.run_until_signal(Duration::from_secs(30)).await?;

See docs/spec/manifest-v0.md in the main repository for the full manifest specification.

Modules

testkit

In-memory ContainerRuntime and supporting helpers for tests.

Structs

ContainerId

Opaque identifier for a container managed by the runtime.

ContainerSpec

Self-contained description of a container to start, derived from a manifest resource declaration.

DockerRuntime

Docker container runtime backed by the bollard crate.

EnvReport

Report over every ${env.*} reference found in a plan’s environment values and command arguments.

EnvVarReport

One referenced variable together with its resolution status.

HealthcheckSpec

Healthcheck resolved from the manifest, with duration strings already parsed into std::time::Duration values.

LifecycleManager

Coordinates the startup, supervision, and shutdown of every resource declared in a LifecyclePlan.

LifecyclePlan

Topologically sorted execution plan.

LogChunk

One chunk of streamed log output.

ManagedContainer

One entry returned by DockerRuntime::list_managed.

ManagerHandle

Newtype adapter turning an Arc<LifecycleManager<R>> into a LifecycleHandle.

PlanNode

A single resource to manage, with its resolved ContainerSpec, its exposed outputs and its explicit dependencies.

PortBinding

Host-to-container port binding resolved from the manifest.

ResolvedResource

A ContainerSpec bundled with the ResourceOutputs the resource exposes to its dependents at runtime.

ResourceView

Dashboard-friendly view of a single managed resource.

VolumeBinding

Volume or bind-mount mapping resolved from the manifest.

Enums

ContainerStatus

Lifecycle status reported by the runtime when inspecting a container.

EnvSource

Where a resolved variable’s effective value comes from.

EnvVarStatus

Resolution status of a single referenced environment variable.

ImageSource

How the container image is obtained.

LifecycleError

Errors raised by the lifecycle layer.

LifecycleEvent

Event emitted by crate::LifecycleManager for consumption by a CLI, dashboard or test harness.

LifecycleHandleError

Errors returned by LifecycleHandle operations.

LogStream

Which stream a log chunk came from.

NodeStatus

Lifecycle status of a single managed resource.

ResourceStatus

Coarse-grained resource status, derived from NodeStatus and flattened for UI consumption.

RuntimeError

Errors raised by a crate::ContainerRuntime implementation.

SpecError

Errors raised while building a crate::ContainerSpec from a manifest resource declaration.

VolumeSource

Origin of the content mounted into the container.

Constants

LABEL_PROJECT

Docker label key set on every container managed by LightShuttle to carry the manifest project name.

LABEL_RESOURCE

Docker label key set on every container to carry the manifest resource name.

Traits

ContainerRuntime

Container runtime abstraction.

LifecycleHandle

Control-plane facing view of a running stack.

Functions

from_resource

Resolve a manifest resource declaration into a ResolvedResource.

Type Aliases

LogChunkStream

Boxed, pinned stream of LogChunk items for a single container.

ResourceOutputs

Key/value properties that a managed resource exposes to its dependents.

Result

Shorthand alias for std::result::Result<T, RuntimeError>.