fastapi-webrtc 0.1.0__tar.gz

fastapi_webrtc-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+tests/typescript/dist/
+tests/browser/dist/
+tests/browser/results/
+tests/browser/report/

fastapi_webrtc-0.1.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## 0.1.0 - 2026-10-20
+
+Initial release.
+
+- `WebRtcRouter.session()` declares WebRTC sessions as WebSocket signaling
+  endpoints. FastAPI dependencies admit sessions before any peer is created and
+  stay open until cleanup finished, also when the server cancels the endpoint.
+- `Session` handlers: `on_start`, `run`, `on_track`, typed `on_message`,
+  `on_close` and outgoing tracks. `Peer` sends messages and tracks with
+  renegotiation, and exposes stats and close codes. Stats report jitter as
+  `None` when the engine cannot convert it to seconds (aiortc). `on_close` runs
+  once per accepted session and keeps at least one second even when cancelled
+  handlers used up `shutdown_timeout_seconds`.
+- Track ownership: session tracks and `send_track(track)` are stopped on removal
+  or cleanup, including rejected and partially started sessions;
+  `send_track(track, owned=False)` keeps shared sources running behind a
+  sender-local forwarding track. Only active
+  incoming tracks count against `MediaPolicy.max_incoming_tracks`.
+- Typed data channels from Pydantic models, `str` or `bytes`. JSON messages use
+  the contract's serialization aliases. Channels support negotiated IDs,
+  validated keyword-only reliability options, size limits, bounded inbound
+  queues and send backpressure. A `DataChannelSpec` is generic over its message
+  types: `on_message` accepts specs as keys, and `peer.channel(spec)` and
+  `peer.send_message(spec, ...)` are type-checked against its models.
+  `Never` as `receive_model` or `send_model` declares a one-way channel
+  (format `none`); the generated client omits `send` or `subscribe` for it.
+- Signaling protocol `fastapi-webrtc.v1`. It uses perfect negotiation,
+  candidate buffering, ICE username checks, categorized close codes and
+  negotiation, media and transport deadlines. Negotiation timeouts and shutdown
+  cancel blocked ICE and engine startup.
+- ICE server providers, `TurnRestCredentials` with separate engine URLs and
+  session event hooks.
+- `WebRtcRouter(allowed_origins=...)` refuses cross-site browser handshakes with
+  HTTP 403 before the session factory runs.
+- A pluggable `Engine` protocol, with an `aiortc` reference engine behind the
+  `aiortc` extra.
+- Tested Canon/Dishka composition with explicit async-factory injection,
+  session services, per-message request scopes and ordered cleanup.
+- `fastapi-webrtc contract` and `fastapi-webrtc generate` export a session
+  contract and generate a dependency-free TypeScript browser client with typed
+  parameters, channels and errors. Query models become flat named parameters.
+  Ambiguous generated names fail before files are written. Both commands support
+  `--check` drift detection.
+- The browser client merges query values from the base URL, shared credential
+  providers, per-call maps and named parameters, in that order; `null` removes
+  a value. `timeoutMs` bounds credential resolution and connection setup;
+  `signal` cancels the whole session. Renegotiation
+  and channel sends (`sendTimeoutMs`) have deadlines after connect, and
+  permanent transport failure rejects pending operations.

