Crate lightshuttle_control 

Local HTTP control plane and dashboard for LightShuttle.

This crate is the developer-facing control surface that runs alongside the LightShuttle orchestrator. It depends on lightshuttle_runtime for the lightshuttle_runtime::LifecycleHandle trait and the resource view types, and adds an HTTP layer on top: a REST API, WebSocket streams for logs and lifecycle events, Prometheus metrics, and an SSR dashboard built with Askama and HTMX.

Crate layout

Public item	Role
ControlState	Shared axum state (project name + lifecycle handle + metrics)
ControlServer	HTTP server wrapping an axum router
bind	Async helper to open a TcpListener before building the server
Metrics	Prometheus recorder and scrape renderer
observe_event_duration	Record a lifecycle-event duration histogram sample
ApiError / ApiErrorBody	HTTP error type returned by every REST handler

Security note

The control plane is designed for local development only. It carries no authentication and the caller is expected to bind it to the loopback address (127.0.0.1). Never expose this server on a non-loopback interface or in a shared or production environment.

Quick start

use std::net::SocketAddr;
use lightshuttle_control::{ControlState, ControlServer, Metrics, bind};

#[tokio::main]
async fn main() -> std::io::Result<()> {
    // Bind to loopback only. The control plane has no authentication.
    let addr: SocketAddr = "127.0.0.1:9090".parse().unwrap();
    let listener = bind(addr).await?;

    let metrics = std::sync::Arc::new(Metrics::install());
    let state = ControlState::with_metrics("my-project", MyHandle, metrics);
    let server = ControlServer::new(state);

    server.serve(listener, async { /* await shutdown signal */ }).await
}

Structs

ApiError

HTTP error type returned by every control-plane REST handler.

ApiErrorBody

Wire representation of an API error body, serialised as JSON.

ControlServer

HTTP server that hosts the control plane router.

ControlState

Shared state injected into every route of the control plane.

Metrics

Prometheus metrics handle for the control plane.

Functions

bind

Open a TCP listener that will be passed to ControlServer::serve.

observe_event_duration

Record a sample in the lightshuttle_lifecycle_event_duration_seconds histogram.