openframe-protocol-base 0.3.0__tar.gz → 0.4.0__tar.gz

{openframe_protocol_base-0.3.0 → openframe_protocol_base-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openframe-protocol-base
-Version: 0.3.0
+Version: 0.4.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/

{openframe_protocol_base-0.3.0 → openframe_protocol_base-0.4.0}/openframe/protocol/base/__init__.py

@@ -3,9 +3,10 @@ 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.
+construction (`context.py`), the inbound request/response conformance
+suite (`testing.py`), the session-lifecycle loop (`session.py`), and its
+own conformance suite (`session_testing.py`). No transport dependencies —
+a binding package depends on this one, never the reverse.
 
 .. stability: experimental
 """
@@ -19,6 +20,17 @@ from openframe.protocol.base.errors import (
     categorize,
     raise_for_envelope,
 )
+from openframe.protocol.base.session import (
+    open_session,
+    run_opened_session,
+    run_session,
+    send_error_event,
+)
+from openframe.protocol.base.session_testing import (
+    SessionConformanceTests,
+    SessionDriver,
+    SessionResult,
+)
 from openframe.protocol.base.testing import (
     UNEXPECTED_ERROR_SECRET,
     DriverResult,
@@ -41,4 +53,11 @@ __all__ = [
     "UNEXPECTED_ERROR_SECRET",
     "RemoteClientDriver",
     "RemoteClientConformanceTests",
+    "open_session",
+    "run_opened_session",
+    "run_session",
+    "send_error_event",
+    "SessionResult",
+    "SessionDriver",
+    "SessionConformanceTests",
 ]

openframe_protocol_base-0.4.0/openframe/protocol/base/session.py

@@ -0,0 +1,212 @@
+"""
+openframe/protocol/base/session.py
+=====================================
+`open_session` + `run_opened_session` (and `run_session`, the convenience
+wrapper combining both) — the one open/dispatch/error/close state machine
+every `SessionHandler`-based transport's `server.py` reuses, instead of
+hand-rolling it per transport. The session-lifecycle counterpart to
+`create_app`/`create_server` (M1c) — same motivation (real, demonstrated
+duplication avoided before it happens, not a hypothetical abstraction),
+applied one layer lower.
+
+**Why `open_session` is a separate function, not just the first half of
+`run_session` inline** — found by actually tracing through Starlette's
+`StreamingResponse`, not assumed: `StreamingResponse.stream_response`
+sends the `http.response.start` ASGI message (status code + headers)
+*before* it ever requests the body generator's first item. If
+`on_open`'s accept/reject decision ran *inside* that generator, a reject
+would arrive too late — the 200 status would already be on the wire,
+with no way to turn it into the 4xx/5xx `install_error_handlers` would
+otherwise produce. The same timing issue applies to a WebSocket's own
+`accept()`/handshake. So a transport must call `open_session` *before*
+constructing its `StreamingResponse`/completing its handshake, and only
+proceed to `run_opened_session` (inside the generator / after the
+handshake) once `open_session` has confirmed the handler accepted.
+
+Two different failure points, two different wire treatments — found
+while designing this, not assumed:
+
+- **`on_open` rejecting** happens *before* anything is committed — no
+  response headers sent yet (SSE), no handshake accepted yet (WebSocket).
+  `run_session` therefore lets that exception **propagate out** to the
+  caller (after still firing `on_close`/`session.close()` for contract
+  compliance — see `SessionHandler.on_close`'s own docstring: it fires
+  "however the session ended", including an `on_open` failure) so the
+  transport's own `server.py` maps it through the exact same
+  `categorize`/`build_envelope` → status-code path `install_error_handlers`
+  already uses for a plain request/response failure — a reject should
+  look like any other mapped pre-stream error, not a different shape.
+- **`on_event` raising mid-session** happens *after* the stream/handshake
+  already committed — there is no status code left to change. This is
+  sent **in-band**, via `session.send()`, as a plain dict shaped
+  `{"error": {"code", "message", "retryable", "correlation_id"}}` —
+  `build_envelope`'s own fields — regardless of the session's `TOut`,
+  since a transport's wire format (JSON, for both transports this repo
+  builds today) already serialises a plain dict alongside whatever `TOut`
+  normally produces.
+
+`asyncio.CancelledError` (not `Exception` — it subclasses `BaseException`
+and is deliberately not caught by the `except Exception` branch below) is
+treated as `CloseReason.CLIENT_DISCONNECT`, then re-raised — standard
+asyncio cancellation hygiene: a cancellation is reported, never swallowed.
+A transport that needs to distinguish `SERVER_SHUTDOWN` from a genuine
+client disconnect (both commonly surface as cancellation to the task
+running `run_session`) does so by catching the re-raised
+`CancelledError` in its own shutdown path and calling
+`handler.on_close(session, CloseReason.SERVER_SHUTDOWN)` itself — outside
+`run_session`, which only knows about one connection, never server-wide
+shutdown.
+
+Dependency order:
+    protocol/base/session → protocol/base/errors, openframe.core.inbound
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import AsyncIterator, TypeVar
+
+from openframe.core.inbound import CloseReason, Session, SessionHandler
+from openframe.protocol.base.errors import build_envelope
+
+__all__ = ["open_session", "run_opened_session", "run_session", "send_error_event"]
+
+_logger = logging.getLogger(__name__)
+
+TIn = TypeVar("TIn")
+TOut = TypeVar("TOut")
+
+
+async def open_session(handler: SessionHandler[TIn, TOut], session: Session[TOut]) -> None:
+    """
+    Call `on_open(session)` — the accept/reject half of a session's
+    lifecycle, meant to run *before* a transport commits anything to the
+    wire (before constructing a `StreamingResponse`, before completing a
+    WebSocket handshake).
+
+    If `on_open` raises (a reject, or a genuine failure), `on_close`/
+    `session.close()` still fire — `on_close`'s own contract says
+    "however the session ended", including an `on_open` failure — but the
+    exception then **propagates to the caller**, since nothing has been
+    committed to the wire yet. The caller (the transport's own
+    `server.py`) is expected to let this propagate into its normal
+    request/response error handling (`install_error_handlers`'s
+    `categorize`/`build_envelope` path), exactly as any other
+    request/response failure.
+
+    On success, returns normally — the session is open and ready for
+    `run_opened_session`.
+    """
+    try:
+        await handler.on_open(session)
+    except asyncio.CancelledError:
+        await handler.on_close(session, CloseReason.CLIENT_DISCONNECT)
+        await session.close(CloseReason.CLIENT_DISCONNECT)
+        raise
+    except Exception:
+        await handler.on_close(session, CloseReason.ERROR)
+        await session.close(CloseReason.ERROR)
+        raise
+
+
+async def run_opened_session(
+    handler: SessionHandler[TIn, TOut],
+    session: Session[TOut],
+    inbound_events: AsyncIterator[TIn],
+) -> None:
+    """
+    Run the dispatch/error/close half of a session's lifecycle, assuming
+    `open_session` has already succeeded for *session*.
+
+    Iterates `inbound_events`, calling `on_event(session, event)` for
+    each, in order. `inbound_events` simply never yields for a
+    one-directional transport (SSE) — the loop executes zero times, a
+    valid lifecycle, not a special case this function needs to detect.
+
+    Any exception from `on_event` (other than `CancelledError`) is sent
+    **in-band** to the client via `session.send()` as a mapped error
+    envelope — the stream already committed by this point (that's the
+    whole reason `open_session` ran first), so there is no status code
+    left to change — and the session closes with `CloseReason.ERROR`.
+    This exception does NOT propagate — the session itself absorbs it and
+    closes gracefully.
+
+    `asyncio.CancelledError` is reported as `CloseReason.CLIENT_DISCONNECT`
+    and always re-raised — standard cancellation hygiene, never
+    swallowed. A transport that needs to distinguish `SERVER_SHUTDOWN`
+    from a genuine client disconnect (both commonly surface as
+    cancellation to the task running this function) does so by catching
+    the re-raised `CancelledError` in its own shutdown path and calling
+    `handler.on_close(session, CloseReason.SERVER_SHUTDOWN)` itself —
+    outside this function, which only knows about one connection, never
+    server-wide shutdown.
+
+    `on_close(session, reason)` and `session.close(reason)` are always
+    called exactly once, in a `finally` block, however the loop ended.
+    """
+    reason = CloseReason.COMPLETED
+    try:
+        async for event in inbound_events:
+            await handler.on_event(session, event)
+    except asyncio.CancelledError:
+        reason = CloseReason.CLIENT_DISCONNECT
+        raise
+    except Exception as exc:
+        reason = CloseReason.ERROR
+        await send_error_event(session, exc)
+    finally:
+        await handler.on_close(session, reason)
+        await session.close(reason)
+
+
+async def run_session(
+    handler: SessionHandler[TIn, TOut],
+    session: Session[TOut],
+    inbound_events: AsyncIterator[TIn],
+) -> None:
+    """
+    Convenience wrapper: `open_session` followed by `run_opened_session`.
+
+    Correct for a transport that has no "commit point" distinction to
+    worry about (e.g. an in-process caller, as every test in this
+    package's own `tests/test_session.py` is), or where the handshake has
+    already been fully committed by the time this is called. A transport
+    like SSE or WebSocket, which must decide accept/reject *before*
+    committing to the wire, calls `open_session` and `run_opened_session`
+    separately instead — see this module's own docstring for why.
+    """
+    await open_session(handler, session)
+    await run_opened_session(handler, session, inbound_events)
+
+
+async def send_error_event(session: Session, exc: BaseException) -> None:
+    """
+    Map *exc* through `build_envelope` and send it in-band as a plain
+    dict. Never raises — a session already failing is not made worse by
+    a failure to report the failure; logged instead.
+
+    Public (not `run_opened_session`-only) since a push-only transport
+    (SSE) whose handler drives its own background production — rather
+    than responding to dispatched inbound events — has no `on_event` call
+    for `run_opened_session` to wrap, and so maps its own background
+    task's failures through this directly instead. See
+    `openframe.protocol.http.sse`'s own module docstring for why it
+    doesn't route through `run_opened_session` at all.
+    """
+    envelope = build_envelope(exc, correlation_id=session.context.correlation_id)
+    try:
+        await session.send(
+            {
+                "error": {
+                    "code": envelope.code,
+                    "message": envelope.message,
+                    "retryable": envelope.retryable,
+                    "correlation_id": envelope.correlation_id,
+                }
+            }
+        )
+    except Exception:
+        _logger.warning(
+            "failed to send error event to session %s", session.context.correlation_id,
+            exc_info=True,
+        )

