Validate ID tokens against discovered issuer and refreshed tokens

OIDCClient.validate_id_token compared the iss claim against
OIDCConfig.issuer (the discovery URL) instead of the issuer advertised by
the provider metadata. This broke Microsoft Entra ID, whose v2 metadata
advertises the templated issuer
https://login.microsoftonline.com/{tenantid}/v2.0 while tokens carry the
concrete tenant GUID, and it also affected tenant-domain issuers.

- Validate iss against the discovered metadata issuer and substitute
  {tenantid} with the token's tid claim.
- Catch jwt.PyJWTError in the OIDC callback so invalid tokens return 400
  instead of 500 (InvalidIssuerError is not a ValueError).
- Re-enable aud/exp/iat/nbf checks for unsigned (alg: none) ID tokens.
- Validate ID tokens returned by the refresh grant before storing them,
  including nonce continuity when present and sub continuity with the
  session user.
- Document Entra ID support and update tests.

.gitea/workflows/build.yaml

@@ -60,6 +60,10 @@ jobs:
         run: |
           .venv/bin/python -m mypy -p kaya.forwarded
           .venv/bin/python -m unittest discover -s packages/kaya-forwarded/tests
+      - name: Check kaya-otel
+        run: |
+          .venv/bin/python -m mypy -p kaya.otel
+          .venv/bin/python -m unittest discover -s packages/kaya-otel/tests
       - name: Publish kaya-core artifacts
         env:
           TWINE_REPOSITORY_URL: ${{ vars.PYPI_REGISTRY_URL }}