fastapi_webrtc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathis Arends
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_webrtc-0.1.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.5
+Name: fastapi-webrtc
+Version: 0.1.0
+Summary: Typed WebRTC sessions for FastAPI with signaling, engines and generated browser clients
+Project-URL: Repository, https://github.com/mathisarends/canon
+Project-URL: Source, https://github.com/mathisarends/canon/tree/main/packages/fastapi-webrtc
+Project-URL: Documentation, https://github.com/mathisarends/canon/tree/main/packages/fastapi-webrtc/docs
+Project-URL: Issues, https://github.com/mathisarends/canon/issues
+Author-email: Mathis Arends <mathisarends27@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Conferencing
+Classifier: Topic :: Multimedia :: Video
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.12
+Requires-Dist: anyio>=4
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: starlette>=0.41
+Requires-Dist: typing-extensions>=4.12
+Provides-Extra: aiortc
+Requires-Dist: aiortc<2,>=1.14; extra == 'aiortc'
+Description-Content-Type: text/markdown
+
+# fastapi-webrtc
+
+Typed WebRTC sessions for FastAPI. You declare a session like a route: its
+factory is an ordinary FastAPI dependency, so authentication, path and query
+parameters and `yield` cleanup work as usual. They all run before any peer
+connection exists. The package exports a contract and generates a typed,
+framework-free browser client from it.
+
+```console
+pip install "fastapi-webrtc[aiortc]"
+```
+
+The core depends on FastAPI, Pydantic and Starlette >=0.41. The Starlette
+lower bound ensures that an admission dependency's `HTTPException` returns an
+HTTP response before accepting the WebSocket. Media engines are adapters; the
+`aiortc` extra installs the reference engine. Canon, RPCKit and GStreamer are
+not dependencies.
+
+## Server
+
+```python
+from typing import Annotated
+
+from aiortc.contrib.media import MediaRelay
+from fastapi import Depends, FastAPI, HTTPException, Query
+from pydantic import BaseModel
+
+from fastapi_webrtc import (
+    DataChannelSpec,
+    Direction,
+    IncomingTrack,
+    MediaPolicy,
+    Peer,
+    Session,
+    WebRtcRouter,
+)
+from fastapi_webrtc.engines.aiortc import AiortcEngine
+
+
+class Prompt(BaseModel):
+    text: str
+
+
+class Feedback(BaseModel):
+    text: str
+    words: int
+
+
+# The spec types the channel handles: `peer.channel(MESSAGES)` receives
+# `Prompt` and sends `Feedback`.
+MESSAGES = DataChannelSpec("messages", receive_model=Prompt, send_model=Feedback)
+
+
+def lesson_access(lesson_id: str, token: Annotated[str, Query()]) -> str:
+    if token != "demo":
+        raise HTTPException(status_code=403)  # HTTP 403; no peer is created.
+    return lesson_id
+
+
+rtc = WebRtcRouter(prefix="/rtc", engine=AiortcEngine(), max_sessions=50)
+
+
+@rtc.session(
+    "/lessons/{lesson_id}",
+    name="practice",
+    media=MediaPolicy(audio=Direction.SEND_RECEIVE),
+    data_channels=(MESSAGES,),
+)
+def practice(lesson: Annotated[str, Depends(lesson_access)]) -> Session:
+    relay = MediaRelay()
+
+    async def on_track(peer: Peer, track: IncomingTrack) -> None:
+        await peer.send_track(relay.subscribe(track.native))  # Echo the microphone.
+
+    async def on_prompt(peer: Peer, prompt: Prompt) -> None:
+        await peer.send_message(
+            MESSAGES, Feedback(text=prompt.text, words=len(prompt.text.split()))
+        )
+
+    return Session(on_track=on_track, on_message={MESSAGES: on_prompt})
+
+
+app = FastAPI()
+app.include_router(rtc)
+```
+
+A `Session` is assembled from handlers:
+
+- `on_start(peer)`: runs once the transport is connected and channels are open.
+- `run(peer)`: the session's main task. When it returns, the session closes normally.
+- `on_track(peer, track)`: called for each incoming track. `track.recv()` or
+  `async for frame in track` reads frames.
+- `on_message={spec: handler}`: validated messages per channel, keyed by its
+  `DataChannelSpec` or its name. Without a handler, a channel can be consumed
+  with `async for message in peer.channel(spec)`.
+- `on_close(peer, code)`: runs before the engine releases resources.
+- `tracks=[...]`: outgoing tracks. `ice_servers` overrides the router's ICE servers.
+
+`Peer` sends with `send_message`, `send_track` and `remove_track`, which
+renegotiate. `peer.channel(spec)` and `peer.send_message(spec, message)` are
+typed by the spec's `receive_model` and `send_model`; a channel name gives an
+untyped handle. Reliability options such as `ordered` are keyword-only.
+
+`receive_model=Never` or `send_model=Never` declares a one-way channel. The
+server drops and reports messages it does not accept, `send_message` raises
+`WebRtcError(invalid_message)`, and `on_message` handlers or `async for` on a
+channel without inbound messages are refused. The generated client omits
+`send` or `subscribe` for that direction. `Never` is not inferred as a type
+argument; annotate the spec, for example `DataChannelSpec[Never, Tick]`. It also provides `stats()`, `close(code)` and `wait_closed()`.
+The session stops tracks it owns when it closes. It never stops tracks passed
+with `owned=False`.
+
+Set `role=Role.OFFERER` when the server should create the offer, for example
+when the browser only watches.
+
+## Browser client
+
+```console
+fastapi-webrtc contract --app app:app --output contract.json
+fastapi-webrtc generate --contract contract.json --output src/rtc --client-name PracticeRtcClient
+```
+
+```ts
+import { PracticeRtcClient, isRtcError } from "./rtc/index.js";
+
+const client = new PracticeRtcClient({ baseUrl: "https://api.example.com" });
+const microphone = await navigator.mediaDevices.getUserMedia({ audio: true });
+
+const session = await client.practice.connect({
+  lessonId: "greetings", // path parameter
+  token: "demo", // query parameter
+  tracks: microphone, // borrowed: never stopped by the session
+  timeoutMs: 10_000,
+  onTrack: ({ track }) => {
+    audio.srcObject = new MediaStream([track]);
+  },
+  onMessage: { messages: (feedback) => console.log(feedback.words) },
+});
+
+await session.channels.messages.send({ text: "hello" }); // typed as Prompt
+await session.close(); // idempotent
+```
+
+`timeoutMs` limits connection setup, including asynchronous credential providers,
+and stops applying once the session is ready. Use `signal` for cancellation of
+the session's entire lifetime: aborting it also closes an already running audio
+or video session. An `AbortSignal.timeout(...)` therefore ends the session when
+its timer expires, even if connection setup already succeeded.
+
+Later renegotiations, including `addTrack()` and `removeTrack()`, use the
+server's `negotiation_timeout_ms` and end the session with `negotiation_timeout`
+if they cannot complete. Channel sends wait at most `sendTimeoutMs` (10 seconds
+by default) for opening or buffer drainage before ending with `slow_consumer`.
+Permanent peer-connection failure rejects pending operations with `transport_lost`.
+
+Failures are `RtcError`s with a stable `code`, such as `session_limit`,
+`negotiation_timeout`, `media_rejected` or `transport_lost`. Browsers do not
+expose the HTTP status of a refused WebSocket handshake. A session denied by a
+dependency therefore fails with `connection_failed`. The full list of codes is
+in [the protocol](docs/protocol.md#close-codes).
+
+Both commands accept `--check`, which fails on drift without writing.
+Generated directories contain a manifest. Stale generated files are removed;
+files you add yourself are kept.
+
+Configure shared credentials with `new PracticeRtcClient({ query: async () =>
+({ token: await refreshToken() }) })`. The provider runs for every connection.
+Query values are merged in this order, with later sources taking precedence:
+the `baseUrl` query string, `client.config.query`, `connect({ query: ... })`, then
+named connect parameters such as `connect({ lessonId: "greetings", token: "new" })`.
+Use wire aliases as keys inside query maps. An omitted named parameter preserves
+shared values; `null` explicitly removes a query value. Required query parameters
+are checked after merging. Generated query fields are optional so shared
+credentials can supply them; required path parameters must still be passed.
+
+## Security
+
+Session admission is ordinary FastAPI dependency code, so authorization stays in
+your application. Two WebSocket properties need attention:
+
+- **Origins.** CORS does not apply to WebSocket handshakes, and browsers attach
+  cookies to cross-site handshakes. If admission relies on cookies, pass
+  `WebRtcRouter(allowed_origins=["https://app.example.com"])`. Handshakes from
+  other origins are refused with HTTP 403 before the session factory runs.
+  Requests without an `Origin` header come from non-browser clients and are not
+  restricted by this check.
+- **Query tokens.** Browsers cannot set headers on a WebSocket, so tokens travel
+  in the URL. URLs can appear in proxy and server access logs. Prefer short-lived,
+  single-use session tickets issued by an authenticated HTTP endpoint over
+  long-lived access tokens, and supply them through the client's `query` provider.
+
+## Limits and ICE
+
+`SessionLimits` bounds negotiation time, pending candidates, signaling and
+message sizes, inbound queues and send buffers. It also sets grace periods for
+transport and signaling loss. Every limit has a categorized error.
+`TurnRestCredentials` issues time-limited TURN REST credentials per user. It can
+give the server-side engine internal relay URLs.
+
+## Documentation
+
+- [Signaling protocol](docs/protocol.md)
+- [Canon composition and Dishka session/message scopes](docs/canon-dishka.md)
+- [Changelog](CHANGELOG.md)
+- Runnable example: [`examples/practice`](examples/practice). Its generated
+  client is in `examples/practice/client`.
+
+The engine interface abstracts signaling and lifecycle. Native outgoing tracks
+and received frames remain engine-specific: aiortc uses `MediaStreamTrack` and
+PyAV frames. Its statistics return `jitter_seconds=None` because the public
+report does not identify the per-stream codec clock rate needed for conversion.
+
+Generated TypeScript models provide compile-time message types; the browser
+runtime checks formats and sizes but does not enforce every JSON Schema rule.
+Server-side Pydantic adapters validate incoming and outgoing typed messages.

fastapi_webrtc-0.1.0/README.md

@@ -0,0 +1,215 @@
+# fastapi-webrtc
+
+Typed WebRTC sessions for FastAPI. You declare a session like a route: its
+factory is an ordinary FastAPI dependency, so authentication, path and query
+parameters and `yield` cleanup work as usual. They all run before any peer
+connection exists. The package exports a contract and generates a typed,
+framework-free browser client from it.
+
+```console
+pip install "fastapi-webrtc[aiortc]"
+```
+
+The core depends on FastAPI, Pydantic and Starlette >=0.41. The Starlette
+lower bound ensures that an admission dependency's `HTTPException` returns an
+HTTP response before accepting the WebSocket. Media engines are adapters; the
+`aiortc` extra installs the reference engine. Canon, RPCKit and GStreamer are
+not dependencies.
+
+## Server
+
+```python
+from typing import Annotated
+
+from aiortc.contrib.media import MediaRelay
+from fastapi import Depends, FastAPI, HTTPException, Query
+from pydantic import BaseModel
+
+from fastapi_webrtc import (
+    DataChannelSpec,
+    Direction,
+    IncomingTrack,
+    MediaPolicy,
+    Peer,
+    Session,
+    WebRtcRouter,
+)
+from fastapi_webrtc.engines.aiortc import AiortcEngine
+
+
+class Prompt(BaseModel):
+    text: str
+
+
+class Feedback(BaseModel):
+    text: str
+    words: int
+
+
+# The spec types the channel handles: `peer.channel(MESSAGES)` receives
+# `Prompt` and sends `Feedback`.
+MESSAGES = DataChannelSpec("messages", receive_model=Prompt, send_model=Feedback)
+
+
+def lesson_access(lesson_id: str, token: Annotated[str, Query()]) -> str:
+    if token != "demo":
+        raise HTTPException(status_code=403)  # HTTP 403; no peer is created.
+    return lesson_id
+
+
+rtc = WebRtcRouter(prefix="/rtc", engine=AiortcEngine(), max_sessions=50)
+
+
+@rtc.session(
+    "/lessons/{lesson_id}",
+    name="practice",
+    media=MediaPolicy(audio=Direction.SEND_RECEIVE),
+    data_channels=(MESSAGES,),
+)
+def practice(lesson: Annotated[str, Depends(lesson_access)]) -> Session:
+    relay = MediaRelay()
+
+    async def on_track(peer: Peer, track: IncomingTrack) -> None:
+        await peer.send_track(relay.subscribe(track.native))  # Echo the microphone.
+
+    async def on_prompt(peer: Peer, prompt: Prompt) -> None:
+        await peer.send_message(
+            MESSAGES, Feedback(text=prompt.text, words=len(prompt.text.split()))
+        )
+
+    return Session(on_track=on_track, on_message={MESSAGES: on_prompt})
+
+
+app = FastAPI()
+app.include_router(rtc)
+```
+
+A `Session` is assembled from handlers:
+
+- `on_start(peer)`: runs once the transport is connected and channels are open.
+- `run(peer)`: the session's main task. When it returns, the session closes normally.
+- `on_track(peer, track)`: called for each incoming track. `track.recv()` or
+  `async for frame in track` reads frames.
+- `on_message={spec: handler}`: validated messages per channel, keyed by its
+  `DataChannelSpec` or its name. Without a handler, a channel can be consumed
+  with `async for message in peer.channel(spec)`.
+- `on_close(peer, code)`: runs before the engine releases resources.
+- `tracks=[...]`: outgoing tracks. `ice_servers` overrides the router's ICE servers.
+
+`Peer` sends with `send_message`, `send_track` and `remove_track`, which
+renegotiate. `peer.channel(spec)` and `peer.send_message(spec, message)` are
+typed by the spec's `receive_model` and `send_model`; a channel name gives an
+untyped handle. Reliability options such as `ordered` are keyword-only.
+
+`receive_model=Never` or `send_model=Never` declares a one-way channel. The
+server drops and reports messages it does not accept, `send_message` raises
+`WebRtcError(invalid_message)`, and `on_message` handlers or `async for` on a
+channel without inbound messages are refused. The generated client omits
+`send` or `subscribe` for that direction. `Never` is not inferred as a type
+argument; annotate the spec, for example `DataChannelSpec[Never, Tick]`. It also provides `stats()`, `close(code)` and `wait_closed()`.
+The session stops tracks it owns when it closes. It never stops tracks passed
+with `owned=False`.
+
+Set `role=Role.OFFERER` when the server should create the offer, for example
+when the browser only watches.
+
+## Browser client
+
+```console
+fastapi-webrtc contract --app app:app --output contract.json
+fastapi-webrtc generate --contract contract.json --output src/rtc --client-name PracticeRtcClient
+```
+
+```ts
+import { PracticeRtcClient, isRtcError } from "./rtc/index.js";
+
+const client = new PracticeRtcClient({ baseUrl: "https://api.example.com" });
+const microphone = await navigator.mediaDevices.getUserMedia({ audio: true });
+
+const session = await client.practice.connect({
+  lessonId: "greetings", // path parameter
+  token: "demo", // query parameter
+  tracks: microphone, // borrowed: never stopped by the session
+  timeoutMs: 10_000,
+  onTrack: ({ track }) => {
+    audio.srcObject = new MediaStream([track]);
+  },
+  onMessage: { messages: (feedback) => console.log(feedback.words) },
+});
+
+await session.channels.messages.send({ text: "hello" }); // typed as Prompt
+await session.close(); // idempotent
+```
+
+`timeoutMs` limits connection setup, including asynchronous credential providers,
+and stops applying once the session is ready. Use `signal` for cancellation of
+the session's entire lifetime: aborting it also closes an already running audio
+or video session. An `AbortSignal.timeout(...)` therefore ends the session when
+its timer expires, even if connection setup already succeeded.
+
+Later renegotiations, including `addTrack()` and `removeTrack()`, use the
+server's `negotiation_timeout_ms` and end the session with `negotiation_timeout`
+if they cannot complete. Channel sends wait at most `sendTimeoutMs` (10 seconds
+by default) for opening or buffer drainage before ending with `slow_consumer`.
+Permanent peer-connection failure rejects pending operations with `transport_lost`.
+
+Failures are `RtcError`s with a stable `code`, such as `session_limit`,
+`negotiation_timeout`, `media_rejected` or `transport_lost`. Browsers do not
+expose the HTTP status of a refused WebSocket handshake. A session denied by a
+dependency therefore fails with `connection_failed`. The full list of codes is
+in [the protocol](docs/protocol.md#close-codes).
+
+Both commands accept `--check`, which fails on drift without writing.
+Generated directories contain a manifest. Stale generated files are removed;
+files you add yourself are kept.
+
+Configure shared credentials with `new PracticeRtcClient({ query: async () =>
+({ token: await refreshToken() }) })`. The provider runs for every connection.
+Query values are merged in this order, with later sources taking precedence:
+the `baseUrl` query string, `client.config.query`, `connect({ query: ... })`, then
+named connect parameters such as `connect({ lessonId: "greetings", token: "new" })`.
+Use wire aliases as keys inside query maps. An omitted named parameter preserves
+shared values; `null` explicitly removes a query value. Required query parameters
+are checked after merging. Generated query fields are optional so shared
+credentials can supply them; required path parameters must still be passed.
+
+## Security
+
+Session admission is ordinary FastAPI dependency code, so authorization stays in
+your application. Two WebSocket properties need attention:
+
+- **Origins.** CORS does not apply to WebSocket handshakes, and browsers attach
+  cookies to cross-site handshakes. If admission relies on cookies, pass
+  `WebRtcRouter(allowed_origins=["https://app.example.com"])`. Handshakes from
+  other origins are refused with HTTP 403 before the session factory runs.
+  Requests without an `Origin` header come from non-browser clients and are not
+  restricted by this check.
+- **Query tokens.** Browsers cannot set headers on a WebSocket, so tokens travel
+  in the URL. URLs can appear in proxy and server access logs. Prefer short-lived,
+  single-use session tickets issued by an authenticated HTTP endpoint over
+  long-lived access tokens, and supply them through the client's `query` provider.
+
+## Limits and ICE
+
+`SessionLimits` bounds negotiation time, pending candidates, signaling and
+message sizes, inbound queues and send buffers. It also sets grace periods for
+transport and signaling loss. Every limit has a categorized error.
+`TurnRestCredentials` issues time-limited TURN REST credentials per user. It can
+give the server-side engine internal relay URLs.
+
+## Documentation
+
+- [Signaling protocol](docs/protocol.md)
+- [Canon composition and Dishka session/message scopes](docs/canon-dishka.md)
+- [Changelog](CHANGELOG.md)
+- Runnable example: [`examples/practice`](examples/practice). Its generated
+  client is in `examples/practice/client`.
+
+The engine interface abstracts signaling and lifecycle. Native outgoing tracks
+and received frames remain engine-specific: aiortc uses `MediaStreamTrack` and
+PyAV frames. Its statistics return `jitter_seconds=None` because the public
+report does not identify the per-stream codec clock rate needed for conversion.
+
+Generated TypeScript models provide compile-time message types; the browser
+runtime checks formats and sizes but does not enforce every JSON Schema rule.
+Server-side Pydantic adapters validate incoming and outgoing typed messages.

fastapi_webrtc-0.1.0/docs/canon-dishka.md

@@ -0,0 +1,92 @@
+# Canon and Dishka
+
+Register `WebRtcRouter` directly in `Feature.routers`. Canon installs Dishka's
+middleware and manages the application container. WebRTC does not need a Canon
+adapter or a required dependency on Canon or Dishka.
+
+The session factory is a FastAPI dependency. Decorate an **async factory** with
+`@inject` below `@rtc.session(...)`; Canon does not automatically inject this
+factory. Session services use `Scope.SESSION`, matching Dishka's
+[WebSocket scope model](https://dishka.readthedocs.io/en/stable/integrations/fastapi.html#websockets).
+
+```python
+from collections.abc import AsyncIterator
+
+from dishka import AsyncContainer, FromDishka, Provider, Scope, provide
+from dishka.integrations.fastapi import inject
+from fastapi import FastAPI
+from fastapi_canon import Composition, Feature
+from fastapi_webrtc import DataChannelSpec, Peer, Session, WebRtcRouter
+from fastapi_webrtc.engines.aiortc import AiortcEngine
+
+
+class Transcript:
+    def __init__(self) -> None:
+        self.messages: list[str] = []
+
+
+class MessageWork:
+    def reply(self, text: str, transcript: Transcript) -> str:
+        transcript.messages.append(text)
+        return text.upper()
+
+
+class Services(Provider):
+    @provide(scope=Scope.SESSION)
+    async def transcript(self) -> AsyncIterator[Transcript]:
+        transcript = Transcript()
+        yield transcript
+        # Persist or release session resources here, after on_close.
+
+    @provide(scope=Scope.REQUEST)
+    async def work(self) -> AsyncIterator[MessageWork]:
+        yield MessageWork()
+        # Release this message's transaction or other short-lived resources.
+
+
+rtc = WebRtcRouter(engine=AiortcEngine())
+
+
+CHAT = DataChannelSpec("chat", receive_model=str, send_model=str)
+
+
+@rtc.session("/chat", data_channels=[CHAT])
+@inject
+async def chat(
+    transcript: FromDishka[Transcript], container: FromDishka[AsyncContainer]
+) -> Session:
+    async def on_message(peer: Peer, text: str) -> None:
+        async with container(scope=Scope.REQUEST) as request:
+            work = await request.get(MessageWork)
+            await peer.send_message(CHAT, work.reply(text, transcript))
+
+    return Session(on_message={CHAT: on_message})
+
+
+app = Composition(Feature(name="chat", routers=[rtc], providers=[Services])).apply(
+    FastAPI()
+)
+```
+
+Callbacks are called directly with the documented `Peer`, message, track or
+close-code arguments. Capture session services in the factory's closures;
+adding `FromDishka[...]` callback parameters does not inject them. For resources
+per message, enter a new child `Scope.REQUEST` and resolve services explicitly,
+as above. Await all work using those resources before leaving the child scope.
+
+Accepted sessions call `on_close` while session services remain available.
+Owned tracks and engine peers are then released before the session dependency
+scope exits, including when the ASGI task is cancelled during cleanup. Canon
+runs feature-router shutdown before closing feature resources and its
+application container.
+
+FastAPI authentication dependencies can deny admission before the factory runs.
+Capacity and router-shutdown checks happen after factory resolution: if a
+returned `Session` is refused, its owned `tracks` are stopped before dependency
+teardown, without calling `on_close` or allocating an engine peer. Factories
+must clean up resources they create if they raise before returning a `Session`.
+
+The executable [integration tests](../../../tests/integration/test_webrtc_dishka.py)
+cover HTTP admission denial, capacity rejection, disconnect, application
+shutdown, cleanup order and two real aiortc data-channel messages with distinct
+request scopes sharing one session service.