Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -357,7 +357,8 @@ repos:
# - model_action_config_value.py: Action config value types
# - model_node_config_value.py: Node config entry and schema types
# - mixin_event_bus.py: Duck-typed Protocol defined alongside mixin that uses it
exclude: ^(tests/|archived/|archive/|scripts/validation/|src/omnibase_core/utils/util_singleton_holders\.py$|src/omnibase_core/models/core/model_action_config_value\.py$|src/omnibase_core/models/configuration/model_node_config_value\.py$|src/omnibase_core/mixins/mixin_event_bus\.py$|src/omnibase_core/protocols/)
# - mixin_health_check.py: Duck-typed Protocols (connection pools, clients) alongside health check mixin
exclude: ^(tests/|archived/|archive/|scripts/validation/|src/omnibase_core/utils/util_singleton_holders\.py$|src/omnibase_core/models/core/model_action_config_value\.py$|src/omnibase_core/models/configuration/model_node_config_value\.py$|src/omnibase_core/mixins/mixin_event_bus\.py$|src/omnibase_core/mixins/mixin_health_check\.py$|src/omnibase_core/protocols/)
stages: [pre-commit]

- id: validate-enum-model-imports
Expand Down
4 changes: 4 additions & 0 deletions src/omnibase_core/enums/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@
organized by functional domains for better maintainability.
"""

# Action status enum (OMN-1309)
from .enum_action_status import EnumActionStatus

# Architecture and system enums
from .enum_architecture import EnumArchitecture

Expand Down Expand Up @@ -372,6 +375,7 @@
"EnumValueType",
"EnumNumericValueType",
# Orchestrator domain (from nodes)
"EnumActionStatus",
"EnumActionType",
"EnumBranchCondition",
"EnumWorkflowState",
Expand Down
183 changes: 183 additions & 0 deletions src/omnibase_core/enums/enum_action_status.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,183 @@
# SPDX-FileCopyrightText: 2025 OmniNode Team <info@omninode.ai>
#
# SPDX-License-Identifier: Apache-2.0
"""
Action Status Enumeration for Action Metadata Tracking.

Provides status values for tracking action lifecycle in orchestrator workflows.
Actions progress through states from creation to completion or failure.

State Machine:
CREATED -> READY -> RUNNING -> COMPLETED
| |
v v
FAILED FAILED
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

.. versionadded:: 0.6.5
Added as part of OMN-1309 to replace hardcoded status strings with enum references.
"""

from enum import Enum, unique

from omnibase_core.utils.util_str_enum_base import StrValueHelper


@unique
class EnumActionStatus(StrValueHelper, str, Enum):
"""
Action status values for action metadata tracking.

Represents the lifecycle states of an action within orchestrator workflows.
Inherits from ``str`` for proper JSON serialization - values serialize
to lowercase strings.

Attributes:
CREATED: Initial state when action is constructed but not yet ready.
READY: Action has been validated and is ready for execution.
RUNNING: Action execution is currently in progress.
COMPLETED: Action has completed successfully.
FAILED: Action has failed with an error.

Example:
>>> status = EnumActionStatus.CREATED
>>> str(status)
'created'
>>> import json
>>> json.dumps({"status": status})
'{"status": "created"}'

.. versionadded:: 0.6.5
Added as part of OMN-1309 to replace hardcoded status strings.
"""

CREATED = "created"
READY = "ready"
RUNNING = "running"
COMPLETED = "completed"
FAILED = "failed"

def is_terminal(self) -> bool:
"""
Check if this status represents a terminal state.

Terminal states indicate the action has finished execution
and will not transition to any other state.

Returns:
True if COMPLETED or FAILED, False otherwise.

Example:
>>> EnumActionStatus.COMPLETED.is_terminal()
True
>>> EnumActionStatus.RUNNING.is_terminal()
False
"""
return self in {EnumActionStatus.COMPLETED, EnumActionStatus.FAILED}

def is_active(self) -> bool:
"""
Check if this status represents an active execution state.

Active states indicate the action is currently being executed.

