openframe-protocol-http 0.5.0__tar.gz

openframe_protocol_http-0.5.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_http-0.5.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: openframe-protocol-http
+Version: 0.5.0
+Summary: OpenFrame Microservice Suite - HTTP/ASGI server binding for openframe.core.inbound handlers.
+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: fastapi,hexagonal,http,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: httpx>=0.27; extra == 'client'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; 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: fastapi>=0.110; extra == 'server'
+Description-Content-Type: text/markdown
+
+# openframe-protocol-http
+
+HTTP/ASGI server binding. Wires a `QueryHandler`/`CommandHandler`/`UseCase`
+(`openframe.core.inbound`) to a FastAPI route through the shared error
+mapper and `RequestContext` builder in `openframe-protocol-base`, instead
+of each route hand-mapping `HTTPException`s itself.
+
+Install the `[server]` extra for the FastAPI/ASGI dependencies —
+`openframe-protocol-http[server]`.
+
+## Wiring example
+
+```python
+from openframe.protocol.http import bind_query, bind_command, install_error_handlers
+
+router = APIRouter(prefix="/items")
+
+bind_query(
+    router, "/{item_id}",
+    handler_dep=get_get_item_handler,
+    path_param=("item_id", str),
+    response_model=Item,
+    not_found_when=lambda item: item is None,
+)
+
+bind_command(
+    router, "", method="POST",
+    handler_dep=get_create_item_handler,
+    body_model=Item,
+    status_code=201,
+    response_model=Item,
+)
+
+install_error_handlers(app)
+```
+
+## Status
+
+Experimental, M1 of the project's own build plan — proves the inbound
+handler contract survives a real transport before anything else
+(HTTP client, gRPC, sessions) is attempted.

openframe_protocol_http-0.5.0/README.md

@@ -0,0 +1,41 @@
+# openframe-protocol-http
+
+HTTP/ASGI server binding. Wires a `QueryHandler`/`CommandHandler`/`UseCase`
+(`openframe.core.inbound`) to a FastAPI route through the shared error
+mapper and `RequestContext` builder in `openframe-protocol-base`, instead
+of each route hand-mapping `HTTPException`s itself.
+
+Install the `[server]` extra for the FastAPI/ASGI dependencies —
+`openframe-protocol-http[server]`.
+
+## Wiring example
+
+```python
+from openframe.protocol.http import bind_query, bind_command, install_error_handlers
+
+router = APIRouter(prefix="/items")
+
+bind_query(
+    router, "/{item_id}",
+    handler_dep=get_get_item_handler,
+    path_param=("item_id", str),
+    response_model=Item,
+    not_found_when=lambda item: item is None,
+)
+
+bind_command(
+    router, "", method="POST",
+    handler_dep=get_create_item_handler,
+    body_model=Item,
+    status_code=201,
+    response_model=Item,
+)
+
+install_error_handlers(app)
+```
+
+## Status
+
+Experimental, M1 of the project's own build plan — proves the inbound
+handler contract survives a real transport before anything else
+(HTTP client, gRPC, sessions) is attempted.

openframe_protocol_http-0.5.0/openframe/protocol/http/__init__.py

