sidecar_markers

Module: sidecar_markers

Contents

Structs

• MetadataFile - On-disk schema of <runtime>/run/<sandbox_id>/metadata.toml.
• SidecarEntry - One row of firma sidecar status. Serialized verbatim by --json.

Functions

• gc_stale - Remove every stale marker dir under <runtime>/run. Returns the
• get - Probe a single sidecar by sandbox_id. Returns Ok(None) when no such
• list - List all live per-run sidecars under <runtime>/run, GC’ing stale
• probe_entry - Read + probe a single marker directory.

---

firma_stack::sidecar_markers::MetadataFile

Struct

On-disk schema of <runtime>/run/<sandbox_id>/metadata.toml. Mirror of firma-run::sidecar::metadata::Metadata.

Fields:

• sandbox_id: String - Sandbox identifier for this run.
• agent_id: String - Agent identifier for this run.
• session_id: String - Session identifier for this run.
• authority_url: String - URL of the authority that issued the capability tokens for this run.
• policy_bundle_version: String - Policy bundle version digest string, as written by firma-run at startup.
• pid: u32 - PID of the sidecar process.
• started_at: String - RFC 3339 UTC timestamp of when the sidecar process started.

Trait Implementations:

• Deserialize
  • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
• Clone
  • fn clone(self: &Self) -> MetadataFile
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_stack::sidecar_markers::SidecarEntry

Struct

One row of firma sidecar status. Serialized verbatim by --json.

Fields:

• sandbox_id: String - Sandbox identifier for this run.
• agent_id: String - Agent identifier for this run.
• session_id: String - Session identifier for this run.
• authority_url: String - URL of the authority that issued the capability tokens for this run.
• policy_bundle_version: String - Policy bundle version digest string.
• pid: u32 - PID of the sidecar process.
• started_at: String - RFC 3339 UTC timestamp of when the sidecar process started.
• state: crate::status::State - Coarse-grained liveness state derived from pid + socket probes.
• listen: std::path::PathBuf - Path to the sidecar’s listen socket (<marker_dir>/sidecar.sock).
• uptime_secs: Option<u64> - Seconds since sidecar.pid was written in the marker directory, used as a proxy for sidecar start time. None if the file is absent or its mtime is in the future.

Trait Implementations:

• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• Clone
  • fn clone(self: &Self) -> SidecarEntry
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_stack::sidecar_markers::gc_stale

Function

Remove every stale marker dir under <runtime>/run. Returns the sandbox ids removed, sorted. Missing run/ is not an error.

Errors

Returns [crate::error::StackError::Io] if the run/ dir exists but cannot be enumerated.

fn gc_stale(runtime_dir: &std::path::Path) -> crate::error::Result<Vec<String>>

firma_stack::sidecar_markers::get

Function

Probe a single sidecar by sandbox_id. Returns Ok(None) when no such marker dir exists.

Errors

Returns a parse or I/O error from [probe_entry] when the marker exists but is malformed.

fn get(runtime_dir: &std::path::Path, sandbox_id: &str) -> crate::error::Result<Option<SidecarEntry>>

firma_stack::sidecar_markers::list

Function

List all live per-run sidecars under <runtime>/run, GC’ing stale marker dirs as a side effect. Sorted by sandbox_id.

Corrupt or transiently-missing markers (race away between readdir and open, or with an unparseable metadata.toml) are skipped so that one bad marker does not break the full listing. Use [get] when you need an error surfaced for a specific sandbox id.

Errors

Returns [crate::error::StackError::Io] if run/ exists but cannot be enumerated, or any I/O error other than NotFound from [probe_entry].

fn list(runtime_dir: &std::path::Path) -> crate::error::Result<Vec<SidecarEntry>>

firma_stack::sidecar_markers::probe_entry

Function

Read + probe a single marker directory.

This is the lower-level single-marker primitive used by [list] and [get]. It is pub for module-level integration tests but is not re-exported at the crate root.

Errors

Returns [crate::error::StackError::Io] when metadata.toml cannot be read and [crate::error::StackError::MarkerParse] on parse failure (fail-closed: an unreadable marker is surfaced, never silently treated as healthy).

fn probe_entry(marker_dir: &std::path::Path) -> crate::error::Result<SidecarEntry>