Returns:
True if RUNNING, False otherwise.

Example:
>>> EnumActionStatus.RUNNING.is_active()
True
>>> EnumActionStatus.READY.is_active()
False
"""
return self == EnumActionStatus.RUNNING

def is_pending(self) -> bool:
"""
Check if this status represents a pending state.

Pending states indicate the action has not yet started execution.

Returns:
True if CREATED or READY, False otherwise.

Example:
>>> EnumActionStatus.CREATED.is_pending()
True
>>> EnumActionStatus.RUNNING.is_pending()
False
"""
return self in {EnumActionStatus.CREATED, EnumActionStatus.READY}

def is_success(self) -> bool:
"""
Check if this status represents successful completion.

Returns:
True if COMPLETED, False otherwise.

Example:
>>> EnumActionStatus.COMPLETED.is_success()
True
>>> EnumActionStatus.FAILED.is_success()
False
"""
return self == EnumActionStatus.COMPLETED

def is_failure(self) -> bool:
"""
Check if this status represents a failure state.

Returns:
True if FAILED, False otherwise.

Example:
>>> EnumActionStatus.FAILED.is_failure()
True
>>> EnumActionStatus.COMPLETED.is_failure()
False
"""
return self == EnumActionStatus.FAILED

def can_transition_to(self, target: "EnumActionStatus") -> bool:
"""
Check if transitioning to the target state is valid.

Valid state transitions:
- CREATED -> READY (action validated and ready)
- CREATED -> FAILED (validation failure)
- READY -> RUNNING (execution started)
- READY -> FAILED (pre-execution failure)
- RUNNING -> COMPLETED (successful completion)
- RUNNING -> FAILED (execution failure)

Terminal states (COMPLETED, FAILED) cannot transition to any state.

Args:
target: The target status to transition to.

Returns:
True if the transition is valid, False otherwise.

Example:
>>> EnumActionStatus.CREATED.can_transition_to(EnumActionStatus.READY)
True
>>> EnumActionStatus.COMPLETED.can_transition_to(EnumActionStatus.RUNNING)
False
>>> EnumActionStatus.RUNNING.can_transition_to(EnumActionStatus.COMPLETED)
True
"""
return target in _VALID_TRANSITIONS.get(self, set())


# Class-level constant for valid state transitions.
# Defined after the enum class to allow self-referential enum values.
_VALID_TRANSITIONS: dict[EnumActionStatus, set[EnumActionStatus]] = {
EnumActionStatus.CREATED: {EnumActionStatus.READY, EnumActionStatus.FAILED},
EnumActionStatus.READY: {EnumActionStatus.RUNNING, EnumActionStatus.FAILED},
EnumActionStatus.RUNNING: {EnumActionStatus.COMPLETED, EnumActionStatus.FAILED},
EnumActionStatus.COMPLETED: set(),
EnumActionStatus.FAILED: set(),
}


__all__ = ["EnumActionStatus"]
51 changes: 49 additions & 2 deletions src/omnibase_core/enums/enum_circuit_breaker_state.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,62 @@
from enum import Enum, unique
from typing import Never, NoReturn

from omnibase_core.utils.util_str_enum_base import StrValueHelper

__all__ = ["EnumCircuitBreakerState"]


@unique
class EnumCircuitBreakerState(Enum):
class EnumCircuitBreakerState(StrValueHelper, str, Enum):
"""
Circuit breaker state enumeration.

CLOSED: Normal operation. OPEN: Requests rejected. HALF_OPEN: Testing recovery.
The circuit breaker pattern prevents cascading failures by tracking the
health of external dependencies and temporarily blocking requests when
failures exceed a threshold.

Inherits from ``str`` to ensure proper JSON serialization - enum values
serialize directly to their lowercase string values (e.g., "closed", "open").

States:
CLOSED: Normal operation, requests pass through. The circuit monitors
for failures and transitions to OPEN if the failure threshold is exceeded.
OPEN: Circuit tripped, requests are rejected immediately without attempting
the operation. After a timeout period, transitions to HALF_OPEN.
HALF_OPEN: Testing recovery, limited requests allowed through to probe
whether the service has recovered. Success returns to CLOSED,
failure returns to OPEN.

