pondsocket 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.
Files changed (46) hide show
  1. pondsocket-0.0.1/.gitignore +12 -0
  2. pondsocket-0.0.1/PKG-INFO +144 -0
  3. pondsocket-0.0.1/README.md +132 -0
  4. pondsocket-0.0.1/pyproject.toml +24 -0
  5. pondsocket-0.0.1/src/pondsocket/__init__.py +205 -0
  6. pondsocket-0.0.1/src/pondsocket/channel.py +580 -0
  7. pondsocket-0.0.1/src/pondsocket/contexts/__init__.py +16 -0
  8. pondsocket-0.0.1/src/pondsocket/contexts/connection_context.py +135 -0
  9. pondsocket-0.0.1/src/pondsocket/contexts/event_context.py +127 -0
  10. pondsocket-0.0.1/src/pondsocket/contexts/join_context.py +162 -0
  11. pondsocket-0.0.1/src/pondsocket/contexts/leave_context.py +78 -0
  12. pondsocket-0.0.1/src/pondsocket/contexts/outgoing_context.py +72 -0
  13. pondsocket-0.0.1/src/pondsocket/distributed/__init__.py +5 -0
  14. pondsocket-0.0.1/src/pondsocket/distributed/redis_pubsub.py +137 -0
  15. pondsocket-0.0.1/src/pondsocket/endpoint.py +348 -0
  16. pondsocket-0.0.1/src/pondsocket/errors.py +90 -0
  17. pondsocket-0.0.1/src/pondsocket/hooks.py +227 -0
  18. pondsocket-0.0.1/src/pondsocket/in_memory_transport.py +112 -0
  19. pondsocket-0.0.1/src/pondsocket/lobby.py +183 -0
  20. pondsocket-0.0.1/src/pondsocket/middleware.py +100 -0
  21. pondsocket-0.0.1/src/pondsocket/parser.py +85 -0
  22. pondsocket-0.0.1/src/pondsocket/presence.py +109 -0
  23. pondsocket-0.0.1/src/pondsocket/pubsub.py +44 -0
  24. pondsocket-0.0.1/src/pondsocket/pubsub_local.py +85 -0
  25. pondsocket-0.0.1/src/pondsocket/py.typed +0 -0
  26. pondsocket-0.0.1/src/pondsocket/server.py +88 -0
  27. pondsocket-0.0.1/src/pondsocket/sse_transport.py +122 -0
  28. pondsocket-0.0.1/src/pondsocket/store.py +83 -0
  29. pondsocket-0.0.1/src/pondsocket/transport.py +29 -0
  30. pondsocket-0.0.1/src/pondsocket/types.py +154 -0
  31. pondsocket-0.0.1/src/pondsocket/wire.py +87 -0
  32. pondsocket-0.0.1/tests/test_pondsocket_channel.py +281 -0
  33. pondsocket-0.0.1/tests/test_pondsocket_distributed_local.py +256 -0
  34. pondsocket-0.0.1/tests/test_pondsocket_errors.py +46 -0
  35. pondsocket-0.0.1/tests/test_pondsocket_hooks_integration.py +335 -0
  36. pondsocket-0.0.1/tests/test_pondsocket_hooks_unit.py +266 -0
  37. pondsocket-0.0.1/tests/test_pondsocket_in_memory_transport.py +177 -0
  38. pondsocket-0.0.1/tests/test_pondsocket_integration.py +467 -0
  39. pondsocket-0.0.1/tests/test_pondsocket_middleware.py +159 -0
  40. pondsocket-0.0.1/tests/test_pondsocket_parser.py +79 -0
  41. pondsocket-0.0.1/tests/test_pondsocket_presence.py +155 -0
  42. pondsocket-0.0.1/tests/test_pondsocket_pubsub.py +204 -0
  43. pondsocket-0.0.1/tests/test_pondsocket_redis_pubsub.py +151 -0
  44. pondsocket-0.0.1/tests/test_pondsocket_smoke.py +7 -0
  45. pondsocket-0.0.1/tests/test_pondsocket_sse_transport.py +160 -0
  46. pondsocket-0.0.1/tests/test_pondsocket_store.py +108 -0
