pondsocket-asgi 0.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,12 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.egg-info/
6
+ .pytest_cache/
7
+ .mypy_cache/
8
+ .ruff_cache/
9
+ build/
10
+ dist/
11
+ .coverage
12
+ htmlcov/
@@ -0,0 +1,143 @@
1
+ Metadata-Version: 2.4
2
+ Name: pondsocket-asgi
3
+ Version: 0.0.1
4
+ Summary: Canonical ASGI adapter for PondSocket.
5
+ Author: eleven-am
6
+ License: GPL-3.0-or-later
7
+ Requires-Python: >=3.11
8
+ Requires-Dist: pondsocket-common<0.1.0,>=0.0.1
9
+ Requires-Dist: pondsocket<0.1.0,>=0.0.1
10
+ Description-Content-Type: text/markdown
11
+
12
+ # pondsocket-asgi
13
+
14
+ Canonical ASGI adapter for [`pondsocket`](../pondsocket/). Mount under any ASGI host — FastAPI, Starlette, Litestar, Django, raw uvicorn.
15
+
16
+ Handles WebSocket and SSE (Server-Sent Events) transports. The same `PondSocket` instance serves both — the adapter detects the request type and dispatches.
17
+
18
+ ## Install
19
+
20
+ ```
21
+ pip install pondsocket-asgi
22
+ ```
23
+
24
+ Pulls in `pondsocket` and `pondsocket-common` automatically.
25
+
26
+ ## Quick start: raw uvicorn
27
+
28
+ ```python
29
+ from pondsocket import ConnectionContext, EventContext, JoinContext, PondSocket
30
+ from pondsocket_asgi import PondASGIApp
31
+
32
+
33
+ async def auth(ctx: ConnectionContext) -> None:
34
+ ctx.accept()
35
+
36
+
37
+ async def on_join(ctx: JoinContext) -> None:
38
+ await ctx.accept()
39
+
40
+
41
+ async def on_message(ctx: EventContext) -> None:
42
+ await ctx.broadcast(ctx.event_name, ctx.get_payload())
43
+
44
+
45
+ pond = PondSocket()
46
+ endpoint = pond.create_endpoint("/socket", auth)
47
+ lobby = endpoint.create_channel("/chat/:room_id", on_join)
48
+ lobby.on_message("message", on_message)
49
+
50
+ app = PondASGIApp(pond)
51
+ ```
52
+
53
+ ```
54
+ uvicorn module:app --host 127.0.0.1 --port 8000
55
+ ```
56
+
57
+ WebSocket clients connect to `ws://127.0.0.1:8000/socket`.
58
+
59
+ ## Mount under FastAPI
60
+
61
+ ```python
62
+ from fastapi import FastAPI
63
+ from pondsocket_asgi import PondASGIApp
64
+
65
+ app = FastAPI()
66
+ app.mount("/ws", PondASGIApp(pond))
67
+ ```
68
+
69
+ When mounted at `/ws`, the adapter sees `scope["path"]` already stripped of the prefix — register your pond endpoints with the *post-mount* path (e.g. `/socket` resolves at `ws://host/ws/socket`).
70
+
71
+ See [`examples/`](./examples/) for FastAPI, Starlette, and raw uvicorn variants.
72
+
73
+ ## SSE transport
74
+
75
+ The same endpoint serves Server-Sent Events to clients that don't have WebSocket:
76
+
77
+ ```
78
+ GET /socket
79
+ Accept: text/event-stream
80
+ → 200, response carries X-Connection-ID header and a `CONNECTION` event with `payload.connectionId`, stream of "event: <name>\ndata: <json>\n\n" frames
81
+
82
+ POST /socket
83
+ X-Connection-ID: <id>
84
+ Content-Type: application/json
85
+ body: <client message JSON>
86
+ → 204
87
+
88
+ DELETE /socket
89
+ X-Connection-ID: <id>
90
+ → 204
91
+ ```
92
+
93
+ Use SSE when WebSocket is blocked (some corporate proxies). The connection handler is the same — the adapter routes by `Accept` header and method.
94
+
95
+ ## Lifespan
96
+
97
+ `PondASGIApp` handles the ASGI lifespan protocol. On `lifespan.startup`, it acknowledges immediately. On `lifespan.shutdown`, it closes the PondSocket (which closes every endpoint, every channel, every transport).
98
+
99
+ ## Testing
100
+
101
+ `pondsocket_asgi.testing` exposes an in-memory ASGI driver — no real network needed:
102
+
103
+ ```python
104
+ from pondsocket_asgi.testing import ASGITestDriver
105
+
106
+ driver = ASGITestDriver(PondASGIApp(pond))
107
+
108
+ # WebSocket
109
+ session = await driver.connect_websocket("/socket")
110
+ await session.send_client_message(
111
+ action="JOIN_CHANNEL",
112
+ channel_name="/chat/1",
113
+ event="join",
114
+ )
115
+ ack = await session.receive_json()
116
+ await session.disconnect()
117
+
118
+ # SSE
119
+ sse = await driver.connect_sse("/socket")
120
+ status, _ = await driver.sse_push(sse.connection_id, {"action": "BROADCAST", ...})
121
+ frame = await sse.receive_event()
122
+ await sse.disconnect()
123
+
124
+ # Lifespan
125
+ lifespan = await driver.open_lifespan()
126
+ await lifespan.startup()
127
+ await lifespan.shutdown()
128
+ ```
129
+
130
+ ## Public API
131
+
132
+ `from pondsocket_asgi import ...`
133
+
134
+ - `PondASGIApp` — the adapter itself
135
+ - `ASGIWebSocketTransport` — WebSocket transport (you usually don't construct this directly; the app does)
136
+
137
+ `from pondsocket_asgi.testing import ...`
138
+
139
+ - `ASGITestDriver`, `WebSocketSession`, `LifespanSession`, `SSESession`
140
+
141
+ ## License
142
+
143
+ GPL-3.0-or-later.
@@ -0,0 +1,132 @@
1
+ # pondsocket-asgi
2
+
3
+ Canonical ASGI adapter for [`pondsocket`](../pondsocket/). Mount under any ASGI host — FastAPI, Starlette, Litestar, Django, raw uvicorn.
4
+
5
+ Handles WebSocket and SSE (Server-Sent Events) transports. The same `PondSocket` instance serves both — the adapter detects the request type and dispatches.
6
+
7
+ ## Install
8
+
9
+ ```
10
+ pip install pondsocket-asgi
11
+ ```
12
+
13
+ Pulls in `pondsocket` and `pondsocket-common` automatically.
14
+
15
+ ## Quick start: raw uvicorn
16
+
17
+ ```python
18
+ from pondsocket import ConnectionContext, EventContext, JoinContext, PondSocket
19
+ from pondsocket_asgi import PondASGIApp
20
+
21
+
22
+ async def auth(ctx: ConnectionContext) -> None:
23
+ ctx.accept()
24
+
25
+
26
+ async def on_join(ctx: JoinContext) -> None:
27
+ await ctx.accept()
28
+
29
+
30
+ async def on_message(ctx: EventContext) -> None:
31
+ await ctx.broadcast(ctx.event_name, ctx.get_payload())
32
+
33
+
34
+ pond = PondSocket()
35
+ endpoint = pond.create_endpoint("/socket", auth)
36
+ lobby = endpoint.create_channel("/chat/:room_id", on_join)
37
+ lobby.on_message("message", on_message)
38
+
39
+ app = PondASGIApp(pond)
40
+ ```
41
+
42
+ ```
43
+ uvicorn module:app --host 127.0.0.1 --port 8000
44
+ ```
45
+
46
+ WebSocket clients connect to `ws://127.0.0.1:8000/socket`.
47
+
48
+ ## Mount under FastAPI
49
+
50
+ ```python
51
+ from fastapi import FastAPI
52
+ from pondsocket_asgi import PondASGIApp
53
+
54
+ app = FastAPI()
55
+ app.mount("/ws", PondASGIApp(pond))
56
+ ```
57
+
58
+ When mounted at `/ws`, the adapter sees `scope["path"]` already stripped of the prefix — register your pond endpoints with the *post-mount* path (e.g. `/socket` resolves at `ws://host/ws/socket`).
59
+
60
+ See [`examples/`](./examples/) for FastAPI, Starlette, and raw uvicorn variants.
61
+
62
+ ## SSE transport
63
+
64
+ The same endpoint serves Server-Sent Events to clients that don't have WebSocket:
65
+
66
+ ```
67
+ GET /socket
68
+ Accept: text/event-stream
69
+ → 200, response carries X-Connection-ID header and a `CONNECTION` event with `payload.connectionId`, stream of "event: <name>\ndata: <json>\n\n" frames
70
+
71
+ POST /socket
72
+ X-Connection-ID: <id>
73
+ Content-Type: application/json
74
+ body: <client message JSON>
75
+ → 204
76
+
77
+ DELETE /socket
78
+ X-Connection-ID: <id>
79
+ → 204
80
+ ```
81
+
82
+ Use SSE when WebSocket is blocked (some corporate proxies). The connection handler is the same — the adapter routes by `Accept` header and method.
83
+
84
+ ## Lifespan
85
+
86
+ `PondASGIApp` handles the ASGI lifespan protocol. On `lifespan.startup`, it acknowledges immediately. On `lifespan.shutdown`, it closes the PondSocket (which closes every endpoint, every channel, every transport).
87
+
88
+ ## Testing
89
+
90
+ `pondsocket_asgi.testing` exposes an in-memory ASGI driver — no real network needed:
91
+
92
+ ```python
93
+ from pondsocket_asgi.testing import ASGITestDriver
94
+
95
+ driver = ASGITestDriver(PondASGIApp(pond))
96
+
97
+ # WebSocket
98
+ session = await driver.connect_websocket("/socket")
99
+ await session.send_client_message(
100
+ action="JOIN_CHANNEL",
101
+ channel_name="/chat/1",
102
+ event="join",
103
+ )
104
+ ack = await session.receive_json()
105
+ await session.disconnect()
106
+
107
+ # SSE
108
+ sse = await driver.connect_sse("/socket")
109
+ status, _ = await driver.sse_push(sse.connection_id, {"action": "BROADCAST", ...})
110
+ frame = await sse.receive_event()
111
+ await sse.disconnect()
112
+
113
+ # Lifespan
114
+ lifespan = await driver.open_lifespan()
115
+ await lifespan.startup()
116
+ await lifespan.shutdown()
117
+ ```
118
+
119
+ ## Public API
120
+
121
+ `from pondsocket_asgi import ...`
122
+
123
+ - `PondASGIApp` — the adapter itself
124
+ - `ASGIWebSocketTransport` — WebSocket transport (you usually don't construct this directly; the app does)
125
+
126
+ `from pondsocket_asgi.testing import ...`
127
+
128
+ - `ASGITestDriver`, `WebSocketSession`, `LifespanSession`, `SSESession`
129
+
130
+ ## License
131
+
132
+ GPL-3.0-or-later.
@@ -0,0 +1,46 @@
1
+ from __future__ import annotations
2
+
3
+ from fastapi import FastAPI
4
+
5
+ from pondsocket import (
6
+ ConnectionContext,
7
+ EventContext,
8
+ JoinContext,
9
+ PondSocket,
10
+ )
11
+ from pondsocket_asgi import PondASGIApp
12
+
13
+
14
+ async def auth(ctx: ConnectionContext) -> None:
15
+ ctx.accept()
16
+
17
+
18
+ async def on_join(ctx: JoinContext) -> None:
19
+ await ctx.accept()
20
+
21
+
22
+ async def on_message(ctx: EventContext) -> None:
23
+ await ctx.broadcast(ctx.event_name, ctx.get_payload())
24
+
25
+
26
+ pond = PondSocket()
27
+ endpoint = pond.create_endpoint("/", auth)
28
+ lobby = endpoint.create_channel("/chat/:room_id", on_join)
29
+ lobby.on_message("message", on_message)
30
+
31
+
32
+ app = FastAPI()
33
+
34
+
35
+ @app.get("/")
36
+ async def index() -> dict[str, str]:
37
+ return {"status": "ok"}
38
+
39
+
40
+ app.mount("/ws", PondASGIApp(pond))
41
+
42
+
43
+ if __name__ == "__main__":
44
+ import uvicorn
45
+
46
+ uvicorn.run(app, host="127.0.0.1", port=8000)
@@ -0,0 +1,40 @@
1
+ from __future__ import annotations
2
+
3
+ from pondsocket import (
4
+ ConnectionContext,
5
+ EventContext,
6
+ JoinContext,
7
+ PondSocket,
8
+ )
9
+ from pondsocket_asgi import PondASGIApp
10
+
11
+
12
+ async def auth(ctx: ConnectionContext) -> None:
13
+ token = ctx.query.get("token")
14
+ if token != "secret":
15
+ ctx.decline(401, "Invalid token")
16
+ return
17
+ ctx.accept(token=token)
18
+
19
+
20
+ async def on_join(ctx: JoinContext) -> None:
21
+ await ctx.accept()
22
+ await ctx.track({"status": "online"})
23
+
24
+
25
+ async def on_message(ctx: EventContext) -> None:
26
+ await ctx.broadcast(ctx.event_name, ctx.get_payload())
27
+
28
+
29
+ pond = PondSocket()
30
+ endpoint = pond.create_endpoint("/socket", auth)
31
+ lobby = endpoint.create_channel("/chat/:room_id", on_join)
32
+ lobby.on_message("message", on_message)
33
+
34
+ app = PondASGIApp(pond)
35
+
36
+
37
+ if __name__ == "__main__":
38
+ import uvicorn
39
+
40
+ uvicorn.run(app, host="127.0.0.1", port=8000)
@@ -0,0 +1,49 @@
1
+ from __future__ import annotations
2
+
3
+ from starlette.applications import Starlette
4
+ from starlette.responses import JSONResponse
5
+ from starlette.routing import Mount, Route
6
+
7
+ from pondsocket import (
8
+ ConnectionContext,
9
+ EventContext,
10
+ JoinContext,
11
+ PondSocket,
12
+ )
13
+ from pondsocket_asgi import PondASGIApp
14
+
15
+
16
+ async def auth(ctx: ConnectionContext) -> None:
17
+ ctx.accept()
18
+
19
+
20
+ async def on_join(ctx: JoinContext) -> None:
21
+ await ctx.accept()
22
+
23
+
24
+ async def on_message(ctx: EventContext) -> None:
25
+ await ctx.broadcast(ctx.event_name, ctx.get_payload())
26
+
27
+
28
+ pond = PondSocket()
29
+ endpoint = pond.create_endpoint("/", auth)
30
+ lobby = endpoint.create_channel("/chat/:room_id", on_join)
31
+ lobby.on_message("message", on_message)
32
+
33
+
34
+ async def healthcheck(_request: object) -> JSONResponse:
35
+ return JSONResponse({"status": "ok"})
36
+
37
+
38
+ app = Starlette(
39
+ routes=[
40
+ Route("/", endpoint=healthcheck),
41
+ Mount("/ws", app=PondASGIApp(pond)),
42
+ ]
43
+ )
44
+
45
+
46
+ if __name__ == "__main__":
47
+ import uvicorn
48
+
49
+ uvicorn.run(app, host="127.0.0.1", port=8000)
@@ -0,0 +1,23 @@
1
+ [project]
2
+ name = "pondsocket-asgi"
3
+ version = "0.0.1"
4
+ description = "Canonical ASGI adapter for PondSocket."
5
+ readme = "README.md"
6
+ requires-python = ">=3.11"
7
+ license = { text = "GPL-3.0-or-later" }
8
+ authors = [{ name = "eleven-am" }]
9
+ dependencies = [
10
+ "pondsocket>=0.0.1,<0.1.0",
11
+ "pondsocket-common>=0.0.1,<0.1.0",
12
+ ]
13
+
14
+ [build-system]
15
+ requires = ["hatchling"]
16
+ build-backend = "hatchling.build"
17
+
18
+ [tool.hatch.build.targets.wheel]
19
+ packages = ["src/pondsocket_asgi"]
20
+
21
+ [tool.uv.sources]
22
+ pondsocket = { workspace = true }
23
+ pondsocket-common = { workspace = true }
@@ -0,0 +1,17 @@
1
+ from __future__ import annotations
2
+
3
+ from importlib.metadata import PackageNotFoundError, version
4
+
5
+ from .app import PondASGIApp
6
+ from .transport import ASGIWebSocketTransport
7
+
8
+ try:
9
+ __version__ = version("pondsocket-asgi")
10
+ except PackageNotFoundError:
11
+ __version__ = "0.0.1"
12
+
13
+ __all__ = [
14
+ "ASGIWebSocketTransport",
15
+ "PondASGIApp",
16
+ "__version__",
17
+ ]
@@ -0,0 +1,55 @@
1
+ from __future__ import annotations
2
+
3
+ from http.cookies import SimpleCookie
4
+ from typing import Any
5
+ from urllib.parse import parse_qs
6
+
7
+ from pondsocket.types import Route
8
+ from pondsocket_common import Headers, IncomingConnection
9
+
10
+
11
+ def parse_query(query_string: bytes) -> dict[str, str]:
12
+ if not query_string:
13
+ return {}
14
+ qs = query_string.decode("utf-8", errors="replace")
15
+ parsed = parse_qs(qs, keep_blank_values=True)
16
+ return {k: v[0] if v else "" for k, v in parsed.items()}
17
+
18
+
19
+ def parse_cookies(headers: Headers) -> dict[str, str]:
20
+ cookie_header = headers.get("cookie")
21
+ if cookie_header is None:
22
+ return {}
23
+ jar: SimpleCookie = SimpleCookie()
24
+ try:
25
+ jar.load(cookie_header)
26
+ except Exception:
27
+ return {}
28
+ return {key: morsel.value for key, morsel in jar.items()}
29
+
30
+
31
+ def client_address(scope: dict[str, Any]) -> str:
32
+ client = scope.get("client")
33
+ if client and isinstance(client, (list, tuple)) and len(client) >= 1:
34
+ host = client[0]
35
+ if isinstance(host, str):
36
+ return host
37
+ return ""
38
+
39
+
40
+ def build_incoming_connection(
41
+ *,
42
+ user_id: str,
43
+ scope: dict[str, Any],
44
+ route: Route,
45
+ ) -> IncomingConnection:
46
+ raw_headers = scope.get("headers", [])
47
+ headers = Headers(raw_headers)
48
+ return IncomingConnection(
49
+ id=user_id,
50
+ address=client_address(scope),
51
+ headers=headers,
52
+ cookies=parse_cookies(headers),
53
+ query=parse_query(scope.get("query_string", b"")),
54
+ params=dict(route.params),
55
+ )
@@ -0,0 +1,15 @@
1
+ from __future__ import annotations
2
+
3
+ from pondsocket.wire import (
4
+ event_to_json,
5
+ event_to_wire,
6
+ parse_inbound_text,
7
+ wire_to_event,
8
+ )
9
+
10
+ __all__ = [
11
+ "event_to_json",
12
+ "event_to_wire",
13
+ "parse_inbound_text",
14
+ "wire_to_event",
15
+ ]
@@ -0,0 +1,14 @@
1
+ from __future__ import annotations
2
+
3
+ from pondsocket.types import Event
4
+ from pondsocket.wire import event_to_json
5
+
6
+
7
+ def event_to_sse_frame(event: Event) -> bytes:
8
+ body = event_to_json(event)
9
+ name = event.event or "message"
10
+ return f"event: {name}\ndata: {body}\n\n".encode()
11
+
12
+
13
+ def sse_comment(text: str) -> bytes:
14
+ return f": {text}\n\n".encode()