openframe_protocol_base-0.4.0/openframe/protocol/base/session_testing.py

@@ -0,0 +1,158 @@
+"""
+openframe/protocol/base/session_testing.py
+=============================================
+`SessionDriver` + `SessionConformanceTests` — the one conformance suite
+every inbound `SessionHandler`-based `openframe-protocol-*` binding
+proves itself against. The session-lifecycle counterpart to
+`testing.py`'s `TransportDriver`/`TransportConformanceTests`, in its own
+module (not added to `testing.py`) since the two suites share no
+scenarios — a session's `SessionDriver` methods set up an open
+connection and drive its lifecycle, not one call-and-respond exchange.
+
+Incubating here, not in `openframe-core`, mirroring `testing.py`'s own
+precedent: `openframe.core.testing.contracts.inbound`'s new
+`SessionHandlerContractTests` is shape-only (does the handler have the
+right methods) — it knows nothing about transports, in-band error
+mapping, or session-lifetime correlation ids. This suite is promoted to
+`openframe.core.testing` only after two session transports (SSE,
+WebSocket) both pass it for real — the same rule-of-three discipline
+`TransportConformanceTests`'s own docstring already applies.
+
+Covers exactly what `openframe-protocol-design.md` section 7 specifies
+for sessions: open/reject, ordered delivery, clean close, abrupt
+disconnect, and correlation id stability across the session's lifetime.
+Back-pressure is deliberately not covered here — it has no
+transport-neutral normalised shape the way open/close/delivery/
+correlation-id do; a transport-specific back-pressure test belongs in
+that transport's own test suite, not this generic one.
+
+No top-level pytest import — importable without pytest installed,
+matching `testing.py`'s own convention.
+
+Dependency order:
+    protocol/base/session_testing → protocol/base/errors, openframe.core.inbound
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from openframe.core.inbound import CloseReason
+from openframe.protocol.base.errors import ErrorCategory
+
+__all__ = ["SessionResult", "SessionDriver", "SessionConformanceTests"]
+
+
+@dataclass(frozen=True)
+class SessionResult:
+    """
+    One session's outcome, normalised to a shape every session transport
+    can produce.
+
+    Attributes:
+        opened:          Whether `on_open` accepted the session (returned
+                         normally) rather than rejecting it (raised).
+        close_reason:    The `CloseReason` the session ended with.
+        received_events: Events the client actually received, via
+                         `session.send()`, **in the order they arrived**
+                         — the thing `test_ordered_delivery` checks.
+        correlation_ids: The correlation id associated with each received
+                         event — same length as `received_events`. All
+                         entries must be identical for a well-behaved
+                         session: one `RequestContext` for the whole
+                         session, not one per event.
+        error_category:  `None` unless the session ended via `on_open`
+                         rejecting or an `on_event` exception — the
+                         `ErrorCategory` the error mapped to.
+    """
+
+    opened: bool
+    close_reason: CloseReason | None
+    received_events: tuple[Any, ...]
+    correlation_ids: tuple[str, ...]
+    error_category: ErrorCategory | None = None
+
+
+@runtime_checkable
+class SessionDriver(Protocol):
+    """
+    What a session transport's own test module implements to run this
+    suite. Each method exercises one bound `SessionHandler` scenario end
+    to end (through the real session binding, not by calling handler
+    methods directly) and returns the outcome as a `SessionResult`.
+    """
+
+    async def open_accepts(self) -> SessionResult:
+        """A session whose handler accepts, sends nothing, and closes cleanly."""
+        ...
+
+    async def open_rejects(self) -> SessionResult:
+        """A session whose handler's `on_open` raises — must never open or deliver events."""
+        ...
+
+    async def ordered_delivery(self) -> SessionResult:
+        """
+        A session whose handler sends exactly three events, in order:
+        `"event-1"`, `"event-2"`, `"event-3"`. Must arrive in that exact
+        order — proves the binding doesn't reorder or buffer out of
+        sequence.
+        """
+        ...
+
+    async def abrupt_disconnect(self) -> SessionResult:
+        """
+        A session where the client disconnects mid-session (not a clean,
+        handler-initiated close). Must close with
+        `CloseReason.CLIENT_DISCONNECT`.
+        """
+        ...
+
+    async def correlation_id_stable(self) -> SessionResult:
+        """
+        A session whose handler sends at least two events. The
+        correlation id must be identical across all of them.
+        """
+        ...
+
+
+class SessionConformanceTests:
+    """
+    Reusable pytest base class. Subclasses provide one fixture:
+
+    ``driver``
+        A fresh instance satisfying `SessionDriver`, wired to a real
+        bound `SessionHandler` over the session transport under test.
+
+    .. stability: experimental
+       New alongside `openframe-protocol-base` itself. Promotion to
+       `openframe.core.testing` is gated on two session transports (SSE,
+       WebSocket) passing this suite for real.
+    """
+
+    async def test_open_accepts(self, driver: SessionDriver) -> None:
+        result = await driver.open_accepts()
+        assert result.opened
+        assert result.close_reason is CloseReason.COMPLETED
+
+    async def test_open_rejects(self, driver: SessionDriver) -> None:
+        result = await driver.open_rejects()
+        assert not result.opened
+        assert result.close_reason is CloseReason.ERROR
+        assert result.error_category is not None
+        assert not result.received_events, "a rejected session must never deliver events"
+
+    async def test_ordered_delivery(self, driver: SessionDriver) -> None:
+        result = await driver.ordered_delivery()
+        assert result.received_events == ("event-1", "event-2", "event-3")
+
+    async def test_abrupt_disconnect_closes_with_client_disconnect(self, driver: SessionDriver) -> None:
+        result = await driver.abrupt_disconnect()
+        assert result.close_reason is CloseReason.CLIENT_DISCONNECT
+
+    async def test_correlation_id_stable_across_session(self, driver: SessionDriver) -> None:
+        result = await driver.correlation_id_stable()
+        assert len(result.correlation_ids) >= 2
+        assert len(set(result.correlation_ids)) == 1, (
+            "correlation_id must be identical across every event in one session — "
+            "one RequestContext for the session's whole lifetime, not one per event"
+        )

