openframe-protocol-http 0.5.0__tar.gz → 0.8.0__tar.gz

{openframe_protocol_http-0.5.0 → openframe_protocol_http-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openframe-protocol-http
-Version: 0.5.0
+Version: 0.8.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/
@@ -32,6 +32,7 @@ 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'
+Requires-Dist: uvicorn>=0.30; extra == 'dev'
 Provides-Extra: server
 Requires-Dist: fastapi>=0.110; extra == 'server'
 Description-Content-Type: text/markdown

{openframe_protocol_http-0.5.0 → openframe_protocol_http-0.8.0}/openframe/protocol/http/__init__.py

@@ -30,6 +30,9 @@ 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
+    from openframe.protocol.http.sse import SseSession, bind_session
+    from openframe.protocol.http.websocket import WebSocketSession, bind_websocket
+    from openframe.protocol.http.webhook import SignatureVerificationError, bind_webhook, verify_hmac_sha256
 
 __all__ = [
     "bind_query",
@@ -39,10 +42,20 @@ __all__ = [
     "HttpRemoteQueryClient",
     "HttpRemoteCommandClient",
     "RequestSpec",
+    "bind_session",
+    "SseSession",
+    "bind_websocket",
+    "WebSocketSession",
+    "bind_webhook",
+    "verify_hmac_sha256",
+    "SignatureVerificationError",
 ]
 
 _FROM_SERVER = {"bind_query", "bind_command", "install_error_handlers", "create_app"}
 _FROM_CLIENT = {"HttpRemoteQueryClient", "HttpRemoteCommandClient", "RequestSpec"}
+_FROM_SSE = {"bind_session", "SseSession"}
+_FROM_WEBSOCKET = {"bind_websocket", "WebSocketSession"}
+_FROM_WEBHOOK = {"bind_webhook", "verify_hmac_sha256", "SignatureVerificationError"}
 
 
 def __getattr__(name: str):
@@ -54,4 +67,21 @@ def __getattr__(name: str):
         from openframe.protocol.http import client
 
         return getattr(client, name)
+    if name in _FROM_SSE:
+        # Needs the [server] extra (FastAPI) — same as _FROM_SERVER, not
+        # its own extra, since SSE's dependency footprint is identical.
+        from openframe.protocol.http import sse
+
+        return getattr(sse, name)
+    if name in _FROM_WEBSOCKET:
+        # Same [server] extra as SSE — Starlette's own WebSocket support
+        # needs no package beyond FastAPI itself to build or test against.
+        from openframe.protocol.http import websocket
+
+        return getattr(websocket, name)
+    if name in _FROM_WEBHOOK:
+        # Same [server] extra — hmac/hashlib are stdlib, no new dependency.
+        from openframe.protocol.http import webhook
+
+        return getattr(webhook, name)
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

openframe_protocol_http-0.8.0/openframe/protocol/http/sse.py

@@ -0,0 +1,140 @@
+"""
+openframe/protocol/http/sse.py
+=================================
+`bind_session` — register a Server-Sent Events route backed by a
+`SessionHandler` (`openframe.core.inbound`, ADR-008), the first real
+transport to implement it. A module of `-http`, not a new package —
+per the design spec's own placement decision: SSE has no handshake
+beyond a normal HTTP GET, so it belongs with HTTP, not as its own
+transport family.
+
+**Does not use `openframe.protocol.base.session.run_opened_session`** —
+found while spiking this, not assumed. `run_opened_session` dispatches
+inbound events to `on_event`, mapping any exception it raises into an
+in-band error. SSE has **no inbound events at all** — `on_event` is
+never called (see `SessionHandler.on_event`'s own docstring) — so there
+is nothing for `run_opened_session` to dispatch. An SSE handler instead
+drives its own background production after `on_open` returns (e.g.
+`asyncio.create_task` inside `on_open`, pushing via `session.send()`
+until it calls `session.close()`), and is responsible for catching its
+own background task's failures and reporting them via the now-public
+`openframe.protocol.base.session.send_error_event` directly — the same
+mapping `run_opened_session` would have used, just invoked by the
+handler's own code instead of a generic dispatch loop with nothing to
+dispatch. `open_session` is still used, and still matters: it's the
+accept/reject half, and SSE needs that exactly as much as any other
+session transport (see that function's own docstring for why it must
+run before `StreamingResponse` is constructed, not inside it).
+
+Dependency order:
+    protocol/http/sse → protocol/base/context, protocol/base/session,
+    openframe.core.inbound
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any, Callable
+
+from fastapi import APIRouter, Request
+from fastapi.responses import StreamingResponse
+
+from openframe.core.inbound import CloseReason, RequestContext, SessionHandler
+from openframe.protocol.base.context import build_request_context
+from openframe.protocol.base.session import open_session
+
+__all__ = ["SseSession", "bind_session"]
+
+_logger = logging.getLogger(__name__)
+
+_SENTINEL = object()
+
+
+class SseSession:
+    """
+    `Session[TOut]` backed by an `asyncio.Queue` — `send()` enqueues,
+    the SSE body generator (`_drain`) dequeues and formats each item as
+    a `data: {json}\\n\\n` line. `close()` is idempotent and records the
+    *first* reason it was called with, in :attr:`close_reason` — the
+    transport reads this after the stream ends to call `on_close` with
+    the reason the session actually intended, not a generically-guessed
+    one.
+    """
+
+    def __init__(self, *, context: RequestContext) -> None:
+        self.context = context
+        self._queue: asyncio.Queue[Any] = asyncio.Queue()
+        self._closed = False
+        self.close_reason: CloseReason | None = None
+
+    async def send(self, event: Any) -> None:
+        if self._closed:
+            raise RuntimeError("cannot send on a closed session")
+        await self._queue.put(event)
+
+    async def close(self, reason: CloseReason = CloseReason.COMPLETED) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self.close_reason = reason
+        await self._queue.put(_SENTINEL)
+
+    async def _drain(self):
+        """Yields formatted SSE lines until `close()` enqueues the sentinel."""
+        while True:
+            item = await self._queue.get()
+            if item is _SENTINEL:
+                break
+            yield f"data: {json.dumps(item, default=str)}\n\n"
+
+
+def bind_session(
+    router: APIRouter,
+    path: str,
+    *,
+    handler_factory: Callable[[], SessionHandler],
+) -> None:
+    """
+    Register a GET route at *path* opening an SSE stream backed by a
+    fresh `SessionHandler` (built by `handler_factory`, called once per
+    request — a plain callable, not a FastAPI `Depends`, since there is
+    no per-request dependency graph need beyond "build me a handler").
+
+    `on_open` runs — and can reject — *before* the `StreamingResponse` is
+    constructed, so a reject becomes a normal mapped error response
+    (through `install_error_handlers`, wired by `create_app`), not a
+    stream that already sent a 200 before failing. See
+    `openframe.protocol.base.session.open_session`'s own docstring for
+    the full reasoning.
+    """
+
+    async def endpoint(request: Request) -> StreamingResponse:
+        context = build_request_context(dict(request.headers))
+        session = SseSession(context=context)
+        handler = handler_factory()
+
+        # Accept/reject before anything is committed to the wire.
+        await open_session(handler, session)
+
+        async def event_stream():
+            try:
+                async for line in session._drain():
+                    yield line
+            except asyncio.CancelledError:
+                # The ASGI framework cancels this generator's task on a
+                # real client disconnect — report it, then re-raise
+                # (standard cancellation hygiene: never swallow it).
+                await session.close(CloseReason.CLIENT_DISCONNECT)
+                raise
+            finally:
+                await handler.on_close(session, session.close_reason or CloseReason.COMPLETED)
+
+        response = StreamingResponse(event_stream(), media_type="text/event-stream")
+        # Same convention as bind_query/bind_command — one correlation id
+        # for the whole response, set once, not per-event: a session has
+        # exactly one RequestContext for its entire lifetime.
+        response.headers["X-Correlation-ID"] = context.correlation_id
+        return response
+
+    router.add_api_route(path, endpoint, methods=["GET"])

openframe_protocol_http-0.8.0/openframe/protocol/http/webhook.py

@@ -0,0 +1,152 @@
+"""
+openframe/protocol/http/webhook.py
+=====================================
+`bind_webhook` — register a webhook receiver backed by a
+`CommandHandler`/`UseCase`, verifying an HMAC signature against the
+**raw** request body before the handler ever runs.
+
+Deliberately NOT a `SessionHandler` (ADR-008) — a webhook is a one-shot
+exchange, one HTTP POST in, one ack out, exactly the shape
+`CommandHandler`/`UseCase` already fit (confirmed by the design spec's
+own text, §5.5: "`CommandHandler`/`QueryHandler` fit one-shot exchanges
+— HTTP, gRPC, webhooks..."). The one thing a webhook receiver needs that
+`bind_command` doesn't provide: proving the payload actually came from
+the claimed sender, not just that it's well-formed JSON — which needs
+the **raw** bytes, read once, verified, then parsed from those same
+bytes (not re-serialized from an already-parsed body, which wouldn't
+byte-match what was actually signed).
+
+A module of `-http`, not its own package — per the design spec's own
+placement decision ("SSE and webhook receivers as `server.py` modules"),
+alongside `sse.py`/`websocket.py`.
+
+**Signature verification is deliberately not universal.** Providers
+differ: GitHub/Shopify sign the raw body directly with HMAC-SHA256,
+hex-encoded, often prefixed (`"sha256=..."`); Stripe signs a
+timestamp+payload concatenation instead. `verify_hmac_sha256` here
+covers the common GitHub/Shopify-style case; a provider with a different
+scheme supplies its own `verify` callable to `bind_webhook` rather than
+this module trying to special-case every provider's own format.
+
+A signature failure maps straight to a 401 here, not through
+`categorize()`/`build_envelope()` — this is an authentication concern
+specific to this one binder, not a generic error shape a
+`CommandHandler`/`UseCase` would also produce, so it doesn't need a new
+`ErrorCategory` member (the existing five don't draw an
+authenticated/unauthenticated distinction, and adding one for a single
+binder's own pre-handler check would be the kind of addition `-base`'s
+own rule-of-three discipline warns against). Any error the *handler*
+itself raises after signature verification passes still flows through
+`install_error_handlers`'s normal path unchanged.
+
+Dependency order:
+    protocol/http/webhook → protocol/base/context, openframe.core.inbound
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import logging
+from typing import Any, Callable
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel
+
+from openframe.core.inbound import RequestContext
+from openframe.protocol.base.context import build_request_context
+
+__all__ = ["bind_webhook", "verify_hmac_sha256", "SignatureVerificationError"]
+
+_logger = logging.getLogger(__name__)
+
+
+class SignatureVerificationError(Exception):
+    """Raised by a `verify` callable when a webhook's signature does not match."""
+
+
+def verify_hmac_sha256(*, secret: str, raw_body: bytes, signature: str, prefix: str = "sha256=") -> None:
+    """
+    Default verifier — the common GitHub/Shopify-style scheme: HMAC-SHA256
+    over the raw body, hex-encoded, optionally prefixed.
+
+    Uses `hmac.compare_digest` — a plain `==` on digests is a timing-attack
+    surface; this is the standard library's own constant-time comparison.
+
+    Args:
+        secret:    The shared webhook secret.
+        raw_body:  The exact bytes the sender signed — not a re-serialized
+                   parse of them.
+        signature: The header value to check, e.g. `"sha256=abcd1234..."`.
+        prefix:    Stripped from `signature` before comparing, if present.
+                   Pass `""` for a provider that sends the bare hex digest
+                   with no prefix.
+
+    Raises:
+        SignatureVerificationError: If the signature does not match.
+    """
+    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
+    candidate = signature[len(prefix):] if prefix and signature.startswith(prefix) else signature
+    if not hmac.compare_digest(expected, candidate):
+        raise SignatureVerificationError("webhook signature mismatch")
+
+
+def bind_webhook(
+    router: APIRouter,
+    path: str,
+    *,
+    handler_dep: Callable[..., Any],
+    body_model: type[BaseModel],
+    signature_header: str,
+    secret: str,
+    verify: Callable[..., None] = verify_hmac_sha256,
+    status_code: int = 200,
+) -> None:
+    """
+    Register a POST route at *path* backed by a `CommandHandler`/`UseCase`,
+    verifying *signature_header*'s value against the raw request body
+    with *verify* before the handler ever runs.
+
+    Args:
+        router:           The `APIRouter` to register onto.
+        path:             Route path, e.g. `"/webhooks/github"`.
+        handler_dep:      A FastAPI dependency resolving to the handler
+                          instance for this request — same convention as
+                          `bind_command`'s own `handler_dep`.
+        body_model:       The payload's Pydantic model. Parsed directly
+                          from the same raw bytes the signature was
+                          checked against (`model_validate_json`), not
+                          FastAPI's own `Body(...)` extraction — there is
+                          only one read of the body, used for both.
+        signature_header: The request header carrying the signature, e.g.
+                          `"X-Hub-Signature-256"`.
+        secret:           The shared webhook secret passed to *verify*.
+        verify:           `(secret, raw_body, signature) -> None`, raising
+                          `SignatureVerificationError` on mismatch.
+                          Defaults to `verify_hmac_sha256`; a provider
+                          with a different scheme (e.g. Stripe's
+                          timestamp+payload concatenation) supplies its
+                          own.
+        status_code:      Defaults to 200 — most webhook providers just
+                          need an ack, not a particular response shape.
+
+    A missing or invalid signature returns 401 **before** `body_model`
+    validation or the handler ever runs — a sender that can't prove who
+    it is doesn't get to cause a validation error or a handler side
+    effect either.
+    """
+
+    async def endpoint(request: Request, __handler__: Any = Depends(handler_dep)) -> Any:
+        raw_body = await request.body()
+        signature = request.headers.get(signature_header)
+        if signature is None:
+            raise HTTPException(status_code=401, detail="missing webhook signature")
+        try:
+            verify(secret=secret, raw_body=raw_body, signature=signature)
+        except SignatureVerificationError:
+            raise HTTPException(status_code=401, detail="invalid webhook signature") from None
+
+        body = body_model.model_validate_json(raw_body)
+        context: RequestContext = build_request_context(dict(request.headers))
+        return await __handler__.execute(body, context)
+
+    router.add_api_route(path, endpoint, methods=["POST"], status_code=status_code)

openframe_protocol_http-0.8.0/openframe/protocol/http/websocket.py

@@ -0,0 +1,176 @@
+"""
+openframe/protocol/http/websocket.py
+=======================================
+`bind_websocket` — register a WebSocket route backed by a `SessionHandler`
+(`openframe.core.inbound`, ADR-008), the second real transport to
+implement it (after SSE) and the first to exercise `on_event` for real —
+WebSocket is genuinely bidirectional, unlike SSE. A module of `-http`,
+not its own package: FastAPI/Starlette's WebSocket support needs no extra
+dependency beyond `[server]` (same as `bind_session`) — serving real WS
+traffic over uvicorn needs `websockets` or `wsproto` installed, but
+that's an operational concern for whoever runs the service, not this
+package's own dependency surface (the same relationship uvicorn itself
+already has to this package).
+
+**Accept/reject timing, confirmed with a real spike (`TestClient.
+websocket_connect`), not assumed** — a WebSocket connection has no
+response body/status the way an SSE GET does, so `open_session`'s own
+"run `on_open` before committing to the wire" advice maps onto the
+`accept()` call, not a `StreamingResponse`. Calling `websocket.close()`
+*before* `accept()` sends a real rejection the client sees as a failed
+handshake — `websocket_connect` raises on `__enter__` in that case,
+confirmed directly. `on_open` therefore always runs before `accept()`; a
+handler that wants to push something immediately on accept does so from
+a background task it starts inside `on_open` itself (same pattern as
+SSE's own handlers), since `WebSocketSession.send()` accepts the
+connection on first call if it hasn't happened yet — a handler can
+decide to accept without sending anything at all (a listen-only session
+waiting on `on_event`).
+
+**`WebSocketDisconnect` is translated to `asyncio.CancelledError`**,
+confirmed necessary, not assumed: `run_opened_session`
+(`openframe-protocol-base`) only special-cases `asyncio.CancelledError`
+as `CloseReason.CLIENT_DISCONNECT` — it has no Starlette dependency of
+its own and can't know about `WebSocketDisconnect`. A real client
+disconnect during `websocket.receive_text()` raises `WebSocketDisconnect`
+to Starlette; `inbound_events()` here re-raises it as `CancelledError`
+instead, so `run_opened_session`'s existing disconnect handling applies
+unchanged rather than this module needing to duplicate it.
+
+Dependency order:
+    protocol/http/websocket → protocol/base/context, protocol/base/session,
+    openframe.core.inbound
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any, Callable
+
+from fastapi import APIRouter
+from starlette.websockets import WebSocket, WebSocketDisconnect, WebSocketState
+
+from openframe.core.inbound import CloseReason, RequestContext, SessionHandler
+from openframe.protocol.base.context import build_request_context
+from openframe.protocol.base.session import open_session, run_opened_session
+
+__all__ = ["WebSocketSession", "bind_websocket"]
+
+_logger = logging.getLogger(__name__)
+
+_CLOSE_CODES: dict[CloseReason, int] = {
+    CloseReason.COMPLETED: 1000,
+    CloseReason.SERVER_SHUTDOWN: 1001,
+    CloseReason.ERROR: 1011,
+}
+
+
+class WebSocketSession:
+    """
+    `Session[TOut]` backed directly by a Starlette `WebSocket` — no
+    intermediate queue needed (unlike `SseSession`), since `send()` can
+    just call the real socket's own `send_text()` directly.
+
+    `send()` accepts the connection on first call if it hasn't happened
+    yet, so a handler that decides to accept in `on_open` without
+    immediately sending anything (a listen-only session) still works —
+    the connection is accepted explicitly via :meth:`accept`, called by
+    `bind_websocket` right after `on_open` succeeds, not lazily deferred
+    to the first `send()`.
+    """
+
+    def __init__(self, *, websocket: WebSocket, context: RequestContext) -> None:
+        self.context = context
+        self._websocket = websocket
+        self._closed = False
+        self.close_reason: CloseReason | None = None
+
+    async def accept(self) -> None:
+        """Accept the connection if not already accepted. Idempotent."""
+        if self._websocket.client_state == WebSocketState.CONNECTING:
+            await self._websocket.accept()
+
+    async def send(self, event: Any) -> None:
+        if self._closed:
+            raise RuntimeError("cannot send on a closed session")
+        await self.accept()
+        await self._websocket.send_text(json.dumps(event, default=str))
+
+    async def close(self, reason: CloseReason = CloseReason.COMPLETED) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self.close_reason = reason
+        if self._websocket.client_state == WebSocketState.DISCONNECTED:
+            return  # the client is already gone — nothing to send
+        try:
+            await self._websocket.close(code=_CLOSE_CODES.get(reason, 1000))
+        except RuntimeError:
+            # Starlette raises if close() races a concurrent disconnect —
+            # the connection is ending either way; nothing more to do.
+            _logger.debug("websocket already closing for session %s", self.context.correlation_id)
+
+
+def bind_websocket(
+    router: APIRouter,
+    path: str,
+    *,
+    handler_factory: Callable[[], SessionHandler],
+) -> None:
+    """
+    Register a WebSocket route at *path* backed by a fresh `SessionHandler`
+    (built by `handler_factory`, called once per connection — a plain
+    callable, same convention as `bind_session`).
+
+    `on_open` runs — and can reject — before `accept()`, so a reject
+    becomes a real failed handshake (`websocket.close()` called by
+    `open_session` itself via `session.close(CloseReason.ERROR)`), not a
+    message sent after the client thinks it's connected.
+    """
+
+    async def endpoint(websocket: WebSocket) -> None:
+        context = build_request_context(dict(websocket.headers))
+        session = WebSocketSession(websocket=websocket, context=context)
+        handler = handler_factory()
+
+        try:
+            await open_session(handler, session)
+        except Exception:
+            # Already closed/rejected and reported via on_close by
+            # open_session itself — nothing left to do here.
+            return
+
+        await session.accept()
+
+        async def inbound_events():
+            try:
+                while True:
+                    # A handler can close the session itself from inside
+                    # on_event (a clean, self-initiated end, not a client
+                    # disconnect) — confirmed by testing, not assumed:
+                    # without this check, the next receive_text() call
+                    # raises WebSocketDisconnected (a different exception
+                    # than WebSocketDisconnect below) against the
+                    # already-closed socket, which this generator doesn't
+                    # otherwise know how to distinguish from a real error.
+                    # Ending the generator here instead lets
+                    # run_opened_session's loop finish normally —
+                    # CloseReason.COMPLETED, matching what actually
+                    # happened, not CloseReason.ERROR.
+                    if session._closed:
+                        return
+                    data = await websocket.receive_text()
+                    try:
+                        yield json.loads(data)
+                    except json.JSONDecodeError:
+                        yield data
+            except WebSocketDisconnect:
+                raise asyncio.CancelledError() from None
+
+        try:
+            await run_opened_session(handler, session, inbound_events())
+        except asyncio.CancelledError:
+            pass  # client disconnected — on_close/session.close already ran
+
+    router.add_api_websocket_route(path, endpoint)

{openframe_protocol_http-0.5.0 → openframe_protocol_http-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openframe-protocol-http"
-version = "0.5.0"
+version = "0.8.0"
 description = "OpenFrame Microservice Suite - HTTP/ASGI server binding for openframe.core.inbound handlers."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -40,6 +40,7 @@ dev = [
     "pytest-mock>=3.14",
     "fastapi>=0.110",
     "httpx>=0.27",
+    "uvicorn>=0.30",
 ]
 
 [[project.authors]]