From 9a9bdf3b753c00e2e5471ad0abe37e063f4c7013 Mon Sep 17 00:00:00 2001
From: Alex Mazzeo <alex.mazzeo@temporal.io>
Date: Fri, 13 Feb 2026 10:50:21 -0800
Subject: [PATCH] Mark Handler, Middleware, Serializer and other related
 concepts as experimental. These APIs may be removed with the expectation that
 a transport layer implement them rather than the SDK.

---
 src/nexusrpc/_serializer.py                |  9 +++++++++
 src/nexusrpc/handler/_core.py              | 14 ++++++++++++++
 src/nexusrpc/handler/_operation_handler.py |  3 +++
 3 files changed, 26 insertions(+)

diff --git a/src/nexusrpc/_serializer.py b/src/nexusrpc/_serializer.py
index 645a8455..8b0b831d 100644
--- a/src/nexusrpc/_serializer.py
+++ b/src/nexusrpc/_serializer.py
@@ -16,6 +16,9 @@ class Content:
     A container for a map of headers and a byte array of data.
 
     It is used by the SDK's Serializer interface implementations.
+
+    .. warning::
+        This API is experimental and may change in the future.
     """
 
     headers: Mapping[str, str]
@@ -32,6 +35,9 @@ class Content:
 class Serializer(Protocol):
     """
     Serializer is used by the framework to serialize/deserialize input and output.
+
+    .. warning::
+        This API is experimental and may change in the future.
     """
 
     def serialize(self, value: Any) -> Union[Content, Awaitable[Content]]:
@@ -63,6 +69,9 @@ class LazyValue(LazyValueT):
 
     It is used to stream inputs and outputs in the various client and server APIs.
 
+    .. warning::
+        This API is experimental and may change in the future.
+
     Example:
         .. code-block:: python
 
diff --git a/src/nexusrpc/handler/_core.py b/src/nexusrpc/handler/_core.py
index eb3b01a7..68c832ba 100644
--- a/src/nexusrpc/handler/_core.py
+++ b/src/nexusrpc/handler/_core.py
@@ -126,6 +126,11 @@
 
 
 class AbstractHandler(ABC):
+    """
+    .. warning::
+        This API is experimental and may change in the future.
+    """
+
     @abstractmethod
     def start_operation(
         self,
@@ -161,6 +166,9 @@ class BaseServiceCollectionHandler(AbstractHandler, ABC):
 
     Operation requests are delegated to a :py:class:`ServiceHandler` based on the service
     name in the operation context.
+
+    .. warning::
+        This API is experimental and may change in the future.
     """
 
     def __init__(
@@ -226,6 +234,9 @@ class Handler(BaseServiceCollectionHandler):
     The methods of this class itself are `async def`. There is currently no alternative
     Handler class with `def` methods.
 
+    .. warning::
+        This API is experimental and may change in the future.
+
     Example:
         .. code-block:: python
 
@@ -417,6 +428,9 @@ class OperationHandlerMiddleware(ABC):
     Middleware for operation handlers.
 
     This should be extended by any operation handler middelware.
+
+    .. warning::
+        This API is experimental and may change in the future.
     """
 
     @abstractmethod
diff --git a/src/nexusrpc/handler/_operation_handler.py b/src/nexusrpc/handler/_operation_handler.py
index 181fa674..53ec8c35 100644
--- a/src/nexusrpc/handler/_operation_handler.py
+++ b/src/nexusrpc/handler/_operation_handler.py
@@ -106,6 +106,9 @@ class MiddlewareSafeOperationHandler(OperationHandler[Any, Any], ABC):
     can be awaited by an async runtime. It can produce a result synchronously by returning
     :py:class:`StartOperationResultSync` or asynchronously by returning :py:class:`StartOperationResultAsync`
     in the same fashion that :py:class:`OperationHandler` does.
+
+    .. warning::
+        This API is experimental and may change in the future.
     """
 
     @abstractmethod