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.
- pondsocket_client/__init__.py +52 -0
- pondsocket_client/_base.py +181 -0
- pondsocket_client/_channel.py +345 -0
- pondsocket_client/_websocket.py +83 -0
- pondsocket_client/client.py +52 -0
- pondsocket_client/py.typed +0 -0
- pondsocket_client/types.py +35 -0
- pondsocket_client-0.0.1.dist-info/METADATA +126 -0
- pondsocket_client-0.0.1.dist-info/RECORD +10 -0
- pondsocket_client-0.0.1.dist-info/WHEEL +4 -0
|
@@ -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,,
|