sidecar_markers

Module: sidecar_markers

Contents

Structs

• MetadataFile - On-disk schema of <runtime>/run/<sandbox_id>/metadata.toml.
• SidecarEntry - Observed state of one persisted per-run sidecar marker.

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 readable per-run sidecars under <runtime>/run, sorted by
• probe_entry - Read + probe a single marker directory.
• publish - Publish a consistent sidecar marker generation in marker_dir.
• read - Read and validate metadata.toml from one marker directory.

---

firma_runtime_state::sidecar_markers::MetadataFile

Struct

On-disk schema of <runtime>/run/<sandbox_id>/metadata.toml.

Fields:

• sandbox_id: firma_identifiers::SandboxId - 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: crate::process_id::UserProcessId - PID of the sidecar process.
• started_at: String - RFC 3339 UTC timestamp of when the sidecar process started.
• listen: String - Interceptor listen endpoint to health-probe: a host:port pair for an

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
• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>

firma_runtime_state::sidecar_markers::SidecarEntry

Struct

Observed state of one persisted per-run sidecar marker.

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: Option<crate::process_id::UserProcessId> - PID of the sidecar process, when known.
• 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 - Interceptor listen endpoint: a TCP host:port value or Unix-domain socket path.
• 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_runtime_state::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::RuntimeStateError::Io] if the run/ dir exists but cannot be enumerated.

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

firma_runtime_state::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: &firma_identifiers::SandboxId) -> crate::error::Result<Option<SidecarEntry>>

firma_runtime_state::sidecar_markers::list

Function

List all readable per-run sidecars under <runtime>/run, 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. This operation is observational; callers that want to delete stale markers must invoke [gc_stale] explicitly.

Errors

Returns [crate::error::RuntimeStateError::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_runtime_state::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::RuntimeStateError::Io] when metadata.toml cannot be read and [crate::error::RuntimeStateError::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>

firma_runtime_state::sidecar_markers::publish

Function

Publish a consistent sidecar marker generation in marker_dir.

Publication and stale collection hold the same process-shared namespace lock. metadata.toml, which is authoritative for liveness, is committed before the ancillary PID file. Both files are flushed and renamed from temporary files in the marker directory.

Errors

Returns serialization, locking, or filesystem errors. A failure after the metadata commit may leave a stale or absent PID file, which only suppresses the observational uptime value.

fn publish(marker_dir: &std::path::Path, metadata: &MetadataFile) -> crate::error::Result<()>

firma_runtime_state::sidecar_markers::read

Function

Read and validate metadata.toml from one marker directory.

Errors

Returns an I/O or parse error, or an identity-mismatch error when the metadata’s sandbox ID differs from the marker directory name.

fn read(marker_dir: &std::path::Path) -> crate::error::Result<MetadataFile>