{openframe_protocol_base-0.3.0 → openframe_protocol_base-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openframe-protocol-base"
-version = "0.3.0"
+version = "0.4.0"
 description = "OpenFrame Microservice Suite - shared transport-neutral protocol mechanics (error mapping, RequestContext construction, inbound conformance suite)."
 readme = "README.md"
 requires-python = ">=3.11"

openframe_protocol_base-0.4.0/tests/test_session.py

@@ -0,0 +1,219 @@
+"""
+Tests for openframe.protocol.base.session's run_session — the
+open/dispatch/error/close state machine every SessionHandler-based
+transport reuses.
+"""
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from openframe.core.exceptions import AdapterConnectionError
+from openframe.core.inbound import CloseReason, RequestContext
+from openframe.core.testing import InMemorySession
+from openframe.protocol.base.session import open_session, run_opened_session, run_session
+
+
+async def _empty_events():
+    return
+    yield  # pragma: no cover — makes this a generator that never yields
+
+
+async def _events(*items):
+    for item in items:
+        yield item
+
+
+class _Handler:
+    """Configurable SessionHandler for testing run_session's state machine."""
+
+    def __init__(self, *, reject_with: BaseException | None = None, fail_on_event: BaseException | None = None):
+        self._reject_with = reject_with
+        self._fail_on_event = fail_on_event
+        self.opened = False
+        self.events: list = []
+        self.closed_with: CloseReason | None = None
+        self.close_calls = 0
+
+    async def on_open(self, session) -> None:
+        if self._reject_with is not None:
+            raise self._reject_with
+        self.opened = True
+
+    async def on_event(self, session, event) -> None:
+        if self._fail_on_event is not None:
+            raise self._fail_on_event
+        self.events.append(event)
+        await session.send(event)
+
+    async def on_close(self, session, reason: CloseReason) -> None:
+        self.closed_with = reason
+        self.close_calls += 1
+
+
+def _session() -> InMemorySession:
+    return InMemorySession(context=RequestContext(correlation_id="corr-1"))
+
+
+# ---------------------------------------------------------------------------
+# Happy path
+# ---------------------------------------------------------------------------
+
+
+async def test_run_session_accepts_and_closes_cleanly() -> None:
+    handler = _Handler()
+    session = _session()
+    await run_session(handler, session, _empty_events())
+    assert handler.opened
+    assert session.closed
+    assert session.close_reason is CloseReason.COMPLETED
+    assert handler.closed_with is CloseReason.COMPLETED
+    assert handler.close_calls == 1
+
+
+async def test_run_session_delivers_events_in_order() -> None:
+    handler = _Handler()
+    session = _session()
+    await run_session(handler, session, _events("a", "b", "c"))
+    assert handler.events == ["a", "b", "c"]
+    assert session.sent == ["a", "b", "c"]
+
+
+# ---------------------------------------------------------------------------
+# on_open rejecting — propagates, no in-band send, on_close still fires
+# ---------------------------------------------------------------------------
+
+
+async def test_run_session_reject_propagates_the_exception() -> None:
+    handler = _Handler(reject_with=PermissionError("nope"))
+    session = _session()
+    with pytest.raises(PermissionError):
+        await run_session(handler, session, _empty_events())
+
+
+async def test_run_session_reject_still_calls_on_close() -> None:
+    handler = _Handler(reject_with=PermissionError("nope"))
+    session = _session()
+    with pytest.raises(PermissionError):
+        await run_session(handler, session, _empty_events())
+    assert handler.closed_with is CloseReason.ERROR
+    assert handler.close_calls == 1
+
+
+async def test_run_session_reject_closes_the_session() -> None:
+    handler = _Handler(reject_with=PermissionError("nope"))
+    session = _session()
+    with pytest.raises(PermissionError):
+        await run_session(handler, session, _empty_events())
+    assert session.closed
+    assert session.close_reason is CloseReason.ERROR
+
+
+async def test_run_session_reject_sends_nothing_in_band() -> None:
+    """A reject never committed to the wire — nothing should be sent."""
+    handler = _Handler(reject_with=PermissionError("nope"))
+    session = _session()
+    with pytest.raises(PermissionError):
+        await run_session(handler, session, _empty_events())
+    assert session.sent == []
+
+
+# ---------------------------------------------------------------------------
+# on_event failing mid-session — in-band, does NOT propagate
+# ---------------------------------------------------------------------------
+
+
+async def test_run_session_on_event_failure_does_not_propagate() -> None:
+    handler = _Handler(fail_on_event=AdapterConnectionError("down", adapter="x", operation="get"))
+    session = _session()
+    await run_session(handler, session, _events("trigger"))  # must not raise
+
+
+async def test_run_session_on_event_failure_sends_error_envelope_in_band() -> None:
+    handler = _Handler(fail_on_event=AdapterConnectionError("down", adapter="x", operation="get"))
+    session = _session()
+    await run_session(handler, session, _events("trigger"))
+    assert len(session.sent) == 1
+    envelope = session.sent[0]["error"]
+    assert envelope["code"] == "adapter.connection"
+    assert envelope["correlation_id"] == "corr-1"
+
+
+async def test_run_session_on_event_failure_closes_with_error() -> None:
+    handler = _Handler(fail_on_event=RuntimeError("boom"))
+    session = _session()
+    await run_session(handler, session, _events("trigger"))
+    assert session.close_reason is CloseReason.ERROR
+    assert handler.closed_with is CloseReason.ERROR
+
+
+async def test_run_session_on_event_failure_unexpected_error_does_not_leak_message() -> None:
+    handler = _Handler(fail_on_event=RuntimeError("driver-internal-secret"))
+    session = _session()
+    await run_session(handler, session, _events("trigger"))
+    envelope = session.sent[0]["error"]
+    assert "driver-internal-secret" not in envelope["message"]
+
+
+# ---------------------------------------------------------------------------
+# Cancellation — reported as CLIENT_DISCONNECT, never swallowed
+# ---------------------------------------------------------------------------
+
+
+async def test_run_session_cancellation_during_events_is_client_disconnect_and_reraises() -> None:
+    class _CancellingHandler(_Handler):
+        async def on_event(self, session, event) -> None:
+            raise asyncio.CancelledError()
+
+    handler = _CancellingHandler()
+    session = _session()
+    with pytest.raises(asyncio.CancelledError):
+        await run_session(handler, session, _events("trigger"))
+    assert handler.closed_with is CloseReason.CLIENT_DISCONNECT
+    assert session.close_reason is CloseReason.CLIENT_DISCONNECT
+
+
+async def test_run_session_cancellation_during_open_is_client_disconnect_and_reraises() -> None:
+    handler = _Handler(reject_with=asyncio.CancelledError())
+    session = _session()
+    with pytest.raises(asyncio.CancelledError):
+        await run_session(handler, session, _empty_events())
+    assert handler.closed_with is CloseReason.CLIENT_DISCONNECT
+    assert session.close_reason is CloseReason.CLIENT_DISCONNECT
+
+
+# ---------------------------------------------------------------------------
+# open_session / run_opened_session called separately — the shape a
+# transport that must decide accept/reject before committing to the wire
+# (SSE, WebSocket) actually uses, rather than the combined run_session().
+# ---------------------------------------------------------------------------
+
+
+async def test_open_session_succeeds_without_running_event_loop() -> None:
+    handler = _Handler()
+    session = _session()
+    await open_session(handler, session)
+    assert handler.opened
+    assert not session.closed, "open_session alone must not close the session"
+    assert handler.close_calls == 0, "on_close belongs to run_opened_session, not open_session"
+
+
+async def test_open_session_reject_propagates_before_any_commit() -> None:
+    handler = _Handler(reject_with=PermissionError("nope"))
+    session = _session()
+    with pytest.raises(PermissionError):
+        await open_session(handler, session)
+    assert session.closed
+    assert session.close_reason is CloseReason.ERROR
+    assert handler.close_calls == 1
+
+
+async def test_run_opened_session_after_successful_open_session() -> None:
+    handler = _Handler()
+    session = _session()
+    await open_session(handler, session)
+    await run_opened_session(handler, session, _events("a", "b"))
+    assert session.sent == ["a", "b"]
+    assert session.close_reason is CloseReason.COMPLETED
+    assert handler.close_calls == 1

openframe_protocol_base-0.4.0/tests/test_session_testing.py

@@ -0,0 +1,143 @@
+"""
+Proves SessionConformanceTests itself is correct, against a real
+in-process driver that runs real SessionHandler instances through the
+real run_session()/InMemorySession — not just hand-built SessionResult
+objects — so this also doubles as an integration test of run_session
+itself, before any real session transport (SSE) exists to run the suite
+against.
+"""
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from openframe.core.exceptions import AdapterTimeoutError
+from openframe.core.inbound import CloseReason, RequestContext
+from openframe.core.testing import InMemorySession
+from openframe.protocol.base.errors import categorize
+from openframe.protocol.base.session import run_session
+from openframe.protocol.base.session_testing import (
+    SessionConformanceTests,
+    SessionDriver,
+    SessionResult,
+)
+
+
+class _AcceptingHandler:
+    async def on_open(self, session) -> None:
+        pass
+
+    async def on_event(self, session, event) -> None:
+        await session.send(event)
+
+    async def on_close(self, session, reason) -> None:
+        pass
+
+
+class _RejectingHandler:
+    async def on_open(self, session) -> None:
+        raise AdapterTimeoutError("too slow", adapter="x", operation="connect")
+
+    async def on_event(self, session, event) -> None:
+        pass
+
+    async def on_close(self, session, reason) -> None:
+        pass
+
+
+class _DisconnectingHandler:
+    async def on_open(self, session) -> None:
+        pass
+
+    async def on_event(self, session, event) -> None:
+        raise asyncio.CancelledError()
+
+    async def on_close(self, session, reason) -> None:
+        pass
+
+
+async def _empty_events():
+    return
+    yield  # pragma: no cover
+
+
+async def _events(*items):
+    for item in items:
+        yield item
+
+
+def _new_session() -> InMemorySession:
+    return InMemorySession(context=RequestContext(correlation_id="corr-driver-1"))
+
+
+class _InProcessSessionDriver:
+    """Runs real handlers through the real run_session()/InMemorySession."""
+
+    async def open_accepts(self) -> SessionResult:
+        session = _new_session()
+        await run_session(_AcceptingHandler(), session, _empty_events())
+        return SessionResult(
+            opened=True,
+            close_reason=session.close_reason,
+            received_events=tuple(session.sent),
+            correlation_ids=(session.context.correlation_id,) if session.sent else (),
+        )
+
+    async def open_rejects(self) -> SessionResult:
+        session = _new_session()
+        exc = AdapterTimeoutError("too slow", adapter="x", operation="connect")
+        try:
+            await run_session(_RejectingHandler(), session, _empty_events())
+        except AdapterTimeoutError:
+            pass
+        return SessionResult(
+            opened=False,
+            close_reason=session.close_reason,
+            received_events=tuple(session.sent),
+            correlation_ids=(),
+            error_category=categorize(exc),
+        )
+
+    async def ordered_delivery(self) -> SessionResult:
+        session = _new_session()
+        await run_session(_AcceptingHandler(), session, _events("event-1", "event-2", "event-3"))
+        return SessionResult(
+            opened=True,
+            close_reason=session.close_reason,
+            received_events=tuple(session.sent),
+            correlation_ids=(session.context.correlation_id,) * len(session.sent),
+        )
+
+    async def abrupt_disconnect(self) -> SessionResult:
+        session = _new_session()
+        try:
+            await run_session(_DisconnectingHandler(), session, _events("trigger"))
+        except asyncio.CancelledError:
+            pass
+        return SessionResult(
+            opened=True,
+            close_reason=session.close_reason,
+            received_events=tuple(session.sent),
+            correlation_ids=(),
+        )
+
+    async def correlation_id_stable(self) -> SessionResult:
+        session = _new_session()
+        await run_session(_AcceptingHandler(), session, _events("x", "y"))
+        return SessionResult(
+            opened=True,
+            close_reason=session.close_reason,
+            received_events=tuple(session.sent),
+            correlation_ids=(session.context.correlation_id,) * len(session.sent),
+        )
+
+
+class TestInProcessSessionConformance(SessionConformanceTests):
+    @pytest.fixture
+    def driver(self) -> _InProcessSessionDriver:
+        return _InProcessSessionDriver()
+
+
+def test_driver_satisfies_session_driver_protocol() -> None:
+    assert isinstance(_InProcessSessionDriver(), SessionDriver)