State Transitions::

CLOSED --[failure threshold exceeded]--> OPEN
OPEN --[timeout elapsed]--> HALF_OPEN
HALF_OPEN --[probe succeeds]--> CLOSED
HALF_OPEN --[probe fails]--> OPEN

Example:
.. code-block:: python

from omnibase_core.enums import EnumCircuitBreakerState

state = EnumCircuitBreakerState.CLOSED
if state == EnumCircuitBreakerState.OPEN:
raise CircuitOpenError("Circuit is open")

# Using in match statement with exhaustive checking
match state:
case EnumCircuitBreakerState.CLOSED:
result = execute_request()
case EnumCircuitBreakerState.OPEN:
raise CircuitOpenError("Circuit is open")
case EnumCircuitBreakerState.HALF_OPEN:
result = execute_probe_request()
case _ as unreachable:
EnumCircuitBreakerState.assert_exhaustive(unreachable)

.. versionadded:: 0.4.0
.. versionchanged:: 0.6.5
Now inherits from ``str`` for proper JSON serialization (OMN-1309).
"""

CLOSED = "closed"
Expand Down
87 changes: 87 additions & 0 deletions src/omnibase_core/enums/enum_node_lifecycle_status.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
"""
Node Lifecycle Status Enum.

Defines the lifecycle states for nodes in the ONEX system.
Used by NodeCoreBase and derived node types for tracking
initialization and cleanup phases.

.. versionadded:: 0.6.5
Added as part of OMN-1309 (replace hardcoded status strings).
"""

from enum import Enum, unique

from omnibase_core.utils.util_str_enum_base import StrValueHelper


@unique
class EnumNodeLifecycleStatus(StrValueHelper, str, Enum):
"""
Node lifecycle status values.

Inherits from ``str`` to ensure proper JSON serialization - enum values
serialize directly to their lowercase string values.

Lifecycle Flow::

INITIALIZED -> INITIALIZING -> READY -> CLEANING_UP -> CLEANED_UP
\\-> FAILED
CLEANING_UP -> CLEANUP_FAILED

States:
INITIALIZED: Node has been constructed but not yet started.
INITIALIZING: Node initialization is in progress.
READY: Node is fully initialized and ready for processing.
FAILED: Node initialization or processing failed.
CLEANING_UP: Node cleanup is in progress.
CLEANED_UP: Node cleanup completed successfully.
CLEANUP_FAILED: Node cleanup failed (logged but not raised).
"""

INITIALIZED = "initialized"
"""Node has been constructed but not yet started."""

INITIALIZING = "initializing"
"""Node initialization is in progress."""

READY = "ready"
"""Node is fully initialized and ready for processing."""

FAILED = "failed"
"""Node initialization or processing failed."""

CLEANING_UP = "cleaning_up"
"""Node cleanup is in progress."""

CLEANED_UP = "cleaned_up"
"""Node cleanup completed successfully."""

CLEANUP_FAILED = "cleanup_failed"
"""Node cleanup failed (logged but not raised)."""

def is_terminal(self) -> bool:
"""Check if this is a terminal state (no further transitions expected)."""
return self in {
EnumNodeLifecycleStatus.CLEANED_UP,
EnumNodeLifecycleStatus.CLEANUP_FAILED,
EnumNodeLifecycleStatus.FAILED,
}

def is_active(self) -> bool:
"""Check if this state indicates the node is actively processing."""
return self in {
EnumNodeLifecycleStatus.INITIALIZING,
EnumNodeLifecycleStatus.READY,
EnumNodeLifecycleStatus.CLEANING_UP,
}

def is_error(self) -> bool:
"""Check if this state indicates an error condition."""
return self in {
EnumNodeLifecycleStatus.FAILED,
EnumNodeLifecycleStatus.CLEANUP_FAILED,
}


# Export for use
__all__ = ["EnumNodeLifecycleStatus"]
Loading