openframe-protocol-base 0.3.0__tar.gz

openframe_protocol_base-0.3.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_base-0.3.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.5
+Name: openframe-protocol-base
+Version: 0.3.0
+Summary: OpenFrame Microservice Suite - shared transport-neutral protocol mechanics (error mapping, RequestContext construction, inbound conformance suite).
+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: 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: opentelemetry-api>=1.24
+Provides-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'
+Description-Content-Type: text/markdown
+
+# openframe-protocol-base
+
+Shared, transport-neutral mechanics every `openframe-protocol-*` binding
+package builds on. No transport dependencies of its own.
+
+- `errors.py` — `categorize(exc) -> ErrorCategory` and `build_envelope(exc)`,
+  the one place every transport maps `OpenFrameError` (and anything else)
+  to a caller-safe error shape.
+- `context.py` — `build_request_context(headers)`, building
+  `openframe.core.inbound.RequestContext` consistently across transports
+  (trace id, then a correlation header, then a generated uuid4).
+- `testing.py` — `TransportConformanceTests` + `TransportDriver`, the
+  suite every binding proves itself against.
+
+## Wiring example
+
+```python
+from openframe.protocol.base import build_envelope, build_request_context
+
+context = build_request_context(request.headers)
+try:
+    result = await handler.execute(command, context)
+except Exception as exc:
+    envelope = build_envelope(exc, correlation_id=context.correlation_id)
+    # serialise envelope in whatever shape this transport uses
+```
+
+## Status
+
+Experimental — incubating the inbound conformance suite here until two
+transports (HTTP, gRPC) both pass it for real, per the project's own
+rule-of-three discipline for promoting shared infrastructure into
+`openframe-core`.

openframe_protocol_base-0.3.0/README.md

@@ -0,0 +1,33 @@
+# openframe-protocol-base
+
+Shared, transport-neutral mechanics every `openframe-protocol-*` binding
+package builds on. No transport dependencies of its own.
+
+- `errors.py` — `categorize(exc) -> ErrorCategory` and `build_envelope(exc)`,
+  the one place every transport maps `OpenFrameError` (and anything else)
+  to a caller-safe error shape.
+- `context.py` — `build_request_context(headers)`, building
+  `openframe.core.inbound.RequestContext` consistently across transports
+  (trace id, then a correlation header, then a generated uuid4).
+- `testing.py` — `TransportConformanceTests` + `TransportDriver`, the
+  suite every binding proves itself against.
+
+## Wiring example
+
+```python
+from openframe.protocol.base import build_envelope, build_request_context
+
+context = build_request_context(request.headers)
+try:
+    result = await handler.execute(command, context)
+except Exception as exc:
+    envelope = build_envelope(exc, correlation_id=context.correlation_id)
+    # serialise envelope in whatever shape this transport uses
+```
+
+## Status
+
+Experimental — incubating the inbound conformance suite here until two
+transports (HTTP, gRPC) both pass it for real, per the project's own
+rule-of-three discipline for promoting shared infrastructure into
+`openframe-core`.

openframe_protocol_base-0.3.0/openframe/protocol/base/__init__.py

@@ -0,0 +1,44 @@
+"""
+openframe.protocol.base
+==========================
+Shared, transport-neutral mechanics every `openframe-protocol-*` binding
+builds on: error categorisation (`errors.py`), `RequestContext`
+construction (`context.py`), and the inbound conformance suite
+(`testing.py`). No transport dependencies — a binding package depends on
+this one, never the reverse.
+
+.. stability: experimental
+"""
+from __future__ import annotations
+
+from openframe.protocol.base.context import build_request_context
+from openframe.protocol.base.errors import (
+    ErrorCategory,
+    ErrorEnvelope,
+    build_envelope,
+    categorize,
+    raise_for_envelope,
+)
+from openframe.protocol.base.testing import (
+    UNEXPECTED_ERROR_SECRET,
+    DriverResult,
+    RemoteClientConformanceTests,
+    RemoteClientDriver,
+    TransportConformanceTests,
+    TransportDriver,
+)
+
+__all__ = [
+    "ErrorCategory",
+    "ErrorEnvelope",
+    "categorize",
+    "build_envelope",
+    "raise_for_envelope",
+    "build_request_context",
+    "DriverResult",
+    "TransportDriver",
+    "TransportConformanceTests",
+    "UNEXPECTED_ERROR_SECRET",
+    "RemoteClientDriver",
+    "RemoteClientConformanceTests",
+]

