openframe-protocol-grpc 0.2.0__tar.gz → 0.3.0__tar.gz

{openframe_protocol_grpc-0.2.0 → openframe_protocol_grpc-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openframe-protocol-grpc
-Version: 0.2.0
+Version: 0.3.0
 Summary: OpenFrame Microservice Suite - gRPC server and client binding for openframe.core.inbound/remote.
 Project-URL: Homepage, https://github.com/Furious-Meteors/openframe-protocol
 Project-URL: Documentation, https://furious-meteors.github.io/openframe-protocol/
@@ -35,6 +35,7 @@ Requires-Dist: pytest-mock>=3.14; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Provides-Extra: server
 Requires-Dist: grpcio>=1.60; extra == 'server'
+Requires-Dist: pydantic>=2.0; extra == 'server'
 Description-Content-Type: text/markdown
 
 # openframe-protocol-grpc

{openframe_protocol_grpc-0.2.0 → openframe_protocol_grpc-0.3.0}/openframe/protocol/grpc/server.py

@@ -38,7 +38,7 @@ from contextlib import asynccontextmanager
 from typing import Any, AsyncIterator, Awaitable, Callable
 
 import grpc
-from pydantic import ValidationError
+from pydantic import BaseModel, TypeAdapter, ValidationError
 
 from openframe.core.exceptions import AdapterConnectionError
 from openframe.core.inbound import RequestContext
@@ -103,11 +103,31 @@ def _get_or_create_servicer(server: grpc.aio.Server) -> _RouteRegisteringService
     return servicer
 
 
+def _to_jsonable(value: Any) -> Any:
+    """
+    Recursively converts a handler's result into something `json.dumps`
+    can actually serialise. Needed because handlers built for `-http`
+    (where FastAPI's own response_model machinery already handles this)
+    routinely return `BaseModel` instances or plain containers of them —
+    e.g. `GetItem` returning an `Item`, or `ListItems` returning
+    `{"items": [Item, ...], "total": N}` — and `json.dumps` has no idea
+    what to do with a `BaseModel` on its own.
+    """
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if isinstance(value, dict):
+        return {k: _to_jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_to_jsonable(v) for v in value]
+    return value
+
+
 def bind_service(
     server: grpc.aio.Server,
     route: str,
     *,
     handler_factory: Callable[[], Any],
+    input_model: Any = None,
     not_found_when: Callable[[Any], bool] | None = None,
 ) -> None:
     """
@@ -130,21 +150,43 @@ def bind_service(
                          Called once per request, no caching, matching
                          `handler_dep`'s own per-request lifecycle in
                          `-http`'s `server.py`.
+        input_model:     The gRPC counterpart of `-http`'s `body_model` —
+                         a real need, not a speculative one: handlers
+                         built for `-http` (e.g. `CreateItem.execute(self,
+                         item: Item, ...)`) expect a validated domain
+                         object, but the decoded `json_payload` is just a
+                         plain dict/list with no casting of its own
+                         (unlike FastAPI, which already validates a
+                         `body_model` before the handler ever sees it).
+                         Any type `pydantic.TypeAdapter` accepts — a
+                         `BaseModel` subclass, `list[Item]`, etc. `None`
+                         (the default) passes the decoded value through
+                         unchanged, for handlers whose input is already a
+                         plain dict/str/int/list of primitives.
         not_found_when:  If the handler's result satisfies this, abort
                          with `NOT_FOUND` instead of returning it.
     """
     servicer = _get_or_create_servicer(server)
+    adapter = TypeAdapter(input_model) if input_model is not None else None
 
     async def _handle(
         request: "generic_pb2.GenericRequest", context: grpc.aio.ServicerContext
     ) -> "generic_pb2.GenericResponse":
         handler = handler_factory()
-        handler_input = json.loads(request.json_payload) if request.json_payload else None
         metadata = dict(context.invocation_metadata())
         request_context: RequestContext = build_request_context(metadata)
         context.set_trailing_metadata((("x-correlation-id", request_context.correlation_id),))
 
         try:
+            raw_input = json.loads(request.json_payload) if request.json_payload else None
+            # Validation errors from an invalid input_model cast go through
+            # the same categorize()/build_envelope() path as a handler's
+            # own exception — matching how FastAPI's RequestValidationError
+            # (from an invalid body_model) categorizes as INVALID on -http,
+            # rather than crashing uncaught before context.abort() runs.
+            handler_input = (
+                adapter.validate_python(raw_input) if adapter is not None and raw_input is not None else raw_input
+            )
             result = await handler.execute(handler_input, request_context)
         except BaseException as exc:
             await _abort_for_exception(context, exc, request_context.correlation_id)
@@ -154,7 +196,7 @@ def bind_service(
             await context.abort(grpc.StatusCode.NOT_FOUND, "not found")
             return  # unreachable
 
-        return generic_pb2.GenericResponse(json_payload=json.dumps(result))
+        return generic_pb2.GenericResponse(json_payload=json.dumps(_to_jsonable(result)))
 
     servicer.register(route, _handle)
 

{openframe_protocol_grpc-0.2.0 → openframe_protocol_grpc-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openframe-protocol-grpc"
-version = "0.2.0"
+version = "0.3.0"
 description = "OpenFrame Microservice Suite - gRPC server and client binding for openframe.core.inbound/remote."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -30,6 +30,12 @@ dependencies = [
 [project.optional-dependencies]
 server = [
     "grpcio>=1.60",
+    # bind_service's input_model casting / output serialisation
+    # (TypeAdapter, BaseModel.model_dump) — a real runtime dependency now,
+    # not just a test-only one, since a real handler built for -http
+    # (expecting a validated domain object, not a raw decoded dict) needs
+    # this to work over gRPC at all.
+    "pydantic>=2.0",
 ]
 client = [
     # Unlike HTTP, gRPC's client and server share the same core

openframe_protocol_grpc-0.3.0/tests/test_bind_service_input_model.py

@@ -0,0 +1,134 @@
+"""
+Proves bind_service(input_model=...) and the matching output
+serialisation — added when wiring a real HTTP-built domain handler
+(CreateItem.execute(self, item: Item, ...)) over gRPC for the first time
+revealed two real gaps: the decoded json_payload is a plain dict/list
+with no casting (unlike FastAPI's body_model, which already validates
+before a handler ever sees it), and json.dumps can't serialise a
+BaseModel a handler returns on its own.
+"""
+from __future__ import annotations
+
+import grpc
+import pytest
+from pydantic import BaseModel
+
+from openframe.protocol.grpc import ROUTE_METADATA_KEY, bind_service, generic_pb2, generic_pb2_grpc
+
+
+class _Item(BaseModel):
+    id: str
+    name: str
+
+
+class _EchoHandler:
+    """Returns exactly what it received — proves the cast happened and the type survived."""
+
+    async def execute(self, value, context=None):
+        return value
+
+
+class _CreateItemLikeHandler:
+    """Mirrors a real -http-built handler: expects a validated _Item, returns one."""
+
+    async def execute(self, item: _Item, context=None):
+        assert isinstance(item, _Item)  # would be a plain dict without input_model casting
+        return item
+
+
+@pytest.fixture
+async def grpc_server():
+    server = grpc.aio.server()
+    bind_service(server, "echo_raw", handler_factory=lambda: _EchoHandler())
+    bind_service(
+        server, "create_item", handler_factory=lambda: _CreateItemLikeHandler(), input_model=_Item
+    )
+    bind_service(
+        server, "list_items", handler_factory=lambda: _EchoHandler(), input_model=list[_Item]
+    )
+    port = server.add_insecure_port("127.0.0.1:0")
+    await server.start()
+    yield server, port
+    await server.stop(None)
+
+
+async def _call(port: int, route: str, payload) -> str:
+    import json
+
+    channel = grpc.aio.insecure_channel(f"127.0.0.1:{port}")
+    stub = generic_pb2_grpc.GenericServiceStub(channel)
+    response = await stub.Call(
+        generic_pb2.GenericRequest(json_payload=json.dumps(payload)),
+        metadata=((ROUTE_METADATA_KEY, route),),
+    )
+    await channel.close()
+    return response.json_payload
+
+
+async def test_without_input_model_raw_dict_passes_through(grpc_server) -> None:
+    _server, port = grpc_server
+    result = await _call(port, "echo_raw", {"id": "abc", "name": "Widget"})
+    assert result == '{"id": "abc", "name": "Widget"}'
+
+
+async def test_input_model_casts_dict_into_basemodel_before_execute(grpc_server) -> None:
+    _server, port = grpc_server
+    result = await _call(port, "create_item", {"id": "abc", "name": "Widget"})
+    # The handler asserted isinstance(item, _Item) internally — reaching
+    # here with the right JSON back proves the cast AND the serialisation
+    # of the returned BaseModel both worked.
+    assert result == '{"id": "abc", "name": "Widget"}'
+
+
+async def test_input_model_casts_list_of_basemodels() -> None:
+    server = grpc.aio.server()
+    bind_service(server, "list_items", handler_factory=lambda: _EchoHandler(), input_model=list[_Item])
+    port = server.add_insecure_port("127.0.0.1:0")
+    await server.start()
+    try:
+        result = await _call(port, "list_items", [{"id": "a", "name": "A"}, {"id": "b", "name": "B"}])
+        assert result == '[{"id": "a", "name": "A"}, {"id": "b", "name": "B"}]'
+    finally:
+        await server.stop(None)
+
+
+async def test_invalid_input_categorises_as_invalid_argument() -> None:
+    server = grpc.aio.server()
+    bind_service(server, "create_item", handler_factory=lambda: _CreateItemLikeHandler(), input_model=_Item)
+    port = server.add_insecure_port("127.0.0.1:0")
+    await server.start()
+    try:
+        channel = grpc.aio.insecure_channel(f"127.0.0.1:{port}")
+        stub = generic_pb2_grpc.GenericServiceStub(channel)
+        import json
+
+        with pytest.raises(grpc.aio.AioRpcError) as exc_info:
+            await stub.Call(
+                generic_pb2.GenericRequest(json_payload=json.dumps({"id": "abc"})),  # missing "name"
+                metadata=((ROUTE_METADATA_KEY, "create_item"),),
+            )
+        assert exc_info.value.code() == grpc.StatusCode.INVALID_ARGUMENT
+        await channel.close()
+    finally:
+        await server.stop(None)
+
+
+async def test_dict_result_containing_basemodels_is_serialised() -> None:
+    class _ListLikeHandler:
+        async def execute(self, value, context=None):
+            return {"items": [_Item(id="a", name="A"), _Item(id="b", name="B")], "total": 2}
+
+    server = grpc.aio.server()
+    bind_service(server, "list_items", handler_factory=lambda: _ListLikeHandler())
+    port = server.add_insecure_port("127.0.0.1:0")
+    await server.start()
+    try:
+        result = await _call(port, "list_items", None)
+        import json
+
+        assert json.loads(result) == {
+            "items": [{"id": "a", "name": "A"}, {"id": "b", "name": "B"}],
+            "total": 2,
+        }
+    finally:
+        await server.stop(None)