Struct Instances 

pub struct Instances<E> { /* private fields */ }

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:

• project <workspace>_<env>_r<revision>: trestle names can’t contain _, so a project name parses back to its parts and reconcile tells instance projects from any other;
• host label <workspace>-<env>-r<revision> (demo-dev-r2.localhost);
• the slot the store leases the instance, host-wide.

The rendered tree lives in <state>/instances/<id>/ (owner-only) and is a cache, re-rendered from the revision on every start. It holds no credential: they reach Compose as process environment only (see MaterializedOutput::into_launch_env).

Implementations

impl<E: ComposeEngine> Instances<E>

pub fn new(store: Arc<Store>, engine: E, state_dir: impl Into<PathBuf>) -> Self

Run store’s instances on engine, materializing them under state_dir (<state_dir>/instances/<id>/). Secrets resolve with the env provider only until with_providers says otherwise.

pub fn with_providers(self, providers: SecretProviders) -> Self

Resolve secrets with providers (and no others).

pub fn with_source(self, source: impl Source + 'static) -> Self

Make source available to instances that name it.

pub fn without_port_probe(self) -> Self

Don’t check host ports before starting (tests on a shared host, a fake engine).

pub fn with_wait_timeout(self, timeout: Duration) -> Self

Give up waiting for health after timeout on start.

pub fn engine(&self) -> &E

The engine.

pub fn store(&self) -> &Store

The store.

pub fn dir(&self, id: &InstanceId) -> PathBuf

Where the instance’s tree is materialized.

pub fn placement( &self, id: &InstanceId, ) -> Result<RuntimePlacement, InstanceError>

Where the instance runs: its compose project, host label, mesh and slot. Leases it a slot if it has none.

pub async fn effective_env( &self, id: &InstanceId, ) -> Result<EffectiveEnv, InstanceError>

The instance’s environment, every variable with its provenance (see EffectiveEnv).

pub async fn materialize( &self, id: &InstanceId, ) -> Result<Materialized, InstanceError>

Render the instance into its directory, from scratch, and return what it launches with. The tree holds no credential.

pub async fn start( &self, id: &InstanceId, ) -> Result<Materialized, InstanceError>

Start the instance: lease it a slot (if it has none), check its host ports, render it afresh and up it, waiting for health. The store records it as wanted running first, so a crash mid-start is reconciled as running.

pub async fn stop( &self, id: &InstanceId, volumes: bool, ) -> Result<(), InstanceError>

Stop the instance (down, with its volumes when volumes), keeping its slot.

When a source fails (a Neon outage, say), the tree rendered at the last start is taken down without its launch env: Compose then interpolates the missing variables as empty, which down doesn’t mind, so a source never keeps an instance from stopping.

pub async fn remove( &self, id: &InstanceId, volumes: bool, ) -> Result<(), InstanceError>

Stop the instance if it runs, drop its tree, and delete it from the store (releasing its slot).

pub async fn health( &self, id: &InstanceId, ) -> Result<BTreeMap<String, Health>, InstanceError>

The health of each of the instance’s services (empty when it doesn’t run).

pub async fn events( &self, id: &InstanceId, ) -> Result<EngineStream<InstanceEvent>, InstanceError>

The instance’s events from now on: its containers’ lifecycle and health changes.

pub async fn reconcile( &self, opts: ReconcileOptions, ) -> Result<Reconciled, InstanceError>

Match what Docker runs against the store, after a restart of the runtime: a running instance project is adopted (its instance marked running), an instance wanted running whose project is gone is marked stopped, and an instance-shaped project the store doesn’t know is an orphan (taken down with ReconcileOptions::remove_orphans).