frame-core 0.3.0

//! Typed registration and lifecycle failures.

use beamr::scheduler::MailboxSendError;
use serde::{Deserialize, Serialize};
use thiserror::Error;

use crate::capability::{Capability, CapabilityRequest, ScopeValidationError};
use crate::component::ComponentId;
use crate::event::LifecycleState;

/// Stable classification of a beamr process tombstone.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub enum TombstoneKind {
    /// Process completed normally.
    Normal,
    /// Host requested an untrappable kill.
    Kill,
    /// Process observed a kill and terminated.
    Killed,
    /// Runtime execution failed.
    Error,
    /// A linked distributed node disconnected.
    NoConnection,
    /// A link targeted a process that was already absent.
    NoProcess,
}

/// Observable reason a component entered [`LifecycleState::Failed`].
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct FailureReason {
    /// Child associated with the failure, if a child had been identified.
    pub child: Option<String>,
    /// Tombstone observed for the failing process, when one existed.
    pub tombstone: Option<TombstoneKind>,
    /// Runtime detail; rich exception information is intentionally optional.
    pub detail: String,
}

/// A typed refusal or runtime failure from the component registry.
#[derive(Debug, Error)]
pub enum RegistryError {
    /// Registration attempted to reuse a stable identity.
    #[error("component {id} is already registered")]
    DuplicateComponent {
        /// Conflicting stable identity.
        id: ComponentId,
    },
    /// A declared dependency was not in the registration table.
    #[error("component {component} requires missing component {required}")]
    MissingDependency {
        /// Component being registered.
        component: ComponentId,
        /// Missing edge target.
        required: ComponentId,
    },
    /// A dependency edge would make the graph cyclic.
    #[error("dependency edge {component} -> {required} creates a cycle")]
    CyclicDependency {
        /// Source of the cyclic edge.
        component: ComponentId,
        /// Target of the cyclic edge.
        required: ComponentId,
    },
    /// Two registered components claimed the same capability identifier.
    #[error("capability {capability} is already provided by component {provider}")]
    CapabilityConflict {
        /// Colliding service capability identifier.
        capability: String,
        /// Existing provider.
        provider: ComponentId,
    },
    /// A host-authority declaration used a malformed typed scope.
    #[error("component {component} declares invalid capability need {request:?}: {reason}")]
    InvalidCapabilityScope {
        /// Component being registered.
        component: ComponentId,
        /// Offending declaration.
        request: CapabilityRequest,
        /// Exact scope validation refusal.
        reason: ScopeValidationError,
    },
    /// An action declaration failed field validation (empty id, description,
    /// or schema source).
    #[error("component {component} action '{action}' declaration is invalid: {detail}")]
    InvalidActionDeclaration {
        /// Component being registered.
        component: ComponentId,
        /// Offending action id text (possibly empty — the offense itself).
        action: String,
        /// Exact field refusal.
        detail: String,
    },
    /// A component declared the same local action id twice.
    #[error("component {component} declares action id '{action}' more than once")]
    DuplicateActionId {
        /// Component being registered.
        component: ComponentId,
        /// Duplicate local id.
        action: String,
    },
    /// One action listed an exact capability requirement twice.
    #[error(
        "component {component} action '{action}' lists requirement {requirement:?} more than once"
    )]
    DuplicateActionRequirement {
        /// Component being registered.
        component: ComponentId,
        /// Action with the duplicate requirement.
        action: String,
        /// Duplicate requirement.
        requirement: Capability,
    },
    /// An action requires a capability its component never declared as a
    /// need — a permanently dead tool, refused at registration (F-6a R1).
    #[error(
        "component {component} action '{action}' requires {requirement:?} which is not among its declared needs"
    )]
    ActionRequirementUndeclared {
        /// Component being registered.
        component: ComponentId,
        /// Action naming the undeclared requirement.
        action: String,
        /// The requirement no declared need covers.
        requirement: Capability,
    },
    /// A fragment declaration failed field validation (empty id or kind).
    #[error("component {component} fragment '{fragment}' declaration is invalid: {detail}")]
    InvalidFragmentDeclaration {
        /// Component being registered.
        component: ComponentId,
        /// Offending fragment id text (possibly empty — the offense itself).
        fragment: String,
        /// Exact field refusal.
        detail: String,
    },
    /// A component declared the same local fragment id twice (F-5a R1's
    /// typed refusal; the whole batch is refused atomically).
    #[error("component {component} declares fragment id '{fragment}' more than once")]
    DuplicateFragmentId {
        /// Component being registered.
        component: ComponentId,
        /// Duplicate local id.
        fragment: String,
    },
    /// Fragment content exceeded the registry's caller-supplied byte limit
    /// (registration and content update validate identically — F-5a R2).
    #[error(
        "component {component} fragment '{fragment}' content is {size} bytes, over the configured max_fragment_bytes limit of {limit}"
    )]
    FragmentContentOversize {
        /// Declaring or updating component.
        component: ComponentId,
        /// Offending fragment id.
        fragment: String,
        /// Offered content size in bytes.
        size: usize,
        /// The caller-supplied limit in force.
        limit: usize,
    },
    /// Fragments were declared but the embedding host supplied no
    /// `max_fragment_bytes` — there is no hidden default limit (F-5a R1);
    /// the host states one in its lifecycle configuration or fragments are
    /// refused loudly.
    #[error(
        "component {component} declares fragments but the registry's lifecycle configuration carries no max_fragment_bytes limit"
    )]
    FragmentLimitUnconfigured {
        /// Component being registered.
        component: ComponentId,
    },
    /// A fragment act named a fragment id with no live entry in the
    /// authority — an undeclared local id (the ID set is static per
    /// incarnation, F-5a R2), or an internal invariant breach surfaced
    /// loudly rather than papered over.
    #[error("component {component} carries no live fragment '{fragment}'")]
    UnknownFragment {
        /// Component named by the act.
        component: ComponentId,
        /// The fragment id with no live entry.
        fragment: String,
    },
    /// A fragment act carried an incarnation that is not the live Running
    /// incarnation — the typed held-vs-current refusal (F-2a's rule applied
    /// to fragments, F-5a R2). `current` is absent when no incarnation is
    /// live (the component is not Running).
    #[error(
        "component {component} fragment '{fragment}' act holds incarnation {held:?} but the live incarnation is {current:?}"
    )]
    FragmentIncarnationStale {
        /// Component named by the act.
        component: ComponentId,
        /// Fragment named by the act.
        fragment: String,
        /// The incarnation the caller holds.
        held: crate::fragment::ComponentIncarnation,
        /// The live Running incarnation, absent when not Running.
        current: Option<crate::fragment::ComponentIncarnation>,
    },
    /// A manifest repeated an exact kind-and-scope pair.
    #[error("component {component} declares capability need {request:?} more than once")]
    DuplicateCapabilityNeed {
        /// Component being registered.
        component: ComponentId,
        /// Duplicate declaration.
        request: CapabilityRequest,
    },
    /// Registration omitted the mandatory restart intensity declaration.
    #[error("component {id} has no declared supervision intensity")]
    UndeclaredSupervision {
        /// Component missing the declaration.
        id: ComponentId,
    },
    /// A restart window of zero cannot define an intensity interval.
    #[error("component {id} declares a zero-length supervision window")]
    InvalidSupervisionWindow {
        /// Component with the invalid policy.
        id: ComponentId,
    },
    /// Child names are component-local unique keys.
    #[error("component {id} declares child name {child} more than once")]
    DuplicateChild {
        /// Component with the duplicate declaration.
        id: ComponentId,
        /// Duplicate child key.
        child: String,
    },
    /// The requested component is not registered.
    #[error("component {id} is not registered")]
    NotRegistered {
        /// Requested identity.
        id: ComponentId,
    },
    /// A start is already in flight for this identity.
    #[error("component {id} is already starting")]
    AlreadyStarting {
        /// Busy identity.
        id: ComponentId,
    },
    /// The component is already running.
    #[error("component {id} is already running")]
    AlreadyRunning {
        /// Running identity.
        id: ComponentId,
    },
    /// A stop is already in flight for this identity.
    #[error("component {id} is already stopping")]
    AlreadyStopping {
        /// Busy identity.
        id: ComponentId,
    },
    /// A remove is already in flight for this identity.
    #[error("component {id} is already being removed")]
    AlreadyRemoving {
        /// Busy identity.
        id: ComponentId,
    },
    /// A bytecode upgrade is already in flight for this identity.
    #[error("component {id} is already upgrading")]
    AlreadyUpgrading {
        /// Busy identity.
        id: ComponentId,
    },
    /// A bytecode upgrade was requested outside the stopped states.
    #[error(
        "component {id} bytecode upgrade requires Registered or Stopped, found {state:?}: \
         the upgrade barrier drains and stops the old incarnation before new bytes stage"
    )]
    UpgradeRequiresStopped {
        /// Requested identity.
        id: ComponentId,
        /// The state that refused the upgrade.
        state: LifecycleState,
    },
    /// A dependency exists but has not reached Running.
    #[error("component {component} requires {required} to be Running, found {state:?}")]
    DependencyNotRunning {
        /// Component whose start was refused.
        component: ComponentId,
        /// Required component.
        required: ComponentId,
        /// Observed dependency state.
        state: LifecycleState,
    },
    /// A running component still depends on the removal target.
    #[error("running component {dependent} depends on {required}")]
    RunningDependent {
        /// Running dependent preventing removal.
        dependent: ComponentId,
        /// Requested removal target.
        required: ComponentId,
    },
    /// Hot-loaded bytecode carries `erlang:*` imports the scheduler composition
    /// left Deferred — dispatch would kill the process at first use.
    #[error(
        "component {id} module {module} defers built-in imports [{imports}]: the scheduler was \
         composed without a populated BIF registry; compose through \
         frame_core::composition::compose_scheduler, never bare Scheduler::with_services"
    )]
    DeferredBifImports {
        /// Component whose start was refused.
        id: ComponentId,
        /// Module whose committed import table carries the deferrals.
        module: String,
        /// Deferred imports in `erlang:name/arity` form.
        imports: String,
    },
    /// beamr refused or could not parse component bytecode.
    #[error("failed to load bytecode for component {id}: {detail}")]
    ModuleLoad {
        /// Component being started.
        id: ComponentId,
        /// beamr loader detail.
        detail: String,
    },
    /// A native supervisor or linked child could not be spawned.
    #[error("failed to spawn {process} for component {id}: {detail}")]
    Spawn {
        /// Component being started or restarted.
        id: ComponentId,
        /// Supervisor or child name.
        process: String,
        /// beamr spawn detail.
        detail: String,
    },
    /// A child did not answer its declared mailbox probe in time.
    #[error("component {id} child {child} liveness probe timed out")]
    LivenessTimeout {
        /// Component being started or probed.
        id: ComponentId,
        /// Child that did not answer.
        child: String,
    },
    /// Start failed after entering Starting; status remains Failed.
    #[error("component {id} failed during start: {reason:?}")]
    StartFailed {
        /// Failed identity.
        id: ComponentId,
        /// Observable reason retained in status.
        reason: FailureReason,
    },
    /// Ordered stop observed a non-normal or missing tombstone.
    #[error("component {id} failed during ordered stop: {reason:?}")]
    StopFailed {
        /// Component being stopped.
        id: ComponentId,
        /// Exact observed failure.
        reason: FailureReason,
    },
    /// A retained old module generation could not be safely purged.
    #[error("failed to purge module {module} for component {id}: {detail}")]
    ModulePurge {
        /// Component being removed.
        id: ComponentId,
        /// Module display name.
        module: String,
        /// beamr purge detail.
        detail: String,
    },
    /// The current module generation was absent when removal expected it.
    #[error("module {module} for component {id} was not present during delete")]
    ModuleDelete {
        /// Component being removed.
        id: ComponentId,
        /// Module display name.
        module: String,
    },
    /// Lookup still found code after deletion.
    #[error("module {module} for component {id} remained visible after delete")]
    ModuleStillLoaded {
        /// Component being removed.
        id: ComponentId,
        /// Module display name.
        module: String,
    },
    /// beamr refused a typed host command at supervisor mailbox admission.
    #[error("component {id} supervisor {command} command delivery failed: {source}")]
    CommandDelivery {
        /// Affected component.
        id: ComponentId,
        /// Stable command kind whose delivery was attempted.
        command: &'static str,
        /// Exact beamr mailbox admission refusal.
        #[source]
        source: MailboxSendError,
    },
    /// Host/supervisor mailbox protocol was violated.
    #[error("component {id} supervisor protocol failed: {detail}")]
    SupervisorProtocol {
        /// Affected component.
        id: ComponentId,
        /// Protocol detail.
        detail: String,
    },
    /// Internal synchronization was poisoned by a panic.
    #[error("component registry synchronization is poisoned")]
    SynchronizationPoisoned,
    /// A component monitor thread terminated without returning its result.
    #[error("component {id} monitor thread terminated unexpectedly")]
    MonitorTerminated {
        /// Component whose monitor was lost.
        id: ComponentId,
    },
}