@@ -0,0 +1,57 @@
+"""
+openframe.protocol.http
+==========================
+HTTP/ASGI binding, both directions (draft 7/8's redefinition):
+
+- `bind_query`/`bind_command`/`install_error_handlers` (`server.py`,
+  needs the `[server]` extra, i.e. FastAPI) — wire a `QueryHandler`/
+  `CommandHandler`/`UseCase` to a route through the shared error mapper
+  and `RequestContext` builder in `openframe.protocol.base`.
+- `HttpRemoteQueryClient`/`HttpRemoteCommandClient` (`client.py`, needs
+  the `[client]` extra, i.e. httpx) — call another service built on
+  this platform, the outbound counterpart.
+
+Lazily imported (PEP 562, `__getattr__` below) rather than eagerly
+importing both submodules here — `server.py` needs FastAPI and
+`client.py` needs httpx, and eagerly importing both from this file
+would mean installing *either* extra alone still fails at
+`import openframe.protocol.http` with the *other* extra's missing
+dependency. Found and fixed before this ever shipped: both submodules
+were originally imported unconditionally here, silently defeating the
+`[server]`/`[client]` extras split this package's own `pyproject.toml`
+already promised.
+
+.. stability: experimental
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from openframe.protocol.http.server import bind_command, bind_query, create_app, install_error_handlers
+    from openframe.protocol.http.client import HttpRemoteCommandClient, HttpRemoteQueryClient, RequestSpec
+
+__all__ = [
+    "bind_query",
+    "bind_command",
+    "install_error_handlers",
+    "create_app",
+    "HttpRemoteQueryClient",
+    "HttpRemoteCommandClient",
+    "RequestSpec",
+]
+
+_FROM_SERVER = {"bind_query", "bind_command", "install_error_handlers", "create_app"}
+_FROM_CLIENT = {"HttpRemoteQueryClient", "HttpRemoteCommandClient", "RequestSpec"}
+
+
+def __getattr__(name: str):
+    if name in _FROM_SERVER:
+        from openframe.protocol.http import server
+
+        return getattr(server, name)
+    if name in _FROM_CLIENT:
+        from openframe.protocol.http import client
+
+        return getattr(client, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

openframe_protocol_http-0.5.0/openframe/protocol/http/client.py

@@ -0,0 +1,207 @@
+"""
+openframe/protocol/http/client.py
+====================================
+`HttpRemoteQueryClient`/`HttpRemoteCommandClient` — HTTP implementations
+of `openframe.core.remote`'s `RemoteQueryClient`/`RemoteCommandClient`,
+for calling another service built on this platform (M1b).
+
+Lifecycle, per draft 8's D10: no `BasePort`/`PluginRegistry` involvement.
+Each client owns (or borrows) a plain `httpx.AsyncClient` and exposes
+`aclose()` for a caller's own lifespan to manage directly — the same
+reasoning that kept `RemoteQueryClient`/`RemoteCommandClient` themselves
+out of the `Capability` system in the first place applies to their
+lifecycle too: there's no dynamic resolution happening, so there's
+nothing for a registry to orchestrate.
+
+Request construction deliberately mirrors `server.py`'s own
+`build_input` philosophy rather than guessing how to serialise an
+arbitrary input: a `build_request` hook returns exactly which path
+params, query params, and JSON body a given call needs. Support exactly
+the shapes `items-postgres`'s own routes need (path param only, query
+params only, JSON body only) — not a fully generic REST client.
+
+Dependency order:
+    protocol/http/client → protocol/base (errors, for the reverse mapping)
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Generic, TypeVar
+
+import httpx
+from opentelemetry import propagate
+
+from openframe.core.inbound import RequestContext
+from openframe.protocol.base.errors import ErrorCategory, ErrorEnvelope, categorize, raise_for_envelope
+
+__all__ = ["RequestSpec", "HttpRemoteQueryClient", "HttpRemoteCommandClient"]
+
+TInput = TypeVar("TInput")
+TOutput = TypeVar("TOutput")
+
+_STATUS_TO_CATEGORY: dict[int, ErrorCategory] = {
+    404: ErrorCategory.NOT_FOUND,
+    422: ErrorCategory.INVALID,
+    504: ErrorCategory.TIMEOUT,
+    503: ErrorCategory.UNAVAILABLE,
+}
+
+
+@dataclass(frozen=True)
+class RequestSpec:
+    """
+    What one call actually sends — returned by a `build_request` hook,
+    given the handler's own input value.
+
+    Attributes:
+        path_params: Substituted into the client's `path` template via
+                     `str.format(**path_params)`, e.g. `{"item_id": "abc"}`
+                     for a path of `"/items/{item_id}"`.
+        query_params: Sent as the URL query string.
+        json_body:    Sent as the request's JSON body. `None` means no
+                     body at all (correct for GET, not just "empty dict").
+    """
+
+    path_params: dict[str, Any] = field(default_factory=dict)
+    query_params: dict[str, Any] = field(default_factory=dict)
+    json_body: Any = None
+
+
+def _default_request_spec(value: Any) -> RequestSpec:
+    """
+    `build_request=None` default: if the input is falsy/None, send
+    nothing; otherwise send it as the JSON body. Covers the common
+    "one JSON-body input, no path or query params" case without
+    requiring every caller to write a trivial `build_request`.
+    """
+    if value is None:
+        return RequestSpec()
+    return RequestSpec(json_body=value)
+
+
+class _HttpRemoteCallMixin:
+    """Shared machinery both client classes below use — not public itself."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        path: str,
+        method: str,
+        client: httpx.AsyncClient | None = None,
+        build_request: Callable[[Any], RequestSpec] | None = None,
+        remote_name: str | None = None,
+    ) -> None:
+        if client is None and base_url is None:
+            raise ValueError("Either base_url or an existing client must be provided.")
+        self._client = client if client is not None else httpx.AsyncClient(base_url=base_url)
+        self._owns_client = client is None
+        self._path = path
+        self._method = method
+        self._build_request = build_request or _default_request_spec
+        self._remote_name = remote_name or f"http:{method} {path}"
+
+    async def aclose(self) -> None:
+        """Close the underlying httpx client — only if this instance created it."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def _call(self, value: Any, context: RequestContext | None) -> Any:
+        spec = self._build_request(value)
+        url = self._path.format(**spec.path_params) if spec.path_params else self._path
+
+        headers: dict[str, str] = {}
+        propagate.inject(headers)  # outgoing traceparent — joins the inbound trace, if any is active
+        if context is not None:
+            headers["X-Correlation-ID"] = context.correlation_id
+
+        try:
+            response = await self._client.request(
+                self._method, url, params=spec.query_params or None, json=spec.json_body, headers=headers
+            )
+        except httpx.TimeoutException as exc:
+            from openframe.core.exceptions import AdapterTimeoutError
+
+            raise AdapterTimeoutError(
+                f"Timed out calling {self._remote_name}", adapter=self._remote_name, operation="call", cause=exc
+            ) from exc
+        except httpx.ConnectError as exc:
+            from openframe.core.exceptions import AdapterConnectionError
+
+            raise AdapterConnectionError(
+                f"Could not connect for {self._remote_name}", adapter=self._remote_name, operation="call", cause=exc
+            ) from exc
+
+        if response.status_code < 400:
+            if response.status_code == 204 or not response.content:
+                return None
+            return response.json()
+
+        category = _STATUS_TO_CATEGORY.get(response.status_code, ErrorCategory.INTERNAL)
+        body = response.json() if response.content else {}
+        error = body.get("error", body)
+        envelope = ErrorEnvelope(
+            code=error.get("code", "unknown"),
+            message=error.get("message", f"{self._remote_name} failed with status {response.status_code}"),
+            retryable=error.get("retryable", False),
+            correlation_id=error.get("correlation_id", ""),
+        )
+        raise_for_envelope(category, envelope, remote_name=self._remote_name)
+
+
+class HttpRemoteQueryClient(_HttpRemoteCallMixin, Generic[TInput, TOutput]):
+    """
+    `RemoteQueryClient` over HTTP. Satisfies
+    `openframe.core.remote.RemoteQueryClient` structurally.
+
+    Args: see `_HttpRemoteCallMixin.__init__` — `method` defaults
+    naturally to `"GET"` for queries (pass explicitly if a query uses a
+    different verb, though that would be unusual).
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        path: str,
+        method: str = "GET",
+        client: httpx.AsyncClient | None = None,
+        build_request: Callable[[TInput], RequestSpec] | None = None,
+        remote_name: str | None = None,
+    ) -> None:
+        super().__init__(
+            base_url=base_url, path=path, method=method, client=client,
+            build_request=build_request, remote_name=remote_name,
+        )
+
+    async def execute(self, query: TInput, context: RequestContext | None = None) -> TOutput:
+        return await self._call(query, context)
+
+
+class HttpRemoteCommandClient(_HttpRemoteCallMixin, Generic[TInput]):
+    """
+    `RemoteCommandClient` over HTTP. Satisfies
+    `openframe.core.remote.RemoteCommandClient` structurally.
+
+    `method` has no default here (unlike the query client) — a command
+    is meaningfully POST, PUT, PATCH, or DELETE, and none of those is
+    clearly "the" default the way GET is for queries.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        path: str,
+        method: str,
+        client: httpx.AsyncClient | None = None,
+        build_request: Callable[[TInput], RequestSpec] | None = None,
+        remote_name: str | None = None,
+    ) -> None:
+        super().__init__(
+            base_url=base_url, path=path, method=method, client=client,
+            build_request=build_request, remote_name=remote_name,
+        )
+
+    async def execute(self, command: TInput, context: RequestContext | None = None) -> None:
+        await self._call(command, context)