openframe-protocol-grpc 0.2.0__py3-none-any.whl

openframe/protocol/grpc/__init__.py

@@ -0,0 +1,67 @@
+"""
+openframe.protocol.grpc
+==========================
+gRPC binding, both directions, same two-file schema `-http` established:
+
+- `bind_service` (`server.py`, needs the `[server]` extra) — wire a
+  `QueryHandler`/`CommandHandler`/`UseCase` to a `grpc.aio.Server` through
+  the shared error mapper and `RequestContext` builder in
+  `openframe.protocol.base`.
+- `GrpcRemoteQueryClient`/`GrpcRemoteCommandClient` (`client.py`, needs
+  the `[client]` extra) — call another service built on this platform,
+  the outbound counterpart.
+
+Unlike `-http`, both extras pull in the same underlying dependency
+(`grpcio`) — there is no separate client-only wire library the way httpx
+is separate from FastAPI. The `[server]`/`[client]` split is kept anyway,
+for the same reason `-http` has it: so a package that only ever calls out
+(never serves) doesn't need to reason about why a server dependency is
+present, even if today that dependency happens to be identical.
+
+Lazily imported (PEP 562, `__getattr__` below), matching `-http`'s own
+`__init__.py` exactly — not because the dependency differs here, but
+because the *schema* is the point: every future `openframe-protocol-*`
+package follows this same lazy-import shape regardless of whether a given
+transport's own extras happen to overlap.
+
+`generic_pb2`/`generic_pb2_grpc` (the compiled `.proto` stubs) are
+re-exported too, but not lazily — they need `grpcio` either way, the same
+as everything else in this package, so there is no extras boundary for
+them to respect.
+
+.. stability: experimental
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from openframe.protocol.grpc import generic_pb2, generic_pb2_grpc
+
+if TYPE_CHECKING:
+    from openframe.protocol.grpc.client import GrpcRemoteCommandClient, GrpcRemoteQueryClient
+    from openframe.protocol.grpc.server import ROUTE_METADATA_KEY, bind_service, create_server
+
+__all__ = [
+    "bind_service",
+    "ROUTE_METADATA_KEY",
+    "create_server",
+    "GrpcRemoteQueryClient",
+    "GrpcRemoteCommandClient",
+    "generic_pb2",
+    "generic_pb2_grpc",
+]
+
+_FROM_SERVER = {"bind_service", "ROUTE_METADATA_KEY", "create_server"}
+_FROM_CLIENT = {"GrpcRemoteQueryClient", "GrpcRemoteCommandClient"}
+
+
+def __getattr__(name: str):
+    if name in _FROM_SERVER:
+        from openframe.protocol.grpc import server
+
+        return getattr(server, name)
+    if name in _FROM_CLIENT:
+        from openframe.protocol.grpc import client
+
+        return getattr(client, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

openframe/protocol/grpc/client.py

@@ -0,0 +1,121 @@
+"""
+openframe/protocol/grpc/client.py
+=====================================
+`GrpcRemoteQueryClient`/`GrpcRemoteCommandClient` — gRPC implementations
+of `openframe.core.remote`'s `RemoteQueryClient`/`RemoteCommandClient`,
+the gRPC counterpart of `-http`'s `HttpRemoteQueryClient`/
+`HttpRemoteCommandClient`.
+
+No `RequestSpec`-equivalent needed — simpler than the HTTP client's
+`build_request` hook, not a weaker version of it. gRPC has no path/query/
+body split: a request is just one message (`GenericRequest`), so the
+handler's input value is JSON-encoded into `json_payload` directly, no
+hook required to decide where each piece of it goes.
+
+Lifecycle, per draft 8's D10 (same reasoning as `-http`'s client.py):
+no `BasePort`/`PluginRegistry` involvement. Each client owns (or borrows)
+a plain `grpc.aio.Channel` and exposes `aclose()` for a caller's own
+lifespan to manage directly.
+
+Dependency order:
+    protocol/grpc/client → protocol/base (errors, for the reverse mapping), protocol/grpc (generic_pb2*)
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Generic, TypeVar
+
+import grpc
+
+from openframe.core.inbound import RequestContext
+from openframe.protocol.base.errors import ErrorCategory, ErrorEnvelope, raise_for_envelope
+from openframe.protocol.grpc import generic_pb2, generic_pb2_grpc
+from openframe.protocol.grpc.server import ROUTE_METADATA_KEY
+
+__all__ = ["GrpcRemoteQueryClient", "GrpcRemoteCommandClient"]
+
+TInput = TypeVar("TInput")
+TOutput = TypeVar("TOutput")
+
+_STATUS_CODE_TO_CATEGORY: dict[grpc.StatusCode, ErrorCategory] = {
+    grpc.StatusCode.NOT_FOUND: ErrorCategory.NOT_FOUND,
+    grpc.StatusCode.INVALID_ARGUMENT: ErrorCategory.INVALID,
+    grpc.StatusCode.DEADLINE_EXCEEDED: ErrorCategory.TIMEOUT,
+    grpc.StatusCode.UNAVAILABLE: ErrorCategory.UNAVAILABLE,
+}
+
+
+class _GrpcRemoteCallMixin:
+    """Shared machinery both client classes below use — not public itself."""
+
+    def __init__(
+        self,
+        *,
+        target: str | None = None,
+        route: str,
+        channel: "grpc.aio.Channel | None" = None,
+        remote_name: str | None = None,
+    ) -> None:
+        if channel is None and target is None:
+            raise ValueError("Either target or an existing channel must be provided.")
+        self._channel = channel if channel is not None else grpc.aio.insecure_channel(target)
+        self._owns_channel = channel is None
+        self._stub = generic_pb2_grpc.GenericServiceStub(self._channel)
+        self._route = route
+        self._remote_name = remote_name or f"grpc:{route}"
+
+    async def aclose(self) -> None:
+        """Close the underlying channel — only if this instance created it."""
+        if self._owns_channel:
+            await self._channel.close()
+
+    async def _call(self, value: Any, context: RequestContext | None) -> Any:
+        metadata: list[tuple[str, str]] = [(ROUTE_METADATA_KEY, self._route)]
+        if context is not None:
+            metadata.append(("x-correlation-id", context.correlation_id))
+
+        request = generic_pb2.GenericRequest(json_payload=json.dumps(value))
+
+        try:
+            response = await self._stub.Call(request, metadata=tuple(metadata))
+        except grpc.aio.AioRpcError as exc:
+            category = _STATUS_CODE_TO_CATEGORY.get(exc.code(), ErrorCategory.INTERNAL)
+            details = exc.details() or ""
+            try:
+                body = json.loads(details)
+                error = body.get("error", body)
+            except (json.JSONDecodeError, AttributeError):
+                error = {}
+            envelope = ErrorEnvelope(
+                code=error.get("code", "unknown"),
+                message=error.get("message", details or f"{self._remote_name} failed with {exc.code()}"),
+                retryable=error.get("retryable", False),
+                correlation_id=error.get("correlation_id", ""),
+            )
+            raise_for_envelope(category, envelope, remote_name=self._remote_name)
+
+        if not response.json_payload:
+            return None
+        return json.loads(response.json_payload)
+
+
+class GrpcRemoteQueryClient(_GrpcRemoteCallMixin, Generic[TInput, TOutput]):
+    """
+    `RemoteQueryClient` over gRPC. Satisfies
+    `openframe.core.remote.RemoteQueryClient` structurally.
+
+    Args: see `_GrpcRemoteCallMixin.__init__`.
+    """
+
+    async def execute(self, query: TInput, context: RequestContext | None = None) -> TOutput:
+        return await self._call(query, context)
+
+
+class GrpcRemoteCommandClient(_GrpcRemoteCallMixin, Generic[TInput]):
+    """
+    `RemoteCommandClient` over gRPC. Satisfies
+    `openframe.core.remote.RemoteCommandClient` structurally.
+    """
+
+    async def execute(self, command: TInput, context: RequestContext | None = None) -> None:
+        await self._call(command, context)

