pondsocket 0.0.1__py3-none-any.whl

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.
pondsocket/channel.py ADDED
@@ -0,0 +1,580 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ from collections.abc import Awaitable, Callable
5
+ from dataclasses import dataclass, field
6
+ from typing import Any, TypeAlias
7
+
8
+ from pondsocket_common import (
9
+ PondAssigns,
10
+ PondMessage,
11
+ PondPresence,
12
+ PresenceEventTypes,
13
+ ServerActions,
14
+ uuid,
15
+ )
16
+
17
+ from .contexts.leave_context import LeaveContext
18
+ from .contexts.outgoing_context import OutgoingContext
19
+ from .errors import internal, not_found
20
+ from .middleware import Middleware, execute_with_middleware
21
+ from .presence import PresenceClient
22
+ from .pubsub import PubSub, format_topic
23
+ from .store import Store
24
+ from .transport import Transport
25
+ from .types import (
26
+ AllExceptSender,
27
+ AllUsers,
28
+ Event,
29
+ LeaveReason,
30
+ MessageEvent,
31
+ Options,
32
+ RecipientSpec,
33
+ SystemEvents,
34
+ ToUsers,
35
+ User,
36
+ )
37
+ from .wire import event_to_pubsub_bytes, pubsub_bytes_to_event
38
+
39
+ LeaveHandler: TypeAlias = Callable[[LeaveContext], Awaitable[None]]
40
+ LeaveMiddlewareFn: TypeAlias = Callable[
41
+ [LeaveContext, Callable[[], Awaitable[None]]], Awaitable[None]
42
+ ]
43
+ OnDestroy: TypeAlias = Callable[[], Awaitable[None]]
44
+
45
+
46
+ @dataclass(slots=True)
47
+ class _DispatchItem:
48
+ event: Event
49
+ recipient_ids: list[str]
50
+
51
+
52
+ @dataclass(slots=True)
53
+ class ChannelOptions:
54
+ name: str
55
+ options: Options = field(default_factory=Options)
56
+ message_middleware: Middleware[MessageEvent, Channel] | None = None
57
+ outgoing_middleware: Middleware[OutgoingContext, None] | None = None
58
+ leave_handler: LeaveHandler | None = None
59
+ leave_middlewares: list[LeaveMiddlewareFn] = field(default_factory=list)
60
+ on_destroy: OnDestroy | None = None
61
+ endpoint_path: str = ""
62
+ pubsub: PubSub | None = None
63
+
64
+
65
+ class Channel:
66
+ __slots__ = (
67
+ "_active",
68
+ "_assigns",
69
+ "_connections",
70
+ "_dispatch_queue",
71
+ "_dispatch_semaphore",
72
+ "_dispatch_task",
73
+ "_endpoint_path",
74
+ "_leave_handler",
75
+ "_leave_middlewares",
76
+ "_lifecycle_lock",
77
+ "_message_middleware",
78
+ "_on_destroy",
79
+ "_options",
80
+ "_outgoing_middleware",
81
+ "_presence",
82
+ "_pubsub",
83
+ "name",
84
+ "node_id",
85
+ )
86
+
87
+ def __init__(self, opts: ChannelOptions) -> None:
88
+ self.name = opts.name
89
+ self.node_id = opts.options.node_id or ""
90
+ self._options = opts.options
91
+ self._endpoint_path = opts.endpoint_path
92
+ self._pubsub = opts.pubsub
93
+ self._message_middleware: Middleware[MessageEvent, Channel] = (
94
+ opts.message_middleware or Middleware()
95
+ )
96
+ self._outgoing_middleware: Middleware[OutgoingContext, None] = (
97
+ opts.outgoing_middleware or Middleware()
98
+ )
99
+ self._leave_handler = opts.leave_handler
100
+ self._leave_middlewares = list(opts.leave_middlewares)
101
+ self._on_destroy = opts.on_destroy
102
+ self._active: bool = False
103
+ self._connections: Store[Transport] = Store()
104
+ self._assigns: Store[PondAssigns] = Store()
105
+ self._presence = PresenceClient(self)
106
+ self._dispatch_queue: asyncio.Queue[_DispatchItem] = asyncio.Queue(
107
+ self._options.internal_queue_buffer
108
+ )
109
+ self._dispatch_semaphore = asyncio.Semaphore(
110
+ self._options.dispatch_concurrency
111
+ )
112
+ self._dispatch_task: asyncio.Task[None] | None = None
113
+ self._lifecycle_lock = asyncio.Lock()
114
+
115
+ async def start(self) -> None:
116
+ async with self._lifecycle_lock:
117
+ if self._active:
118
+ return
119
+ self._active = True
120
+ self._dispatch_task = asyncio.create_task(self._dispatch_loop())
121
+ await self._subscribe_to_pubsub()
122
+ self._fire_metric_channel_created()
123
+
124
+ async def close(self) -> None:
125
+ async with self._lifecycle_lock:
126
+ if not self._active:
127
+ return
128
+ self._active = False
129
+ if self._dispatch_task is not None and not self._dispatch_task.done():
130
+ self._dispatch_task.cancel()
131
+ await self._unsubscribe_from_pubsub()
132
+ self._fire_metric_channel_destroyed()
133
+ await self._fire_on_destroy()
134
+
135
+ async def _fire_on_destroy(self) -> None:
136
+ handler = self._on_destroy
137
+ if handler is None:
138
+ return
139
+ self._on_destroy = None
140
+ try:
141
+ await handler()
142
+ except Exception:
143
+ return
144
+
145
+ @property
146
+ def is_active(self) -> bool:
147
+ return self._active
148
+
149
+ async def user_count(self) -> int:
150
+ return await self._connections.len()
151
+
152
+ async def has_user(self, user_id: str) -> bool:
153
+ return await self._connections.has(user_id)
154
+
155
+ async def add_user(self, transport: Transport) -> None:
156
+ if not self._active:
157
+ raise internal(self.name, "Channel is not active")
158
+ user_id = transport.get_id()
159
+ await self._connections.create(user_id, transport)
160
+ await self._assigns.upsert(user_id, dict(transport.clone_assigns()))
161
+ self._fire_metric_channel_joined(user_id)
162
+
163
+ async def remove_user(
164
+ self, user_id: str, reason: str = LeaveReason.EXPLICIT_LEAVE.value
165
+ ) -> None:
166
+ if not await self._connections.discard(user_id):
167
+ return
168
+ assigns = await self._assigns.get(user_id, {}) or {}
169
+ presence: PondPresence | None = None
170
+ if await self._presence.has(user_id):
171
+ presence = await self._presence.get(user_id)
172
+ user = User(id=user_id, assigns=dict(assigns), presence=presence)
173
+
174
+ await self._assigns.discard(user_id)
175
+ await self._presence.untrack(user_id)
176
+ self._fire_metric_channel_left(user_id)
177
+
178
+ await self._fire_leave_handler(user, reason)
179
+
180
+ if await self._connections.len() == 0:
181
+ await self._fire_on_destroy()
182
+
183
+ async def _fire_leave_handler(self, user: User, reason: str) -> None:
184
+ if self._leave_handler is None:
185
+ return
186
+ ctx = LeaveContext(channel=self, user=user, reason=reason)
187
+ handler = self._leave_handler
188
+ try:
189
+ await execute_with_middleware(ctx, handler, self._leave_middlewares)
190
+ except Exception:
191
+ return
192
+
193
+ async def get_user(self, user_id: str) -> User:
194
+ if not await self._connections.has(user_id):
195
+ raise not_found(self.name, f"User {user_id} not in channel")
196
+ assigns = await self._assigns.get(user_id, {}) or {}
197
+ presence: PondPresence | None = None
198
+ if await self._presence.has(user_id):
199
+ presence = await self._presence.get(user_id)
200
+ return User(id=user_id, assigns=dict(assigns), presence=presence)
201
+
202
+ async def get_user_assign(self, user_id: str, key: str) -> Any:
203
+ assigns = await self._assigns.get(user_id, {}) or {}
204
+ return assigns.get(key)
205
+
206
+ async def update_assign(self, user_id: str, key: str, value: Any) -> None:
207
+ if not await self._assigns.has(user_id):
208
+ raise not_found(self.name, f"User {user_id} not in channel")
209
+ current = await self._assigns.get(user_id, {}) or {}
210
+ current = dict(current)
211
+ current[key] = value
212
+ await self._assigns.update(user_id, current)
213
+
214
+ async def get_assigns(self) -> dict[str, PondAssigns]:
215
+ snap = await self._assigns.snapshot()
216
+ return {uid: dict(a) for uid, a in snap.items()}
217
+
218
+ async def get_presence(self) -> dict[str, PondPresence]:
219
+ return await self._presence.get_all()
220
+
221
+ async def track_presence(self, user_id: str, data: PondPresence) -> None:
222
+ await self._presence.track(user_id, data)
223
+
224
+ async def update_presence(self, user_id: str, data: PondPresence) -> None:
225
+ await self._presence.update(user_id, data)
226
+
227
+ async def untrack_presence(self, user_id: str) -> None:
228
+ await self._presence.untrack(user_id)
229
+
230
+ async def evict_user(self, user_id: str, reason: str) -> None:
231
+ ev = Event(
232
+ action=ServerActions.SYSTEM.value,
233
+ channel_name=self.name,
234
+ request_id=uuid(),
235
+ event="EVICTED",
236
+ payload={"reason": reason},
237
+ node_id=self.node_id,
238
+ )
239
+ await self._send_direct([user_id], ev)
240
+ await self.remove_user(user_id, reason=LeaveReason.EVICTED.value)
241
+
242
+ async def broadcast(self, event_name: str, payload: PondMessage) -> None:
243
+ await self._send_event(
244
+ recipients=AllUsers(),
245
+ action=ServerActions.BROADCAST.value,
246
+ event_name=event_name,
247
+ payload=payload,
248
+ )
249
+
250
+ async def broadcast_to(
251
+ self,
252
+ event_name: str,
253
+ payload: PondMessage,
254
+ *user_ids: str,
255
+ ) -> None:
256
+ await self._send_event(
257
+ recipients=ToUsers(tuple(user_ids)),
258
+ action=ServerActions.BROADCAST.value,
259
+ event_name=event_name,
260
+ payload=payload,
261
+ )
262
+
263
+ async def broadcast_from(
264
+ self,
265
+ event_name: str,
266
+ payload: PondMessage,
267
+ exclude_user_id: str,
268
+ ) -> None:
269
+ await self._send_event(
270
+ recipients=AllExceptSender(exclude_user_id),
271
+ action=ServerActions.BROADCAST.value,
272
+ event_name=event_name,
273
+ payload=payload,
274
+ )
275
+
276
+ async def send_system(
277
+ self,
278
+ event_name: str,
279
+ payload: PondMessage,
280
+ *,
281
+ request_id: str,
282
+ user_ids: list[str],
283
+ ) -> None:
284
+ ev = Event(
285
+ action=ServerActions.SYSTEM.value,
286
+ channel_name=self.name,
287
+ request_id=request_id,
288
+ event=event_name,
289
+ payload=payload,
290
+ node_id=self.node_id,
291
+ )
292
+ await self._send_direct(user_ids, ev)
293
+
294
+ async def send_acknowledge(self, request_id: str, user_id: str) -> None:
295
+ await self.send_system(
296
+ SystemEvents.ACKNOWLEDGE.value,
297
+ {},
298
+ request_id=request_id,
299
+ user_ids=[user_id],
300
+ )
301
+
302
+ async def send_unauthorized(
303
+ self,
304
+ request_id: str,
305
+ user_id: str,
306
+ *,
307
+ code: int,
308
+ message: str,
309
+ ) -> None:
310
+ ev = Event(
311
+ action=ServerActions.SYSTEM.value,
312
+ channel_name=self.name,
313
+ request_id=request_id,
314
+ event=SystemEvents.UNAUTHORIZED.value,
315
+ payload={"code": code, "message": message},
316
+ node_id=self.node_id,
317
+ )
318
+ await self._send_direct([user_id], ev)
319
+
320
+ async def _send_direct(self, user_ids: list[str], event: Event) -> None:
321
+ for user_id in user_ids:
322
+ transport = await self._connections.get(user_id)
323
+ if transport is None or not transport.is_active():
324
+ continue
325
+ try:
326
+ await transport.send_event(event)
327
+ except Exception:
328
+ continue
329
+
330
+ async def handle_incoming_event(self, event: Event, sender_id: str) -> None:
331
+ if not await self._connections.has(sender_id):
332
+ return
333
+ user = await self.get_user(sender_id)
334
+ msg = MessageEvent(event=event, user=user)
335
+
336
+ async def final(_req: MessageEvent, _resp: Channel) -> None:
337
+ return
338
+
339
+ before_err = await self._fire_before_message(event)
340
+ if before_err is not None:
341
+ await self._fire_after_message(event, before_err)
342
+ return
343
+
344
+ caught: BaseException | None = None
345
+ try:
346
+ await self._message_middleware.handle(msg, self, final)
347
+ except Exception as exc:
348
+ caught = exc
349
+ await self._fire_after_message(event, caught)
350
+
351
+ async def publish_presence_change(
352
+ self,
353
+ *,
354
+ event_type: PresenceEventTypes,
355
+ changed_user_id: str,
356
+ changed: PondPresence,
357
+ presence_snapshot: list[PondPresence],
358
+ ) -> None:
359
+ ev = Event(
360
+ action=ServerActions.PRESENCE.value,
361
+ channel_name=self.name,
362
+ request_id=uuid(),
363
+ event=event_type.value,
364
+ payload={"presence": presence_snapshot, "changed": changed},
365
+ node_id=self.node_id,
366
+ )
367
+ recipients = await self._presence.keys()
368
+ if recipients:
369
+ await self._enqueue_dispatch(ev, recipients)
370
+ await self._publish_event_to_pubsub(ev, f"presence:{event_type.value.lower()}")
371
+
372
+ async def _resolve_recipients(self, spec: RecipientSpec) -> list[str]:
373
+ match spec:
374
+ case AllUsers():
375
+ return await self._connections.keys()
376
+ case AllExceptSender(sender_id=sender):
377
+ return [uid for uid in await self._connections.keys() if uid != sender]
378
+ case ToUsers(user_ids=ids):
379
+ return list(ids)
380
+
381
+ async def _send_event(
382
+ self,
383
+ *,
384
+ recipients: RecipientSpec,
385
+ action: str,
386
+ event_name: str,
387
+ payload: PondMessage,
388
+ request_id: str | None = None,
389
+ ) -> None:
390
+ ev = Event(
391
+ action=action,
392
+ channel_name=self.name,
393
+ request_id=request_id or uuid(),
394
+ event=event_name,
395
+ payload=payload,
396
+ node_id=self.node_id,
397
+ )
398
+ resolved = await self._resolve_recipients(recipients)
399
+ if resolved:
400
+ await self._enqueue_dispatch(ev, resolved)
401
+ if action == ServerActions.BROADCAST.value:
402
+ await self._publish_event_to_pubsub(ev, "message")
403
+
404
+ async def _enqueue_dispatch(self, event: Event, recipient_ids: list[str]) -> None:
405
+ if not self._active:
406
+ return
407
+ item = _DispatchItem(event=event, recipient_ids=recipient_ids)
408
+ timeout = self._options.internal_queue_timeout
409
+ try:
410
+ await asyncio.wait_for(self._dispatch_queue.put(item), timeout=timeout)
411
+ except TimeoutError:
412
+ return
413
+
414
+ async def _dispatch_loop(self) -> None:
415
+ while True:
416
+ try:
417
+ item = await self._dispatch_queue.get()
418
+ except asyncio.CancelledError:
419
+ return
420
+ if not self._active:
421
+ return
422
+ await self._dispatch_item(item)
423
+
424
+ async def _dispatch_item(self, item: _DispatchItem) -> None:
425
+ async def bounded_deliver(rid: str) -> None:
426
+ async with self._dispatch_semaphore:
427
+ try:
428
+ await self._deliver_one(item.event, rid)
429
+ except Exception:
430
+ return
431
+
432
+ await asyncio.gather(
433
+ *(bounded_deliver(rid) for rid in item.recipient_ids),
434
+ return_exceptions=False,
435
+ )
436
+
437
+ async def _deliver_one(self, event: Event, recipient_id: str) -> None:
438
+ transport = await self._connections.get(recipient_id)
439
+ if transport is None or not transport.is_active():
440
+ return
441
+ try:
442
+ user = await self.get_user(recipient_id)
443
+ except Exception:
444
+ return
445
+ delivery_event = Event(
446
+ action=event.action,
447
+ channel_name=event.channel_name,
448
+ request_id=event.request_id,
449
+ event=event.event,
450
+ payload=event.payload,
451
+ node_id=event.node_id,
452
+ )
453
+ ctx = OutgoingContext(
454
+ channel=self,
455
+ event=delivery_event,
456
+ user=user,
457
+ transport=transport,
458
+ )
459
+
460
+ async def noop_final(_req: OutgoingContext, _resp: None) -> None:
461
+ return
462
+
463
+ await self._outgoing_middleware.handle(ctx, None, noop_final)
464
+
465
+ if ctx.is_blocked():
466
+ return
467
+ try:
468
+ await transport.send_event(ctx.event)
469
+ except Exception:
470
+ return
471
+
472
+ def _clean_endpoint(self) -> str:
473
+ ep = self._endpoint_path
474
+ return ep[1:] if ep.startswith("/") else ep
475
+
476
+ def _pubsub_pattern(self) -> str:
477
+ return format_topic(self._clean_endpoint(), self.name, ".*")
478
+
479
+ async def _subscribe_to_pubsub(self) -> None:
480
+ if self._pubsub is None or not self._endpoint_path:
481
+ return
482
+ try:
483
+ await self._pubsub.subscribe(self._pubsub_pattern(), self._handle_pubsub_message)
484
+ except Exception:
485
+ return
486
+
487
+ async def _unsubscribe_from_pubsub(self) -> None:
488
+ if self._pubsub is None or not self._endpoint_path:
489
+ return
490
+ try:
491
+ await self._pubsub.unsubscribe(self._pubsub_pattern())
492
+ except Exception:
493
+ return
494
+
495
+ async def _publish_event_to_pubsub(self, event: Event, event_subtype: str) -> None:
496
+ if self._pubsub is None or not self._endpoint_path:
497
+ return
498
+ topic = format_topic(self._clean_endpoint(), self.name, event_subtype)
499
+ try:
500
+ await self._pubsub.publish(topic, event_to_pubsub_bytes(event))
501
+ except Exception:
502
+ return
503
+
504
+ async def _handle_pubsub_message(self, _topic: str, data: bytes) -> None:
505
+ event = pubsub_bytes_to_event(data)
506
+ if event is None:
507
+ return
508
+ if event.node_id and event.node_id == self.node_id:
509
+ return
510
+ if event.channel_name != self.name:
511
+ return
512
+ if not self._active:
513
+ return
514
+ if event.action == ServerActions.BROADCAST.value:
515
+ recipients = await self._connections.keys()
516
+ if recipients:
517
+ await self._enqueue_dispatch(event, recipients)
518
+ return
519
+ if event.action == ServerActions.PRESENCE.value:
520
+ recipients = await self._presence.keys()
521
+ if recipients:
522
+ await self._enqueue_dispatch(event, recipients)
523
+ return
524
+
525
+ def _fire_metric_channel_created(self) -> None:
526
+ hooks = self._options.hooks
527
+ if hooks is None or hooks.metrics is None:
528
+ return
529
+ try:
530
+ hooks.metrics.channel_created(self.name)
531
+ except Exception:
532
+ return
533
+
534
+ def _fire_metric_channel_destroyed(self) -> None:
535
+ hooks = self._options.hooks
536
+ if hooks is None or hooks.metrics is None:
537
+ return
538
+ try:
539
+ hooks.metrics.channel_destroyed(self.name)
540
+ except Exception:
541
+ return
542
+
543
+ def _fire_metric_channel_joined(self, user_id: str) -> None:
544
+ hooks = self._options.hooks
545
+ if hooks is None or hooks.metrics is None:
546
+ return
547
+ try:
548
+ hooks.metrics.channel_joined(user_id, self.name)
549
+ except Exception:
550
+ return
551
+
552
+ def _fire_metric_channel_left(self, user_id: str) -> None:
553
+ hooks = self._options.hooks
554
+ if hooks is None or hooks.metrics is None:
555
+ return
556
+ try:
557
+ hooks.metrics.channel_left(user_id, self.name)
558
+ except Exception:
559
+ return
560
+
561
+ async def _fire_before_message(self, event: Event) -> BaseException | None:
562
+ hooks = self._options.hooks
563
+ if hooks is None or hooks.before_message is None:
564
+ return None
565
+ try:
566
+ await hooks.before_message(event)
567
+ except Exception as exc:
568
+ return exc
569
+ return None
570
+
571
+ async def _fire_after_message(
572
+ self, event: Event, err: BaseException | None
573
+ ) -> None:
574
+ hooks = self._options.hooks
575
+ if hooks is None or hooks.after_message is None:
576
+ return
577
+ try:
578
+ await hooks.after_message(event, err)
579
+ except Exception:
580
+ return
@@ -0,0 +1,16 @@
1
+ from __future__ import annotations
2
+
3
+ from .connection_context import ConnectionContext, ConnectionDecision
4
+ from .event_context import EventContext
5
+ from .join_context import JoinContext
6
+ from .leave_context import LeaveContext
7
+ from .outgoing_context import OutgoingContext
8
+
9
+ __all__ = [
10
+ "ConnectionContext",
11
+ "ConnectionDecision",
12
+ "EventContext",
13
+ "JoinContext",
14
+ "LeaveContext",
15
+ "OutgoingContext",
16
+ ]