Require type equality for operation handler input/output types (#44)

* Add test demonstrating covariant operation ouput types

* Require exact type identity for operation handler input/output types

   Replace covariant/contravariant type checking with strict identity checks.
   Operation handler implementations must now declare the exact same input and
   output types as the service definition, rather than allowing subtype
   relationships. This simplifies type validation and makes the type contract
   more explicit.

   Also replace dataclass_transform with standard @DataClass decorator in tests.

* Update comments around operation input/output type checking

* Remove is_subtype function and fix import ordering

Remove the now-unused is_subtype function since type checking requires
exact type identity. Also fix import ordering in test files to follow
PEP 8 conventions.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Fix error message formatting and typo in test class name

- Add missing colon and space in type mismatch error messages
- Fix typo: OutputCovarianceImplOutputCannnotBeStrictSuperclass ->
  OutputCovarianceImplOutputCannotBeStrictSuperclass

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Add tests for generic type comparison in operation handlers

Adds test cases using parameterized types (list[int], dict[str, bool])
to validate that equality comparison (!=) works correctly for type
checking. This ensures generic types are properly compared since they
create new objects on each evaluation, making identity comparison (is)
unreliable.

Also adds missing InputContravarianceImplInputCannotBeSubclass to the
parametrize list.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* use equality checks instead of identity checks

* Add in new test file

* Update docstring and add tests for Any type behavior

- Fix stale docstring that described covariance/contravariance
- Add tests clarifying that Any requires exact match, not wildcard

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: VegetarianOrc

src/nexusrpc/_util.py

@@ -2,7 +2,6 @@
 
 import functools
 import inspect
-import typing
 from collections.abc import Awaitable
 from typing import TYPE_CHECKING, Any, Callable, Optional
 
@@ -142,14 +141,6 @@ def get_callable_name(fn: Callable[..., Any]) -> str:
     return method_name
 
 
-def is_subtype(type1: type[Any], type2: type[Any]) -> bool:
-    # Note that issubclass() argument 2 cannot be a parameterized generic
-    # TODO(nexus-preview): review desired type compatibility logic
-    if type1 == type2:
-        return True
-    return issubclass(type1, typing.get_origin(type2) or type2)
-
-
 # See
 # https://docs.python.org/3/howto/annotations.html#accessing-the-annotations-dict-of-an-object-in-python-3-9-and-older
 

src/nexusrpc/handler/_operation_handler.py

@@ -12,7 +12,6 @@
     get_operation_factory,
     is_async_callable,
     is_callable,
-    is_subtype,
 )
 
 from ._common import (
@@ -180,9 +179,8 @@ def validate_operation_handler_methods(
     1. There must be a method in ``user_methods`` whose method name matches the method
        name from the service definition.
 
-    2. The input and output types of the user method must be such that the user method
-       is a subtype of the operation defined in the service definition, i.e. respecting
-       input type contravariance and output type covariance.
+    2. The input and output types of the handler method must exactly match the types
+       declared in the service definition.
     """
     operation_handler_factories_by_method_name = (
         operation_handler_factories_by_method_name.copy()
@@ -212,40 +210,21 @@ def validate_operation_handler_methods(
                 f"is '{op_defn.name}'. Operation handlers may not override the name of an operation "
                 f"in the service definition."
             )
-        # Input type is contravariant: op handler input must be superclass of op defn input.
         # If handler's input_type is None (missing annotation), skip validation - the handler
         # relies on the service definition for type information. This supports handlers without
         # explicit type annotations when a service definition is provided.
-        if (
-            op.input_type is not None
-            and Any not in (op.input_type, op_defn.input_type)
-            and not (
-                op_defn.input_type == op.input_type
-                or is_subtype(op_defn.input_type, op.input_type)
-            )
-        ):
+        if op.input_type is not None and op_defn.input_type != op.input_type:
             raise TypeError(
-                f"Operation '{op_defn.method_name}' in service '{service_cls}' "
-                f"has input type '{op.input_type}', which is not "
-                f"compatible with the input type '{op_defn.input_type}' in interface "
-                f"'{service_definition.name}'. The input type must be the same as or a "
-                f"superclass of the operation definition input type."
+                f"OperationHandler input type mismatch for '{service_cls}.{op_defn.method_name}': "
+                f"expected {op_defn.input_type}, got {op.input_type}"
             )
 
-        # Output type is covariant: op handler output must be subclass of op defn output.
         # If handler's output_type is None (missing annotation), skip validation - the handler
         # relies on the service definition for type information.
-        if (
-            op.output_type is not None
-            and Any not in (op.output_type, op_defn.output_type)
-            and not is_subtype(op.output_type, op_defn.output_type)
-        ):
+        if op.output_type is not None and op.output_type != op_defn.output_type:
             raise TypeError(
-                f"Operation '{op_defn.method_name}' in service '{service_cls}' "
-                f"has output type '{op.output_type}', which is not "
-                f"compatible with the output type '{op_defn.output_type}' in interface "
-                f" '{service_definition}'. The output type must be the same as or a "
-                f"subclass of the operation definition output type."
+                f"OperationHandler output type mismatch for '{service_cls}.{op_defn.method_name}': "
+                f"expected {op_defn.output_type}, got {op.output_type}"
             )
     if operation_handler_factories_by_method_name:
         raise ValueError(

tests/handler/test_handler_validates_service_handler_collection.py

@@ -5,15 +5,17 @@
 
 import pytest
 
+from nexusrpc import HandlerError, LazyValue
 from nexusrpc.handler import (
     CancelOperationContext,
     Handler,
     OperationHandler,
     StartOperationContext,
     StartOperationResultSync,
+    operation_handler,
     service_handler,
 )
-from nexusrpc.handler._decorators import operation_handler
+from tests.helpers import DummySerializer, TestOperationTaskCancellation
 
 
 def test_service_must_use_decorator():
@@ -63,3 +65,31 @@ class Service2:
 
     with pytest.raises(RuntimeError):
         _ = Handler([Service1(), Service2()])
+
+
+@pytest.mark.asyncio
+async def test_operations_must_have_decorator():
+    @service_handler
+    class TestService:
+        async def op(self, _ctx: StartOperationContext, input: str) -> str:
+            return input
+
+    handler = Handler([TestService()])
+
+    with pytest.raises(HandlerError, match="has no operation 'op'"):
+        _ = await handler.start_operation(
+            StartOperationContext(
+                service=TestService.__name__,
+                operation=TestService.op.__name__,
+                headers={},
+                request_id="test-req",
+                task_cancellation=TestOperationTaskCancellation(),
+                request_deadline=None,
+                callback_url=None,
+            ),
+            LazyValue(
+                serializer=DummySerializer(value="test"),
+                headers={},
+                stream=None,
+            ),
+        )

tests/handler/test_invalid_usage.py

@@ -3,10 +3,9 @@
 handler implementations.
 """
 
-from typing import Any, Callable
+from dataclasses import dataclass
 
 import pytest
-from typing_extensions import dataclass_transform
 
 import nexusrpc
 from nexusrpc.handler import (
@@ -19,15 +18,14 @@
 from nexusrpc.handler._operation_handler import OperationHandler
 
 
-@dataclass_transform()
-class _BaseTestCase:
-    pass
-
-
-class _TestCase(_BaseTestCase):
-    build: Callable[..., Any]
+@dataclass()
+class _TestCase:
     error_message: str
 
+    @staticmethod
+    def build():
+        pass
+
 
 class OperationHandlerOverridesNameInconsistentlyWithServiceDefinition(_TestCase):
     @staticmethod

tests/handler/test_operation_handler_runtime_behavior.py

@@ -0,0 +1,95 @@
+"""
+Test runtime behavior of operation handlers invoked through Handler.start_operation().
+
+This file tests actual execution behavior, distinct from:
+- Decoration-time validation (test_service_handler_decorator_validates_against_service_contract.py)
+- Handler constructor validation (test_handler_validates_service_handler_collection.py)
+"""
+
+import pytest
+
+from nexusrpc import LazyValue, Operation, service
+from nexusrpc.handler import (
+    CancelOperationContext,
+    Handler,
+    OperationHandler,
+    StartOperationContext,
+    StartOperationResultSync,
+    operation_handler,
+    service_handler,
+)
+from nexusrpc.handler._decorators import sync_operation
+from tests.helpers import DummySerializer, TestOperationTaskCancellation
+
+
+@pytest.mark.asyncio
+async def test_handler_can_return_covariant_type():
+    class Superclass:
+        pass
+
+    class Subclass(Superclass):
+        pass
+
+    @service
+    class CovariantService:
+        op_handler: Operation[None, Superclass]
+        inline: Operation[None, Superclass]
+
+    class ValidOperationHandler(OperationHandler[None, Superclass]):
+        async def start(
+            self, ctx: StartOperationContext, input: None
+        ) -> StartOperationResultSync[Subclass]:
+            return StartOperationResultSync(Subclass())
+
+        async def cancel(self, ctx: CancelOperationContext, token: str) -> None:
+            pass
+
+    @service_handler(service=CovariantService)
+    class CovariantServiceHandler:
+        @operation_handler
+        def op_handler(self) -> OperationHandler[None, Superclass]:
+            return ValidOperationHandler()
+
+        @sync_operation
+        async def inline(self, ctx: StartOperationContext, input: None) -> Superclass:  # pyright: ignore[reportUnusedParameter]
+            return Subclass()
+
+    handler = Handler([CovariantServiceHandler()])
+
+    result = await handler.start_operation(
+        StartOperationContext(
+            service=CovariantService.__name__,
+            operation=CovariantService.op_handler.name,
+            headers={},
+            request_id="test-req",
+            task_cancellation=TestOperationTaskCancellation(),
+            request_deadline=None,
+            callback_url=None,
+        ),
+        LazyValue(
+            serializer=DummySerializer(None),
+            headers={},
+            stream=None,
+        ),
+    )
+    assert type(result) is StartOperationResultSync
+    assert type(result.value) is Subclass
+
+    result = await handler.start_operation(
+        StartOperationContext(
+            service=CovariantService.__name__,
+            operation=CovariantService.inline.name,
+            headers={},
+            request_id="test-req",
+            task_cancellation=TestOperationTaskCancellation(),
+            request_deadline=None,
+            callback_url=None,
+        ),
+        LazyValue(
+            serializer=DummySerializer(None),
+            headers={},
+            stream=None,
+        ),
+    )
+    assert type(result) is StartOperationResultSync
+    assert type(result.value) is Subclass

tests/handler/test_request_routing.py

@@ -1,7 +1,7 @@
+from dataclasses import dataclass
 from typing import Any, Callable, cast
 
 import pytest
-from typing_extensions import dataclass_transform
 
 import nexusrpc
 from nexusrpc import LazyValue
@@ -16,12 +16,8 @@
 from tests.helpers import DummySerializer, TestOperationTaskCancellation
 
 
-@dataclass_transform()
-class _BaseTestCase:
-    pass
-
-
-class _TestCase(_BaseTestCase):
+@dataclass()
+class _TestCase:
     UserService: type[Any]
     # (service_name, op_name)
     supported_request: tuple[str, str]

tests/handler/test_service_handler_decorator_requirements.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import Any
 
 import pytest
-from typing_extensions import dataclass_transform
 
 import nexusrpc
 from nexusrpc._util import get_service_definition
@@ -15,12 +15,8 @@
 from nexusrpc.handler._decorators import operation_handler
 
 
-@dataclass_transform()
-class _TestCase:
-    pass
-
-
-class _DecoratorValidationTestCase(_TestCase):
+@dataclass()
+class _DecoratorValidationTestCase:
     UserService: type[Any]
     UserServiceHandler: type[Any]
     expected_error_message_pattern: str
@@ -71,7 +67,8 @@ def test_decorator_validates_definition_compliance(
         service_handler(service=test_case.UserService)(test_case.UserServiceHandler)
 
 
-class _ServiceHandlerInheritanceTestCase(_TestCase):
+@dataclass()
+class _ServiceHandlerInheritanceTestCase:
     UserServiceHandler: type[Any]
     expected_operations: set[str]
 
@@ -134,7 +131,8 @@ def test_service_implementation_inheritance(
     )
 
 
-class _ServiceDefinitionInheritanceTestCase(_TestCase):
+@dataclass()
+class _ServiceDefinitionInheritanceTestCase:
     UserService: type[Any]
     expected_ops: set[str]
 

tests/handler/test_service_handler_decorator_results_in_correctly_functioning_operation_factories.py

@@ -2,10 +2,10 @@
 Test that operation decorators result in operation factories that return the correct result.
 """
 
+from dataclasses import dataclass
 from typing import Any, Union, cast
 
 import pytest
-from typing_extensions import dataclass_transform
 
 import nexusrpc
 from nexusrpc import InputT, OutputT
@@ -26,12 +26,8 @@
 from tests.helpers import TestOperationTaskCancellation
 
 
-@dataclass_transform()
-class _BaseTestCase:
-    pass
-
-
-class _TestCase(_BaseTestCase):
+@dataclass()
+class _TestCase:
     Service: type[Any]
     expected_operation_factories: dict[str, Any]
 

tests/handler/test_service_handler_decorator_selects_correct_service_name.py

@@ -1,7 +1,7 @@
+from dataclasses import dataclass
 from typing import Optional
 
 import pytest
-from typing_extensions import dataclass_transform
 
 import nexusrpc
 from nexusrpc._util import get_service_definition
@@ -18,12 +18,8 @@ class ServiceInterfaceWithNameOverride:
     pass
 
 
-@dataclass_transform()
-class _BaseTestCase:
-    pass
-
-
-class _NameOverrideTestCase(_BaseTestCase):
+@dataclass()
+class _NameOverrideTestCase:
     ServiceImpl: type
     expected_name: str
     expected_error: Optional[type[Exception]] = None