@@ -132,3 +136,11 @@ jobs:
         run: |
           .venv/bin/pyproject-build packages/kaya-forwarded
           .venv/bin/twine upload --repository gitea packages/kaya-forwarded/dist/*.whl packages/kaya-forwarded/dist/*.tar.gz
+      - name: Publish kaya-otel artifacts
+        env:
+          TWINE_REPOSITORY_URL: ${{ vars.PYPI_REGISTRY_URL }}
+          TWINE_USERNAME: ${{ vars.PUBLISHER_USERNAME }}
+          TWINE_PASSWORD: ${{ secrets.PUBLISHER_TOKEN }}
+        run: |
+          .venv/bin/pyproject-build packages/kaya-otel
+          .venv/bin/twine upload --repository gitea packages/kaya-otel/dist/*.whl packages/kaya-otel/dist/*.tar.gz

README.md

@@ -15,6 +15,7 @@ This repository is a monorepo for the Kaya framework. The code is split into ind
 - **kaya-openapi** — automatic OpenAPI specification generation (`packages/kaya-openapi/`)
 - **kaya-cors** — CORS (Cross-Origin Resource Sharing) support (`packages/kaya-cors/`)
 - **kaya-forwarded** — trusted-proxy `Forwarded`/`X-Forwarded-*` client address resolution (`packages/kaya-forwarded/`)
+- **kaya-otel** — OpenTelemetry tracing and metrics (`packages/kaya-otel/`)
 
 Additional `kaya-*` packages can be added as new directories under `packages/`.
 
@@ -29,7 +30,7 @@ pip install --index-url https://gitea.woggioni.net/api/packages/woggioni/pypi/si
 Install the packages in development mode:
 
 ```bash
-pip install -e packages/kaya-core -e packages/kaya-rsgi -e packages/kaya-session -e packages/kaya-session-redis -e packages/kaya-session-memcache -e packages/kaya-oidc -e packages/kaya-openapi -e packages/kaya-cors -e packages/kaya-forwarded
+pip install -e packages/kaya-core -e packages/kaya-rsgi -e packages/kaya-session -e packages/kaya-session-redis -e packages/kaya-session-memcache -e packages/kaya-oidc -e packages/kaya-openapi -e packages/kaya-cors -e packages/kaya-forwarded -e packages/kaya-otel
 ```
 
 Run the example:
@@ -50,6 +51,7 @@ python -m unittest discover -s packages/kaya-oidc/tests
 python -m unittest discover -s packages/kaya-openapi/tests
 python -m unittest discover -s packages/kaya-cors/tests
 python -m unittest discover -s packages/kaya-forwarded/tests
+python -m unittest discover -s packages/kaya-otel/tests
 ```
 
 ## Static analysis
@@ -64,6 +66,7 @@ mypy -p kaya.oidc
 mypy -p kaya.openapi
 mypy -p kaya.cors
 mypy -p kaya.forwarded
+mypy -p kaya.otel
 ```
 
 ## Building packages
@@ -78,4 +81,5 @@ python -m build packages/kaya-oidc
 python -m build packages/kaya-openapi
 python -m build packages/kaya-cors
 python -m build packages/kaya-forwarded
+python -m build packages/kaya-otel
 ```

packages/kaya-core/src/kaya/core/__init__.py

@@ -4,7 +4,7 @@ from ._http_context import HttpContext
 from ._mixin import KayaMixin
 from ._tree import Tree, PathIterator
 from ._path_handler import PathHandler, Matches
-from ._websocket import WebSocket, WebSocketMessage
+from ._websocket import WebSocket, WebSocketDisconnect, WebSocketMessage
 
 
 __all__ = [
@@ -18,5 +18,6 @@ __all__ = [
     'Matches',
     'PathIterator',
     'WebSocket',
+    'WebSocketDisconnect',
     'WebSocketMessage'
 ]

packages/kaya-core/src/kaya/core/_app.py

@@ -9,7 +9,7 @@ from ._http_method import HttpMethod
 from ._mixin import KayaMixin
 from ._path_handler import Context
 from ._types import StrOrStrings
-from ._websocket import WebSocket, WebSocketMessage
+from ._websocket import WebSocket, WebSocketDisconnect, WebSocketMessage
 from ._asgi import AsgiContext, AsgiWebSocket
 from ._tree import Tree
 from ._types.asgi import LifespanScope, HTTPScope as ASGIHTTPScope, WebSocketScope as ASGIWebSocketScope
@@ -145,6 +145,9 @@ class KayaApp(AbstractKayaApp):
                 await handler.handle_request(ctx, captured)
             else:
                 await ctx.send_empty(404)
+        except Exception as exc:
+            ctx.exception = exc
+            raise
         finally:
             for hook in reversed(self._after_request_hooks):
                 await hook(ctx)
@@ -161,6 +164,15 @@ class KayaApp(AbstractKayaApp):
                 await handler.handle_request(ws, captured)
             else:
                 await ws.close(1000)
+        except WebSocketDisconnect:
+            # The peer went away while the handler was using the websocket
+            # (e.g. sending on a vanished transport). This is normal
+            # termination, not an application error, so it is not recorded
+            # on the socket nor re-raised.
+            pass
+        except Exception as exc:
+            ws.exception = exc
+            raise
         finally:
             for hook in reversed(self._after_websocket_hooks):
                 await hook(ws)
@@ -173,6 +185,10 @@ class KayaApp(AbstractKayaApp):
         for mixin in self._mixins:
             mixin.shutdown(loop)
 
+    def route_template(self, url: str, method: HttpMethod = HttpMethod.GET) -> Optional[str]:
+        """Return the registered route template that would handle ``url``."""
+        return self._tree.route_template(url, method)
+
     def route(self,
               paths: StrOrStrings,
               methods: Optional[HttpMethod | Sequence[HttpMethod]] = None,

packages/kaya-core/src/kaya/core/_asgi.py

@@ -17,7 +17,7 @@ from pwo import Maybe
 from pathlib import Path
 from ._http_method import HttpMethod
 from ._http_context import HttpContext
-from ._websocket import WebSocket, WebSocketMessage
+from ._websocket import WebSocket, WebSocketDisconnect, WebSocketMessage
 from ._types import StrOrStrings
 from ._types.asgi import HTTPScope, WebSocketScope
 
@@ -179,7 +179,16 @@ class AsgiWebSocket(WebSocket):
             # Emit a list rather than a tuple: wsproto's AcceptConnection (used
             # by httpx_ws and others) requires list concatenation.
             message['headers'] = list(encode_headers(headers))
-        await self._send(message)
+        await self._send_message(message)
+
+    async def _send_message(self, message: Mapping[str, Any]) -> None:
+        try:
+            await self._send(message)
+        except OSError as exc:
+            # ASGI servers (e.g. uvicorn) report a vanished peer with an
+            # OSError subclass; surface it as a kaya-level disconnect so
+            # handlers do not need to know about server internals.
+            raise WebSocketDisconnect(code=1006) from exc
 
     async def receive(self) -> WebSocketMessage:
         message = await self._receive()
@@ -200,13 +209,13 @@ class AsgiWebSocket(WebSocket):
             return WebSocketMessage(kind='close')
 
     async def send_text(self, data: str) -> None:
-        await self._send({'type': 'websocket.send', 'text': data})
+        await self._send_message({'type': 'websocket.send', 'text': data})
 
     async def send_bytes(self, data: bytes) -> None:
-        await self._send({'type': 'websocket.send', 'bytes': data})
+        await self._send_message({'type': 'websocket.send', 'bytes': data})
 
     async def close(self, code: int = 1000) -> None:
-        await self._send({'type': 'websocket.close', 'code': code})
+        await self._send_message({'type': 'websocket.close', 'code': code})
 
     async def __anext__(self) -> WebSocketMessage:
         message = await self.receive()

packages/kaya-core/src/kaya/core/_http_context.py

@@ -29,6 +29,7 @@ class HttpContext(ABC):
     server: Optional[Tuple[str, Optional[int]]]
     request_body: AsyncIterator[bytes]
     session: Optional[Any] = None
+    exception: Optional[BaseException] = None
 
     @abstractmethod
     async def stream_body(self,

packages/kaya-core/src/kaya/core/_mixin.py

@@ -29,9 +29,22 @@ class KayaMixin(ABC):
         pass
 
     def setup(self, loop: AbstractEventLoop) -> None:
-        """Called on lifespan startup (default: no-op)."""
+        """Called on lifespan startup (default: no-op).
+
+        Under RSGI (granian) the loop is NOT yet running when this is
+        called: schedule work on the passed ``loop`` (e.g.
+        ``loop.create_task``) instead of calling
+        ``asyncio.get_running_loop()``, which raises ``RuntimeError``
+        there. Under ASGI the lifespan runs inside a coroutine, so a
+        running loop happens to be available — do not rely on that.
+        """
         pass
 
     def shutdown(self, loop: AbstractEventLoop) -> None:
-        """Called on lifespan shutdown (default: no-op)."""
+        """Called on lifespan shutdown (default: no-op).
+
+        As with :meth:`setup`, use the passed ``loop``; it may already be
+        stopped under RSGI, so ``asyncio.get_running_loop()`` is not
+        reliable here either.
+        """
         pass

packages/kaya-core/src/kaya/core/_tree.py

@@ -237,6 +237,37 @@ class Tree:
             #     return (handler, unmatched)
         return None
 
+    def route_template(self, url: str, method: HttpMethod = HttpMethod.GET) -> Optional[str]:
+        """Return the registered route template that would handle ``url``.
+
+        Static segments are returned verbatim, ``${name}``/``${name:int}``
+        parameter matchers are reconstructed from the matched nodes, and glob
+        matchers keep their pattern. Returns ``None`` when no route (including
+        recursive fallback routes) would handle the request.
+        """
+        result = self.find_node((p for p in PathIterator(urlparse(url).path)), method)
+        if result is None:
+            return None
+        node, captured = result
+        if len(captured.unmatched_paths) > 0 and not any(handler.recursive for handler in node.handlers):
+            return None
+
+        parts: List[str] = []
+        current: Optional[Node | PathMatcher] = node
+        while current is not None:
+            if isinstance(current, Node):
+                key = current.key
+                if not isinstance(key, HttpMethod) and key != '/':
+                    parts.append(str(key))
+            elif isinstance(current, IntMatcher):
+                parts.append('${%s:int}' % current.name)
+            elif isinstance(current, StrMatcher):
+                parts.append('${%s}' % current.name)
+            elif isinstance(current, GlobMatcher):
+                parts.append(current.pattern)
+            current = current.parent
+        return '/' + '/'.join(reversed(parts)) if parts else '/'
+
     def parse(self, leaf: str, parent: Optional[Node | PathMatcher]) -> Node | PathMatcher:
         start = 0
         result = index_of_with_escape(leaf, '${', '\\', 0)

packages/kaya-core/src/kaya/core/_websocket.py

@@ -13,6 +13,41 @@ class WebSocketMessage:
     data: WebSocketData = None
 
 
+class WebSocketDisconnect(Exception):
+    """Raised when using a websocket whose peer has disconnected.
+
+    Concrete websocket implementations raise this from ``send_text()`` and
+    ``send_bytes()`` when the transport reports that the peer is gone (for
+    example when a browser tab is closed without a close handshake), so
+    handlers can catch it and stop producing output:
+
+    .. code-block:: python
+
+        try:
+            await ws.send_text('hello')
+        except WebSocketDisconnect:
+            pass
+
+    Reading from a disconnected websocket is not an error: ``receive()``
+    reports a ``close`` message and iterating with ``async for`` simply ends,
+    which is what most handlers should rely on instead.
+
+    ``code`` is a websocket close code; ``1006`` means the connection was
+    closed abnormally, without a close handshake.
+    """
+
+    code: int
+    reason: str
+
+    def __init__(self, code: int = 1006, reason: str = '') -> None:
+        self.code = code
+        self.reason = reason
+        message = f'WebSocket disconnected (code={code})'
+        if reason:
+            message = f'{message}: {reason}'
+        super().__init__(message)
+
+
 class WebSocket(ABC):
     path: str
     query_string: str
@@ -21,6 +56,7 @@ class WebSocket(ABC):
     client: Optional[Tuple[str, int]]
     server: Optional[Tuple[str, Optional[int]]]
     session: Optional[Any] = None
+    exception: Optional[BaseException] = None
 
     @abstractmethod
     async def accept(self, headers: Optional[Mapping[str, StrOrStrings]] = None) -> None:

packages/kaya-core/tests/test_asgi.py

@@ -250,3 +250,32 @@ class AsgiTest(unittest.TestCase):
             r = await client.put("/restaurants/42/menu")
             self.assertEqual(404, r.status_code)
 
+    def test_route_template(self):
+        self.assertEqual('/employee/${employee_id}',
+                         self.app.route_template('/employee/101325', HttpMethod.GET))
+        self.assertEqual('/square/${x:int}', self.app.route_template('/square/30', HttpMethod.GET))
+        self.assertIsNone(self.app.route_template('/unknown', HttpMethod.GET))
+
+    @async_test
+    async def test_exception_exposed_to_after_hooks(self):
+        app = KayaApp()
+        seen = []
+
+        async def after_request(ctx: HttpContext) -> None:
+            seen.append(ctx.exception)
+
+        app.add_after_request_hook(after_request)
+
+        @app.GET('/raises')
+        async def raises(ctx: HttpContext) -> None:
+            raise RuntimeError('boom')
+
+        transport = httpx.ASGITransport(app=app)
+        async with httpx.AsyncClient(transport=transport, base_url="http://127.0.0.1:80") as client:
+            with self.assertRaises(RuntimeError):
+                await client.get('/raises')
+
+        self.assertEqual(1, len(seen))
+        self.assertIsInstance(seen[0], RuntimeError)
+        self.assertEqual('boom', str(seen[0]))
+

packages/kaya-core/tests/test_tree.py

@@ -80,6 +80,27 @@ class TreeTest(unittest.TestCase):
                 self.assertIs(Maybe.of(handler_num).map(self.handlers.__getitem__).or_none(),
                               Maybe.of_nullable(res).map(lambda it: it[0]).or_none())
 
+    def test_route_template(self):
+        cases: Tuple[Tuple[str, HttpMethod, Optional[str]], ...] = (
+            ('/home/something', HttpMethod.GET, '/home/something'),
+            ('/home/something_else', HttpMethod.POST, '/home/something_else'),
+            ('/home/README.md', HttpMethod.GET, '/home/*.md'),
+            ('/home/something/ciao/blah/README.md', HttpMethod.GET, '/home/something/*/blah/*.md'),
+            ('/home/bar/ciao/blah/README.md', HttpMethod.GET, '/home/bar/*'),
+            ('/unknown', HttpMethod.GET, None),
+        )
+        for url, method, expected in cases:
+            with self.subTest(f'{method} {url}'):
+                self.assertEqual(expected, self.tree.route_template(url, method))
+
+    def test_route_template_with_params(self):
+        tree = Tree()
+        tree.add((p for p in ('foo', '${id:int}')), HttpMethod.PUT, self.handlers[0])
+        tree.add((p for p in ('foo', '${name}')), HttpMethod.GET, self.handlers[1])
+        self.assertEqual('/foo/${id:int}', tree.route_template('/foo/42', HttpMethod.PUT))
+        self.assertEqual('/foo/${name}', tree.route_template('/foo/bar', HttpMethod.GET))
+        self.assertIsNone(tree.route_template('/foo/bar', HttpMethod.DELETE))
+
     def test_two_method_agnostic_matchers_raise(self):
         tree = Tree()
         tree.add((p for p in ('foo', '*')), None, self.handlers[0])

packages/kaya-core/tests/test_websocket.py

@@ -1,9 +1,9 @@
 import unittest
 import httpx
 from pwo import async_test
-from httpx_ws import aconnect_ws, WebSocketDisconnect
+from httpx_ws import aconnect_ws, WebSocketDisconnect as HttpxWebSocketDisconnect
 from httpx_ws.transport import ASGIWebSocketTransport
-from kaya.core import KayaApp, WebSocket
+from kaya.core import KayaApp, WebSocket, WebSocketDisconnect, WebSocketMessage
 from kaya.core._asgi import AsgiWebSocket
 
 
@@ -66,7 +66,7 @@ class WebSocketTest(unittest.TestCase):
         transport = ASGIWebSocketTransport(app=self.app)
 
         async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
-            with self.assertRaises(WebSocketDisconnect) as cm:
+            with self.assertRaises(HttpxWebSocketDisconnect) as cm:
                 async with aconnect_ws("/unknown", client) as ws:
                     pass
 
@@ -151,3 +151,113 @@ class WebSocketTest(unittest.TestCase):
         }
         ws = AsgiWebSocket(scope, receive, send)
         self.assertEqual('ws', ws.scheme)
+
+
+class FakeWebSocket(WebSocket):
+    """Minimal in-memory websocket for exercising ``KayaApp`` directly."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        self.query_string = ''
+        self.scheme = 'ws'
+        self.headers: dict[str, list[str]] = {}
+        self.client = ('127.0.0.1', 12345)
+        self.server = ('127.0.0.1', 80)
+        self.closed: list[int] = []
+
+    async def accept(self, headers=None) -> None:
+        pass
+
+    async def receive(self) -> WebSocketMessage:
+        return WebSocketMessage(kind='close')
+
+    async def send_text(self, data: str) -> None:
+        pass
+
+    async def send_bytes(self, data: bytes) -> None:
+        pass
+
+    async def close(self, code: int = 1000) -> None:
+        self.closed.append(code)
+
+    async def __anext__(self) -> WebSocketMessage:
+        raise StopAsyncIteration
+
+
+class WebSocketDisconnectTest(unittest.TestCase):
+
+    def setUp(self):
+        self.app = KayaApp()
+
+        @self.app.websocket('/disconnect')
+        async def disconnect(ws: WebSocket) -> None:
+            await ws.accept()
+            await ws.send_text('before')
+            raise WebSocketDisconnect()
+
+        @self.app.websocket('/failure')
+        async def failure(ws: WebSocket) -> None:
+            await ws.accept()
+            raise RuntimeError('boom')
+
+    @async_test
+    async def test_disconnect_terminates_quietly(self):
+        after_hook_calls = []
+
+        async def after(ws: WebSocket) -> None:
+            after_hook_calls.append(ws)
+
+        self.app.add_after_websocket_hook(after)
+        ws = FakeWebSocket('/disconnect')
+        await self.app.handle_websocket(ws)
+        self.assertEqual([ws], after_hook_calls)
+        self.assertIsNone(ws.exception)
+
+    @async_test
+    async def test_other_errors_are_recorded_and_reraised(self):
+        ws = FakeWebSocket('/failure')
+        with self.assertRaises(RuntimeError):
+            await self.app.handle_websocket(ws)
+        self.assertIsInstance(ws.exception, RuntimeError)
+
+    @async_test
+    async def test_asgi_send_after_disconnect_raises_websocket_disconnect(self):
+        async def send(message):
+            raise OSError('client gone')
+
+        async def receive():
+            return {'type': 'websocket.disconnect', 'code': 1006}
+
+        ws = AsgiWebSocket(self._scope(), receive, send)
+        with self.assertRaises(WebSocketDisconnect) as ctx:
+            await ws.send_text('hello')
+        self.assertEqual(1006, ctx.exception.code)
+        with self.assertRaises(WebSocketDisconnect):
+            await ws.send_bytes(b'hello')
+        with self.assertRaises(WebSocketDisconnect):
+            await ws.close()
+
+    @async_test
+    async def test_asgi_accept_after_disconnect_raises_websocket_disconnect(self):
+        async def send(message):
+            raise OSError('client gone')
+
+        async def receive():
+            return {'type': 'websocket.connect'}
+
+        ws = AsgiWebSocket(self._scope(), receive, send)
+        with self.assertRaises(WebSocketDisconnect) as ctx:
+            await ws.accept()
+        self.assertEqual(1006, ctx.exception.code)
+
+    @staticmethod
+    def _scope() -> dict:
+        return {
+            'type': 'websocket',
+            'path': '/echo',
+            'query_string': b'',
+            'scheme': 'ws',
+            'client': ('127.0.0.1', 12345),
+            'server': ('127.0.0.1', 80),
+            'headers': [],
+        }

packages/kaya-oidc/README.md

@@ -40,20 +40,174 @@ async def profile(ctx: HttpContext):
 `OIDCMixin` depends on `SessionMixin`; passing only `oidc` to `KayaApp(mixins=...)`
 also works because the app applies mixin dependencies automatically.
 
+## Multiple providers
+
+Use `OIDCProviders` to run several OIDC providers in one application. Each
+config's `provider` becomes a route segment under `base_path`
+(`/auth/{provider}/login`, `/auth/{provider}/callback` and
+`/auth/{provider}/logout`), and all providers share a single `SessionMixin`:
+
+```python
+from kaya.oidc import OIDCConfig, OIDCProviders
+
+session = SessionMixin(InMemorySessionStore())
+oidc = OIDCProviders(
+    [
+        OIDCConfig(
+            issuer='https://accounts.google.com',
+            client_id=os.environ['GOOGLE_CLIENT_ID'],
+            client_secret=os.environ['GOOGLE_CLIENT_SECRET'],
+            redirect_uri='http://localhost:8000/auth/google/callback',
+            provider='google',
+        ),
+        OIDCConfig(
+            issuer='https://github.com/login/oauth',  # or any OIDC issuer
+            client_id=os.environ['GITHUB_CLIENT_ID'],
+            client_secret=os.environ['GITHUB_CLIENT_SECRET'],
+            redirect_uri='http://localhost:8000/auth/github/callback',
+            provider='github',
+        ),
+    ],
+    session=session,
+    base_path='/auth',  # optional
+)
+app = KayaApp(mixins=[session, oidc])
+
+@app.GET('/google-profile')
+@oidc.require_auth('google')
+async def google_profile(ctx: HttpContext):
+    user = oidc.get_user(ctx, 'google')
+    await ctx.send_str(200, f"Hello {user.email or user.sub}")
+
+@app.GET('/who')
+async def who(ctx: HttpContext):
+    users = oidc.get_users(ctx)                     # {provider: OIDCUser}
+    providers = oidc.logged_in_providers(ctx)       # ['google', ...]
+    await ctx.send_str(200, ', '.join(users))
+```
+
+Each provider's session state is namespaced as `oidc:{provider}:...`. Make sure
+each config's `redirect_uri` points at that provider's derived callback path.
+
+### Identity strategy
+
+`strategy` controls how many identities may coexist in the shared session:
+
+- `'single-identity'` (default): completing a login evicts every other
+  provider's identity and tokens, so the session holds exactly one user — last
+  login wins, like Spring Security. After a GitHub login, `get_user(ctx,
+  'google')` returns `None` and `require_auth('google')` redirects to the Google
+  login.
+- `'multi-identity'`: each provider stays logged in independently. Use it for
+  linked accounts, aggregating several provider APIs, or step-up flows. Logging
+  out of one provider keeps the shared session alive while another provider is
+  still logged in.
+
+```python
+oidc = OIDCProviders([google_config, github_config], session=session,
+                     strategy='multi-identity')
+```
+
+Ephemeral flow keys (`state`, `nonce`, `code_verifier`) are never evicted, so
+logins already in flight can still complete; under `'single-identity'` the last
+callback to finish wins. Under either strategy, `get_users(ctx)` only reports
+providers actually present in the session.
+
+The composable alternative is to create one `OIDCMixin` per provider, pointing
+each at distinct `login_path`/`callback_path`/`logout_path` values and sharing
+the same `SessionMixin`. The same `strategy` keyword is accepted and defaults to
+`'single-identity'`:
+
+```python
+google = OIDCMixin(google_config, session=session)
+github = OIDCMixin(github_config, session=session, strategy='multi-identity')
+app = KayaApp(mixins=[session, google, github])
+```
+
+> **Upgrading:** session keys are now prefixed with `oidc:{provider}:` (the
+> default provider is `default`). Existing logged-in users are signed out once
+> and simply re-authenticate.
+
+## Pushed authorization requests (PAR)
+
+`OIDCConfig.par` controls RFC 9126 Pushed Authorization Requests:
+
+- `'never'` (default): the authorization request travels as query parameters,
+  as before.
+- `'auto'`: push the request whenever the provider advertises a
+  `pushed_authorization_request_endpoint`; otherwise fall back to the plain
+  redirect.
+- `'always'`: always push; login raises a `RuntimeError` if the provider does
+  not support PAR.
+
+```python
+OIDCConfig(..., par='auto')
+```
+
+A provider that advertises `require_pushed_authorization_requests: true` must be
+configured with `par='auto'` or `par='always'`. With `par='never'` the login
+fails fast with a clear error instead of issuing a redirect the provider would
+reject.
+
+The same parameters as the plain authorization request (PKCE challenge,
+`state`, `nonce`, scopes, ...) are POSTed directly to the provider, and the
+browser is redirected with only `client_id` and the single-use `request_uri`.
+Request parameters therefore no longer travel through the user agent. PKCE,
+`state`, and `nonce` are still used and protect against request URI swapping.
+
+Client authentication follows the token endpoint: HTTP Basic when
+`client_secret` is set, or none for public clients. PAR with other client
+authentication methods (`private_key_jwt`, mTLS) is not supported.
+
 ## Features
 
 - Generic OIDC discovery
 - Authorization Code Flow with PKCE (S256)
 - ID token signature validation with JWKS
+- Issuer validation against discovery metadata, including support for
+  Microsoft Entra ID `{tenantid}` issuer templates
+- Refreshed ID token validation on token refresh
 - `state` and `nonce` protection
 - Session fixation defense via `regenerate_id()` after login
 - Optional userinfo endpoint fetch
 - Refresh token support
 - RP-initiated logout (when provider advertises `end_session_endpoint`)
+- Pushed Authorization Requests (RFC 9126) via `OIDCConfig.par`
+- Multiple providers in one app via `OIDCProviders` (or several `OIDCMixin` instances)
+- `single-identity` (default) or `multi-identity` session strategy
 - Composable with any other `KayaMixin` (RSGI, MCP, etc.)
 
+## Microsoft Entra ID
+
+Entra ID v2 ID tokens carry an `iss` claim of the form
+`https://login.microsoftonline.com/<tenant-id>/v2.0`, while the discovery
+metadata for the multi-tenant endpoints advertises the templated issuer
+`https://login.microsoftonline.com/{tenantid}/v2.0`. `kaya-oidc` validates the
+`iss` claim against the discovered metadata and substitutes the token's `tid`
+claim into `{tenantid}`, so both tenant-specific and multi-tenant issuers work:
+
+```python
+OIDCConfig(
+    issuer='https://login.microsoftonline.com/<tenant-id-or-domain>/v2.0',
+    client_id=os.environ['OIDC_CLIENT_ID'],
+    client_secret=os.environ['OIDC_CLIENT_SECRET'],
+    redirect_uri='https://example.com/auth/callback',
+)
+```
+
+Use a tenant-specific issuer (the tenant GUID or a verified domain name) to
+restrict logins to that tenant. The `common` and `organizations` aliases are
+multi-tenant: any tenant in that cloud can obtain an ID token that passes
+validation. If you build a multi-tenant application, check the `tid` claim
+against the tenants you trust.
+
 ## Security notes
 
+- The `iss` claim is validated against the `issuer` value of the provider's
+  discovery document, not against `OIDCConfig.issuer` (they can differ, for
+  example for Entra ID multi-tenant endpoints).
+- Refreshed ID tokens are validated before being stored; the `nonce` is also
+  checked when the refreshed token carries one.
 - The `none` signing algorithm is rejected by default.
 - Only algorithms listed in `OIDCConfig.allowed_id_token_algorithms` are accepted.
 - Always use HTTPS for `redirect_uri` in production.

packages/kaya-oidc/src/kaya/oidc/__init__.py

@@ -1,11 +1,15 @@
 from ._client import OIDCClient
-from ._config import OIDCConfig
+from ._config import OIDCConfig, PARPolicy
-from ._mixin import OIDCMixin, OIDCUser
+from ._mixin import IdentityStrategy, OIDCMixin, OIDCUser
+from ._providers import OIDCProviders
 
 
 __all__ = [
+    'IdentityStrategy',
     'OIDCClient',
     'OIDCConfig',
     'OIDCMixin',
+    'OIDCProviders',
     'OIDCUser',
+    'PARPolicy',
 ]

packages/kaya-oidc/src/kaya/oidc/_client.py

@@ -1,3 +1,4 @@
+import re
 from typing import Any, Mapping, Optional, Sequence, cast
 from urllib.parse import urlencode
 
@@ -5,9 +6,11 @@ import httpx
 import jwt
 from jwt import PyJWK
 
-from ._config import OIDCConfig
+from ._config import PARPolicy, OIDCConfig
 from ._utils import generate_nonce, generate_pkce, generate_state
 
+_TENANT_ID_PLACEHOLDER = re.compile(r'\{tenantid\}', re.IGNORECASE)
+
 
 class OIDCClient:
     """Low-level OIDC client implementing discovery, PKCE, and token validation."""
@@ -42,8 +45,14 @@ class OIDCClient:
         async with httpx.AsyncClient() as client:
             return await client.request(method, url, **kwargs)
 
-    async def build_authorization_url(self) -> tuple[str, str, str, str]:
+    async def build_authorization_url(self, par: PARPolicy = 'never') -> tuple[str, str, str, str]:
-        """Return (authorization_url, state, nonce, code_verifier)."""
+        """Return (authorization_url, state, nonce, code_verifier).
+
+        When ``par`` selects Pushed Authorization Requests (RFC 9126), the
+        authorization request parameters are POSTed to the provider's PAR
+        endpoint first and the returned URL carries only ``client_id`` and
+        ``request_uri``.
+        """
         metadata = await self._ensure_metadata()
         authorization_endpoint = metadata.get('authorization_endpoint')
         if not isinstance(authorization_endpoint, str):
@@ -54,7 +63,6 @@ class OIDCClient:
         code_verifier, code_challenge = generate_pkce()
 
         params = {
-            'client_id': self._config.client_id,
             'response_type': 'code',
             'scope': ' '.join(self._config.scopes),
             'redirect_uri': self._config.redirect_uri,
@@ -63,9 +71,67 @@ class OIDCClient:
             'code_challenge': code_challenge,
             'code_challenge_method': 'S256',
         }
-        url = authorization_endpoint + '?' + urlencode(params)
+
+        if self._use_par(metadata, par):
+            request_uri = await self._push_authorization_request(metadata, params)
+            redirect_params = {'client_id': self._config.client_id, 'request_uri': request_uri}
+        else:
+            redirect_params = {'client_id': self._config.client_id, **params}
+
+        url = authorization_endpoint + '?' + urlencode(redirect_params)
         return url, state, nonce, code_verifier
 
+    def _use_par(self, metadata: Mapping[str, Any], policy: PARPolicy) -> bool:
+        endpoint = metadata.get('pushed_authorization_request_endpoint')
+        required = metadata.get('require_pushed_authorization_requests') is True
+
+        if required:
+            if not isinstance(endpoint, str):
+                raise RuntimeError(
+                    'OIDC provider requires pushed authorization requests but does not '
+                    'advertise a pushed_authorization_request_endpoint'
+                )
+            if policy == 'never':
+                raise RuntimeError(
+                    "OIDC provider requires pushed authorization requests; set par to "
+                    "'auto' or 'always'"
+                )
+            return True
+
+        if policy == 'always':
+            if not isinstance(endpoint, str):
+                raise RuntimeError(
+                    'OIDC provider does not advertise a pushed_authorization_request_endpoint'
+                )
+            return True
+
+        return policy == 'auto' and isinstance(endpoint, str)
+
+    async def _push_authorization_request(
+        self, metadata: Mapping[str, Any], params: Mapping[str, str]
+    ) -> str:
+        endpoint = metadata.get('pushed_authorization_request_endpoint')
+        if not isinstance(endpoint, str):
+            raise RuntimeError(
+                'OIDC provider does not advertise a pushed_authorization_request_endpoint'
+            )
+
+        # RFC 9126 section 2.1: client_id is required in the body even when the
+        # client authenticates with the Authorization header.
+        data = {'client_id': self._config.client_id, **params}
+        resp = await self._request('POST', endpoint, data=data, auth=self._client_auth())
+        resp.raise_for_status()
+        body = resp.json()
+        request_uri = body.get('request_uri') if isinstance(body, Mapping) else None
+        if not isinstance(request_uri, str):
+            raise RuntimeError('PAR endpoint response is missing request_uri')
+        return request_uri
+
+    def _client_auth(self) -> Optional[tuple[str, str]]:
+        if self._config.client_secret is None:
+            return None
+        return (self._config.client_id, self._config.client_secret)
+
     async def fetch_token(self, code: str, code_verifier: str) -> Mapping[str, Any]:
         metadata = await self._ensure_metadata()
         token_endpoint = metadata.get('token_endpoint')
@@ -79,11 +145,8 @@ class OIDCClient:
             'client_id': self._config.client_id,
             'code_verifier': code_verifier,
         }
-        auth: Optional[tuple[str, str]] = None
-        if self._config.client_secret is not None:
-            auth = (self._config.client_id, self._config.client_secret)
 
-        resp = await self._request('POST', token_endpoint, data=data, auth=auth)
+        resp = await self._request('POST', token_endpoint, data=data, auth=self._client_auth())
         resp.raise_for_status()
         return cast(Mapping[str, Any], resp.json())
 
@@ -98,15 +161,35 @@ class OIDCClient:
             'refresh_token': refresh_token,
             'client_id': self._config.client_id,
         }
-        auth: Optional[tuple[str, str]] = None
-        if self._config.client_secret is not None:
-            auth = (self._config.client_id, self._config.client_secret)
 
-        resp = await self._request('POST', token_endpoint, data=data, auth=auth)
+        resp = await self._request('POST', token_endpoint, data=data, auth=self._client_auth())
         resp.raise_for_status()
         return cast(Mapping[str, Any], resp.json())
 
     async def validate_id_token(self, id_token: str, nonce: str) -> Mapping[str, Any]:
+        payload = await self._decode_id_token(id_token)
+        if payload.get('nonce') != nonce:
+            raise ValueError('ID token nonce mismatch')
+        return payload
+
+    async def validate_refreshed_id_token(
+        self,
+        id_token: str,
+        expected_nonce: Optional[str] = None,
+    ) -> Mapping[str, Any]:
+        """Validate an ID token returned by the refresh token grant.
+
+        Unlike the authorization code flow, the provider may omit the ``nonce``
+        claim; when it is present and the original nonce is known, the two must
+        match (OIDC Core 12.2).
+        """
+        payload = await self._decode_id_token(id_token)
+        token_nonce = payload.get('nonce')
+        if token_nonce is not None and expected_nonce is not None and token_nonce != expected_nonce:
+            raise ValueError('ID token nonce mismatch')
+        return payload
+
+    async def _decode_id_token(self, id_token: str) -> Mapping[str, Any]:
         header = jwt.get_unverified_header(id_token)
         alg = header.get('alg')
         if not isinstance(alg, str):
@@ -115,29 +198,59 @@ class OIDCClient:
         if alg == 'none':
             if not self._config.allow_unsigned_id_tokens:
                 raise ValueError('Unsigned ID tokens are not allowed')
+            metadata_issuer = await self._get_metadata_issuer()
             payload = jwt.decode(
                 id_token,
-                options={'verify_signature': False},
+                audience=self._config.client_id,
+                options={
+                    'verify_signature': False,
+                    'verify_aud': True,
+                    'verify_exp': True,
+                    'verify_iat': True,
+                    'verify_nbf': True,
+                },
             )
         else:
             if alg not in self._config.allowed_id_token_algorithms:
                 raise ValueError(f'ID token algorithm {alg} is not allowed')
+            metadata_issuer = await self._get_metadata_issuer()
             jwks = await self._ensure_jwks()
             signing_key = self._get_signing_key(jwks, header.get('kid'), alg)
             payload = jwt.decode(
                 id_token,
                 signing_key.key,
                 algorithms=[alg],
-                issuer=self._config.issuer,
                 audience=self._config.client_id,
             )
 
         if not isinstance(payload, dict):
             raise ValueError('ID token payload is not a JSON object')
-        if payload.get('nonce') != nonce:
+        self._validate_issuer(payload, metadata_issuer)
-            raise ValueError('ID token nonce mismatch')
         return payload
 
+    async def _get_metadata_issuer(self) -> str:
+        metadata = await self._ensure_metadata()
+        issuer = metadata.get('issuer')
+        if not isinstance(issuer, str):
+            raise RuntimeError('OIDC provider does not advertise an issuer')
+        return issuer
+
+    @staticmethod
+    def _validate_issuer(payload: Mapping[str, Any], metadata_issuer: str) -> None:
+        iss = payload.get('iss')
+        if not isinstance(iss, str):
+            raise jwt.MissingRequiredClaimError('iss')
+
+        expected = metadata_issuer
+        if _TENANT_ID_PLACEHOLDER.search(expected):
+            tenant_id = payload.get('tid')
+            if not isinstance(tenant_id, str):
+                raise jwt.InvalidIssuerError('Invalid issuer')
+            expected = _TENANT_ID_PLACEHOLDER.sub(tenant_id, expected, count=1)
+
+        if iss != expected:
+            raise jwt.InvalidIssuerError('Invalid issuer')
+
     def _get_signing_key(self, jwks: Mapping[str, Any], kid: Optional[str], alg: str) -> PyJWK:
         keys = jwks.get('keys')
         if not isinstance(keys, Sequence):

packages/kaya-oidc/src/kaya/oidc/_config.py

@@ -1,13 +1,31 @@
+import re
 from dataclasses import dataclass, field
-from typing import Any, Optional, Sequence
+from typing import Any, Literal, Optional, Sequence
 
 import httpx
 
+_PROVIDER_PATTERN = re.compile(r'^[A-Za-z0-9_-]+$')
+
+type PARPolicy = Literal['never', 'auto', 'always']
+
+_PAR_POLICIES: tuple[PARPolicy, ...] = ('never', 'auto', 'always')
+
 
 @dataclass
 class OIDCConfig:
     """Configuration for an OpenID Connect provider.
 
+    ``provider`` is a stable identifier for this provider. It namespaces the
+    session state (``oidc:{provider}:...``) so several providers can be used in
+    the same application without interfering with each other.
+
+    ``par`` selects when to use Pushed Authorization Requests (RFC 9126):
+    ``'never'`` uses a plain query-string authorization request, ``'auto'``
+    pushes the request whenever the provider advertises a
+    ``pushed_authorization_request_endpoint``, and ``'always'`` requires PAR.
+    A provider that sets ``require_pushed_authorization_requests`` is always
+    treated as requiring PAR.
+
     ``client_secret`` is optional; omit it for public clients.
     ``fetch_userinfo`` controls whether the userinfo endpoint is queried after
     token exchange.
@@ -35,8 +53,21 @@ class OIDCConfig:
         'EdDSA',
     ))
     http_client: Optional[httpx.AsyncClient] = None
+    provider: str = 'default'
+    par: PARPolicy = 'never'
 
     def __post_init__(self) -> None:
+        if not self.provider or _PROVIDER_PATTERN.match(self.provider) is None:
+            raise ValueError(
+                'provider must be a non-empty string of letters, digits, '
+                "underscores or hyphens (got "
+                f'{self.provider!r})'
+            )
+        if self.par not in _PAR_POLICIES:
+            raise ValueError(
+                f'par must be one of {", ".join(map(repr, _PAR_POLICIES))} '
+                f'(got {self.par!r})'
+            )
         scopes_list = list(self.scopes)
         if 'openid' not in scopes_list:
             self.scopes = ('openid', *scopes_list)

packages/kaya-oidc/src/kaya/oidc/_mixin.py

@@ -1,5 +1,6 @@
-from typing import Any, Awaitable, Callable, Mapping, Optional, Sequence
+from typing import Any, Awaitable, Callable, Literal, Mapping, Optional, Sequence, cast
 
+import jwt
 from kaya.core import HttpContext, KayaApp, KayaMixin
 from kaya.session import Session, SessionMixin
 from urllib.parse import parse_qs
@@ -10,6 +11,13 @@ from ._config import OIDCConfig
 
 type HttpHandler = Callable[..., Awaitable[None]]
 
+type IdentityStrategy = Literal['single-identity', 'multi-identity']
+
+_SESSION_NAMESPACE = 'oidc'
+_USER_SUFFIX = 'user'
+_IDENTITY_FIELDS = frozenset({'user', 'id_token', 'access_token', 'refresh_token'})
+_IDENTITY_STRATEGIES: tuple[IdentityStrategy, ...] = ('single-identity', 'multi-identity')
+
 
 class OIDCUser(Mapping[str, Any]):
     """Read-only view of the OIDC userinfo / ID token claims."""
@@ -28,7 +36,7 @@ class OIDCUser(Mapping[str, Any]):
 
     @property
     def sub(self) -> str:
-        return self._data['sub']
+        return cast(str, self._data['sub'])
 
     @property
     def email(self) -> Optional[str]:
@@ -56,6 +64,17 @@ class OIDCMixin(KayaMixin):
     - ``callback_path`` (default ``/auth/callback``): handles the provider callback.
     - ``logout_path`` (default ``/auth/logout``): logs the user out.
 
+    Session state is namespaced by ``OIDCConfig.provider`` as
+    ``oidc:{provider}:...`` so several providers can share one session. Use one
+    ``OIDCMixin`` per provider (with distinct route paths), or
+    :class:`~kaya.oidc.OIDCProviders` to wire several at once.
+
+    ``strategy`` controls how many identities may coexist in the session. The
+    default ``'single-identity'`` evicts every other provider's identity after a
+    successful login, so the session has exactly one user (last login wins).
+    ``'multi-identity'`` keeps each provider logged in independently, which is
+    useful for linked accounts, provider API aggregation, and step-up flows.
+
     Example::
 
         session = SessionMixin(InMemorySessionStore())
@@ -69,10 +88,33 @@ class OIDCMixin(KayaMixin):
             ...
     """
 
-    def __init__(self, config: OIDCConfig, session: SessionMixin) -> None:
+    def __init__(
+        self,
+        config: OIDCConfig,
+        session: SessionMixin,
+        strategy: IdentityStrategy = 'single-identity',
+    ) -> None:
+        if strategy not in _IDENTITY_STRATEGIES:
+            raise ValueError(
+                'strategy must be one of '
+                f'{", ".join(map(repr, _IDENTITY_STRATEGIES))} (got {strategy!r})'
+            )
         self._config = config
         self._session = session
         self._client = OIDCClient(config)
+        self._strategy = strategy
+        self._prefix = f'{_SESSION_NAMESPACE}:{config.provider}:'
+
+    @property
+    def provider(self) -> str:
+        return self._config.provider
+
+    @property
+    def strategy(self) -> IdentityStrategy:
+        return self._strategy
+
+    def _key(self, name: str) -> str:
+        return f'{self._prefix}{name}'
 
     @property
     def dependencies(self) -> Sequence[KayaMixin]:
@@ -81,11 +123,13 @@ class OIDCMixin(KayaMixin):
     def apply(self, app: KayaApp) -> None:
         @app.GET(self._config.login_path)
         async def login(ctx: HttpContext) -> None:
-            auth_url, state, nonce, code_verifier = await self._client.build_authorization_url()
+            auth_url, state, nonce, code_verifier = await self._client.build_authorization_url(
+                par=self._config.par
+            )
             session = self._session_of(ctx)
-            session['oidc_state'] = state
+            session[self._key('state')] = state
-            session['oidc_nonce'] = nonce
+            session[self._key('nonce')] = nonce
-            session['oidc_code_verifier'] = code_verifier
+            session[self._key('code_verifier')] = code_verifier
             await ctx.send_empty(302, {'Location': auth_url})
 
         @app.GET(self._config.callback_path)
@@ -108,13 +152,13 @@ class OIDCMixin(KayaMixin):
                 return
 
             session = self._session_of(ctx)
-            expected_state = session.get('oidc_state')
+            expected_state = session.get(self._key('state'))
             if state != expected_state:
                 await ctx.send_str(400, 'Invalid state')
                 return
 
-            nonce = session.get('oidc_nonce', '')
+            nonce = session.get(self._key('nonce'), '')
-            code_verifier = session.get('oidc_code_verifier', '')
+            code_verifier = session.get(self._key('code_verifier'), '')
 
             try:
                 token_response = await self._client.fetch_token(code, code_verifier)
@@ -131,31 +175,59 @@ class OIDCMixin(KayaMixin):
                     userinfo = await self._client.fetch_userinfo(access_token)
                     user.update(userinfo)
 
-                session.pop('oidc_state', None)
+                session.pop(self._key('state'), None)
-                session.pop('oidc_nonce', None)
+                session.pop(self._key('code_verifier'), None)
-                session.pop('oidc_code_verifier', None)
+                # Keep this provider's nonce so refreshed ID tokens can be
+                # checked for nonce continuity (OIDC Core 12.2).
 
-                session['oidc_user'] = user
+                session[self._key('user')] = user
-                session['oidc_id_token'] = id_token
+                session[self._key('id_token')] = id_token
                 if isinstance(access_token, str):
-                    session['oidc_access_token'] = access_token
+                    session[self._key('access_token')] = access_token
                 if 'refresh_token' in token_response:
-                    session['oidc_refresh_token'] = token_response['refresh_token']
+                    session[self._key('refresh_token')] = token_response['refresh_token']
+
+                if self._strategy == 'single-identity':
+                    self._strip_other_identities(session)
 
                 session.regenerate_id()
                 await ctx.send_empty(302, {'Location': self._config.post_login_redirect})
-            except ValueError as exc:
+            except (ValueError, jwt.PyJWTError) as exc:
                 await ctx.send_str(400, f'Authentication failed: {exc}')
 
         @app.GET(self._config.logout_path)
         async def logout(ctx: HttpContext) -> None:
             session = self._session_of(ctx)
-            id_token = session.get('oidc_id_token')
+            id_token = session.get(self._key('id_token'))
-            session.invalidate()
+            self._logout_session(session)
             logout_url = await self._client.build_logout_url(id_token if isinstance(id_token, str) else None)
             location = logout_url if logout_url is not None else self._config.post_logout_redirect
             await ctx.send_empty(302, {'Location': location})
 
+    def _logout_session(self, session: Session) -> None:
+        """Drop this provider's session state.
+
+        The shared session is only invalidated when no other provider remains
+        logged in, so logging out of one provider does not sign the user out of
+        the others.
+        """
+        for key in [key for key in session if key.startswith(self._prefix)]:
+            del session[key]
+        if not any(_is_user_key(key) for key in session):
+            session.invalidate()
+
+    def _strip_other_identities(self, session: Session) -> None:
+        """Remove every other provider's identity and tokens from the session.
+
+        Only identity keys are dropped; ephemeral flow keys (``state``,
+        ``nonce``, ``code_verifier``) are left alone so logins already in flight
+        can still complete. Under this strategy the last callback to finish
+        wins.
+        """
+        for key in [key for key in session
+                    if _is_identity_key(key) and not key.startswith(self._prefix)]:
+            del session[key]
+
     @staticmethod
     def _session_of(ctx: HttpContext) -> Session:
         session = ctx.session
@@ -169,14 +241,31 @@ class OIDCMixin(KayaMixin):
         return None
 
     def is_authenticated(self, ctx: HttpContext) -> bool:
-        return 'oidc_user' in self._session_of(ctx)
+        return self._key('user') in self._session_of(ctx)
 
     def get_user(self, ctx: HttpContext) -> Optional[OIDCUser]:
-        user = self._session_of(ctx).get('oidc_user')
+        user = self._session_of(ctx).get(self._key('user'))
         if user is None or not isinstance(user, Mapping):
             return None
         return OIDCUser(user)
 
+    def logged_in_providers(self, ctx: HttpContext) -> list[str]:
+        """Return the names of every provider with a user in this session."""
+        return [_provider_of_user_key(key)
+                for key in self._session_of(ctx) if _is_user_key(key)]
+
+    def get_users(self, ctx: HttpContext) -> dict[str, OIDCUser]:
+        """Return the users of every provider logged into this session."""
+        session = self._session_of(ctx)
+        users: dict[str, OIDCUser] = {}
+        for key in session:
+            if not _is_user_key(key):
+                continue
+            data = session.get(key)
+            if isinstance(data, Mapping):
+                users[_provider_of_user_key(key)] = OIDCUser(data)
+        return users
+
     def require_auth(self, handler: HttpHandler) -> HttpHandler:
         async def wrapper(ctx: HttpContext, *args: Any, **kwargs: Any) -> None:
             if not self.is_authenticated(ctx):
@@ -186,18 +275,44 @@ class OIDCMixin(KayaMixin):
         return wrapper
 
     async def refresh_access_token(self, session: Session) -> Optional[str]:
-        refresh_token = session.get('oidc_refresh_token')
+        refresh_token = session.get(self._key('refresh_token'))
         if not isinstance(refresh_token, str):
             return None
         try:
             token_response = await self._client.refresh_token(refresh_token)
             access_token = token_response.get('access_token')
+            id_token = token_response.get('id_token')
+            if isinstance(id_token, str):
+                stored_nonce = session.get(self._key('nonce'))
+                claims = await self._client.validate_refreshed_id_token(
+                    id_token,
+                    stored_nonce if isinstance(stored_nonce, str) else None,
+                )
+                user = session.get(self._key('user'))
+                original_sub = user.get('sub') if isinstance(user, Mapping) else None
+                if isinstance(original_sub, str) and claims.get('sub') != original_sub:
+                    raise ValueError('ID token subject mismatch')
+
             if isinstance(access_token, str):
-                session['oidc_access_token'] = access_token
+                session[self._key('access_token')] = access_token
-            if 'id_token' in token_response:
+            if isinstance(id_token, str):
-                session['oidc_id_token'] = token_response['id_token']
+                session[self._key('id_token')] = id_token
             if 'refresh_token' in token_response:
-                session['oidc_refresh_token'] = token_response['refresh_token']
+                session[self._key('refresh_token')] = token_response['refresh_token']
             return access_token if isinstance(access_token, str) else None
         except Exception:
             return None
+
+
+def _is_user_key(key: str) -> bool:
+    return key.startswith(f'{_SESSION_NAMESPACE}:') and key.endswith(f':{_USER_SUFFIX}')
+
+
+def _is_identity_key(key: str) -> bool:
+    return (key.startswith(f'{_SESSION_NAMESPACE}:')
+            and key.rsplit(':', 1)[-1] in _IDENTITY_FIELDS)
+
+
+def _provider_of_user_key(key: str) -> str:
+    return key[len(_SESSION_NAMESPACE) + 1:-(len(_USER_SUFFIX) + 1)]
+

packages/kaya-oidc/src/kaya/oidc/_providers.py

@@ -0,0 +1,134 @@
+from dataclasses import replace
+from types import MappingProxyType
+from typing import Callable, Mapping, Optional, Sequence
+
+from kaya.core import HttpContext, KayaApp, KayaMixin
+from kaya.session import Session, SessionMixin
+
+from ._config import OIDCConfig
+from ._mixin import (
+    _IDENTITY_STRATEGIES,
+    HttpHandler,
+    IdentityStrategy,
+    OIDCMixin,
+    OIDCUser,
+)
+
+
+class OIDCProviders(KayaMixin):
+    """Wire several OpenID Connect providers into one application.
+
+    Each config's ``provider`` becomes a route segment under ``base_path``:
+    ``{base_path}/{provider}/login``, ``{base_path}/{provider}/callback`` and
+    ``{base_path}/{provider}/logout``. All providers share the supplied
+    :class:`~kaya.session.SessionMixin` and namespace their session state by
+    provider.
+
+    ``strategy`` controls how many identities may coexist in the session. The
+    default ``'single-identity'`` evicts every other provider's identity after a
+    successful login (last login wins). ``'multi-identity'`` keeps each provider
+    logged in independently, so logging out of one provider does not sign the
+    user out of the others.
+
+    Example::
+
+        session = SessionMixin(InMemorySessionStore())
+        oidc = OIDCProviders([google_config, github_config], session=session)
+        app = KayaApp(mixins=[session, oidc])
+
+        @app.GET('/profile')
+        @oidc.require_auth('google')
+        async def profile(ctx: HttpContext):
+            user = oidc.get_user(ctx, 'google')
+            ...
+    """
+
+    def __init__(
+        self,
+        configs: Sequence[OIDCConfig],
+        session: SessionMixin,
+        base_path: str = '/auth',
+        strategy: IdentityStrategy = 'single-identity',
+    ) -> None:
+        if not configs:
+            raise ValueError('At least one OIDCConfig is required')
+        if not base_path.startswith('/'):
+            raise ValueError('base_path must start with "/"')
+        if strategy not in _IDENTITY_STRATEGIES:
+            raise ValueError(
+                'strategy must be one of '
+                f'{", ".join(map(repr, _IDENTITY_STRATEGIES))} (got {strategy!r})'
+            )
+
+        self._session = session
+        self._strategy = strategy
+        self._base_path = base_path.rstrip('/')
+        self._providers: dict[str, OIDCMixin] = {}
+        for config in configs:
+            name = config.provider
+            if name in self._providers:
+                raise ValueError(f'Duplicate OIDC provider {name!r}')
+            self._providers[name] = OIDCMixin(
+                replace(
+                    config,
+                    login_path=f'{self._base_path}/{name}/login',
+                    callback_path=f'{self._base_path}/{name}/callback',
+                    logout_path=f'{self._base_path}/{name}/logout',
+                ),
+                session=session,
+                strategy=strategy,
+            )
+
+    @property
+    def base_path(self) -> str:
+        return self._base_path
+
+    @property
+    def strategy(self) -> IdentityStrategy:
+        return self._strategy
+
+    @property
+    def providers(self) -> Mapping[str, OIDCMixin]:
+        return MappingProxyType(self._providers)
+
+    def provider(self, name: str) -> OIDCMixin:
+        try:
+            return self._providers[name]
+        except KeyError:
+            raise KeyError(f'Unknown OIDC provider {name!r}') from None
+
+    def __getitem__(self, name: str) -> OIDCMixin:
+        return self.provider(name)
+
+    @property
+    def dependencies(self) -> Sequence[KayaMixin]:
+        return [self._session]
+
+    def apply(self, app: KayaApp) -> None:
+        for mixin in self._providers.values():
+            mixin.apply(app)
+
+    def is_authenticated(self, ctx: HttpContext, provider: str) -> bool:
+        return self.provider(provider).is_authenticated(ctx)
+
+    def get_user(self, ctx: HttpContext, provider: str) -> Optional[OIDCUser]:
+        return self.provider(provider).get_user(ctx)
+
+    def get_users(self, ctx: HttpContext) -> dict[str, OIDCUser]:
+        """Return the user of every provider with a session on ``ctx``."""
+        users: dict[str, OIDCUser] = {}
+        for name, mixin in self._providers.items():
+            user = mixin.get_user(ctx)
+            if user is not None:
+                users[name] = user
+        return users
+
+    def logged_in_providers(self, ctx: HttpContext) -> list[str]:
+        """Return the names of the providers logged into ``ctx``."""
+        return [name for name, mixin in self._providers.items() if mixin.is_authenticated(ctx)]
+
+    def require_auth(self, provider: str) -> Callable[[HttpHandler], HttpHandler]:
+        return self.provider(provider).require_auth
+
+    async def refresh_access_token(self, session: Session, provider: str) -> Optional[str]:
+        return await self.provider(provider).refresh_access_token(session)

packages/kaya-otel/README.md

@@ -0,0 +1,89 @@
+# kaya-otel
+
+OpenTelemetry tracing and metrics for the Kaya web framework.
+
+Provides `OTelMixin`, a `KayaMixin` that instruments HTTP requests and
+WebSocket connections with OpenTelemetry spans and exports HTTP server
+metrics, shipping everything to an OTLP/HTTP collector.
+
+## Usage
+
+```python
+from kaya.core import KayaApp, HttpContext
+from kaya.otel import OTelMixin
+
+app = KayaApp(mixins=[
+    OTelMixin(
+        service_name='my-service',
+        endpoint='http://localhost:4318',
+    )
+])
+
+@app.GET('/')
+async def home(ctx: HttpContext):
+    await ctx.send_str(200, 'Hello World!')
+```
+
+## Parameters
+
+- `service_name`: value of the `service.name` resource attribute.
+- `endpoint`: base URL of an OTLP/HTTP collector; the signal paths
+  `/v1/traces` and `/v1/metrics` are appended. When `None`, the exporters
+  use their own defaults, including the standard
+  `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable.
+- `headers`: extra HTTP headers sent to the collector (e.g. authentication).
+- `metric_export_interval_millis`: metric export interval
+  (default `60000`).
+- `tracer_provider` / `meter_provider`: inject custom providers (e.g. with
+  in-memory exporters for tests) instead of the OTLP defaults. The mixin
+  only shuts down providers it created itself.
+- `resource_attributes`: extra resource attributes merged with
+  `service.name` when the mixin creates the providers.
+- `excluded_paths` / `excluded_path_regexes`: skip tracing and metrics for
+  matching paths (useful for health checks and metrics endpoints).
+- `capture_request_headers` / `capture_response_headers`: opt-in HTTP header
+  capture as `http.request.header.<name>` / `http.response.header.<name>`
+  span attributes. Header names are normalized to lowercase with `-`
+  replaced by `_`; values are captured as string lists.
+- `sanitize_headers`: headers captured as `REDACTED` (default:
+  `authorization`, `proxy-authorization`, `cookie`, `set-cookie`).
+- `server_request_hook` / `server_response_hook` / `websocket_connect_hook` /
+  `websocket_close_hook`: optional synchronous callbacks invoked with the
+  span and the Kaya context/websocket at the corresponding lifecycle point.
+  Hook exceptions are logged and do not fail the request.
+- `metrics_include_raw_path`: when `True`, metrics use raw `url.path`
+  attributes (legacy, potentially high cardinality). The default `False`
+  keeps metrics low-cardinality by using `http.route` when Kaya can resolve
+  a route template.
+- `websocket_error_close_codes`: close codes that mark a websocket span as
+  failed. Defaults to protocol/application error codes such as `1002`,
+  `1003` and `1007`-`1011`.
+
+## Behavior
+
+- Every HTTP request gets a `SERVER` span named `<METHOD> <path>` with the
+  usual HTTP semantic attributes (`http.request.method`, `url.path`,
+  `client.address`, `server.address`, ...). When Kaya resolves a route
+  template, the span name is updated to `<METHOD> <route template>` and
+  `http.route` is set. The response status code is recorded as
+  `http.response.status_code` when the handler sends the response; 5xx
+  statuses mark the span as failed. Exceptions escaping the handler are
+  recorded on the span and also mark it as failed.
+- Every WebSocket connection gets one span for its whole lifetime, carrying
+  the applicable standard attributes: `url.scheme`, `url.path`, `url.query`,
+  `network.protocol.name` (`websocket`), `network.transport`,
+  `client.address`/`client.port` and `server.address`/`server.port`. The
+  close code is recorded as `kaya.websocket.close_code`; exceptions and
+  configured error close codes mark the span as failed and set `error.type`
+  (the exception class name, or the close code).
+- W3C `traceparent`/`tracestate` headers on incoming requests are honored,
+  so traces propagate from upstream services.
+- Metrics:
+  - `http.server.request.duration` (histogram, seconds), with
+    `http.request.method`, `http.route` when known and
+    `http.response.status_code` attributes.
+  - `http.server.active_requests` (up-down counter), with
+    `http.request.method` attributes.
+
+`OTelMixin` is a `KayaMixin`, so the app stays a `KayaApp` and both ASGI and
+RSGI keep working.

packages/kaya-otel/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=61.0", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kaya-otel"
+dynamic = ["version"]
+authors = [
+  { name="Walter Oggioni", email="oggioni.walter@gmail.com" },
+]
+description = "OpenTelemetry tracing and metrics for the Kaya lightweight ASGI web framework"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+classifiers = [
+        'Development Status :: 3 - Alpha',
+        'Topic :: Utilities',
+        'Intended Audience :: System Administrators',
+        'Intended Audience :: Developers',
+        'Environment :: Console',
+        'Programming Language :: Python :: 3',
+]
+
+dependencies = [
+    "kaya-core",
+    "opentelemetry-sdk",
+    "opentelemetry-exporter-otlp-proto-http",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build", "mypy", "ipdb", "twine", "httpx", "httpx-ws", "kaya-rsgi"
+]
+
+[project.urls]
+"Homepage" = "https://github.com/woggioni/kaya"
+"Bug Tracker" = "https://github.com/woggioni/kaya/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true
+
+[tool.mypy]
+python_version = "3.12"
+disallow_untyped_defs = true
+show_error_codes = true
+no_implicit_optional = true
+warn_return_any = true
+warn_unused_ignores = true
+exclude = ["scripts", "docs", "test"]
+strict = true
+
+[tool.setuptools_scm]
+root = "../.."
+version_file = "src/kaya/otel/_version.py"
+
+[tool.setuptools_scm.tag]
+prefix = "release/"

packages/kaya-otel/src/kaya/otel/__init__.py

@@ -0,0 +1,10 @@
+from pkgutil import extend_path
+
+__path__ = extend_path(__path__, __name__)
+
+from ._mixin import OTelMixin
+
+
+__all__ = [
+    'OTelMixin',
+]

packages/kaya-otel/src/kaya/otel/_mixin.py

@@ -0,0 +1,518 @@
+import re
+import time
+from asyncio import AbstractEventLoop
+from logging import getLogger
+from pathlib import Path
+from typing import (
+    Any,
+    AsyncGenerator,
+    Callable,
+    Dict,
+    Mapping,
+    Optional,
+    Sequence,
+    Tuple,
+)
+
+from kaya.core import HttpContext, KayaApp, KayaMixin, WebSocket, WebSocketMessage
+from kaya.core._types import StrOrStrings
+from opentelemetry import context as otel_context
+from opentelemetry import trace
+from opentelemetry.context import Context
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.metrics import Histogram, UpDownCounter
+from opentelemetry.propagators.textmap import Getter
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.trace import Span, SpanKind, Status, StatusCode, Tracer
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+log = getLogger(__name__)
+
+RequestHook = Callable[[Span, HttpContext], None]
+WebSocketHook = Callable[[Span, WebSocket], None]
+
+_DEFAULT_SANITIZE_HEADERS = (
+    'authorization',
+    'proxy-authorization',
+    'cookie',
+    'set-cookie',
+)
+_DEFAULT_WEBSOCKET_ERROR_CLOSE_CODES = frozenset((1002, 1003, 1007, 1008, 1009, 1010, 1011))
+
+
+class _HeadersGetter(Getter[Mapping[str, Sequence[str]]]):
+    """Extract propagation headers from a kaya request/websocket context.
+
+    Kaya header mappings have lowercase names with one or more values each,
+    which is all the W3C trace-context propagator needs.
+    """
+
+    def get(self, carrier: Mapping[str, Sequence[str]], key: str) -> Optional[list[str]]:
+        values = carrier.get(key.lower())
+        if not values:
+            return None
+        return list(values)
+
+    def keys(self, carrier: Mapping[str, Sequence[str]]) -> list[str]:
+        return list(carrier.keys())
+
+
+_PROPAGATOR = TraceContextTextMapPropagator()
+_GETTER = _HeadersGetter()
+
+
+def _server_attributes(ctx: HttpContext) -> Dict[str, Any]:
+    attributes: Dict[str, Any] = {
+        'http.request.method': str(ctx.method),
+        'url.scheme': ctx.scheme,
+        'url.path': ctx.path,
+    }
+    if ctx.query_string:
+        attributes['url.query'] = ctx.query_string
+    if ctx.client is not None:
+        attributes['client.address'] = ctx.client[0]
+        attributes['client.port'] = ctx.client[1]
+    if ctx.server is not None:
+        attributes['server.address'] = ctx.server[0]
+        if ctx.server[1] is not None:
+            attributes['server.port'] = ctx.server[1]
+    return attributes
+
+
+def _websocket_attributes(ws: WebSocket) -> Dict[str, Any]:
+    """Standard attributes applicable to a websocket connection span.
+
+    OpenTelemetry defines no websocket-specific conventions; these are the
+    general URL, network and peer attributes that apply to the connection.
+    """
+    attributes: Dict[str, Any] = {
+        'url.scheme': ws.scheme,
+        'url.path': ws.path,
+        'network.protocol.name': 'websocket',
+        'network.transport': 'tcp',
+    }
+    if ws.query_string:
+        attributes['url.query'] = ws.query_string
+    if ws.client is not None:
+        attributes['client.address'] = ws.client[0]
+        attributes['client.port'] = ws.client[1]
+    if ws.server is not None:
+        attributes['server.address'] = ws.server[0]
+        if ws.server[1] is not None:
+            attributes['server.port'] = ws.server[1]
+    return attributes
+
+
+def _normalize_header_name(name: str) -> str:
+    return name.lower().replace('-', '_')
+
+
+def _header_values(value: StrOrStrings | Sequence[str]) -> list[str]:
+    if isinstance(value, str):
+        return [value]
+    return list(value)
+
+
+class _SpanHolder:
+    """Mutable per-request slot shared by the tracing hooks and wrappers."""
+
+    __slots__ = ('span', 'token', 'status_code', 'start_ns', 'active_attributes', 'close_code')
+
+    def __init__(self, span: Span, token: object, active_attributes: Dict[str, Any]) -> None:
+        self.span = span
+        self.token = token
+        self.status_code: Optional[int] = None
+        self.start_ns = time.perf_counter_ns()
+        self.active_attributes = active_attributes
+        self.close_code: Optional[int] = None
+
+
+class _TracedHttpContext(HttpContext):
+    """HttpContext wrapper that records the response status code on the span.
+
+    Attributes not explicitly overridden are delegated to the wrapped context
+    via ``__getattr__``, so it works with any concrete ``HttpContext`` (ASGI
+    or RSGI) and preserves attributes set by other mixins (e.g. ``session``).
+    """
+
+    def __init__(self, ctx: HttpContext, holder: _SpanHolder, mixin: 'OTelMixin') -> None:
+        object.__setattr__(self, '_ctx', ctx)
+        object.__setattr__(self, 'session', ctx.session)
+        object.__setattr__(self, '_holder', holder)
+        object.__setattr__(self, '_mixin', mixin)
+
+    def __getattr__(self, name: str) -> Any:
+        if name == '_ctx':
+            raise AttributeError(name)
+        return getattr(self._ctx, name)
+
+    def _sent(self, status: int, headers: Optional[Mapping[str, StrOrStrings]]) -> None:
+        self._holder.status_code = status
+        self._holder.span.set_attribute('http.response.status_code', status)
+        self._mixin._capture_response_headers(self._holder.span, headers)
+
+    async def stream_body(self,
+                          status: int,
+                          body_generator: AsyncGenerator[bytes, None],
+                          headers: Optional[Mapping[str, StrOrStrings]] = None) -> None:
+        self._sent(status, headers)
+        await self._ctx.stream_body(status, body_generator, headers)
+
+    async def send_bytes(self, status: int, body: bytes, headers: Optional[Mapping[str, StrOrStrings]] = None) -> None:
+        self._sent(status, headers)
+        await self._ctx.send_bytes(status, body, headers)
+
+    async def send_str(self, status: int, body: str, headers: Optional[Mapping[str, StrOrStrings]] = None) -> None:
+        self._sent(status, headers)
+        await self._ctx.send_str(status, body, headers)
+
+    async def send_file(self, status: int, path: Path, headers: Optional[Mapping[str, StrOrStrings]] = None) -> None:
+        self._sent(status, headers)
+        await self._ctx.send_file(status, path, headers)
+
+    async def send_empty(self, status: int, headers: Optional[Mapping[str, StrOrStrings]] = None) -> None:
+        self._sent(status, headers)
+        await self._ctx.send_empty(status, headers)
+
+
+class _TracedWebSocket(WebSocket):
+    """WebSocket wrapper that keeps the connection span reachable.
+
+    Everything is delegated to the wrapped socket via ``__getattr__``, so it
+    works with any concrete ``WebSocket`` (ASGI or RSGI) and preserves
+    attributes set by other mixins (e.g. ``session``).
+    """
+
+    def __init__(self, ws: WebSocket, holder: _SpanHolder) -> None:
+        object.__setattr__(self, '_ws', ws)
+        object.__setattr__(self, 'session', ws.session)
+        object.__setattr__(self, '_holder', holder)
+
+    def __getattr__(self, name: str) -> Any:
+        if name == '_ws':
+            raise AttributeError(name)
+        return getattr(self._ws, name)
+
+    async def accept(self, headers: Optional[Mapping[str, StrOrStrings]] = None) -> None:
+        await self._ws.accept(headers)
+
+    async def receive(self) -> WebSocketMessage:
+        return await self._ws.receive()
+
+    async def send_text(self, data: str) -> None:
+        await self._ws.send_text(data)
+
+    async def send_bytes(self, data: bytes) -> None:
+        await self._ws.send_bytes(data)
+
+    async def close(self, code: int = 1000) -> None:
+        self._holder.close_code = code
+        await self._ws.close(code)
+
+    async def __anext__(self) -> WebSocketMessage:
+        return await self._ws.__anext__()
+
+
+class OTelMixin(KayaMixin):
+    """Kaya mixin adding OpenTelemetry tracing and metrics.
+
+    HTTP requests get a ``SERVER`` span named ``<METHOD> <path>`` carrying the
+    usual HTTP semantic attributes; the response status code is recorded when
+    the handler sends the response and 5xx statuses mark the span as failed.
+    Exceptions escaping the handler are recorded and mark the span as failed.
+    WebSocket connections get one span for the whole connection lifetime,
+    carrying the applicable standard websocket URL, network and peer
+    attributes (``url.scheme``, ``url.path``, ``network.protocol.name``,
+    ``client.address``/``server.address``, ...); exceptions and configured
+    error close codes set ``error.type`` and mark the span as failed.
+    W3C ``traceparent``/``tracestate`` headers on incoming requests are
+    honored, so traces propagate from upstream services.
+
+    Metrics exported on the meter provider:
+
+    - ``http.server.request.duration`` (histogram, seconds), with
+      ``http.request.method``, ``http.route`` when known and
+      ``http.response.status_code`` attributes;
+    - ``http.server.active_requests`` (up-down counter), with
+      ``http.request.method`` attributes.
+
+    Example::
+
+        app = KayaApp(mixins=[
+            OTelMixin(
+                service_name='my-service',
+                endpoint='http://localhost:4318',
+            )
+        ])
+
+    ``endpoint`` is the base URL of an OTLP/HTTP collector (the signal paths
+    ``/v1/traces`` and ``/v1/metrics`` are appended); when ``None`` the
+    exporters fall back to their own defaults, including the standard
+    ``OTEL_EXPORTER_OTLP_ENDPOINT`` environment variable. Custom
+    ``tracer_provider``/``meter_provider`` instances (e.g. with in-memory
+    exporters for tests) can be injected instead of the OTLP defaults; the
+    mixin only shuts down providers it created itself.
+    """
+
+    def __init__(self,
+                 service_name: str,
+                 endpoint: Optional[str] = None,
+                 headers: Optional[Mapping[str, str]] = None,
+                 metric_export_interval_millis: float = 60000,
+                 tracer_provider: Optional[TracerProvider] = None,
+                 meter_provider: Optional[MeterProvider] = None,
+                 resource_attributes: Optional[Mapping[str, Any]] = None,
+                 excluded_paths: Sequence[str] = (),
+                 excluded_path_regexes: Sequence[str] = (),
+                 capture_request_headers: Sequence[str] = (),
+                 capture_response_headers: Sequence[str] = (),
+                 sanitize_headers: Sequence[str] = _DEFAULT_SANITIZE_HEADERS,
+                 server_request_hook: Optional[RequestHook] = None,
+                 server_response_hook: Optional[RequestHook] = None,
+                 websocket_connect_hook: Optional[WebSocketHook] = None,
+                 websocket_close_hook: Optional[WebSocketHook] = None,
+                 metrics_include_raw_path: bool = False,
+                 websocket_error_close_codes: Optional[Sequence[int]] = None) -> None:
+        self._owns_tracer_provider = tracer_provider is None
+        self._owns_meter_provider = meter_provider is None
+        if tracer_provider is None:
+            tracer_provider = TracerProvider(resource=self._create_resource(service_name, resource_attributes))
+            span_exporter = OTLPSpanExporter(
+                endpoint=f'{endpoint}/v1/traces' if endpoint else None,
+                headers=dict(headers) if headers else None,
+            )
+            tracer_provider.add_span_processor(BatchSpanProcessor(span_exporter))
+        if meter_provider is None:
+            meter_provider = MeterProvider(
+                resource=self._create_resource(service_name, resource_attributes),
+                metric_readers=[
+                    PeriodicExportingMetricReader(
+                        OTLPMetricExporter(
+                            endpoint=f'{endpoint}/v1/metrics' if endpoint else None,
+                            headers=dict(headers) if headers else None,
+                        ),
+                        export_interval_millis=metric_export_interval_millis,
+                    )
+                ],
+            )
+        self._tracer_provider = tracer_provider
+        self._meter_provider = meter_provider
+        self._tracer: Tracer = tracer_provider.get_tracer('kaya.otel')
+        meter = meter_provider.get_meter('kaya.otel')
+        self._request_duration: Histogram = meter.create_histogram(
+            'http.server.request.duration',
+            unit='s',
+            description='Duration of HTTP server requests',
+        )
+        self._active_requests: UpDownCounter = meter.create_up_down_counter(
+            'http.server.active_requests',
+            unit='{request}',
+            description='Number of in-flight HTTP server requests',
+        )
+        self._app: Optional[KayaApp] = None
+        self._excluded_paths = frozenset(excluded_paths)
+        self._excluded_path_regexes = tuple(re.compile(regex) for regex in excluded_path_regexes)
+        self._request_headers_to_capture = tuple(capture_request_headers)
+        self._response_headers_to_capture = tuple(capture_response_headers)
+        self._sanitize_headers = frozenset(name.lower() for name in sanitize_headers)
+        self._server_request_hook = server_request_hook
+        self._server_response_hook = server_response_hook
+        self._websocket_connect_hook = websocket_connect_hook
+        self._websocket_close_hook = websocket_close_hook
+        self._metrics_include_raw_path = metrics_include_raw_path
+        self._websocket_error_close_codes = (
+            frozenset(websocket_error_close_codes)
+            if websocket_error_close_codes is not None
+            else _DEFAULT_WEBSOCKET_ERROR_CLOSE_CODES
+        )
+        # Live spans keyed by the id of the (wrapped) context/websocket the
+        # after hooks receive; entries are removed when the span ends.
+        self._spans: Dict[int, _SpanHolder] = {}
+
+    @staticmethod
+    def _create_resource(service_name: str,
+                         resource_attributes: Optional[Mapping[str, Any]]) -> Resource:
+        attributes: Dict[str, Any] = {'service.name': service_name}
+        if resource_attributes:
+            attributes.update(resource_attributes)
+        return Resource.create(attributes)
+
+    def apply(self, app: KayaApp) -> None:
+        self._app = app
+        app.add_before_request_hook(self._before_request)
+        app.add_after_request_hook(self._after_request)
+        app.add_before_websocket_hook(self._before_websocket)
+        app.add_after_websocket_hook(self._after_websocket)
+
+    def _is_excluded(self, path: str) -> bool:
+        if path in self._excluded_paths:
+            return True
+        return any(regex.search(path) is not None for regex in self._excluded_path_regexes)
+
+    @staticmethod
+    def _call_hook(hook: Optional[Callable[[Span, Any], None]], span: Span, value: Any) -> None:
+        if hook is None:
+            return
+        try:
+            hook(span, value)
+        except Exception:
+            log.exception('OpenTelemetry span hook failed')
+
+    def _capture_headers(self,
+                         span: Span,
+                         headers: Mapping[str, StrOrStrings | Sequence[str]],
+                         configured: Sequence[str],
+                         prefix: str) -> None:
+        if not configured:
+            return
+        lower_headers = {name.lower(): value for name, value in headers.items()}
+        for name in configured:
+            key = name.lower()
+            if key not in lower_headers:
+                continue
+            values = _header_values(lower_headers[key])
+            if key in self._sanitize_headers:
+                values = ['REDACTED'] * len(values)
+            span.set_attribute(f'{prefix}.{_normalize_header_name(name)}', values)
+
+    def _capture_request_headers(self, span: Span, headers: Mapping[str, Sequence[str]]) -> None:
+        self._capture_headers(span, headers, self._request_headers_to_capture, 'http.request.header')
+
+    def _capture_response_headers(self,
+                                  span: Span,
+                                  headers: Optional[Mapping[str, StrOrStrings]]) -> None:
+        if headers is None:
+            return
+        self._capture_headers(span, headers, self._response_headers_to_capture, 'http.response.header')
+
+    def _start_span(self, name: str, attributes: Mapping[str, Any],
+                    headers: Mapping[str, Sequence[str]]) -> _SpanHolder:
+        parent: Context = _PROPAGATOR.extract(carrier=headers, getter=_GETTER)
+        span = self._tracer.start_span(
+            name,
+            context=parent,
+            kind=SpanKind.SERVER,
+            attributes=dict(attributes),
+        )
+        self._capture_request_headers(span, headers)
+        token = otel_context.attach(trace.set_span_in_context(span, parent))
+        return _SpanHolder(span, token, {})
+
+    @staticmethod
+    def _finish_span(holder: _SpanHolder, error: bool) -> None:
+        if error:
+            holder.span.set_status(Status(StatusCode.ERROR))
+        holder.span.end()
+        otel_context.detach(holder.token)  # type: ignore[arg-type]
+
+    def _pop_holder(self, obj: Any) -> Optional[_SpanHolder]:
+        """Find and remove the span holder for a context/websocket.
+
+        The before hooks key holders by the id of the context they received,
+        but after hooks run on the outermost wrapper (later mixins may have
+        wrapped the context again), so the id may not match. In that case the
+        holder is reachable through the wrapper delegation chain as
+        ``_holder`` and the stale dict entry is reaped by identity.
+        """
+        holder = self._spans.pop(id(obj), None)
+        if holder is not None:
+            return holder
+        candidate = getattr(obj, '_holder', None)
+        if not isinstance(candidate, _SpanHolder):
+            return None
+        for key, value in list(self._spans.items()):
+            if value is candidate:
+                del self._spans[key]
+        return candidate
+
+    def _route_template(self, ctx: HttpContext) -> Optional[str]:
+        if self._app is None:
+            return None
+        return self._app.route_template(ctx.path, ctx.method)
+
+    async def _before_request(self, ctx: HttpContext) -> Optional[HttpContext]:
+        if self._is_excluded(ctx.path):
+            return None
+        holder = self._start_span(
+            f'{ctx.method} {ctx.path}',
+            _server_attributes(ctx),
+            ctx.headers,
+        )
+        holder.active_attributes = {'http.request.method': str(ctx.method)}
+        if self._metrics_include_raw_path:
+            holder.active_attributes['url.path'] = ctx.path
+        self._spans[id(ctx)] = holder
+        self._active_requests.add(1, holder.active_attributes)
+        self._call_hook(self._server_request_hook, holder.span, ctx)
+        return _TracedHttpContext(ctx, holder, self)
+
+    async def _after_request(self, ctx: HttpContext) -> None:
+        holder = self._pop_holder(ctx)
+        if holder is None:
+            return
+        status_code = holder.status_code
+        exception = getattr(ctx, 'exception', None)
+        error = status_code is not None and status_code >= 500
+        if isinstance(exception, BaseException):
+            holder.span.record_exception(exception)
+            error = True
+        route_template = self._route_template(ctx)
+        if route_template is not None:
+            holder.span.update_name(f'{ctx.method} {route_template}')
+            holder.span.set_attribute('http.route', route_template)
+        self._call_hook(self._server_response_hook, holder.span, ctx)
+        self._finish_span(holder, error)
+        self._active_requests.add(-1, holder.active_attributes)
+        metric_attributes: Dict[str, Any] = {
+            'http.request.method': str(ctx.method),
+        }
+        if self._metrics_include_raw_path:
+            metric_attributes['url.path'] = ctx.path
+        elif route_template is not None:
+            metric_attributes['http.route'] = route_template
+        if status_code is not None:
+            metric_attributes['http.response.status_code'] = status_code
+        duration = (time.perf_counter_ns() - holder.start_ns) / 1e9
+        self._request_duration.record(duration, metric_attributes)
+
+    async def _before_websocket(self, ws: WebSocket) -> Optional[WebSocket]:
+        if self._is_excluded(ws.path):
+            return None
+        holder = self._start_span(f'WS {ws.path}', _websocket_attributes(ws), ws.headers)
+        self._spans[id(ws)] = holder
+        self._call_hook(self._websocket_connect_hook, holder.span, ws)
+        return _TracedWebSocket(ws, holder)
+
+    async def _after_websocket(self, ws: WebSocket) -> None:
+        holder = self._pop_holder(ws)
+        if holder is None:
+            return
+        exception = getattr(ws, 'exception', None)
+        error = isinstance(exception, BaseException)
+        if isinstance(exception, BaseException):
+            holder.span.record_exception(exception)
+            holder.span.set_attribute('error.type', type(exception).__qualname__)
+        close_code = holder.close_code
+        if close_code is not None:
+            holder.span.set_attribute('kaya.websocket.close_code', close_code)
+            if close_code in self._websocket_error_close_codes:
+                error = True
+                if not isinstance(exception, BaseException):
+                    # Mirror the HTTP conventions, where server-side error
+                    # statuses are recorded as ``error.type`` values.
+                    holder.span.set_attribute('error.type', str(close_code))
+        self._call_hook(self._websocket_close_hook, holder.span, ws)
+        self._finish_span(holder, error)
+
+    def shutdown(self, loop: AbstractEventLoop) -> None:
+        # Only providers created by this mixin are shut down; injected ones
+        # stay under the caller's control.
+        if self._owns_tracer_provider:
+            self._tracer_provider.shutdown()
+        if self._owns_meter_provider:
+            self._meter_provider.shutdown()

packages/kaya-otel/tests/test_otel.py

@@ -0,0 +1,420 @@
+import json
+import unittest
+from typing import Any, Optional, Tuple
+
+import httpx
+from pwo import async_test
+
+from kaya.core import HttpContext, KayaApp
+from kaya.core._asgi import AsgiWebSocket
+from kaya.otel import OTelMixin
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import InMemoryMetricReader
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from opentelemetry.trace import StatusCode
+
+TRACEPARENT = '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01'
+
+
+def make_mixin(**kwargs) -> Tuple[OTelMixin, InMemorySpanExporter, InMemoryMetricReader]:
+    resource = Resource.create({'service.name': 'test-service'})
+    span_exporter = InMemorySpanExporter()
+    tracer_provider = TracerProvider(resource=resource)
+    tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
+    metric_reader = InMemoryMetricReader()
+    meter_provider = MeterProvider(resource=resource, metric_readers=[metric_reader])
+    mixin = OTelMixin(
+        service_name='test-service',
+        tracer_provider=tracer_provider,
+        meter_provider=meter_provider,
+        **kwargs,
+    )
+    return mixin, span_exporter, metric_reader
+
+
+def make_app(mixin: OTelMixin) -> KayaApp:
+    app = KayaApp(mixins=[mixin])
+
+    @app.GET('/hello')
+    async def hello(ctx: HttpContext) -> None:
+        await ctx.send_str(200, json.dumps({'ok': True}))
+
+    @app.GET('/boom')
+    async def boom(ctx: HttpContext) -> None:
+        await ctx.send_str(500, 'boom')
+
+    return app
+
+
+async def request(app: KayaApp, path: str = '/hello', headers: Optional[dict[str, str]] = None) -> httpx.Response:
+    transport = httpx.ASGITransport(app=app, client=('127.0.0.1', 123))
+    async with httpx.AsyncClient(transport=transport, base_url="http://127.0.0.1:80") as http_client:
+        return await http_client.get(path, headers=headers)
+
+
+class HttpTracingTest(unittest.TestCase):
+
+    @async_test
+    async def test_request_produces_server_span(self):
+        mixin, span_exporter, _ = make_mixin()
+        app = make_app(mixin)
+        r = await request(app)
+        self.assertEqual(200, r.status_code)
+        spans = span_exporter.get_finished_spans()
+        self.assertEqual(1, len(spans))
+        span = spans[0]
+        self.assertEqual('GET /hello', span.name)
+        assert span.attributes is not None
+        self.assertEqual('GET', span.attributes['http.request.method'])
+        self.assertEqual('/hello', span.attributes['url.path'])
+        self.assertEqual(200, span.attributes['http.response.status_code'])
+        self.assertEqual(StatusCode.UNSET, span.status.status_code)
+
+    @async_test
+    async def test_5xx_marks_span_as_error(self):
+        mixin, span_exporter, _ = make_mixin()
+        app = make_app(mixin)
+        r = await request(app, '/boom')
+        self.assertEqual(500, r.status_code)
+        spans = span_exporter.get_finished_spans()
+        self.assertEqual(1, len(spans))
+        self.assertEqual(500, spans[0].attributes['http.response.status_code'])  # type: ignore[index]
+        self.assertEqual(StatusCode.ERROR, spans[0].status.status_code)
+
+    @async_test
+    async def test_traceparent_header_propagates(self):
+        mixin, span_exporter, _ = make_mixin()
+        app = make_app(mixin)
+        await request(app, headers={'traceparent': TRACEPARENT})
+        spans = span_exporter.get_finished_spans()
+        self.assertEqual(1, len(spans))
+        span = spans[0]
+        self.assertEqual(0x4bf92f3577b34da6a3ce929d0e0e4736, span.context.trace_id)  # type: ignore[union-attr]
+        assert span.parent is not None
+        self.assertEqual(0x00f067aa0ba902b7, span.parent.span_id)
+
+    @async_test
+    async def test_unmatched_route_still_traced(self):
+        mixin, span_exporter, _ = make_mixin()
+        app = make_app(mixin)
+        r = await request(app, '/nowhere')
+        self.assertEqual(404, r.status_code)
+        spans = span_exporter.get_finished_spans()
+        self.assertEqual(1, len(spans))
+        self.assertEqual(404, spans[0].attributes['http.response.status_code'])  # type: ignore[index]
+
+    @async_test
+    async def test_no_leaked_spans_after_requests(self):
+        mixin, span_exporter, _ = make_mixin()
+        app = make_app(mixin)
+        await request(app)
+        await request(app, '/boom')
+        self.assertEqual(0, len(mixin._spans))
+        self.assertEqual(2, len(span_exporter.get_finished_spans()))
+
+
+    @async_test
+    async def test_exception_marks_span_as_error(self):
+        mixin, span_exporter, _ = make_mixin()
+        app = KayaApp(mixins=[mixin])
+
+        @app.GET('/raises')
+        async def raises(ctx: HttpContext) -> None:
+            raise RuntimeError('boom')
+
+        transport = httpx.ASGITransport(app=app, client=('127.0.0.1', 123))
+        async with httpx.AsyncClient(transport=transport, base_url="http://127.0.0.1:80") as http_client:
+            with self.assertRaises(RuntimeError):
+                await http_client.get('/raises')
+
+        spans = span_exporter.get_finished_spans()
+        self.assertEqual(1, len(spans))
+        span = spans[0]
+        self.assertEqual(StatusCode.ERROR, span.status.status_code)
+        self.assertTrue(any(event.name == 'exception' for event in span.events))
+        self.assertEqual(0, len(mixin._spans))
+
+    @async_test
+    async def test_excluded_path_skips_tracing_and_metrics(self):
+        mixin, span_exporter, metric_reader = make_mixin(excluded_paths=('/health',))
+        app = KayaApp(mixins=[mixin])
+
+        @app.GET('/health')
+        async def health(ctx: HttpContext) -> None:
+            await ctx.send_str(200, 'ok')
+
+        @app.GET('/hello')
+        async def hello(ctx: HttpContext) -> None:
+            await ctx.send_str(200, 'hello')
+
+        await request(app, '/health')
+        await request(app, '/hello')
+
+        spans = span_exporter.get_finished_spans()
+        self.assertEqual(1, len(spans))
+        self.assertEqual('GET /hello', spans[0].name)
+
+        metrics = MetricsTest._metric_names(metric_reader)
+        duration_points = list(metrics['http.server.request.duration'].data.data_points)
+        self.assertEqual(1, len(duration_points))
+        self.assertEqual(1, duration_points[0].count)
+
+    @async_test
+    async def test_route_template_used_for_span_name_and_metrics(self):
+        mixin, span_exporter, metric_reader = make_mixin()
+        app = KayaApp(mixins=[mixin])
+
+        @app.GET('/items/${item_id:int}')
+        async def item(ctx: HttpContext, item_id: int) -> None:
+            await ctx.send_str(200, str(item_id))
+
+        r = await request(app, '/items/123')
+        self.assertEqual(200, r.status_code)
+
+        spans = span_exporter.get_finished_spans()
+        self.assertEqual(1, len(spans))
+        span = spans[0]
+        self.assertEqual('GET /items/${item_id:int}', span.name)
+        assert span.attributes is not None
+        self.assertEqual('/items/${item_id:int}', span.attributes['http.route'])
+        self.assertEqual('/items/123', span.attributes['url.path'])
+
+        metrics = MetricsTest._metric_names(metric_reader)
+        duration_points = list(metrics['http.server.request.duration'].data.data_points)
+        self.assertEqual(1, len(duration_points))
+        duration_attributes = dict(duration_points[0].attributes)
+        self.assertEqual('GET', duration_attributes['http.request.method'])
+        self.assertEqual('/items/${item_id:int}', duration_attributes['http.route'])
+        self.assertEqual(200, duration_attributes['http.response.status_code'])
+        self.assertNotIn('url.path', duration_attributes)
+
+        active_points = list(metrics['http.server.active_requests'].data.data_points)
+        self.assertEqual(1, len(active_points))
+        self.assertEqual({'http.request.method': 'GET'}, dict(active_points[0].attributes))
+
+    @async_test
+    async def test_header_capture_and_sanitization(self):
+        mixin, span_exporter, _ = make_mixin(
+            capture_request_headers=('X-Request-Id', 'Authorization'),
+            capture_response_headers=('X-Response-Id', 'Set-Cookie'),
+        )
+        app = KayaApp(mixins=[mixin])
+
+        @app.GET('/headers')
+        async def headers(ctx: HttpContext) -> None:
+            await ctx.send_str(200, 'ok', {
+                'X-Response-Id': 'res-1',
+                'Set-Cookie': 'sid=secret',
+            })
+
+        r = await request(app, '/headers', headers={
+            'X-Request-Id': 'req-1',
+            'Authorization': 'Bearer secret',
+        })
+        self.assertEqual(200, r.status_code)
+
+        spans = span_exporter.get_finished_spans()
+        self.assertEqual(1, len(spans))
+        attributes = spans[0].attributes
+        assert attributes is not None
+        self.assertEqual(['req-1'], list(attributes['http.request.header.x_request_id']))
+        self.assertEqual(['REDACTED'], list(attributes['http.request.header.authorization']))
+        self.assertEqual(['res-1'], list(attributes['http.response.header.x_response_id']))
+        self.assertEqual(['REDACTED'], list(attributes['http.response.header.set_cookie']))
+
+    @async_test
+    async def test_http_hooks_are_called(self):
+        calls = []
+
+        def request_hook(span: Any, ctx: HttpContext) -> None:
+            calls.append(('request', ctx.path))
+            span.set_attribute('test.request_hook', True)
+
+        def response_hook(span: Any, ctx: HttpContext) -> None:
+            calls.append(('response', ctx.path))
+            span.set_attribute('test.response_hook', True)
+
+        mixin, span_exporter, _ = make_mixin(
+            server_request_hook=request_hook,
+            server_response_hook=response_hook,
+        )
+        app = make_app(mixin)
+        await request(app)
+
+        self.assertEqual([('request', '/hello'), ('response', '/hello')], calls)
+        attributes = span_exporter.get_finished_spans()[0].attributes
+        assert attributes is not None
+        self.assertTrue(attributes['test.request_hook'])
+        self.assertTrue(attributes['test.response_hook'])
+
+
+class MetricsTest(unittest.TestCase):
+
+    @staticmethod
+    def _metric_names(metric_reader: InMemoryMetricReader) -> dict:
+        data = metric_reader.get_metrics_data()
+        return {m.name: m for rm in data.resource_metrics for m in rm.scope_metrics[0].metrics
+                if rm.scope_metrics}
+
+    @async_test
+    async def test_duration_histogram_and_active_requests(self):
+        mixin, _, metric_reader = make_mixin()
+        app = make_app(mixin)
+        await request(app)
+        metrics = self._metric_names(metric_reader)
+        self.assertIn('http.server.request.duration', metrics)
+        self.assertIn('http.server.active_requests', metrics)
+        duration_points = list(metrics['http.server.request.duration'].data.data_points)
+        self.assertEqual(1, len(duration_points))
+        self.assertEqual(1, duration_points[0].count)
+        self.assertGreaterEqual(duration_points[0].sum, 0)
+        active_points = list(metrics['http.server.active_requests'].data.data_points)
+        self.assertEqual(1, len(active_points))
+        self.assertEqual(0, active_points[0].value)
+
+
+class WebSocketTracingTest(unittest.TestCase):
+
+    @staticmethod
+    def _make_ws(headers=(), query_string: bytes = b''):
+        async def send(message):
+            pass
+
+        async def receive():
+            return {'type': 'websocket.connect'}
+
+        scope = {
+            'type': 'websocket',
+            'path': '/ws/games/abc',
+            'query_string': query_string,
+            'scheme': 'ws',
+            'client': ('127.0.0.1', 12345),
+            'server': ('127.0.0.1', 80),
+            'headers': headers,
+        }
+        return AsgiWebSocket(scope, receive, send)
+
+    @async_test
+    async def test_websocket_lifecycle_produces_span(self):
+        mixin, span_exporter, _ = make_mixin()
+        ws = self._make_ws()
+        wrapped = await mixin._before_websocket(ws)
+        self.assertIsNotNone(wrapped)
+        self.assertEqual(1, len(mixin._spans))
+        await mixin._after_websocket(wrapped)  # type: ignore[arg-type]
+        self.assertEqual(0, len(mixin._spans))
+        spans = span_exporter.get_finished_spans()
+        self.assertEqual(1, len(spans))
+        span = spans[0]
+        self.assertEqual('WS /ws/games/abc', span.name)
+        assert span.attributes is not None
+        self.assertEqual('ws', span.attributes['url.scheme'])
+        self.assertEqual('/ws/games/abc', span.attributes['url.path'])
+        self.assertNotIn('url.query', span.attributes)
+        self.assertEqual('websocket', span.attributes['network.protocol.name'])
+        self.assertEqual('tcp', span.attributes['network.transport'])
+        self.assertEqual('127.0.0.1', span.attributes['client.address'])
+        self.assertEqual(12345, span.attributes['client.port'])
+        self.assertEqual('127.0.0.1', span.attributes['server.address'])
+        self.assertEqual(80, span.attributes['server.port'])
+
+    @async_test
+    async def test_websocket_query_string_recorded(self):
+        mixin, span_exporter, _ = make_mixin()
+        ws = self._make_ws(query_string=b'room=1&token=abc')
+        wrapped = await mixin._before_websocket(ws)
+        await mixin._after_websocket(wrapped)  # type: ignore[arg-type]
+        spans = span_exporter.get_finished_spans()
+        self.assertEqual(1, len(spans))
+        assert spans[0].attributes is not None
+        self.assertEqual('room=1&token=abc', spans[0].attributes['url.query'])
+
+    @async_test
+    async def test_websocket_traceparent_propagates(self):
+        mixin, span_exporter, _ = make_mixin()
+        ws = self._make_ws(headers=[(b'traceparent', TRACEPARENT.encode())])
+        wrapped = await mixin._before_websocket(ws)
+        await mixin._after_websocket(wrapped)  # type: ignore[arg-type]
+        spans = span_exporter.get_finished_spans()
+        self.assertEqual(1, len(spans))
+        self.assertEqual(0x4bf92f3577b34da6a3ce929d0e0e4736, spans[0].context.trace_id)  # type: ignore[union-attr]
+
+    @async_test
+    async def test_wrapped_websocket_delegates(self):
+        mixin, _, _ = make_mixin()
+        ws = self._make_ws()
+        wrapped = await mixin._before_websocket(ws)
+        assert wrapped is not None
+        self.assertEqual('/ws/games/abc', wrapped.path)
+        self.assertEqual(('127.0.0.1', 12345), wrapped.client)
+        await mixin._after_websocket(wrapped)
+
+    @async_test
+    async def test_websocket_error_close_code_marks_span_error(self):
+        mixin, span_exporter, _ = make_mixin()
+        ws = self._make_ws()
+        wrapped = await mixin._before_websocket(ws)
+        assert wrapped is not None
+        await wrapped.close(1011)
+        await mixin._after_websocket(wrapped)
+
+        spans = span_exporter.get_finished_spans()
+        self.assertEqual(1, len(spans))
+        self.assertEqual(StatusCode.ERROR, spans[0].status.status_code)
+        assert spans[0].attributes is not None
+        self.assertEqual(1011, spans[0].attributes['kaya.websocket.close_code'])
+        self.assertEqual('1011', spans[0].attributes['error.type'])
+
+    @async_test
+    async def test_websocket_exception_marks_span_error(self):
+        mixin, span_exporter, _ = make_mixin()
+        ws = self._make_ws()
+        wrapped = await mixin._before_websocket(ws)
+        assert wrapped is not None
+        wrapped.exception = RuntimeError('ws boom')
+        await mixin._after_websocket(wrapped)
+
+        spans = span_exporter.get_finished_spans()
+        self.assertEqual(1, len(spans))
+        self.assertEqual(StatusCode.ERROR, spans[0].status.status_code)
+        self.assertTrue(any(event.name == 'exception' for event in spans[0].events))
+        assert spans[0].attributes is not None
+        self.assertEqual('RuntimeError', spans[0].attributes['error.type'])
+
+    @async_test
+    async def test_websocket_hooks_are_called(self):
+        calls = []
+
+        def connect_hook(span: Any, ws: Any) -> None:
+            calls.append(('connect', ws.path))
+            span.set_attribute('test.websocket_connect_hook', True)
+
+        def close_hook(span: Any, ws: Any) -> None:
+            calls.append(('close', ws.path))
+            span.set_attribute('test.websocket_close_hook', True)
+
+        mixin, span_exporter, _ = make_mixin(
+            websocket_connect_hook=connect_hook,
+            websocket_close_hook=close_hook,
+        )
+        ws = self._make_ws()
+        wrapped = await mixin._before_websocket(ws)
+        assert wrapped is not None
+        await wrapped.close(1000)
+        await mixin._after_websocket(wrapped)
+
+        self.assertEqual([('connect', '/ws/games/abc'), ('close', '/ws/games/abc')], calls)
+        spans = span_exporter.get_finished_spans()
+        self.assertEqual(1, len(spans))
+        self.assertEqual(StatusCode.UNSET, spans[0].status.status_code)
+        assert spans[0].attributes is not None
+        self.assertNotIn('error.type', spans[0].attributes)
+        self.assertTrue(spans[0].attributes['test.websocket_connect_hook'])
+        self.assertTrue(spans[0].attributes['test.websocket_close_hook'])
+
+
+if __name__ == '__main__':
+    unittest.main()

packages/kaya-rsgi/src/kaya/rsgi/_rsgi.py

@@ -17,13 +17,21 @@ from typing import (
 from granian._granian import (  # type: ignore[attr-defined]
     RSGIHTTPProtocol,
     RSGIHTTPScope,
+    RSGIProtocolClosed,
     RSGIWebsocketProtocol,
     RSGIWebsocketScope,
     RSGIWebsocketTransport,
 )
 from pwo import Maybe
 
-from kaya.core import AbstractKayaApp, HttpContext, HttpMethod, WebSocket, WebSocketMessage
+from kaya.core import (
+    AbstractKayaApp,
+    HttpContext,
+    HttpMethod,
+    WebSocket,
+    WebSocketDisconnect,
+    WebSocketMessage,
+)
 from kaya.core._types import StrOrStrings
 
 
@@ -109,6 +117,7 @@ class RsgiContext(HttpContext):
 class RsgiWebSocket(WebSocket):
     _protocol: RSGIWebsocketProtocol
     _transport: Optional[RSGIWebsocketTransport]
+    _closed: bool
     scheme: str
     path: str
     query_string: str
@@ -124,6 +133,7 @@ class RsgiWebSocket(WebSocket):
             )
         self._protocol = protocol
         self._transport = None
+        self._closed = False
         self.scheme = scope.scheme
         self.path = scope.path
         self.query_string = scope.query_string
@@ -144,13 +154,28 @@ class RsgiWebSocket(WebSocket):
     async def accept(self, headers: Optional[Mapping[str, StrOrStrings]] = None) -> None:
         # RSGI's websocket accept() takes no arguments (https://github.com/emmett-framework/granian/blob/master/docs/spec/RSGI.md),
         # so handshake headers (e.g. Set-Cookie) cannot be sent on RSGI; they are silently ignored here.
-        self._transport = await self._protocol.accept()
+        try:
+            self._transport = await self._protocol.accept()
+        except RSGIProtocolClosed as exc:
+            self._closed = True
+            raise WebSocketDisconnect(code=1006) from exc
 
     async def receive(self) -> WebSocketMessage:
         if self._transport is None:
             raise RuntimeError('WebSocket connection has not been accepted yet')
-        message = await self._transport.receive()
+        if self._closed:
+            return WebSocketMessage(kind='close')
+        try:
+            message = await self._transport.receive()
+        except RSGIProtocolClosed:
+            # Granian raises this when the peer is gone without a close
+            # handshake (browser tab closed, network dropped, ...). Surface it
+            # as a close message so receive loops terminate normally instead
+            # of seeing an exception.
+            self._closed = True
+            return WebSocketMessage(kind='close')
         if message.kind == 0:
+            self._closed = True
             return WebSocketMessage(kind='close')
         elif message.kind == 1:
             return WebSocketMessage(kind='binary', data=message.data)
@@ -162,15 +187,32 @@ class RsgiWebSocket(WebSocket):
     async def send_text(self, data: str) -> None:
         if self._transport is None:
             raise RuntimeError('WebSocket connection has not been accepted yet')
-        await self._transport.send_str(data)
+        if self._closed:
+            raise WebSocketDisconnect(code=1006)
+        try:
+            await self._transport.send_str(data)
+        except RSGIProtocolClosed as exc:
+            self._closed = True
+            raise WebSocketDisconnect(code=1006) from exc
 
     async def send_bytes(self, data: bytes) -> None:
         if self._transport is None:
             raise RuntimeError('WebSocket connection has not been accepted yet')
-        await self._transport.send_bytes(data)
+        if self._closed:
+            raise WebSocketDisconnect(code=1006)
+        try:
+            await self._transport.send_bytes(data)
+        except RSGIProtocolClosed as exc:
+            self._closed = True
+            raise WebSocketDisconnect(code=1006) from exc
 
     async def close(self, code: int = 1000) -> None:
-        self._protocol.close(code)
+        if self._closed:
+            return
+        try:
+            self._protocol.close(code)
+        except RSGIProtocolClosed:
+            self._closed = True
 
     async def __anext__(self) -> WebSocketMessage:
         message = await self.receive()

packages/kaya-rsgi/tests/test_rsgi.py

@@ -1,22 +1,150 @@
 import unittest
+from types import SimpleNamespace
+from typing import Any
+
+from granian.rsgi import ProtocolClosed
+from pwo import async_test
+
+from kaya.core import WebSocketDisconnect
 from kaya.rsgi import RsgiWebSocket
 
 
+class FakeScope:
+    scheme = 'ws'
+    path = '/ws'
+    query_string = ''
+    headers: dict[str, list[str]] = {}
+    client = '127.0.0.1:12345'
+    server = '127.0.0.1:80'
+
+
+class FakeTransport:
+    """A transport whose peer vanished without a close handshake."""
+
+    def __init__(self) -> None:
+        self.receive_calls = 0
+        self.sent: list[Any] = []
+
+    async def receive(self) -> Any:
+        self.receive_calls += 1
+        raise ProtocolClosed()
+
+    async def send_str(self, data: str) -> None:
+        self.sent.append(data)
+        raise ProtocolClosed()
+
+    async def send_bytes(self, data: bytes) -> None:
+        self.sent.append(data)
+        raise ProtocolClosed()
+
+
+class CleanCloseTransport(FakeTransport):
+    """A transport that reports a close message (kind 0)."""
+
+    async def receive(self) -> Any:
+        self.receive_calls += 1
+        return SimpleNamespace(kind=0, data=None)
+
+
+class FakeProtocol:
+    def __init__(self, transport: FakeTransport) -> None:
+        self._transport = transport
+        self.closed: list[int] = []
+
+    async def accept(self) -> FakeTransport:
+        return self._transport
+
+    def close(self, code: int) -> None:
+        self.closed.append(code)
+
+
+class ClosedOnAcceptProtocol(FakeProtocol):
+    """A protocol whose peer vanished during the handshake."""
+
+    async def accept(self) -> FakeTransport:
+        raise ProtocolClosed()
+
+
 class RsgiWebSocketTest(unittest.TestCase):
 
     def test_misconfigured_granian(self):
-        class FakeScope:
+        class FakeProtocolWithoutWebsockets:
-            scheme = 'ws'
-            path = '/ws'
-            query_string = ''
-            headers = {}
-            client = '127.0.0.1:12345'
-            server = '127.0.0.1:80'
-
-        class FakeProtocol:
             pass
 
         with self.assertRaises(RuntimeError) as ctx:
-            RsgiWebSocket(FakeScope(), FakeProtocol())  # type: ignore[arg-type]
+            RsgiWebSocket(FakeScope(), FakeProtocolWithoutWebsockets())  # type: ignore[arg-type]
 
         self.assertIn('Granian was not configured for websockets', str(ctx.exception))
+
+    async def _socket(self, transport: FakeTransport) -> tuple[RsgiWebSocket, FakeProtocol]:
+        protocol = FakeProtocol(transport)
+        ws = RsgiWebSocket(FakeScope(), protocol)  # type: ignore[arg-type]
+        await ws.accept()
+        return ws, protocol
+
+    @async_test
+    async def test_receive_returns_close_when_transport_is_gone(self):
+        ws, _ = await self._socket(FakeTransport())
+        message = await ws.receive()
+        self.assertEqual('close', message.kind)
+
+    @async_test
+    async def test_iteration_ends_when_transport_is_gone(self):
+        ws, _ = await self._socket(FakeTransport())
+        messages = [message async for message in ws]
+        self.assertEqual([], messages)
+
+    @async_test
+    async def test_receive_remembers_the_close(self):
+        transport = FakeTransport()
+        ws, _ = await self._socket(transport)
+        self.assertEqual('close', (await ws.receive()).kind)
+        self.assertEqual('close', (await ws.receive()).kind)
+        self.assertEqual(1, transport.receive_calls)
+
+    @async_test
+    async def test_send_text_raises_disconnect_when_transport_is_gone(self):
+        ws, _ = await self._socket(FakeTransport())
+        with self.assertRaises(WebSocketDisconnect) as ctx:
+            await ws.send_text('hello')
+        self.assertEqual(1006, ctx.exception.code)
+
+    @async_test
+    async def test_send_bytes_raises_disconnect_when_transport_is_gone(self):
+        ws, _ = await self._socket(FakeTransport())
+        with self.assertRaises(WebSocketDisconnect) as ctx:
+            await ws.send_bytes(b'hello')
+        self.assertEqual(1006, ctx.exception.code)
+
+    @async_test
+    async def test_sends_after_disconnect_do_not_touch_the_transport(self):
+        transport = FakeTransport()
+        ws, _ = await self._socket(transport)
+        with self.assertRaises(WebSocketDisconnect):
+            await ws.send_text('first')
+        with self.assertRaises(WebSocketDisconnect):
+            await ws.send_text('second')
+        self.assertEqual(['first'], transport.sent)
+
+    @async_test
+    async def test_send_after_a_clean_close_raises_disconnect(self):
+        transport = CleanCloseTransport()
+        ws, _ = await self._socket(transport)
+        self.assertEqual('close', (await ws.receive()).kind)
+        with self.assertRaises(WebSocketDisconnect):
+            await ws.send_text('hello')
+        self.assertEqual([], transport.sent)
+
+    @async_test
+    async def test_accept_raises_disconnect_when_transport_is_gone(self):
+        ws = RsgiWebSocket(FakeScope(), ClosedOnAcceptProtocol(FakeTransport()))  # type: ignore[arg-type]
+        with self.assertRaises(WebSocketDisconnect) as ctx:
+            await ws.accept()
+        self.assertEqual(1006, ctx.exception.code)
+
+    @async_test
+    async def test_close_is_noop_once_the_transport_is_gone(self):
+        ws, protocol = await self._socket(FakeTransport())
+        await ws.receive()
+        await ws.close(1000)
+        self.assertEqual([], protocol.closed)

requirements-dev.in

@@ -7,6 +7,7 @@ kaya-oidc @ file:./packages/kaya-oidc
 kaya-openapi @ file:./packages/kaya-openapi
 kaya-cors @ file:./packages/kaya-cors
 kaya-forwarded @ file:./packages/kaya-forwarded
+kaya-otel @ file:./packages/kaya-otel
 build
 fakeredis
 mypy

requirements-dev.txt

@@ -44,6 +44,8 @@ executing==2.2.1
     # via stack-data
 fakeredis==2.36.2
     # via -r requirements-dev.in
+googleapis-common-protos==1.75.3
+    # via opentelemetry-exporter-otlp-proto-http
 granian==2.7.9
     # via kaya-rsgi
 h11==0.16.0
@@ -93,6 +95,7 @@ file:./packages/kaya-core
     #   kaya-forwarded
     #   kaya-oidc
     #   kaya-openapi
+    #   kaya-otel
     #   kaya-rsgi
     #   kaya-session
 file:./packages/kaya-cors
@@ -103,6 +106,8 @@ file:./packages/kaya-oidc
     # via -r requirements-dev.in
 file:./packages/kaya-openapi
     # via -r requirements-dev.in
+file:./packages/kaya-otel
+    # via -r requirements-dev.in
 file:./packages/kaya-rsgi
     # via -r requirements-dev.in
 file:./packages/kaya-session
@@ -135,6 +140,25 @@ mypy-extensions==1.1.0
     # via mypy
 nh3==0.3.6
     # via readme-renderer
+opentelemetry-api==1.44.0
+    # via
+    #   opentelemetry-exporter-otlp-proto-http
+    #   opentelemetry-sdk
+    #   opentelemetry-semantic-conventions
+opentelemetry-exporter-otlp-proto-common==1.44.0
+    # via opentelemetry-exporter-otlp-proto-http
+opentelemetry-exporter-otlp-proto-http==1.44.0
+    # via kaya-otel
+opentelemetry-proto==1.44.0
+    # via
+    #   opentelemetry-exporter-otlp-proto-common
+    #   opentelemetry-exporter-otlp-proto-http
+opentelemetry-sdk==1.44.0
+    # via
+    #   kaya-otel
+    #   opentelemetry-exporter-otlp-proto-http
+opentelemetry-semantic-conventions==0.65b0
+    # via opentelemetry-sdk
 packaging==26.2
     # via
     #   build
@@ -147,6 +171,10 @@ pexpect==4.9.0
     # via ipython
 prompt-toolkit==3.0.52
     # via ipython
+protobuf==7.36.2
+    # via
+    #   googleapis-common-protos
+    #   opentelemetry-proto
 psutil==7.2.2
     # via ipython
 ptyprocess==0.7.0
@@ -178,6 +206,7 @@ redis==8.0.1
     #   kaya-session-redis
 requests==2.34.2
     # via
+    #   opentelemetry-exporter-otlp-proto-http
     #   requests-toolbelt
     #   twine
 requests-toolbelt==1.0.0
@@ -202,6 +231,10 @@ typing-extensions==4.16.0
     # via
     #   kaya-core
     #   mypy
+    #   opentelemetry-api
+    #   opentelemetry-exporter-otlp-proto-http
+    #   opentelemetry-sdk
+    #   opentelemetry-semantic-conventions
     #   pwo
 urllib3==2.7.0
     # via