openframe/protocol/grpc/generic.proto

@@ -0,0 +1,18 @@
+syntax = "proto3";
+package openframe.protocol.grpc;
+
+// One generic message pair instead of one per route — mirrors server.py's
+// own inspect.Signature trick for HTTP: the wire schema doesn't need to
+// know the domain type, only that a JSON-encoded payload travels inside it.
+// The actual domain type is JSON-encoded inside json_payload.
+message GenericRequest {
+  string json_payload = 1;
+}
+
+message GenericResponse {
+  string json_payload = 1;
+}
+
+service GenericService {
+  rpc Call(GenericRequest) returns (GenericResponse);
+}

openframe/protocol/grpc/generic_pb2.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: generic.proto
+# Protobuf Python Version: 7.35.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    7,
+    35,
+    1,
+    '',
+    'generic.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\rgeneric.proto\x12\x17openframe.protocol.grpc\"&\n\x0eGenericRequest\x12\x14\n\x0cjson_payload\x18\x01 \x01(\t\"\'\n\x0fGenericResponse\x12\x14\n\x0cjson_payload\x18\x01 \x01(\t2k\n\x0eGenericService\x12Y\n\x04\x43\x61ll\x12\'.openframe.protocol.grpc.GenericRequest\x1a(.openframe.protocol.grpc.GenericResponseb\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'generic_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_GENERICREQUEST']._serialized_start=42
+  _globals['_GENERICREQUEST']._serialized_end=80
+  _globals['_GENERICRESPONSE']._serialized_start=82
+  _globals['_GENERICRESPONSE']._serialized_end=121
+  _globals['_GENERICSERVICE']._serialized_start=123
+  _globals['_GENERICSERVICE']._serialized_end=230
+# @@protoc_insertion_point(module_scope)

