openframe-protocol-grpc 0.2.0__tar.gz

openframe_protocol_grpc-0.2.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

openframe_protocol_grpc-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,57 @@
+# 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/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-0.2.0/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-0.2.0/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-0.2.0/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)