Enum RuntimeError 

pub enum RuntimeError {
    Unavailable {
        message: String,
        target: Option<ActrId>,
    },
    DeadlineExceeded {
        message: String,
        timeout_ms: u64,
    },
    NotFound {
        actor_id: ActrId,
        message: String,
    },
    InvalidArgument(String),
    FailedPrecondition(String),
    PermissionDenied(String),
    DecodeFailure {
        message: String,
        raw_bytes: Option<Vec<u8>>,
    },
    Internal {
        message: String,
        panic_info: Option<String>,
    },
    MailboxError(String),
    ConfigurationError(String),
    InitializationError(String),
    ShutdownError(String),
    IoError(Error),
    JsonError(Error),
    ProtocolError(ProtocolError),
    Other(Error),
}

Runtime error types following gRPC-style classification

Error Classification

• Transient: Temporary failures, safe to retry (UNAVAILABLE, DEADLINE_EXCEEDED)
• Permanent: Require system state fix, do NOT retry (NOT_FOUND, INVALID_ARGUMENT)
• Poison: Corrupted messages requiring manual intervention (decode failures)

Design Philosophy

Unlike classic Actor systems (Erlang/Akka) that use Supervision trees, Actor-RTC treats each Actr as a microservice unit:

• Caller controls retry logic (not framework)
• Explicit error propagation (not transparent restart)
• Dead Letter Queue for poison messages

Variants

Unavailable

Service temporarily unavailable (gRPC UNAVAILABLE)

Transient: Connection lost, peer overloaded, temporary resource exhaustion Caller should: Retry with exponential backoff

Fields

message: String

target: Option<ActrId>

Optional target Actor ID

DeadlineExceeded

Request timeout exceeded (gRPC DEADLINE_EXCEEDED)

Transient: Network delay, peer slow response Caller should: Retry with longer timeout or give up

Fields

message: String

timeout_ms: u64

NotFound

Target Actor not found (gRPC NOT_FOUND)

Permanent: Actor not registered in signaling server Caller should: NOT retry, perform service discovery first

Fields

actor_id: ActrId

message: String

InvalidArgument(String)

Invalid argument provided (gRPC INVALID_ARGUMENT)

Permanent: Malformed request, validation failure Caller should: NOT retry, fix the request

FailedPrecondition(String)

Precondition not met (gRPC FAILED_PRECONDITION)

Permanent: System state incompatible with operation Caller should: NOT retry, fix system state first

PermissionDenied(String)

Permission denied (gRPC PERMISSION_DENIED)

Permanent: ACL check failed Caller should: NOT retry, check authorization

DecodeFailure

Protobuf decode failure

Poison: Corrupted message, cannot be processed Framework: Move to Dead Letter Queue, log raw bytes

Fields

message: String

raw_bytes: Option<Vec<u8>>

Raw bytes for manual analysis

Internal

Internal framework error (gRPC INTERNAL)

Severity: High - indicates framework bug or panic Framework: Log stack trace, capture panic info

Fields

message: String

panic_info: Option<String>

Panic info if caused by handler panic

MailboxError(String)

Mailbox operation error

Severity: Critical - SQLite database issue Framework: Trigger alert, may need manual intervention

ConfigurationError(String)

Configuration error

InitializationError(String)

Initialization error

ShutdownError(String)

Shutdown error

IoError(Error)

IO Error

JsonError(Error)

JSON Error

ProtocolError(ProtocolError)

Protocol Error

Other(Error)

Other error

Implementations

impl RuntimeError

pub fn classification(&self) -> ErrorClassification

Error classification for retry decision

Follows gRPC status code semantics:

• Transient: Safe to retry (UNAVAILABLE, DEADLINE_EXCEEDED)
• Permanent: Do NOT retry (NOT_FOUND, INVALID_ARGUMENT, etc.)
• Poison: Needs manual intervention (DecodeFailure)

pub fn is_retryable(&self) -> bool

Check if error is retryable (Transient classification)

Caller should use exponential backoff for retry.

pub fn requires_dlq(&self) -> bool

Check if error requires Dead Letter Queue

Poison messages cannot be processed and need manual intervention.

pub fn status_code(&self) -> &'static str

Get gRPC-style status code name

For logging and metrics (compatible with gRPC status codes).

pub fn severity(&self) -> u8

Get error severity (1-10, 10 is most critical)

Used for alerting thresholds and monitoring.

pub fn requires_system_shutdown(&self) -> bool

Check if error requires system shutdown

Only fatal configuration/initialization errors should shutdown.

pub fn category(&self) -> &'static str

Get error category for metrics

Used in Prometheus labels: errors_total{category="unavailable"}

Trait Implementations

impl Debug for RuntimeError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for RuntimeError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for RuntimeError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for RuntimeError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for RuntimeError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for RuntimeError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<NetworkError> for RuntimeError

fn from(err: NetworkError) -> Self

Converts to this type from the input type.

impl From<ProtocolError> for RuntimeError

fn from(source: ProtocolError) -> Self

Converts to this type from the input type.