openframe_protocol_base-0.3.0/openframe/protocol/base/context.py

@@ -0,0 +1,96 @@
+"""
+openframe/protocol/base/context.py
+=====================================
+Builds `openframe.core.inbound.RequestContext` for an inbound transport
+binding — the one place that decides what `correlation_id` actually is,
+so every transport does it the same way instead of each reinventing it.
+
+`RequestContext` itself is a frozen dataclass in core with no factory
+function (confirmed empty — nothing in core constructs one outside its
+own tests). `principal`/`tenant` stay `None` here; wiring real auth
+through is deferred to `openframe-infra`/security, per draft 8 section 7's
+"reserve the hook, don't implement it yet" rule — `context_enricher`
+below is that hook.
+
+Dependency order:
+    protocol/base/context → openframe.core.inbound, opentelemetry (trace API)
+"""
+from __future__ import annotations
+
+import uuid
+from typing import Callable, Mapping
+
+from opentelemetry import propagate, trace
+
+from openframe.core.inbound import RequestContext
+
+__all__ = ["build_request_context"]
+
+ContextEnricher = Callable[[RequestContext], RequestContext]
+
+
+def build_request_context(
+    headers: Mapping[str, str],
+    *,
+    correlation_header: str = "x-correlation-id",
+    context_enricher: ContextEnricher | None = None,
+) -> RequestContext:
+    """
+    Build a `RequestContext` for one inbound request.
+
+    `correlation_id` resolution order (first match wins):
+
+    1. The trace id from an incoming W3C `traceparent` header, extracted
+       directly from *this request's own headers* — not from whatever
+       OTel span happens to be ambiently active. This distinction is
+       the fix for a real bug found while building this: `TelemetryMiddleware`
+       starts a span for *every* request regardless of whether one
+       actually propagated in from a caller, so checking
+       `trace.get_current_span()` (ambient state) can never tell "a
+       trace genuinely arrived" apart from "a fresh local span with no
+       upstream caller" — it would always win, making step 2 below
+       unreachable in practice. Extracting straight from `headers`
+       avoids that: no incoming `traceparent` means no trace id here,
+       full stop, regardless of what span is locally active.
+    2. The `correlation_header` request header (default
+       `X-Correlation-ID`), for a caller that sends its own id without
+       a trace context.
+    3. A freshly generated `uuid4`, so `correlation_id` is never empty.
+
+    Args:
+        headers:            The inbound request's headers. Lookup is
+                            case-insensitive — pass whatever mapping the
+                            transport already has; most ASGI frameworks'
+                            header mappings already are.
+        correlation_header: Header name checked in step 2. Override only
+                            if a deployment uses a non-default header.
+        context_enricher:   Optional hook called with the built context
+                            before it's returned, so a caller can attach
+                            `principal`/`tenant` once real auth exists.
+                            `None` (the default) leaves both unset — this
+                            is the reserved-but-unimplemented auth seam
+                            draft 8 asks for, not a finished feature.
+
+    Returns:
+        A `RequestContext` with a non-empty `correlation_id`.
+    """
+    extracted = propagate.extract(headers)
+    span_context = trace.get_current_span(extracted).get_span_context()
+    if span_context.is_valid:
+        correlation_id = f"{span_context.trace_id:032x}"
+    else:
+        correlation_id = _get_header(headers, correlation_header) or str(uuid.uuid4())
+
+    context = RequestContext(correlation_id=correlation_id)
+    if context_enricher is not None:
+        context = context_enricher(context)
+    return context
+
+
+def _get_header(headers: Mapping[str, str], name: str) -> str | None:
+    """Case-insensitive header lookup — ASGI header mappings vary on casing."""
+    lowered = name.lower()
+    for key, value in headers.items():
+        if key.lower() == lowered:
+            return value
+    return None