openframe/protocol/grpc/generic_pb2_grpc.py

@@ -0,0 +1,97 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+from openframe.protocol.grpc import generic_pb2 as generic__pb2
+
+GRPC_GENERATED_VERSION = '1.84.0'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + ' but the generated code in generic_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )
+
+
+class GenericServiceStub:
+    """Missing associated documentation comment in .proto file."""
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.Call = channel.unary_unary(
+                '/openframe.protocol.grpc.GenericService/Call',
+                request_serializer=generic__pb2.GenericRequest.SerializeToString,
+                response_deserializer=generic__pb2.GenericResponse.FromString,
+                _registered_method=True)
+
+
+class GenericServiceServicer:
+    """Missing associated documentation comment in .proto file."""
+
+    def Call(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_GenericServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'Call': grpc.unary_unary_rpc_method_handler(
+                    servicer.Call,
+                    request_deserializer=generic__pb2.GenericRequest.FromString,
+                    response_serializer=generic__pb2.GenericResponse.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'openframe.protocol.grpc.GenericService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('openframe.protocol.grpc.GenericService', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class GenericService:
+    """Missing associated documentation comment in .proto file."""
+
+    @staticmethod
+    def Call(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/openframe.protocol.grpc.GenericService/Call',
+            generic__pb2.GenericRequest.SerializeToString,
+            generic__pb2.GenericResponse.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

openframe/protocol/grpc/server.py

@@ -0,0 +1,275 @@
+"""
+openframe/protocol/grpc/server.py
+=====================================
+`bind_service` — register a `grpc.aio` servicer method that calls into a
+`UseCase`/`CommandHandler`/`QueryHandler` (`openframe.core.inbound`)
+through the shared binder, the gRPC counterpart of `-http`'s
+`bind_query`/`bind_command`.
+
+One generic RPC (`GenericService.Call`) instead of one per route, mirroring
+`-http`'s own `inspect.Signature` trick for avoiding a per-route function
+signature: the wire schema (`GenericRequest`/`GenericResponse`, both just
+`{json_payload: string}`) doesn't need to know the domain type, only that
+a JSON string travels inside it. The actual handler is selected by
+`invocation_metadata()`'s `"x-openframe-route"` key, decoded on the way
+in — the gRPC equivalent of an HTTP path.
+
+No global interceptor. A wrapping function around the generated
+servicer's `Call` method achieves the same effect `install_error_handlers`
+does for HTTP — catch, categorize, `context.abort()` — without depending
+on `grpc.aio`'s own interceptor API, which was not spiked and is not
+needed for what this binder does.
+
+Spiked first (see `PLAN.md`'s "M4 — gRPC" section): confirmed `grpc.aio`
+works end to end (async server + channel), `context.abort(code, details)`
+propagates to the client as `AioRpcError.code()`/`.details()`, and
+`context.invocation_metadata()` carries key-value pairs exactly like HTTP
+headers — so `build_request_context` (built for a header-like `Mapping`)
+works unchanged here, no gRPC-specific context builder needed.
+
+Dependency order:
+    protocol/grpc/server → protocol/base (errors, context), protocol/grpc (generic_pb2*)
+"""
+from __future__ import annotations
+
+import json
+import logging
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator, Awaitable, Callable
+
+import grpc
+from pydantic import ValidationError
+
+from openframe.core.exceptions import AdapterConnectionError
+from openframe.core.inbound import RequestContext
+from openframe.core.telemetry import record_error, record_lifecycle_event, setup_telemetry, shutdown_telemetry
+from openframe.protocol.base.context import build_request_context
+from openframe.protocol.base.errors import ErrorCategory, build_envelope, categorize
+from openframe.protocol.grpc import generic_pb2, generic_pb2_grpc
+
+__all__ = ["bind_service", "ROUTE_METADATA_KEY", "create_server"]
+
+_logger = logging.getLogger(__name__)
+
+_CATEGORY_TO_STATUS_CODE: dict[ErrorCategory, grpc.StatusCode] = {
+    ErrorCategory.NOT_FOUND: grpc.StatusCode.NOT_FOUND,
+    ErrorCategory.INVALID: grpc.StatusCode.INVALID_ARGUMENT,
+    ErrorCategory.TIMEOUT: grpc.StatusCode.DEADLINE_EXCEEDED,
+    ErrorCategory.UNAVAILABLE: grpc.StatusCode.UNAVAILABLE,
+    ErrorCategory.INTERNAL: grpc.StatusCode.INTERNAL,
+}
+
+ROUTE_METADATA_KEY = "x-openframe-route"
+
+
+class _RouteRegisteringServicer(generic_pb2_grpc.GenericServiceServicer):
+    """
+    One servicer instance per `grpc.aio.Server`, holding every route
+    `bind_service` has registered on it so far — the gRPC equivalent of
+    an `APIRouter` accumulating routes before `app.include_router()`.
+    """
+
+    def __init__(self) -> None:
+        self._routes: dict[str, Callable[[Any, grpc.aio.ServicerContext], Any]] = {}
+
+    def register(self, route: str, handler: Callable[[Any, grpc.aio.ServicerContext], Any]) -> None:
+        self._routes[route] = handler
+
+    async def Call(
+        self, request: "generic_pb2.GenericRequest", context: grpc.aio.ServicerContext
+    ) -> "generic_pb2.GenericResponse":
+        metadata = dict(context.invocation_metadata())
+        route = metadata.get(ROUTE_METADATA_KEY)
+        handler = self._routes.get(route)
+        if handler is None:
+            await context.abort(grpc.StatusCode.NOT_FOUND, f"no route bound for {route!r}")
+            return  # unreachable: abort() always raises
+        return await handler(request, context)
+
+
+def _get_or_create_servicer(server: grpc.aio.Server) -> _RouteRegisteringServicer:
+    """
+    Reuse the single `_RouteRegisteringServicer` already added to *server*,
+    if `bind_service` has been called on it before — otherwise create and
+    register one. Mirrors how multiple `bind_query`/`bind_command` calls
+    share one `APIRouter` without each creating its own route table.
+    """
+    existing = getattr(server, "_openframe_generic_servicer", None)
+    if existing is not None:
+        return existing
+    servicer = _RouteRegisteringServicer()
+    generic_pb2_grpc.add_GenericServiceServicer_to_server(servicer, server)
+    server._openframe_generic_servicer = servicer  # type: ignore[attr-defined]
+    return servicer
+
+
+def bind_service(
+    server: grpc.aio.Server,
+    route: str,
+    *,
+    handler_factory: Callable[[], Any],
+    not_found_when: Callable[[Any], bool] | None = None,
+) -> None:
+    """
+    Register one route's handler on *server*, callable by a client that
+    sends `route` in its `x-openframe-route` metadata.
+
+    Args:
+        server:          The `grpc.aio.Server` to register onto. Safe to
+                         call this more than once for the same server —
+                         each call adds one route to a shared servicer,
+                         the same relationship `bind_query`/`bind_command`
+                         have to one `APIRouter`.
+        route:           Logical route name, e.g. `"get_item"` — the
+                         gRPC equivalent of an HTTP path. Not a URL
+                         template; gRPC has no path params, so the
+                         handler's own input carries whatever an HTTP
+                         path param would have (see `client.py`).
+        handler_factory: Builds a fresh handler instance for this call —
+                         the gRPC equivalent of a FastAPI dependency.
+                         Called once per request, no caching, matching
+                         `handler_dep`'s own per-request lifecycle in
+                         `-http`'s `server.py`.
+        not_found_when:  If the handler's result satisfies this, abort
+                         with `NOT_FOUND` instead of returning it.
+    """
+    servicer = _get_or_create_servicer(server)
+
+    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:
+            result = await handler.execute(handler_input, request_context)
+        except BaseException as exc:
+            await _abort_for_exception(context, exc, request_context.correlation_id)
+            return  # unreachable: _abort_for_exception always raises
+
+        if not_found_when is not None and not_found_when(result):
+            await context.abort(grpc.StatusCode.NOT_FOUND, "not found")
+            return  # unreachable
+
+        return generic_pb2.GenericResponse(json_payload=json.dumps(result))
+
+    servicer.register(route, _handle)
+
+
+async def _abort_for_exception(
+    context: grpc.aio.ServicerContext, exc: BaseException, correlation_id: str
+) -> None:
+    """
+    Map *exc* through the shared `categorize()`/`build_envelope()` and
+    `context.abort()` — the gRPC equivalent of `install_error_handlers`'
+    exception handlers for HTTP. One function instead of per-exception-
+    type handlers, since `context.abort()` is the one call site that
+    needs to run regardless of which category the error mapped to.
+
+    Calls `record_error()` for an INTERNAL-category error, for the same
+    reason `install_error_handlers` does: `context.abort()` raises
+    immediately and never reaches any outer recorder on its own.
+    """
+    category = categorize(exc)
+    envelope = build_envelope(exc, correlation_id=correlation_id)
+    if category is ErrorCategory.INTERNAL:
+        record_error(exc if isinstance(exc, Exception) else Exception(str(exc)))
+    status_code = _CATEGORY_TO_STATUS_CODE[category]
+    details = json.dumps(
+        {
+            "error": {
+                "code": envelope.code,
+                "message": envelope.message,
+                "retryable": envelope.retryable,
+                "correlation_id": envelope.correlation_id,
+            }
+        }
+    )
+    await context.abort(status_code, details)
+
+
+# ---------------------------------------------------------------------------
+# Server creation/lifecycle — the gRPC counterpart of -http's create_app
+# ---------------------------------------------------------------------------
+#
+# Named `create_server` for naming symmetry with `-http`'s `create_app`, but
+# shaped differently on purpose, not by oversight: FastAPI's app object is
+# just configuration handed off to an external process (uvicorn) that owns
+# the actual accept loop, so `create_app` can hand back a plain `FastAPI`
+# instance and be done. `grpc.aio.Server` has no external process to hand
+# off to — THIS process owns start()/stop() directly, and routes
+# (`bind_service` calls) must be registered before `start()`, not after.
+# An async context manager is the shape that actually fits that lifecycle,
+# not a plain factory function returning an unstarted server.
+
+
+@asynccontextmanager
+async def create_server(
+    *,
+    address: str,
+    configure: Callable[["grpc.aio.Server"], None],
+    on_startup: Callable[[], Awaitable[None]],
+    on_shutdown: Callable[[], Awaitable[None]],
+    degraded_mode_exceptions: tuple[type[BaseException], ...] = (AdapterConnectionError, ValidationError),
+) -> AsyncIterator["grpc.aio.Server"]:
+    """
+    Async context manager yielding a started `grpc.aio.Server`, with the
+    same telemetry-setup / degraded-mode-startup / telemetry-shutdown shape
+    `-http`'s `create_app` gives FastAPI — the gRPC counterpart of the
+    lifespan block every validation-framework HTTP service hand-wrote
+    identically.
+
+    Args:
+        address:     Passed to `server.add_insecure_port()`, e.g. `"[::]:50051"`.
+        configure:   Called with the bare `grpc.aio.server()` instance
+                     before `on_startup`/`start()` — this is where the
+                     caller's own `bind_service(server, ...)` calls belong,
+                     since gRPC requires routes registered before start().
+        on_startup:  Awaited after `configure`, before `add_insecure_port`/
+                     `start()`. Any exception in `degraded_mode_exceptions`
+                     is caught and logged as a warning rather than
+                     preventing the server from starting — the same
+                     tolerance `create_app` gives a not-yet-ready backend.
+        on_shutdown: Awaited after the `with` block exits, before
+                     `server.stop()`.
+        degraded_mode_exceptions: Same default pair `create_app` uses.
+
+    Usage::
+
+        async with create_server(
+            address="[::]:50051",
+            configure=lambda server: bind_service(server, "get_item", handler_factory=get_get_item_handler),
+            on_startup=dependencies.initialise,
+            on_shutdown=dependencies.shutdown,
+        ) as server:
+            await server.wait_for_termination()
+    """
+    setup_telemetry()
+    record_lifecycle_event("cold_start")
+
+    server = grpc.aio.server()
+    configure(server)
+
+    try:
+        await on_startup()
+    except degraded_mode_exceptions as exc:
+        _logger.warning("dependency not ready at startup: %s — running in degraded mode", exc)
+
+    port = server.add_insecure_port(address)
+    # Stashed the same way bind_service's own _get_or_create_servicer already
+    # stashes _openframe_generic_servicer on the server — the real bound
+    # port matters when address ends in ":0" (an OS-assigned port, the
+    # pattern every other conformance test in this repo uses for an
+    # isolated, parallel-safe test server). A fixed real address doesn't
+    # need this at all; it's here for exactly that ephemeral-port case.
+    server._openframe_bound_port = port  # type: ignore[attr-defined]
+    await server.start()
+    try:
+        yield server
+    finally:
+        await on_shutdown()
+        await server.stop(None)
+        shutdown_telemetry()

openframe_protocol_grpc-0.2.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: openframe-protocol-grpc
+Version: 0.2.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/
+Project-URL: Repository, https://github.com/Furious-Meteors/openframe-protocol
+Project-URL: Changelog, https://github.com/Furious-Meteors/openframe-protocol/blob/production/.github/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/Furious-Meteors/openframe-protocol/issues
+Author-email: Furious Meteors Engineering <engineering@furiousmeteors.dev>
+Maintainer-email: Furious Meteors Engineering <engineering@furiousmeteors.dev>
+License: MIT
+Keywords: grpc,hexagonal,microservice,openframe,protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: openframe-core<4,>=3.2.1
+Requires-Dist: openframe-protocol-base<1,>=0.1
+Provides-Extra: client
+Requires-Dist: grpcio>=1.60; extra == 'client'
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.60; extra == 'dev'
+Requires-Dist: grpcio>=1.60; extra == 'dev'
+Requires-Dist: pydantic>=2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+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'
+Description-Content-Type: text/markdown
+
+# openframe-protocol-grpc
+
+gRPC server and client binding, the second transport (after HTTP) to prove
+`openframe-protocol-base`'s conformance suites for real. Wires a
+`QueryHandler`/`CommandHandler`/`UseCase` (`openframe.core.inbound`) to a
+`grpc.aio.Server`, and provides `GrpcRemoteQueryClient`/
+`GrpcRemoteCommandClient` for calling another service built on this
+platform — through the same shared error mapper and `RequestContext`
+builder `openframe-protocol-http` uses, not a parallel implementation.
+
+One generic RPC (`GenericService.Call`, `{json_payload: string}` in both
+directions) instead of one per route — the domain type travels as JSON
+inside the payload, the gRPC equivalent of `-http`'s dynamic
+`inspect.Signature` trick for avoiding a per-route message type.
+
+Install the `[server]` extra for a server, `[client]` extra to call one —
+both pull in `grpcio` (unlike HTTP, there's no separate client-only wire
+library for gRPC, but the extras split is kept for symmetry with every
+other `openframe-protocol-*` package).
+
+## Server-side wiring example
+
+```python
+from openframe.protocol.grpc import bind_service
+
+server = grpc.aio.server()
+
+bind_service(
+    server, "get_item",
+    handler_factory=get_get_item_handler,
+    not_found_when=lambda item: item is None,
+)
+bind_service(
+    server, "create_item",
+    handler_factory=get_create_item_handler,
+)
+
+server.add_insecure_port("[::]:50051")
+await server.start()
+```
+
+## Client-side wiring example
+
+```python
+from openframe.protocol.grpc import GrpcRemoteQueryClient
+
+get_item = GrpcRemoteQueryClient(target="items-service:50051", route="get_item")
+item = await get_item.execute("abc-123")
+```
+
+## Status
+
+Experimental, M4 of the project's own build plan. Both
+`TransportConformanceTests` and `RemoteClientConformanceTests`
+(`openframe-protocol-base`) pass against this package for real — the
+point of building it: proving the architecture generalizes past HTTP,
+not just adding a second transport for its own sake.

openframe_protocol_grpc-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+openframe/protocol/grpc/__init__.py,sha256=ji4Qc4MtEIXoz8BkhepR_3qXcdxyjatM_QAOteco2CY,2564
+openframe/protocol/grpc/client.py,sha256=4dceAYrgwe3I6EWYa-OTu1rnmTteNPnufPHVB3Xv0Uc,4811
+openframe/protocol/grpc/generic.proto,sha256=gURefnINPc6rtma3hPNjks0VzePEj5QKim1rJCvEqb4,535
+openframe/protocol/grpc/generic_pb2.py,sha256=9P--YG2L8v3TTPaxo_YX8HWGYnmq4Yk319-_X-6En5Q,1699
+openframe/protocol/grpc/generic_pb2_grpc.py,sha256=wbrFGx4ahmYsq4qeFUaojjd4h0Lbf4lr1C9_rxWblBA,3462
+openframe/protocol/grpc/server.py,sha256=Tri13hdCXO5paN_DyX_Fvz61KwqBvyAjMkJuqQOWzfM,12407
+openframe_protocol_grpc-0.2.0.dist-info/METADATA,sha256=AK9yetjaAJNrsgJ93PgOtu3sDhTDxLOtReZ23cJILZI,3913
+openframe_protocol_grpc-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+openframe_protocol_grpc-0.2.0.dist-info/RECORD,,

openframe_protocol_grpc-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any