pondsocket-client 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.
@@ -0,0 +1,52 @@
1
+ from __future__ import annotations
2
+
3
+ from ._base import BaseClient, ConnectionStateHandler, ErrorHandler
4
+ from ._channel import (
5
+ Channel,
6
+ ChannelStateHandler,
7
+ MessageHandler,
8
+ PresenceHandler,
9
+ PresenceUpdateHandler,
10
+ ResponseTimeoutError,
11
+ UsersChangeHandler,
12
+ )
13
+ from ._websocket import WebSocketClient
14
+ from .client import PondClient
15
+ from .types import (
16
+ DEFAULT_BASE_RECONNECT_DELAY,
17
+ DEFAULT_CONNECTION_TIMEOUT,
18
+ DEFAULT_MAX_QUEUE_SIZE,
19
+ DEFAULT_MAX_RECONNECT_DELAY,
20
+ DEFAULT_PING_INTERVAL,
21
+ DEFAULT_RESPONSE_TIMEOUT,
22
+ ClientOptions,
23
+ ConnectionState,
24
+ Publisher,
25
+ )
26
+
27
+ __version__ = "0.0.1"
28
+
29
+ __all__ = [
30
+ "DEFAULT_BASE_RECONNECT_DELAY",
31
+ "DEFAULT_CONNECTION_TIMEOUT",
32
+ "DEFAULT_MAX_QUEUE_SIZE",
33
+ "DEFAULT_MAX_RECONNECT_DELAY",
34
+ "DEFAULT_PING_INTERVAL",
35
+ "DEFAULT_RESPONSE_TIMEOUT",
36
+ "BaseClient",
37
+ "Channel",
38
+ "ChannelStateHandler",
39
+ "ClientOptions",
40
+ "ConnectionState",
41
+ "ConnectionStateHandler",
42
+ "ErrorHandler",
43
+ "MessageHandler",
44
+ "PondClient",
45
+ "PresenceHandler",
46
+ "PresenceUpdateHandler",
47
+ "Publisher",
48
+ "ResponseTimeoutError",
49
+ "UsersChangeHandler",
50
+ "WebSocketClient",
51
+ "__version__",
52
+ ]
@@ -0,0 +1,181 @@
1
+ from __future__ import annotations
2
+
3
+ import abc
4
+ import asyncio
5
+ from collections.abc import Callable
6
+ from typing import TypeAlias
7
+
8
+ from pondsocket_common import (
9
+ BehaviorSubject,
10
+ ChannelEvent,
11
+ ClientMessage,
12
+ JoinParams,
13
+ Subject,
14
+ Unsubscribe,
15
+ ValidationError,
16
+ parse_channel_event,
17
+ )
18
+
19
+ from ._channel import Channel
20
+ from .types import ClientOptions, ConnectionState
21
+
22
+ ConnectionStateHandler: TypeAlias = Callable[[ConnectionState], None]
23
+ ErrorHandler: TypeAlias = Callable[[BaseException], None]
24
+
25
+
26
+ class BaseClient(abc.ABC):
27
+ __slots__ = (
28
+ "_broadcaster",
29
+ "_channels",
30
+ "_connection_state",
31
+ "_disconnecting",
32
+ "_errors",
33
+ "_options",
34
+ "_reconnect_attempts",
35
+ "_reconnect_task",
36
+ "_tasks",
37
+ )
38
+
39
+ def __init__(self, options: ClientOptions | None = None) -> None:
40
+ self._options = options or ClientOptions()
41
+ self._channels: dict[str, Channel] = {}
42
+ self._broadcaster: Subject[ChannelEvent] = Subject()
43
+ self._connection_state: BehaviorSubject[ConnectionState] = BehaviorSubject(
44
+ ConnectionState.DISCONNECTED
45
+ )
46
+ self._errors: Subject[BaseException] = Subject()
47
+ self._reconnect_attempts: int = 0
48
+ self._reconnect_task: asyncio.Task[None] | None = None
49
+ self._disconnecting: bool = False
50
+ self._tasks: set[asyncio.Task[None]] = set()
51
+ self._broadcaster.subscribe(self._route_event)
52
+
53
+ @property
54
+ def options(self) -> ClientOptions:
55
+ return self._options
56
+
57
+ def get_state(self) -> ConnectionState:
58
+ return self._connection_state.value or ConnectionState.DISCONNECTED
59
+
60
+ def create_channel(
61
+ self, name: str, params: JoinParams | None = None
62
+ ) -> Channel:
63
+ existing = self._channels.get(name)
64
+ if existing is not None and existing.channel_state.value not in ("CLOSED", "DECLINED"):
65
+ return existing
66
+ channel = Channel(
67
+ name=name,
68
+ params=params,
69
+ publisher=self._publish_outbound,
70
+ connection_state=self._connection_state,
71
+ max_queue_size=self._options.max_queue_size,
72
+ response_timeout=self._options.response_timeout,
73
+ )
74
+ self._channels[name] = channel
75
+ return channel
76
+
77
+ def on_connection_change(self, callback: ConnectionStateHandler) -> Unsubscribe:
78
+ return self._connection_state.subscribe(callback)
79
+
80
+ def on_error(self, callback: ErrorHandler) -> Unsubscribe:
81
+ return self._errors.subscribe(callback)
82
+
83
+ async def connect(self) -> None:
84
+ self._disconnecting = False
85
+ if self.get_state() != ConnectionState.DISCONNECTED:
86
+ return
87
+ self._connection_state.publish(ConnectionState.CONNECTING)
88
+ try:
89
+ await self._open_transport()
90
+ except Exception as exc:
91
+ self._errors.publish(exc)
92
+ self._connection_state.publish(ConnectionState.DISCONNECTED)
93
+ self._schedule_reconnect()
94
+
95
+ async def disconnect(self) -> None:
96
+ self._disconnecting = True
97
+ if self._reconnect_task is not None and not self._reconnect_task.done():
98
+ self._reconnect_task.cancel()
99
+ self._reconnect_task = None
100
+ await self._close_transport()
101
+ self._connection_state.publish(ConnectionState.DISCONNECTED)
102
+ for channel in list(self._channels.values()):
103
+ channel._force_close()
104
+ self._channels.clear()
105
+
106
+ def _mark_connected(self) -> None:
107
+ self._reconnect_attempts = 0
108
+ self._connection_state.publish(ConnectionState.CONNECTED)
109
+
110
+ def _mark_disconnected(self) -> None:
111
+ self._connection_state.publish(ConnectionState.DISCONNECTED)
112
+ if not self._disconnecting:
113
+ self._schedule_reconnect()
114
+
115
+ def _handle_inbound_text(self, text: str) -> None:
116
+ try:
117
+ import json
118
+
119
+ data = json.loads(text)
120
+ except json.JSONDecodeError as e:
121
+ self._errors.publish(e)
122
+ return
123
+ try:
124
+ event = parse_channel_event(data)
125
+ except ValidationError as e:
126
+ self._errors.publish(e)
127
+ return
128
+ self._broadcaster.publish(event)
129
+
130
+ def _route_event(self, event: ChannelEvent) -> None:
131
+ channel = self._channels.get(event.channel_name)
132
+ if channel is None:
133
+ return
134
+ channel.handle_event(event)
135
+
136
+ def _schedule_reconnect(self) -> None:
137
+ if self._disconnecting:
138
+ return
139
+ max_attempts = self._options.max_reconnect_attempts
140
+ if max_attempts >= 0 and self._reconnect_attempts >= max_attempts:
141
+ return
142
+ if self._reconnect_task is not None and not self._reconnect_task.done():
143
+ return
144
+ delay = min(
145
+ self._options.base_reconnect_delay * (2 ** self._reconnect_attempts),
146
+ self._options.max_reconnect_delay,
147
+ )
148
+ self._reconnect_attempts += 1
149
+ self._reconnect_task = asyncio.create_task(self._reconnect_after(delay))
150
+ self._reconnect_task.add_done_callback(self._on_reconnect_task_done)
151
+
152
+ def _on_reconnect_task_done(self, _task: asyncio.Task[None]) -> None:
153
+ self._reconnect_task = None
154
+
155
+ async def _reconnect_after(self, delay: float) -> None:
156
+ try:
157
+ await asyncio.sleep(delay)
158
+ except asyncio.CancelledError:
159
+ return
160
+ if self._disconnecting:
161
+ return
162
+ await self.connect()
163
+
164
+ async def _publish_outbound(self, message: ClientMessage) -> None:
165
+ await self._send_outbound(message)
166
+
167
+ @abc.abstractmethod
168
+ async def _open_transport(self) -> None: ...
169
+
170
+ @abc.abstractmethod
171
+ async def _close_transport(self) -> None: ...
172
+
173
+ @abc.abstractmethod
174
+ async def _send_outbound(self, message: ClientMessage) -> None: ...
175
+
176
+
177
+ __all__ = [
178
+ "BaseClient",
179
+ "ConnectionStateHandler",
180
+ "ErrorHandler",
181
+ ]
@@ -0,0 +1,345 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ import contextlib
5
+ from collections import deque
6
+ from collections.abc import Callable
7
+ from typing import Any, TypeAlias
8
+
9
+ from pondsocket_common import (
10
+ BehaviorSubject,
11
+ ChannelEvent,
12
+ ChannelState,
13
+ ClientActions,
14
+ ClientMessage,
15
+ Events,
16
+ JoinParams,
17
+ PondMessage,
18
+ PondPresence,
19
+ PresenceEventTypes,
20
+ PresenceMessage,
21
+ PresencePayloadModel,
22
+ ServerActions,
23
+ ServerMessage,
24
+ Subject,
25
+ Unsubscribe,
26
+ uuid,
27
+ )
28
+
29
+ from .types import ConnectionState, Publisher
30
+
31
+ ChannelStateHandler: TypeAlias = Callable[[ChannelState], None]
32
+ MessageHandler: TypeAlias = Callable[[ServerMessage], None]
33
+ PresenceHandler: TypeAlias = Callable[[PondPresence], None]
34
+ PresenceUpdateHandler: TypeAlias = Callable[[PresencePayloadModel], None]
35
+ UsersChangeHandler: TypeAlias = Callable[[list[PondPresence]], None]
36
+
37
+
38
+ class ResponseTimeoutError(Exception):
39
+ pass
40
+
41
+
42
+ class Channel:
43
+ __slots__ = (
44
+ "_closed",
45
+ "_connection_state",
46
+ "_connection_unsub",
47
+ "_events",
48
+ "_params",
49
+ "_pending_responses",
50
+ "_presence",
51
+ "_publisher",
52
+ "_queue",
53
+ "_response_timeout",
54
+ "_state",
55
+ "_tasks",
56
+ "name",
57
+ )
58
+
59
+ def __init__(
60
+ self,
61
+ *,
62
+ name: str,
63
+ params: JoinParams | None,
64
+ publisher: Publisher,
65
+ connection_state: BehaviorSubject[ConnectionState],
66
+ max_queue_size: int = 100,
67
+ response_timeout: float = 5.0,
68
+ ) -> None:
69
+ self.name = name
70
+ self._params: JoinParams = dict(params or {})
71
+ self._publisher = publisher
72
+ self._connection_state = connection_state
73
+ self._state: BehaviorSubject[ChannelState] = BehaviorSubject(ChannelState.IDLE)
74
+ self._events: Subject[ChannelEvent] = Subject()
75
+ self._presence: list[PondPresence] = []
76
+ self._queue: deque[ClientMessage] = deque(maxlen=max_queue_size)
77
+ self._pending_responses: dict[str, asyncio.Future[PondMessage]] = {}
78
+ self._response_timeout = response_timeout
79
+ self._tasks: set[asyncio.Task[None]] = set()
80
+ self._closed = False
81
+ self._connection_unsub: Unsubscribe = self._connection_state.subscribe(
82
+ self.handle_connection_state
83
+ )
84
+
85
+ def _spawn(self, coro: Any) -> None:
86
+ task = asyncio.create_task(coro)
87
+ self._tasks.add(task)
88
+ task.add_done_callback(self._tasks.discard)
89
+
90
+ @property
91
+ def channel_state(self) -> ChannelState:
92
+ value = self._state.value
93
+ return value if value is not None else ChannelState.IDLE
94
+
95
+ @property
96
+ def presence(self) -> list[PondPresence]:
97
+ return list(self._presence)
98
+
99
+ def join(self) -> None:
100
+ if self._closed:
101
+ return
102
+ state = self.channel_state
103
+ if state in (ChannelState.JOINING, ChannelState.JOINED, ChannelState.DECLINED):
104
+ return
105
+ self._state.publish(ChannelState.JOINING)
106
+ msg = self._build_join_message()
107
+ self._enqueue_or_send(msg)
108
+
109
+ def leave(self) -> None:
110
+ if self._closed:
111
+ return
112
+ msg = ClientMessage(
113
+ action=ClientActions.LEAVE_CHANNEL,
114
+ channelName=self.name,
115
+ event=ClientActions.LEAVE_CHANNEL.value,
116
+ requestId=uuid(),
117
+ payload={},
118
+ )
119
+ if self._connection_state.value == ConnectionState.CONNECTED:
120
+ self._spawn(self._publish(msg))
121
+ self._state.publish(ChannelState.CLOSED)
122
+ self._closed = True
123
+ self._teardown()
124
+
125
+ def send_message(self, event: str, payload: PondMessage | None = None) -> None:
126
+ if self._closed:
127
+ return
128
+ msg = ClientMessage(
129
+ action=ClientActions.BROADCAST,
130
+ channelName=self.name,
131
+ event=event,
132
+ requestId=uuid(),
133
+ payload=dict(payload or {}),
134
+ )
135
+ self._enqueue_or_send(msg)
136
+
137
+ async def send_for_response(
138
+ self,
139
+ event: str,
140
+ payload: PondMessage | None = None,
141
+ *,
142
+ wait: float | None = None,
143
+ ) -> PondMessage:
144
+ if self._closed:
145
+ raise ResponseTimeoutError("channel is closed")
146
+ request_id = uuid()
147
+ loop = asyncio.get_running_loop()
148
+ fut: asyncio.Future[PondMessage] = loop.create_future()
149
+ self._pending_responses[request_id] = fut
150
+ msg = ClientMessage(
151
+ action=ClientActions.BROADCAST,
152
+ channelName=self.name,
153
+ event=event,
154
+ requestId=request_id,
155
+ payload=dict(payload or {}),
156
+ )
157
+ self._enqueue_or_send(msg)
158
+ wait_seconds = wait if wait is not None else self._response_timeout
159
+ try:
160
+ return await asyncio.wait_for(fut, timeout=wait_seconds)
161
+ except TimeoutError as e:
162
+ self._pending_responses.pop(request_id, None)
163
+ raise ResponseTimeoutError(
164
+ f"no response received for event {event!r} within {wait_seconds}s"
165
+ ) from e
166
+
167
+ def handle_event(self, event: ChannelEvent) -> None:
168
+ if self._closed:
169
+ return
170
+ if isinstance(event, PresenceMessage):
171
+ self._presence = [dict(p) for p in event.payload.presence]
172
+ if self.channel_state == ChannelState.JOINED:
173
+ self._events.publish(event)
174
+ return
175
+ if event.action == ServerActions.SYSTEM:
176
+ if event.event == Events.ACKNOWLEDGE.value:
177
+ self._acknowledge()
178
+ return
179
+ if event.event == Events.UNAUTHORIZED.value:
180
+ self._decline()
181
+ return
182
+ if event.request_id in self._pending_responses:
183
+ fut = self._pending_responses.pop(event.request_id)
184
+ if not fut.done():
185
+ payload = event.payload if isinstance(event.payload, dict) else {}
186
+ fut.set_result(payload)
187
+ return
188
+ if self.channel_state == ChannelState.JOINED:
189
+ self._events.publish(event)
190
+
191
+ def handle_connection_state(self, state: ConnectionState) -> None:
192
+ if self._closed:
193
+ return
194
+ if state == ConnectionState.CONNECTED:
195
+ if self.channel_state == ChannelState.STALLED:
196
+ msg = self._build_join_message()
197
+ self._spawn(self._publish(msg))
198
+ return
199
+ if self.channel_state == ChannelState.JOINING:
200
+ self._drain_queued_joins()
201
+ elif state == ConnectionState.DISCONNECTED:
202
+ if self.channel_state == ChannelState.JOINED:
203
+ self._state.publish(ChannelState.STALLED)
204
+
205
+ def _drain_queued_joins(self) -> None:
206
+ remaining: deque[ClientMessage] = deque(maxlen=self._queue.maxlen)
207
+ for msg in self._queue:
208
+ if msg.action == ClientActions.JOIN_CHANNEL:
209
+ self._spawn(self._publish(msg))
210
+ else:
211
+ remaining.append(msg)
212
+ self._queue = remaining
213
+
214
+ def on_channel_state_change(self, callback: ChannelStateHandler) -> Unsubscribe:
215
+ return self._state.subscribe(callback)
216
+
217
+ def on_message(self, callback: MessageHandler) -> Unsubscribe:
218
+ def filtered(ev: ChannelEvent) -> None:
219
+ if isinstance(ev, ServerMessage):
220
+ callback(ev)
221
+
222
+ return self._events.subscribe(filtered)
223
+
224
+ def on_message_event(
225
+ self, event_name: str, callback: MessageHandler
226
+ ) -> Unsubscribe:
227
+ def filtered(ev: ChannelEvent) -> None:
228
+ if isinstance(ev, ServerMessage) and ev.event == event_name:
229
+ callback(ev)
230
+
231
+ return self._events.subscribe(filtered)
232
+
233
+ def on_join(self, callback: PresenceHandler) -> Unsubscribe:
234
+ return self._on_presence_kind(PresenceEventTypes.JOIN, callback)
235
+
236
+ def on_leave(self, callback: PresenceHandler) -> Unsubscribe:
237
+ return self._on_presence_kind(PresenceEventTypes.LEAVE, callback)
238
+
239
+ def on_presence_change(self, callback: PresenceUpdateHandler) -> Unsubscribe:
240
+ def filtered(ev: ChannelEvent) -> None:
241
+ if isinstance(ev, PresenceMessage) and ev.event == PresenceEventTypes.UPDATE:
242
+ callback(ev.payload)
243
+
244
+ return self._events.subscribe(filtered)
245
+
246
+ def on_users_change(self, callback: UsersChangeHandler) -> Unsubscribe:
247
+ def filtered(ev: ChannelEvent) -> None:
248
+ if isinstance(ev, PresenceMessage):
249
+ callback([dict(p) for p in ev.payload.presence])
250
+
251
+ return self._events.subscribe(filtered)
252
+
253
+ def _on_presence_kind(
254
+ self, kind: PresenceEventTypes, callback: PresenceHandler
255
+ ) -> Unsubscribe:
256
+ def filtered(ev: ChannelEvent) -> None:
257
+ if isinstance(ev, PresenceMessage) and ev.event == kind:
258
+ callback(dict(ev.payload.changed))
259
+
260
+ return self._events.subscribe(filtered)
261
+
262
+ def _build_join_message(self) -> ClientMessage:
263
+ return ClientMessage(
264
+ action=ClientActions.JOIN_CHANNEL,
265
+ channelName=self.name,
266
+ event=ClientActions.JOIN_CHANNEL.value,
267
+ requestId=uuid(),
268
+ payload=dict(self._params),
269
+ )
270
+
271
+ def _enqueue_or_send(self, msg: ClientMessage) -> None:
272
+ if (
273
+ self._connection_state.value == ConnectionState.CONNECTED
274
+ and self.channel_state == ChannelState.JOINED
275
+ ):
276
+ self._spawn(self._publish(msg))
277
+ return
278
+ is_join = msg.action == ClientActions.JOIN_CHANNEL
279
+ if (
280
+ self._connection_state.value == ConnectionState.CONNECTED
281
+ and is_join
282
+ ):
283
+ self._spawn(self._publish(msg))
284
+ return
285
+ self._queue.append(msg)
286
+
287
+ def _flush_queue(self) -> None:
288
+ if not self._queue:
289
+ return
290
+ pending = list(self._queue)
291
+ self._queue.clear()
292
+ for msg in pending:
293
+ self._spawn(self._publish(msg))
294
+
295
+ def _acknowledge(self) -> None:
296
+ if self.channel_state != ChannelState.JOINED:
297
+ self._state.publish(ChannelState.JOINED)
298
+ self._flush_queue()
299
+
300
+ def _decline(self) -> None:
301
+ self._state.publish(ChannelState.DECLINED)
302
+ self._queue.clear()
303
+ for fut in self._pending_responses.values():
304
+ if not fut.done():
305
+ fut.cancel()
306
+ self._pending_responses.clear()
307
+
308
+ async def _publish(self, msg: ClientMessage) -> None:
309
+ try:
310
+ await self._publisher(msg)
311
+ except Exception:
312
+ return
313
+
314
+ def _teardown(self) -> None:
315
+ with contextlib.suppress(Exception):
316
+ self._connection_unsub()
317
+ for fut in self._pending_responses.values():
318
+ if not fut.done():
319
+ fut.cancel()
320
+ self._pending_responses.clear()
321
+ self._queue.clear()
322
+ self._events.close()
323
+
324
+ def _force_close(self) -> None:
325
+ if self._closed:
326
+ return
327
+ self._state.publish(ChannelState.CLOSED)
328
+ self._closed = True
329
+ self._teardown()
330
+
331
+ def _close_state_subject(self) -> None:
332
+ self._state.close()
333
+
334
+
335
+ _publisher_alias: Any = Publisher
336
+
337
+ __all__ = [
338
+ "Channel",
339
+ "ChannelStateHandler",
340
+ "MessageHandler",
341
+ "PresenceHandler",
342
+ "PresenceUpdateHandler",
343
+ "ResponseTimeoutError",
344
+ "UsersChangeHandler",
345
+ ]
@@ -0,0 +1,83 @@
1
+ from __future__ import annotations
2
+
3
+ import abc
4
+ import asyncio
5
+ import json
6
+ from typing import TYPE_CHECKING
7
+
8
+ from pondsocket_common import ClientMessage
9
+
10
+ from ._base import BaseClient
11
+
12
+ if TYPE_CHECKING:
13
+ from websockets.asyncio.client import ClientConnection
14
+
15
+
16
+ class WebSocketClient(BaseClient, abc.ABC):
17
+ __slots__ = ("_recv_task", "_socket")
18
+
19
+ def __init__(self, *args: object, **kwargs: object) -> None:
20
+ super().__init__(*args, **kwargs) # type: ignore[arg-type]
21
+ self._socket: ClientConnection | None = None
22
+ self._recv_task: asyncio.Task[None] | None = None
23
+
24
+ @abc.abstractmethod
25
+ def _resolve_url(self) -> str: ...
26
+
27
+ async def _open_transport(self) -> None:
28
+ from websockets.asyncio.client import connect
29
+
30
+ url = self._resolve_url()
31
+ timeout = self._options.connection_timeout
32
+ try:
33
+ socket = await asyncio.wait_for(connect(url), timeout=timeout)
34
+ except TimeoutError as e:
35
+ raise ConnectionError(f"WebSocket connection to {url} timed out") from e
36
+ self._socket = socket
37
+ self._mark_connected()
38
+ self._recv_task = asyncio.create_task(self._receive_loop())
39
+
40
+ async def _close_transport(self) -> None:
41
+ if self._recv_task is not None and not self._recv_task.done():
42
+ self._recv_task.cancel()
43
+ self._recv_task = None
44
+ socket = self._socket
45
+ self._socket = None
46
+ if socket is not None:
47
+ try:
48
+ await socket.close()
49
+ except Exception:
50
+ return
51
+
52
+ async def _send_outbound(self, message: ClientMessage) -> None:
53
+ socket = self._socket
54
+ if socket is None:
55
+ raise ConnectionError("WebSocket is not connected")
56
+ wire = message.model_dump(by_alias=True, mode="json")
57
+ await socket.send(json.dumps(wire))
58
+
59
+ async def _receive_loop(self) -> None:
60
+ socket = self._socket
61
+ if socket is None:
62
+ return
63
+ try:
64
+ async for frame in socket:
65
+ if isinstance(frame, bytes):
66
+ try:
67
+ text = frame.decode("utf-8")
68
+ except UnicodeDecodeError:
69
+ continue
70
+ else:
71
+ text = frame
72
+ self._handle_inbound_text(text)
73
+ except asyncio.CancelledError:
74
+ return
75
+ except Exception as e:
76
+ self._errors.publish(e)
77
+ finally:
78
+ if self._socket is socket:
79
+ self._socket = None
80
+ self._mark_disconnected()
81
+
82
+
83
+ __all__ = ["WebSocketClient"]
@@ -0,0 +1,52 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Any
4
+ from urllib.parse import urlencode, urlsplit, urlunsplit
5
+
6
+ from ._websocket import WebSocketClient
7
+ from .types import ClientOptions
8
+
9
+
10
+ class PondClient(WebSocketClient):
11
+ __slots__ = ("_endpoint", "_params")
12
+
13
+ def __init__(
14
+ self,
15
+ endpoint: str,
16
+ params: dict[str, Any] | None = None,
17
+ options: ClientOptions | None = None,
18
+ ) -> None:
19
+ super().__init__(options)
20
+ self._endpoint = endpoint
21
+ self._params = dict(params or {})
22
+
23
+ def _resolve_url(self) -> str:
24
+ normalized = _normalize_ws_scheme(self._endpoint)
25
+ if not self._params:
26
+ return normalized
27
+ parts = urlsplit(normalized)
28
+ existing = parts.query
29
+ merged = urlencode(self._params, doseq=True)
30
+ combined = f"{existing}&{merged}" if existing else merged
31
+ return urlunsplit(
32
+ (parts.scheme, parts.netloc, parts.path, combined, parts.fragment)
33
+ )
34
+
35
+
36
+ def _normalize_ws_scheme(url: str) -> str:
37
+ parts = urlsplit(url)
38
+ scheme = parts.scheme.lower()
39
+ if scheme == "http":
40
+ scheme = "ws"
41
+ elif scheme == "https":
42
+ scheme = "wss"
43
+ elif scheme not in {"ws", "wss"}:
44
+ raise ValueError(
45
+ f"invalid websocket scheme {parts.scheme!r}; expected ws://, wss://, http://, or https://"
46
+ )
47
+ return urlunsplit(
48
+ (scheme, parts.netloc, parts.path, parts.query, parts.fragment)
49
+ )
50
+
51
+
52
+ __all__ = ["PondClient"]
File without changes
@@ -0,0 +1,35 @@
1
+ from __future__ import annotations
2
+
3
+ from collections.abc import Awaitable, Callable
4
+ from dataclasses import dataclass
5
+ from enum import StrEnum
6
+ from typing import TypeAlias
7
+
8
+ from pondsocket_common import ClientMessage
9
+
10
+ DEFAULT_CONNECTION_TIMEOUT: float = 10.0
11
+ DEFAULT_MAX_RECONNECT_DELAY: float = 30.0
12
+ DEFAULT_BASE_RECONNECT_DELAY: float = 1.0
13
+ DEFAULT_PING_INTERVAL: float | None = None
14
+ DEFAULT_MAX_QUEUE_SIZE: int = 100
15
+ DEFAULT_RESPONSE_TIMEOUT: float = 5.0
16
+
17
+
18
+ class ConnectionState(StrEnum):
19
+ DISCONNECTED = "disconnected"
20
+ CONNECTING = "connecting"
21
+ CONNECTED = "connected"
22
+
23
+
24
+ @dataclass(slots=True)
25
+ class ClientOptions:
26
+ connection_timeout: float = DEFAULT_CONNECTION_TIMEOUT
27
+ base_reconnect_delay: float = DEFAULT_BASE_RECONNECT_DELAY
28
+ max_reconnect_delay: float = DEFAULT_MAX_RECONNECT_DELAY
29
+ max_reconnect_attempts: int = -1
30
+ ping_interval: float | None = DEFAULT_PING_INTERVAL
31
+ max_queue_size: int = DEFAULT_MAX_QUEUE_SIZE
32
+ response_timeout: float = DEFAULT_RESPONSE_TIMEOUT
33
+
34
+
35
+ Publisher: TypeAlias = Callable[[ClientMessage], Awaitable[None]]
@@ -0,0 +1,126 @@
1
+ Metadata-Version: 2.4
2
+ Name: pondsocket-client
3
+ Version: 0.0.1
4
+ Summary: PondSocket Python client — connect to a PondSocket server from Python.
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: websockets>=13
10
+ Description-Content-Type: text/markdown
11
+
12
+ # pondsocket-client
13
+
14
+ Python client for the [PondSocket](../pondsocket/) server. Connects to PondSocket servers (Python, Go, or TypeScript implementation) over WebSocket.
15
+
16
+ Modeled after the JavaScript client architecture (`@eleven-am/pondsocket-client`) rather than the Go one — the JS client fixes several bugs the Go client has (see [Parity notes](#parity-notes) below).
17
+
18
+ ## Install
19
+
20
+ ```
21
+ pip install pondsocket-client
22
+ ```
23
+
24
+ ## Quick start
25
+
26
+ ```python
27
+ import asyncio
28
+ from pondsocket_client import PondClient
29
+
30
+
31
+ async def main() -> None:
32
+ client = PondClient("ws://localhost:8000/ws", {"token": "secret"})
33
+ await client.connect()
34
+
35
+ channel = client.create_channel("/chat/42", {"username": "alice"})
36
+ channel.on_message_event("message", lambda m: print(m.payload))
37
+ channel.on_join(lambda user: print("joined:", user))
38
+ channel.join()
39
+
40
+ channel.send_message("message", {"text": "hello"})
41
+
42
+ response = await channel.send_for_response("ping", {"text": "abc"})
43
+ print("got pong:", response)
44
+
45
+ await asyncio.sleep(10)
46
+ await client.disconnect()
47
+
48
+
49
+ asyncio.run(main())
50
+ ```
51
+
52
+ ## Architecture
53
+
54
+ ```
55
+ BaseClient (abstract)
56
+ ├── channel registry
57
+ ├── inbound event routing (ACK / UNAUTHORIZED / CONNECTION / per-channel)
58
+ ├── connection state machine: DISCONNECTED → CONNECTING → CONNECTED
59
+ └── exponential reconnect
60
+
61
+ WebSocketClient(BaseClient) (abstract)
62
+ ├── opens via `websockets` library
63
+ └── receive loop pumps inbound to BaseClient
64
+
65
+ PondClient(WebSocketClient) (concrete)
66
+ ├── URL handling (http → ws, https → wss)
67
+ └── appends query-string params
68
+ ```
69
+
70
+ The `Channel` class holds the per-channel state machine (IDLE → JOINING → JOINED → STALLED → CLOSED/DECLINED), a bounded outbound queue (drops oldest on overflow), and a `send_for_response` that correlates inbound replies by `requestId`.
71
+
72
+ ## Connection states
73
+
74
+ Subscribe via `client.on_connection_change(handler)`:
75
+
76
+ | State | When |
77
+ |---|---|
78
+ | `DISCONNECTED` | initial; after disconnect or socket close |
79
+ | `CONNECTING` | `connect()` called; socket handshake in flight |
80
+ | `CONNECTED` | socket open AND server sent the CONNECTION event |
81
+
82
+ ## Channel states
83
+
84
+ Subscribe via `channel.on_channel_state_change(handler)`:
85
+
86
+ | State | Meaning |
87
+ |---|---|
88
+ | `IDLE` | created but `join()` not called |
89
+ | `JOINING` | `join()` called; awaiting ACKNOWLEDGE |
90
+ | `JOINED` | server acknowledged; messages flow |
91
+ | `STALLED` | socket dropped while JOINED; will rejoin on reconnect |
92
+ | `CLOSED` | `leave()` called |
93
+ | `DECLINED` | server sent UNAUTHORIZED; channel is terminal — create a new one |
94
+
95
+ ## Parity notes
96
+
97
+ Compared to the Go client (`go/pondsocket-client/`):
98
+
99
+ | Behavior | Go | Python |
100
+ |---|---|---|
101
+ | `send_for_response` correlation | event name (buggy) | `requestId` (correct) |
102
+ | Reconnect backoff | linear despite comment | true exponential, capped |
103
+ | `UNAUTHORIZED` handling | not implemented | → `DECLINED` state |
104
+ | Connection state | bool (no CONNECTING) | three-state enum |
105
+ | Outbound queue | unbounded | bounded, drops oldest |
106
+ | Join while disconnected | dropped silently | deferred until CONNECTED |
107
+
108
+ The Python client follows the JS client design where the two diverge.
109
+
110
+ ## Public API
111
+
112
+ ```python
113
+ from pondsocket_client import (
114
+ PondClient,
115
+ Channel,
116
+ ConnectionState,
117
+ ClientOptions,
118
+ ResponseTimeoutError,
119
+ )
120
+ ```
121
+
122
+ Also exposed for adapter authors: `BaseClient`, `WebSocketClient`, `Publisher` (type alias).
123
+
124
+ ## License
125
+
126
+ GPL-3.0-or-later.
@@ -0,0 +1,10 @@
1
+ pondsocket_client/__init__.py,sha256=Y32yEtCaKYhHCRtD24drZtR3r6OV9NYX0byvLaMziAg,1212
2
+ pondsocket_client/_base.py,sha256=rqy4cRpOb612sEQD-HzKLYEG6mCdf1DSboprS-0EPAc,5948
3
+ pondsocket_client/_channel.py,sha256=zzubxBYSOz66vQhQLxbXTe2_Fb248jCk1Tf8llhLGtY,11372
4
+ pondsocket_client/_websocket.py,sha256=PZHVdbVOimViOEfFB9vVg9dJ27vrLo4JRpCsvs3vxGs,2627
5
+ pondsocket_client/client.py,sha256=0Ehkn7Ud96_0gWHHvPi79s14II-EVcqenoWX5OFXpkM,1505
6
+ pondsocket_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
7
+ pondsocket_client/types.py,sha256=LI2evOAtpa2hiRpKj321YHvfcfuje7JvgRsHYdLAOng,1078
8
+ pondsocket_client-0.0.1.dist-info/METADATA,sha256=pX-9QlV6-DT-b2FfxXsJecc8oHjMqzDFAJ_UvW5R_ZM,3847
9
+ pondsocket_client-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
10
+ pondsocket_client-0.0.1.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.29.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any