Skip to content
OpenFirma OpenFirma
Blog

error

Module: error

Section titled “Module: error”

Contents

Section titled “Contents”

Enums

  • OrchestratorError - Error type returned by process orchestration operations in this crate.
  • ShutdownError - Failure returned when shutting down an in-process owned stack.
  • StartError - Distinguishes caller-owned plan resolution failures from orchestration failures.

firma_process_orchestrator::error::OrchestratorError

Section titled “firma_process_orchestrator::error::OrchestratorError”

Enum

Error type returned by process orchestration operations in this crate.

All variants carry enough context to be rendered as a single-line operator-facing message. Callers should generally print format!("{err}") and exit non-zero rather than introspect variants.

Variants:

  • InvalidComponentName{ name: String } - A component name cannot safely identify runtime-state files.
  • DuplicateComponentName{ name: String } - A topology contains the same component name more than once.
  • PlanCountMismatch{ expected: usize, actual: usize } - A resolved plan does not contain exactly one spec per topology component.
  • StateDir(firma_fs::CreatePrivateDirError) - Creating or securing the state directory failed.
  • RuntimeState(firma_runtime_state::RuntimeStateError) - Reading or writing shared runtime state failed.
  • AlreadyRunning{ path: std::path::PathBuf } - Another supervisor already holds the stack lock for this state dir.
  • RuntimeStateBusy{ path: std::path::PathBuf } - Runtime-state cleanup could not acquire serialization without blocking.
  • InvalidStackGeneration{ source: uuid::Error } - The persisted [crate::StackGeneration] is present but malformed.
  • Spawn{ component: String, source: io::Error } - Spawning a child component failed.
  • Readiness{ component: String, timeout_secs: u64 } - A component did not become ready within the configured timeout.
  • ReadinessProcessExited{ component: String, status: std::process::ExitStatus } - A component exited while startup was waiting for it to become ready.
  • TerminationTimeout{ timeout_secs: u64 } - One or more process targets remained present after forced termination.
  • Rollback{ operation: Box<Self>, rollback: Box<Self> } - A startup operation failed and its required rollback also failed.
  • Io(io::Error) - Generic I/O error not classified by a more specific variant.
  • Platform(String) - OS-level failure surfaced from platform_unix / platform_windows

Trait Implementations:

  • From
    • fn from(source: io::Error) -> Self
  • From
    • fn from(source: firma_runtime_state::RuntimeStateError) -> Self
  • Display
    • fn fmt(self: &Self, __formatter: & mut ::core::fmt::Formatter) -> ::core::fmt::Result
  • Error
    • fn source(self: &Self) -> ::core::option::Option<&dyn ::thiserror::__private18::Error>
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_process_orchestrator::error::ShutdownError

Section titled “firma_process_orchestrator::error::ShutdownError”

Enum

Failure returned when shutting down an in-process owned stack.

The variants distinguish uncertain process teardown from failures that occur after every process target is confirmed absent. Callers that own dependencies of the stack must retain them only for [Self::TeardownUncertain].

Variants:

  • TeardownUncertain(OrchestratorError) - One or more process targets may still be live or uncollected.
  • StateCleanup(OrchestratorError) - All process targets are absent, but durable runtime-state cleanup failed.

Methods:

  • fn processes_stopped(self: &Self) -> bool - Whether all owned process targets were confirmed absent.
  • fn into_orchestrator_error(self: Self) -> OrchestratorError - Discard the shutdown phase while preserving the underlying error.

Trait Implementations:

  • Display
    • fn fmt(self: &Self, __formatter: & mut ::core::fmt::Formatter) -> ::core::fmt::Result
  • Error
    • fn source(self: &Self) -> ::core::option::Option<&dyn ::thiserror::__private18::Error>
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_process_orchestrator::error::StartError

Section titled “firma_process_orchestrator::error::StartError”

Enum

Distinguishes caller-owned plan resolution failures from orchestration failures.

Generic Parameters:

  • E

Variants:

  • Plan(E) - The caller’s plan resolver failed after the stack lock was acquired.
  • Orchestrator(OrchestratorError) - Generic process orchestration failed.
  • Rollback{ operation: Box<Self>, rollback: Box<ShutdownError> } - Startup failed and explicit rollback also reported a failure.

Methods:

  • fn rollback_processes_stopped(self: &Self) -> Option<bool> - Whether a failed startup rollback confirmed all process targets absent.

Trait Implementations:

  • From
    • fn from(source: OrchestratorError) -> Self
  • Display
    • fn fmt(self: &Self, __formatter: & mut ::core::fmt::Formatter) -> ::core::fmt::Result
  • Error
    • fn source(self: &Self) -> ::core::option::Option<&dyn ::thiserror::__private18::Error>
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result