Crate olai_stack_runtime 

Run trestle environments on Docker Compose.

olai_stack_topology plans and renders an environment without touching Docker; this crate is the part that runs it. The CLI and the desktop app share it.

• ComposeEngine: what the runtime asks of Compose (up, down, ls, ps, logs, events, network removal). DockerCli runs the docker CLI; FakeEngine (feature testing) is an in-memory stand-in for tests.
• Typed ProjectStatus, ServiceStatus / Health and EngineEvent, parsed from the CLI’s JSON output (the test fixtures are captured from real engines, see docs/runtime.md).
• probe_host_ports: whether a plan’s host ports are free before starting it.
• managed_projects and remove_mesh_if_idle: matching what Docker runs against what the caller manages.
• Instances: runs the revisions of an olai_stack_state::Store as compose projects, side by side, with the layered EffectiveEnv injected and credentials resolved by SecretProviders (EnvProvider, and KeychainProvider behind feature keychain) and Source overlays.

Values that must not reach a file (credentials) go to Compose as process environment only: every lifecycle call takes the variables to add (UpOptions::env).

use olai_stack_runtime::{ComposeEngine, DockerCli, UpOptions};

let docker = DockerCli::new();
let opts = UpOptions { wait: true, ..UpOptions::default() };
docker.up(std::path::Path::new("demo/dev"), &opts).await?;
for project in docker.ls().await? {
    println!("{}: {}", project.name, project.status);
}

Structs

BusyPort

A host port a plan binds that something on this host already holds.

DockerCli

Runs the docker CLI (with the Compose plugin). It honours DOCKER_HOST and the current Docker context like the CLI does; with_context pins one.

DownOptions

How to down a project.

EffectiveEnv

An instance’s resolved environment: every variable with its value and provenance. The same resolution feeds what a UI shows (masked) and what the instance launches with (launch_vars).

EngineEvent

One event about a container of a Compose project.

EnvLayers

The layers an EffectiveEnv is resolved from, each a map of variables. Build it with the with_* methods in any order; resolution applies Layer order.

EnvProvider

Secrets from this process’s environment: the key is a variable name. Named env.

FakeEnginetesting

An in-memory Docker: up creates a project with scripted services, down removes it, and both raise the events Docker would. Clones share state, so a test can hand one to the code under test and inspect another.

InstanceEvent

What happened to one service of an instance.

Instances

Runs the store’s instances on an engine. Each instance runs one revision in its own compose project, on its own slot and under its own host label, so two revisions of one environment run side by side:

KeychainProviderkeychain

Secrets in the OS credential store (macOS Keychain, Windows Credential Manager, the Linux kernel keyring), under one service name; the key is the account. Named keychain.

LogLine

One line a container logged.

LogOptions

How to read a project’s logs.

MaskedVar

One row of EffectiveEnv::masked.

Materialized

What Instances::materialize produced.

Overlay

What a Source contributes to an instance’s environment.

ProjectStatus

One Compose project Docker knows of (a row of docker compose ls --all).

Published

A host port a container publishes.

ReconcileOptions

How Instances::reconcile treats what it finds.

Reconciled

What Instances::reconcile found.

Resolved

A variable as resolved: its value, the layer it came from, and the lower layers it overrode (or, for a placement key, the layers that tried and were ignored).

SecretProviders

The providers a runtime resolves secrets with, by name. A reference to a provider that isn’t registered is an error: a missing keychain never silently falls back to another provider.

SecretValue

A secret’s value. Its Debug and Display print <redacted>.

ServiceStatus

One container of a project (a row of docker compose ps --all).

SourceCtx

What a source is asked for.

SourceError

Why a source failed.

UpOptions

How to up a project.

UserVars

The user’s own variables, as a source named user: literal values only (secrets belong in the store as references).

Enums

EnvValue

One variable’s value: plain, or a secret.

Error

What can go wrong driving a ComposeEngine.

EventAction

What happened to a container.

EventFilter

Which projects’ events to watch.

FakeCalltesting

One call the fake received, for assertions.

Health

A container’s health, as its healthcheck reports it.

InstanceError

What can go wrong running an instance.

Layer

Where a variable’s value comes from, lowest precedence first. A higher layer overrides a lower one, except over Placement, whose keys nothing overrides.

LayerValue

What one layer sets, before secrets are resolved.

Progress

Where a command’s progress output goes.

ProjectMatch

Which projects a caller manages.

SecretError

Why a secret couldn’t be resolved.

State

A container’s lifecycle state, as Docker reports it.

Constants

INSTANCES_DIR

The directory under the state directory instances are materialized into.

MASK

What a masked secret shows as.

PLACEMENT_KEYS

Keys the placement reserves in an instance’s environment: no layer overrides them.

PROJECT_LABEL

The label Compose puts on every container with its project’s name.

SERVICE_LABEL

The label Compose puts on every container with its service’s name.

Traits

ComposeEngine

Docker Compose, as the runtime drives it. DockerCli runs the real CLI; FakeEngine (feature testing) is an in-memory stand-in.

SecretProvider

Where secret values live. The store holds SecretRefs naming a provider and a key; the provider resolves them at launch.

Source

Something outside the store an instance takes variables, endpoints and credentials from, as an overlay on its environment (a Neon branch, say: its Postgres URL, its object-storage endpoint and vended keys, its function URLs). An instance names the sources it takes; they apply in that order, above the store’s vars and below the instance’s own overrides.

Functions

instance_project

The compose project of revision revision of env in workspace.

is_free

Whether port can be bound on every interface, as Docker publishes by default.

managed_projects

The projects Docker knows of (running or stopped) that which picks.

parse_event

Parse one line of docker events --format '{{json .}}'. Ok(None) for an event that isn’t about a Compose container, and for the exec_* events every healthcheck probe raises.

parse_instance_project

(workspace, env, revision) of an instance project name, if it is one.

parse_log_line

Parse one line of docker compose logs --timestamps --no-color, e.g. web-1 | 2026-11-02T19:55:16.807260250Z tick 1. A line without the <container> | prefix is kept whole as the text, with no container.

parse_ls

Parse docker compose ls --all --format json: a JSON array of projects.

parse_ps

Parse docker compose ps --all --format json. Compose prints one JSON object per line; some versions print a single JSON array instead, which is accepted too.

probe_host_ports

Every host port plan binds that can’t be bound right now, so a start can be refused before Compose fails half-way. A check, not a reservation: the port can be taken between the probe and the start.

remove_mesh_if_idle

Remove the shared network once none of members is known to Docker any more; returns whether it was removed.

Type Aliases

EngineStream

A stream of items from a long-running command; dropping it stops the command.

Result

The crate’s result type.