@@ -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,144 @@
1
+ Metadata-Version: 2.4
2
+ Name: pondsocket
3
+ Version: 0.0.1
4
+ Summary: PondSocket - channel-based real-time framework with bring-your-own-server design.
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
+ Provides-Extra: redis
10
+ Requires-Dist: redis>=5; extra == 'redis'
11
+ Description-Content-Type: text/markdown
12
+
13
+ # pondsocket
14
+
15
+ PondSocket - channel-based real-time framework for Python. Bring-your-own-server design: the core knows nothing about HTTP frameworks or WebSocket libraries. You build the layered API (Server -> Endpoint -> Channel -> User), and an adapter (e.g. [`pondsocket-asgi`](../pondsocket-asgi/)) bridges it to your HTTP stack.
16
+
17
+ ## Install
18
+
19
+ ```
20
+ pip install pondsocket
21
+ pip install "pondsocket[redis]" # multi-node deployments
22
+ ```
23
+
24
+ ## Concepts
25
+
26
+ ```
27
+ PondSocket top-level facade, holds endpoints
28
+ └── Endpoint one URL path, runs the connection auth handler, owns transports
29
+ └── Lobby one channel pattern (e.g. "/chat/:room_id"), holds shared middleware
30
+ └── Channel one live channel instance, holds users + presence
31
+ ```
32
+
33
+ ### Five contexts, scoped to lifecycle moments
34
+
35
+ | Context | When | What it decides / does |
36
+ |---|---|---|
37
+ | `ConnectionContext` | HTTP upgrade | accept / decline socket, set initial assigns |
38
+ | `JoinContext` | per channel join | accept / decline membership, track presence |
39
+ | `EventContext` | per incoming event | broadcast, reply, update presence/assigns, evict |
40
+ | `OutgoingContext` | per recipient, per send | transform payload or block delivery |
41
+ | `LeaveContext` | user gone | final cleanup (user already removed) |
42
+
43
+ ## Minimal example
44
+
45
+ ```python
46
+ from pondsocket import ConnectionContext, EventContext, JoinContext, PondSocket
47
+
48
+
49
+ async def auth(ctx: ConnectionContext) -> None:
50
+ if ctx.query.get("token") != "secret":
51
+ ctx.decline(401, "Invalid token")
52
+ return
53
+ ctx.accept(user_id=ctx.query.get("uid", "anon"))
54
+
55
+
56
+ async def on_join(ctx: JoinContext) -> None:
57
+ await ctx.accept()
58
+ await ctx.track({"status": "online"})
59
+
60
+
61
+ async def on_message(ctx: EventContext) -> None:
62
+ await ctx.broadcast(ctx.event_name, ctx.get_payload())
63
+
64
+
65
+ pond = PondSocket()
66
+ endpoint = pond.create_endpoint("/api/socket", auth)
67
+ lobby = endpoint.create_channel("/chat/:room_id", on_join)
68
+ lobby.on_message("message", on_message)
69
+ ```
70
+
71
+ To actually serve traffic, wrap `pond` in an adapter — see [`pondsocket-asgi`](../pondsocket-asgi/) for the canonical one.
72
+
73
+ ## Distributed (multi-node)
74
+
75
+ ```python
76
+ from redis.asyncio import Redis
77
+ from pondsocket import PondSocket
78
+ from pondsocket.distributed import RedisPubSub
79
+
80
+ redis = Redis(host="localhost", port=6379)
81
+ pubsub = RedisPubSub(redis, owns_client=True)
82
+ pond = PondSocket(pubsub=pubsub)
83
+ ```
84
+
85
+ Cross-node broadcasts and presence events propagate via Redis PSUBSCRIBE. `node_id` is auto-generated when a pubsub is configured. Each broadcast carries the `nodeId` so emitters filter their own echo.
86
+
87
+ See [`pondsocket.distributed.RedisPubSub`](src/pondsocket/distributed/redis_pubsub.py) for the implementation. The `PubSub` protocol is implementable for other backends.
88
+
89
+ ## Hooks & metrics
90
+
91
+ ```python
92
+ from pondsocket import Hooks, NoopMetrics, Options, PondSocket, TokenBucketRateLimiter
93
+
94
+ hooks = Hooks(
95
+ rate_limiter=TokenBucketRateLimiter(rate=10, capacity=20),
96
+ metrics=NoopMetrics(),
97
+ )
98
+ pond = PondSocket(options=Options(hooks=hooks))
99
+ ```
100
+
101
+ Auto-fired by the framework: `connection_opened`/`connection_closed`, `channel_created`/`channel_destroyed`/`channel_joined`/`channel_left`, plus `on_connect`/`on_disconnect`/`before_join`/`after_join`/`before_message`/`after_message`.
102
+
103
+ Opt-in middleware factories for per-handler instrumentation:
104
+
105
+ ```python
106
+ from pondsocket import with_metrics, with_rate_limiter
107
+
108
+ lobby.on_message(
109
+ "message",
110
+ on_message,
111
+ with_rate_limiter(hooks, key_fn=lambda msg: msg.user.id),
112
+ with_metrics(hooks),
113
+ )
114
+ ```
115
+
116
+ ## Testing
117
+
118
+ `InMemoryTransport` is a public test utility that satisfies the `Transport` protocol without any network I/O:
119
+
120
+ ```python
121
+ from pondsocket import InMemoryTransport
122
+
123
+ t = InMemoryTransport("alice")
124
+ await endpoint.register_transport(t)
125
+
126
+ await t.push_inbound(some_event)
127
+ sent = await t.receive_sent()
128
+ ```
129
+
130
+ ## Public API
131
+
132
+ `from pondsocket import ...`
133
+
134
+ - Core: `PondSocket`, `Endpoint`, `Lobby`, `Channel`, `Options`, `Event`, `User`, `MessageEvent`, `RecipientSpec`
135
+ - Contexts: `ConnectionContext`, `JoinContext`, `EventContext`, `LeaveContext`, `OutgoingContext`
136
+ - Transport: `Transport` (Protocol), `InMemoryTransport`, `SSEServerTransport`, `TransportType`, `OnCloseCallback`, `OnMessageHandler`
137
+ - PubSub: `PubSub` (Protocol), `LocalPubSub`, `format_topic`, `match_topic`, `PubSubClosedError`
138
+ - Hooks: `Hooks`, `RateLimiter`, `MetricsCollector`, `NoopMetrics`, `TokenBucketRateLimiter`, `with_rate_limiter`, `with_metrics`
139
+ - Wire: `event_to_json`, `event_to_wire`, `parse_inbound_text`, `wire_to_event`, `event_to_pubsub_bytes`, `pubsub_bytes_to_event`
140
+ - Errors: `PondError`, status constructors, `error_event`
141
+
142
+ ## License
143
+
144
+ GPL-3.0-or-later.
@@ -0,0 +1,132 @@
1
+ # pondsocket
2
+
3
+ PondSocket - channel-based real-time framework for Python. Bring-your-own-server design: the core knows nothing about HTTP frameworks or WebSocket libraries. You build the layered API (Server -> Endpoint -> Channel -> User), and an adapter (e.g. [`pondsocket-asgi`](../pondsocket-asgi/)) bridges it to your HTTP stack.
4
+
5
+ ## Install
6
+
7
+ ```
8
+ pip install pondsocket
9
+ pip install "pondsocket[redis]" # multi-node deployments
10
+ ```
11
+
12
+ ## Concepts
13
+
14
+ ```
15
+ PondSocket top-level facade, holds endpoints
16
+ └── Endpoint one URL path, runs the connection auth handler, owns transports
17
+ └── Lobby one channel pattern (e.g. "/chat/:room_id"), holds shared middleware
18
+ └── Channel one live channel instance, holds users + presence
19
+ ```
20
+
21
+ ### Five contexts, scoped to lifecycle moments
22
+
23
+ | Context | When | What it decides / does |
24
+ |---|---|---|
25
+ | `ConnectionContext` | HTTP upgrade | accept / decline socket, set initial assigns |
26
+ | `JoinContext` | per channel join | accept / decline membership, track presence |
27
+ | `EventContext` | per incoming event | broadcast, reply, update presence/assigns, evict |
28
+ | `OutgoingContext` | per recipient, per send | transform payload or block delivery |
29
+ | `LeaveContext` | user gone | final cleanup (user already removed) |
30
+
31
+ ## Minimal example
32
+
33
+ ```python
34
+ from pondsocket import ConnectionContext, EventContext, JoinContext, PondSocket
35
+
36
+
37
+ async def auth(ctx: ConnectionContext) -> None:
38
+ if ctx.query.get("token") != "secret":
39
+ ctx.decline(401, "Invalid token")
40
+ return
41
+ ctx.accept(user_id=ctx.query.get("uid", "anon"))
42
+
43
+
44
+ async def on_join(ctx: JoinContext) -> None:
45
+ await ctx.accept()
46
+ await ctx.track({"status": "online"})
47
+
48
+
49
+ async def on_message(ctx: EventContext) -> None:
50
+ await ctx.broadcast(ctx.event_name, ctx.get_payload())
51
+
52
+
53
+ pond = PondSocket()
54
+ endpoint = pond.create_endpoint("/api/socket", auth)
55
+ lobby = endpoint.create_channel("/chat/:room_id", on_join)
56
+ lobby.on_message("message", on_message)
57
+ ```
58
+
59
+ To actually serve traffic, wrap `pond` in an adapter — see [`pondsocket-asgi`](../pondsocket-asgi/) for the canonical one.
60
+
61
+ ## Distributed (multi-node)
62
+
63
+ ```python
64
+ from redis.asyncio import Redis
65
+ from pondsocket import PondSocket
66
+ from pondsocket.distributed import RedisPubSub
67
+
68
+ redis = Redis(host="localhost", port=6379)
69
+ pubsub = RedisPubSub(redis, owns_client=True)
70
+ pond = PondSocket(pubsub=pubsub)
71
+ ```
72
+
73
+ Cross-node broadcasts and presence events propagate via Redis PSUBSCRIBE. `node_id` is auto-generated when a pubsub is configured. Each broadcast carries the `nodeId` so emitters filter their own echo.
74
+
75
+ See [`pondsocket.distributed.RedisPubSub`](src/pondsocket/distributed/redis_pubsub.py) for the implementation. The `PubSub` protocol is implementable for other backends.
76
+
77
+ ## Hooks & metrics
78
+
79
+ ```python
80
+ from pondsocket import Hooks, NoopMetrics, Options, PondSocket, TokenBucketRateLimiter
81
+
82
+ hooks = Hooks(
83
+ rate_limiter=TokenBucketRateLimiter(rate=10, capacity=20),
84
+ metrics=NoopMetrics(),
85
+ )
86
+ pond = PondSocket(options=Options(hooks=hooks))
87
+ ```
88
+
89
+ Auto-fired by the framework: `connection_opened`/`connection_closed`, `channel_created`/`channel_destroyed`/`channel_joined`/`channel_left`, plus `on_connect`/`on_disconnect`/`before_join`/`after_join`/`before_message`/`after_message`.
90
+
91
+ Opt-in middleware factories for per-handler instrumentation:
92
+
93
+ ```python
94
+ from pondsocket import with_metrics, with_rate_limiter
95
+
96
+ lobby.on_message(
97
+ "message",
98
+ on_message,
99
+ with_rate_limiter(hooks, key_fn=lambda msg: msg.user.id),
100
+ with_metrics(hooks),
101
+ )
102
+ ```
103
+
104
+ ## Testing
105
+
106
+ `InMemoryTransport` is a public test utility that satisfies the `Transport` protocol without any network I/O:
107
+
108
+ ```python
109
+ from pondsocket import InMemoryTransport
110
+
111
+ t = InMemoryTransport("alice")
112
+ await endpoint.register_transport(t)
113
+
114
+ await t.push_inbound(some_event)
115
+ sent = await t.receive_sent()
116
+ ```
117
+
118
+ ## Public API
119
+
120
+ `from pondsocket import ...`
121
+
122
+ - Core: `PondSocket`, `Endpoint`, `Lobby`, `Channel`, `Options`, `Event`, `User`, `MessageEvent`, `RecipientSpec`
123
+ - Contexts: `ConnectionContext`, `JoinContext`, `EventContext`, `LeaveContext`, `OutgoingContext`
124
+ - Transport: `Transport` (Protocol), `InMemoryTransport`, `SSEServerTransport`, `TransportType`, `OnCloseCallback`, `OnMessageHandler`
125
+ - PubSub: `PubSub` (Protocol), `LocalPubSub`, `format_topic`, `match_topic`, `PubSubClosedError`
126
+ - Hooks: `Hooks`, `RateLimiter`, `MetricsCollector`, `NoopMetrics`, `TokenBucketRateLimiter`, `with_rate_limiter`, `with_metrics`
127
+ - Wire: `event_to_json`, `event_to_wire`, `parse_inbound_text`, `wire_to_event`, `event_to_pubsub_bytes`, `pubsub_bytes_to_event`
128
+ - Errors: `PondError`, status constructors, `error_event`
129
+
130
+ ## License
131
+
132
+ GPL-3.0-or-later.
@@ -0,0 +1,24 @@
1
+ [project]
2
+ name = "pondsocket"
3
+ version = "0.0.1"
4
+ description = "PondSocket - channel-based real-time framework with bring-your-own-server design."
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-common>=0.0.1,<0.1.0",
11
+ ]
12
+
13
+ [project.optional-dependencies]
14
+ redis = ["redis>=5"]
15
+
16
+ [build-system]
17
+ requires = ["hatchling"]
18
+ build-backend = "hatchling.build"
19
+
20
+ [tool.hatch.build.targets.wheel]
21
+ packages = ["src/pondsocket"]
22
+
23
+ [tool.uv.sources]
24
+ pondsocket-common = { workspace = true }
@@ -0,0 +1,205 @@
1
+ from __future__ import annotations
2
+
3
+ from importlib.metadata import PackageNotFoundError, version
4
+
5
+ from pondsocket_common import (
6
+ ChannelReceiver,
7
+ Headers,
8
+ IncomingConnection,
9
+ JoinParams,
10
+ PondAssigns,
11
+ PondMessage,
12
+ PondPresence,
13
+ PresenceEventTypes,
14
+ ServerActions,
15
+ UserData,
16
+ uuid,
17
+ )
18
+
19
+ from .channel import Channel, ChannelOptions
20
+ from .contexts import (
21
+ ConnectionContext,
22
+ ConnectionDecision,
23
+ EventContext,
24
+ JoinContext,
25
+ LeaveContext,
26
+ OutgoingContext,
27
+ )
28
+ from .endpoint import (
29
+ ConnectionHandler,
30
+ ConnectionMiddlewareFn,
31
+ Endpoint,
32
+ JoinHandler,
33
+ JoinMiddlewareFn,
34
+ )
35
+ from .errors import (
36
+ MultiError,
37
+ PondError,
38
+ bad_request,
39
+ conflict,
40
+ error_event,
41
+ forbidden,
42
+ internal,
43
+ not_found,
44
+ too_many_requests,
45
+ unauthorized,
46
+ )
47
+ from .hooks import (
48
+ AfterJoin,
49
+ AfterMessage,
50
+ BeforeJoin,
51
+ BeforeMessage,
52
+ Hooks,
53
+ MetricsCollector,
54
+ NoopMetrics,
55
+ OnConnect,
56
+ OnDisconnect,
57
+ RateLimiter,
58
+ TokenBucketRateLimiter,
59
+ with_metrics,
60
+ with_rate_limiter,
61
+ )
62
+ from .in_memory_transport import InMemoryTransport
63
+ from .lobby import EventHandler, EventMiddlewareFn, LeaveHandler, Lobby, OutgoingHandler
64
+ from .middleware import Middleware
65
+ from .parser import parse
66
+ from .presence import PresenceClient
67
+ from .pubsub import (
68
+ PubSub,
69
+ PubSubClosedError,
70
+ format_message_topic,
71
+ format_presence_topic,
72
+ format_system_topic,
73
+ format_topic,
74
+ match_topic,
75
+ )
76
+ from .pubsub_local import LocalPubSub
77
+ from .server import EndpointMatch, PondSocket
78
+ from .sse_transport import SSEServerTransport
79
+ from .store import Store
80
+ from .transport import OnCloseCallback, OnMessageHandler, PushableTransport, Transport
81
+ from .types import (
82
+ AllExceptSender,
83
+ AllUsers,
84
+ Event,
85
+ InternalActions,
86
+ LeaveReason,
87
+ MessageEvent,
88
+ Options,
89
+ RecipientSpec,
90
+ Route,
91
+ SystemEntity,
92
+ SystemEvents,
93
+ ToUsers,
94
+ TransportType,
95
+ User,
96
+ )
97
+ from .wire import (
98
+ event_to_json,
99
+ event_to_pubsub_bytes,
100
+ event_to_wire,
101
+ parse_inbound_text,
102
+ pubsub_bytes_to_event,
103
+ wire_to_event,
104
+ )
105
+
106
+ try:
107
+ __version__ = version("pondsocket")
108
+ except PackageNotFoundError:
109
+ __version__ = "0.0.1"
110
+
111
+ __all__ = [
112
+ "AfterJoin",
113
+ "AfterMessage",
114
+ "AllExceptSender",
115
+ "AllUsers",
116
+ "BeforeJoin",
117
+ "BeforeMessage",
118
+ "Channel",
119
+ "ChannelOptions",
120
+ "ChannelReceiver",
121
+ "ConnectionContext",
122
+ "ConnectionDecision",
123
+ "ConnectionHandler",
124
+ "ConnectionMiddlewareFn",
125
+ "Endpoint",
126
+ "EndpointMatch",
127
+ "Event",
128
+ "EventContext",
129
+ "EventHandler",
130
+ "EventMiddlewareFn",
131
+ "Headers",
132
+ "Hooks",
133
+ "InMemoryTransport",
134
+ "IncomingConnection",
135
+ "InternalActions",
136
+ "JoinContext",
137
+ "JoinHandler",
138
+ "JoinMiddlewareFn",
139
+ "JoinParams",
140
+ "LeaveContext",
141
+ "LeaveHandler",
142
+ "LeaveReason",
143
+ "Lobby",
144
+ "LocalPubSub",
145
+ "MessageEvent",
146
+ "MetricsCollector",
147
+ "Middleware",
148
+ "MultiError",
149
+ "NoopMetrics",
150
+ "OnCloseCallback",
151
+ "OnConnect",
152
+ "OnDisconnect",
153
+ "OnMessageHandler",
154
+ "Options",
155
+ "OutgoingContext",
156
+ "OutgoingHandler",
157
+ "PondAssigns",
158
+ "PondError",
159
+ "PondMessage",
160
+ "PondPresence",
161
+ "PondSocket",
162
+ "PresenceClient",
163
+ "PresenceEventTypes",
164
+ "PubSub",
165
+ "PubSubClosedError",
166
+ "PushableTransport",
167
+ "RateLimiter",
168
+ "RecipientSpec",
169
+ "Route",
170
+ "SSEServerTransport",
171
+ "ServerActions",
172
+ "Store",
173
+ "SystemEntity",
174
+ "SystemEvents",
175
+ "ToUsers",
176
+ "TokenBucketRateLimiter",
177
+ "Transport",
178
+ "TransportType",
179
+ "User",
180
+ "UserData",
181
+ "__version__",
182
+ "bad_request",
183
+ "conflict",
184
+ "error_event",
185
+ "event_to_json",
186
+ "event_to_pubsub_bytes",
187
+ "event_to_wire",
188
+ "forbidden",
189
+ "format_message_topic",
190
+ "format_presence_topic",
191
+ "format_system_topic",
192
+ "format_topic",
193
+ "internal",
194
+ "match_topic",
195
+ "not_found",
196
+ "parse",
197
+ "parse_inbound_text",
198
+ "pubsub_bytes_to_event",
199
+ "too_many_requests",
200
+ "unauthorized",
201
+ "uuid",
202
+ "wire_to_event",
203
+ "with_metrics",
204
+ "with_rate_limiter",
205
+ ]