Add Failure base class with spec-compliant metadata/details (#45)

VegetarianOrc · claude · web-flow · commit 17d79f613248 · 2026-02-25T12:41:10.000-08:00
* Preserve raw HandlerError type

- Make raw_error_type optional in constructor, defaults to error_type.value
- Preserve raw_error_type separately to handle unknown types from the wire
- Remove unnecessary retryable_override property wrapper
- Update docstring examples to show from_error_type() as primary API
- Update usages to use from_error_type()
- Enhance tests with explicit assertions for error_type and raw_error_type

* Remove class methods and make constructor accept either a HandlerErrorType or a str to simplify the API surface

* Add additional assertions to string HanderError test

* Fix spacing in docstring

* Run formatter. Declare classvars in HandlerErrorType. Add ignore for inaccurate mypy linting error

* Update ruff and target python 3.10 for ruff linting. Swap to using a match statement rather than the classvar frozensets.

* Remove ruff from direct dependencies

* Add Failure base class and set spec-compliant metadata/details

Add Failure as a base class for HandlerError and OperationError,
representing protocol-level failures with message, stack_trace,
metadata, details, and cause fields.

Update HandlerError and OperationError to set their inherited Failure
metadata and details properties according to the spec representation:

- HandlerError: metadata["type"] = "nexus.HandlerError", details contains
  "type" (error type) and optionally "retryableOverride"
- OperationError: metadata["type"] = "nexus.OperationError", details
  contains "state" (failed/canceled)

User-provided metadata/details are merged but spec-required keys cannot
be overridden.

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

* Make Failure.stack_trace a property that captures traceback

- Change stack_trace from a simple attribute to a property
- Return explicit stack_trace if provided, otherwise format __traceback__
- Return None when no stack trace is available (instead of empty string)
- Add docstring explaining the property behavior
- Add test verifying traceback capture for Failure, HandlerError, and OperationError

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

* Ignore IDE setting files in gitignore

* Add __repr__ methods and make metadata/details immutable

- Add __repr__ to Failure, HandlerError, and OperationError for debugging
- Make metadata and details immutable using MappingProxyType
- Change Failure.details type from Any to Mapping[str, Any] | None
- Add tests for explicit stack_trace precedence and immutability

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

* Use Python's native __cause__ for Failure exception chaining

Replace custom `cause` attribute with Python's built-in exception
chaining mechanism. This allows users to use standard Python syntax:
`raise Failure(...) from other_exception`

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

* Make Failure.stack_trace a plain attribute instead of a property

This allows consumers to distinguish between explicit stack traces
(from deserialization/remote sources) and local tracebacks (via
Python's native __traceback__).

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

* Revert renaming of HandlerError.type

* Finish error_type -&gt; type revert

* Fix HandlerError docstring to use 'type' parameter name

The docstring examples and :param documentation incorrectly referenced
'error_type' but the actual parameter is named 'type'. Updated docs
and __repr__ output to be consistent with the parameter name.

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

* Add default case to provide runtime default to retryable property

* Swap Failure to basic dataclass. Remove creation of details/metadata out of HandlerError and OperationError in favor of having the transport layer handle that as necessary.

* Fix linter errors and docstrings

---------

Co-authored-by: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -3,3 +3,5 @@ __pycache__
 apidocs
 dist
 docs
+.idea
+.vscode
diff --git a/pyproject.toml b/pyproject.toml
@@ -25,7 +25,7 @@ dev = [
   "pytest-asyncio>=0.26.0",
   "pytest-cov>=6.1.1",
   "pytest-pretty>=1.3.0",
-  "ruff>=0.12.0",
+  "ruff>=0.14.0",
 ]
 
 [build-system]
@@ -71,7 +71,7 @@ include = ["src", "tests"]
 disable_error_code = ["empty-body"]
 
 [tool.ruff]
-target-version = "py39"
+target-version = "py310"
 
 [tool.ruff.lint.isort]
 combine-as-imports = true
diff --git a/src/nexusrpc/__init__.py b/src/nexusrpc/__init__.py
@@ -17,6 +17,7 @@
 
 from . import handler
 from ._common import (
+    Failure,
     HandlerError,
     HandlerErrorType,
     InputT,
@@ -35,6 +36,7 @@
 
 __all__ = [
     "Content",
+    "Failure",
     "get_operation",
     "get_service_definition",
     "handler",
diff --git a/src/nexusrpc/_common.py b/src/nexusrpc/_common.py
@@ -2,7 +2,12 @@
 
 from dataclasses import dataclass
 from enum import Enum
-from typing import Optional, TypeVar
+from logging import getLogger
+from typing import Any, Mapping, TypeVar
+
+from typing_extensions import Never
+
+logger = getLogger(__name__)
 
 InputT = TypeVar("InputT", contravariant=True)
 """Operation input type"""
@@ -17,6 +22,21 @@
 """A user's service definition class, typically decorated with @service"""
 
 
+@dataclass
+class Failure:
+    """
+    A Nexus Failure represents protocol-level failures.
+
+    See https://github.com/nexus-rpc/api/blob/main/SPEC.md#failure
+    """
+
+    message: str
+    stack_trace: str | None = None
+    metadata: Mapping[str, str] | None = None
+    details: Mapping[str, Any] | None = None
+    cause: Failure | None = None
+
+
 class HandlerError(Exception):
     """
     A Nexus handler error.
@@ -39,39 +59,55 @@ class HandlerError(Exception):
             raise nexusrpc.HandlerError(
                 "Database unavailable",
                 type=nexusrpc.HandlerErrorType.INTERNAL,
-                retryable=True
+                retryable_override=True
             )
     """
 
     def __init__(
         self,
         message: str,
         *,
-        type: HandlerErrorType,
-        retryable_override: Optional[bool] = None,
+        type: HandlerErrorType | str,
+        retryable_override: bool | None = None,
+        stack_trace: str | None = None,
+        original_failure: Failure | None = None,
     ):
         """
         Initialize a new HandlerError.
 
-        :param message: A descriptive message for the error. This will become
-                        the `message` in the resulting Nexus Failure object.
+        :param message: A descriptive message for the error.
 
-        :param type: The :py:class:`HandlerErrorType` of the error.
+        :param type: The :py:class:`HandlerErrorType` of the error, or a
+                     string representation of the error type. If a string is
+                     provided and doesn't match a known error type, it will
+                     be treated as UNKNOWN and a warning will be logged.
 
         :param retryable_override: Optionally set whether the error should be
                                    retried. By default, the error type is used
                                    to determine this.
-        """
-        super().__init__(message)
-        self._type = type
-        self._retryable_override = retryable_override
 
-    @property
-    def retryable_override(self) -> Optional[bool]:
-        """
-        The optional retryability override set when this error was created.
+        :param stack_trace: An optional stack trace string.
+
+        :param original_failure: Set if this error is constructed from a failure object.
         """
-        return self._retryable_override
+        # Handle string error types (must be done before super().__init__ to build details)
+        if isinstance(type, str):
+            raw_error_type = type
+            try:
+                type = HandlerErrorType[type]
+            except KeyError:
+                logger.warning(f"Unknown Nexus HandlerErrorType: {type}")
+                type = HandlerErrorType.UNKNOWN
+        else:
+            raw_error_type = type.value
+
+        self.message = message
+        self.type = type
+        self.raw_error_type = raw_error_type
+        self.retryable_override = retryable_override
+        self.stack_trace = stack_trace
+        self.original_failure = original_failure
+        super().__init__(message)
 
     @property
     def retryable(self) -> bool:
@@ -82,40 +118,36 @@ def retryable(self) -> bool:
         error type is used. See
         https://github.com/nexus-rpc/api/blob/main/SPEC.md#predefined-handler-errors
         """
-        if self._retryable_override is not None:
-            return self._retryable_override
-
-        non_retryable_types = {
-            HandlerErrorType.BAD_REQUEST,
-            HandlerErrorType.UNAUTHENTICATED,
-            HandlerErrorType.UNAUTHORIZED,
-            HandlerErrorType.NOT_FOUND,
-            HandlerErrorType.CONFLICT,
-            HandlerErrorType.NOT_IMPLEMENTED,
-        }
-        retryable_types = {
-            HandlerErrorType.REQUEST_TIMEOUT,
-            HandlerErrorType.RESOURCE_EXHAUSTED,
-            HandlerErrorType.INTERNAL,
-            HandlerErrorType.UNAVAILABLE,
-            HandlerErrorType.UPSTREAM_TIMEOUT,
-        }
-        if self._type in non_retryable_types:
-            return False
-        elif self._type in retryable_types:
-            return True
-        else:
-            return True
-
-    @property
-    def type(self) -> HandlerErrorType:
-        """
-        The type of handler error.
-
-        See :py:class:`HandlerErrorType` and
-        https://github.com/nexus-rpc/api/blob/main/SPEC.md#predefined-handler-errors.
-        """
-        return self._type
+        if self.retryable_override is not None:
+            return self.retryable_override
+
+        match self.type:
+            case (
+                HandlerErrorType.BAD_REQUEST
+                | HandlerErrorType.UNAUTHENTICATED
+                | HandlerErrorType.UNAUTHORIZED
+                | HandlerErrorType.NOT_FOUND
+                | HandlerErrorType.CONFLICT
+                | HandlerErrorType.NOT_IMPLEMENTED
+            ):
+                return False
+            case (
+                HandlerErrorType.RESOURCE_EXHAUSTED
+                | HandlerErrorType.REQUEST_TIMEOUT
+                | HandlerErrorType.INTERNAL
+                | HandlerErrorType.UNAVAILABLE
+                | HandlerErrorType.UPSTREAM_TIMEOUT
+                | HandlerErrorType.UNKNOWN
+            ):
+                return True
+
+            # Type checking enforces exhaustive matching but
+            # the default case is included to provide a runtime default.
+            # If a case is missing from above, the assignment to Never
+            # will cause a type checking error.
+            case _ as unreachable:  # pyright: ignore[reportUnnecessaryComparison]
+                _: Never = unreachable  # pyright: ignore[reportUnreachable]
+                return True  # pyright: ignore[reportUnreachable]
 
 
 class HandlerErrorType(Enum):
@@ -124,6 +156,11 @@ class HandlerErrorType(Enum):
     See https://github.com/nexus-rpc/api/blob/main/SPEC.md#predefined-handler-errors
     """
 
+    UNKNOWN = "UNKNOWN"
+    """
+    The error type is unknown. Subsequent requests by the client are permissible.
+    """
+
     BAD_REQUEST = "BAD_REQUEST"
     """
     The handler cannot or will not process the request due to an apparent client error.
@@ -208,11 +245,6 @@ class OperationError(Exception):
     """
     An error that represents "failed" and "canceled" operation results.
 
-    :param message: A descriptive message for the error. This will become the
-                    `message` in the resulting Nexus Failure object.
-
-    :param state:
-
     Example:
         .. code-block:: python
 
@@ -231,16 +263,34 @@ class OperationError(Exception):
             )
     """
 
-    def __init__(self, message: str, *, state: OperationErrorState):
-        super().__init__(message)
-        self._state = state
-
-    @property
-    def state(self) -> OperationErrorState:
+    def __init__(
+        self,
+        message: str,
+        *,
+        state: OperationErrorState,
+        stack_trace: str | None = None,
+        original_failure: Failure | None = None,
+    ):
         """
-        The state of the operation.
+        Initialize a new OperationError.
+
+        :param message: A descriptive message for the error.
+
+        :param state: The state of the operation (:py:class:`OperationErrorState`).
+
+        :param stack_trace: An optional stack trace string.
+
+        :param original_failure: Set if this error is constructed from a failure object.
+
         """
-        return self._state
+
+        self.message = message
+        self.state = state
+        self.stack_trace = stack_trace
+        self.original_failure = original_failure
+
+        self.state = state
+        super().__init__(message)
 
 
 class OperationErrorState(Enum):
diff --git a/tests/test_common.py b/tests/test_common.py
@@ -1,41 +1,38 @@
-from nexusrpc._common import HandlerError, HandlerErrorType
-
-
-def test_handler_error_retryable_type():
-    retryable_error_type = HandlerErrorType.RESOURCE_EXHAUSTED
-    assert HandlerError(
-        "test",
-        type=retryable_error_type,
-        retryable_override=True,
-    ).retryable
-
-    assert not HandlerError(
-        "test",
-        type=retryable_error_type,
-        retryable_override=False,
-    ).retryable
-
-    assert HandlerError(
-        "test",
-        type=retryable_error_type,
-    ).retryable
-
-
-def test_handler_error_non_retryable_type():
-    non_retryable_error_type = HandlerErrorType.BAD_REQUEST
-    assert HandlerError(
-        "test",
-        type=non_retryable_error_type,
-        retryable_override=True,
-    ).retryable
-
-    assert not HandlerError(
-        "test",
-        type=non_retryable_error_type,
-        retryable_override=False,
-    ).retryable
-
-    assert not HandlerError(
-        "test",
-        type=non_retryable_error_type,
-    ).retryable
+from nexusrpc._common import (
+    HandlerError,
+    HandlerErrorType,
+)
+
+
+def test_handler_error_retryable_behavior():
+    """Test retryable behavior based on error type and override."""
+    # Retryable error type (RESOURCE_EXHAUSTED)
+    retryable_type = HandlerErrorType.RESOURCE_EXHAUSTED
+    err = HandlerError("test", type=retryable_type)
+    assert err.retryable
+    assert err.type == retryable_type
+    assert err.raw_error_type == retryable_type.value
+
+    err = HandlerError("test", type=retryable_type, retryable_override=False)
+    assert not err.retryable
+
+    # Non-retryable error type (BAD_REQUEST)
+    non_retryable_type = HandlerErrorType.BAD_REQUEST
+    err = HandlerError("test", type=non_retryable_type)
+    assert not err.retryable
+    assert err.type == non_retryable_type
+    assert err.raw_error_type == non_retryable_type.value
+
+    err = HandlerError("test", type=non_retryable_type, retryable_override=True)
+    assert err.retryable
+
+
+def test_handler_error_unknown_error_type():
+    """Test handling of unknown error type strings."""
+    err = HandlerError("test", type="SOME_UNKNOWN_TYPE")
+    assert err.retryable
+    assert err.type == HandlerErrorType.UNKNOWN
+    assert err.raw_error_type == "SOME_UNKNOWN_TYPE"
+
+    err = HandlerError("test", type="SOME_UNKNOWN_TYPE", retryable_override=False)
+    assert not err.retryable
diff --git a/uv.lock b/uv.lock

-Original file line number
+Diff line change
 apidocs
 dist
 docs
 +.idea
 +.vscode