wse-client 2.3.2__tar.gz → 2.4.0__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.
- {wse_client-2.3.2 → wse_client-2.4.0}/PKG-INFO +19 -6
- {wse_client-2.3.2 → wse_client-2.4.0}/README.md +18 -5
- {wse_client-2.3.2 → wse_client-2.4.0}/pyproject.toml +1 -1
- {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_client.py +9 -2
- wse_client-2.4.0/tests/test_connection.py +42 -0
- wse_client-2.4.0/tests/test_event_sequencer.py +96 -0
- wse_client-2.4.0/wse_client/_version.py +1 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/client.py +110 -34
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/connection.py +16 -5
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/connection_pool.py +1 -1
- wse_client-2.4.0/wse_client/event_sequencer.py +133 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/network_monitor.py +1 -1
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/offline_queue.py +1 -1
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/protocol.py +11 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/types.py +11 -1
- wse_client-2.3.2/tests/test_event_sequencer.py +0 -97
- wse_client-2.3.2/wse_client/_version.py +0 -1
- wse_client-2.3.2/wse_client/event_sequencer.py +0 -143
- {wse_client-2.3.2 → wse_client-2.4.0}/.gitignore +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/tests/conftest.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_circuit_breaker.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_compression.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_connection_pool.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_network_monitor.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_protocol.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_rate_limiter.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_security.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_sync_client.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/__init__.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/_logging.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/circuit_breaker.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/compression.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/constants.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/errors.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/msgpack_handler.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/rate_limiter.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/security.py +0 -0
- {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/sync_client.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: wse-client
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.4.0
|
|
4
4
|
Summary: Python client for WSE (WebSocket Engine) -- real-time event streaming
|
|
5
5
|
Project-URL: Homepage, https://github.com/silvermpx/wse
|
|
6
6
|
Project-URL: Documentation, https://github.com/silvermpx/wse/tree/main/python-client
|
|
@@ -123,6 +123,9 @@ client.run_forever()
|
|
|
123
123
|
| `reconnect` | ReconnectConfig | default config | Reconnection strategy |
|
|
124
124
|
| `extra_headers` | dict[str, str] | None | Additional HTTP headers for the handshake |
|
|
125
125
|
| `queue_size` | int | 1000 | Max events buffered for the async iterator |
|
|
126
|
+
| `encryption` | bool | False | Enable E2E encryption (ECDH P-256 + AES-GCM-256; requires the `[crypto]` extra) |
|
|
127
|
+
| `endpoints` | list[str] | None | Additional endpoints for the built-in connection pool / failover |
|
|
128
|
+
| `load_balancing` | LoadBalancingStrategy | WEIGHTED_RANDOM | Endpoint selection strategy when `endpoints` is set |
|
|
126
129
|
|
|
127
130
|
The `connect(url, **kwargs)` factory returns an `AsyncWSEClient` configured as an async context manager.
|
|
128
131
|
|
|
@@ -195,6 +198,9 @@ class WSEEvent:
|
|
|
195
198
|
priority: int | None = None # Message priority (see MessagePriority)
|
|
196
199
|
correlation_id: str | None = None # Request correlation ID
|
|
197
200
|
signature: str | None = None # Message signature (if signed)
|
|
201
|
+
topic: str | None = None # Recovery stamp: topic ("tp" field)
|
|
202
|
+
epoch: str | None = None # Recovery stamp: buffer epoch, 8-hex ("e")
|
|
203
|
+
offset: int | None = None # Recovery stamp: per-topic offset ("o")
|
|
198
204
|
```
|
|
199
205
|
|
|
200
206
|
## Features
|
|
@@ -246,7 +252,7 @@ ECDH P-256 key exchange with AES-GCM-256 encryption. Requires the `cryptography`
|
|
|
246
252
|
pip install wse-client[crypto]
|
|
247
253
|
```
|
|
248
254
|
|
|
249
|
-
Key exchange happens automatically during the WebSocket handshake. All messages are encrypted with per-connection session keys derived via HKDF-SHA256. Wire format is the `E:` prefix + 12-byte IV + ciphertext + 16-byte auth tag, compatible with the TS client and Rust server.
|
|
255
|
+
Enable it with `AsyncWSEClient(url, encryption=True)` (it is off by default). Key exchange then happens automatically during the WebSocket handshake. All messages are encrypted with per-connection session keys derived via HKDF-SHA256. Wire format is the `E:` prefix + 12-byte IV + ciphertext + 16-byte auth tag, compatible with the TS client and Rust server.
|
|
250
256
|
|
|
251
257
|
### Circuit Breaker
|
|
252
258
|
|
|
@@ -258,9 +264,16 @@ States: CLOSED (normal) -> OPEN (blocking) -> HALF_OPEN (probing) -> CLOSED (rec
|
|
|
258
264
|
|
|
259
265
|
Client-side token bucket rate limiter (1000 tokens, 100/sec refill). Prevents message flooding and coordinates with the server's rate limit feedback (`rate_limit_warning` at 20% capacity).
|
|
260
266
|
|
|
261
|
-
###
|
|
267
|
+
### Idempotent delivery & recovery
|
|
262
268
|
|
|
263
|
-
|
|
269
|
+
Stamped topic messages carry a per-message `(topic, epoch, offset)` (`tp`/`e`/`o`).
|
|
270
|
+
Dedup and ordering are driven by the per-topic `(epoch, offset)`, which is
|
|
271
|
+
authoritative and survives reconnects: a duplicate (offset already seen on the
|
|
272
|
+
same epoch) is dropped, an in-order message is delivered, and an offset gap
|
|
273
|
+
triggers automatic recovery from the last in-order position. An epoch change
|
|
274
|
+
(server restart) re-baselines the topic. Unstamped messages fall back to a
|
|
275
|
+
sliding-window id dedup (10,000-entry cache). The server's global `seq` is a
|
|
276
|
+
diagnostic only — it is not used for ordering.
|
|
264
277
|
|
|
265
278
|
### Network Quality Monitoring
|
|
266
279
|
|
|
@@ -268,10 +281,10 @@ Real-time network quality assessment based on PING/PONG round-trip measurements:
|
|
|
268
281
|
|
|
269
282
|
```python
|
|
270
283
|
stats = client.get_stats()
|
|
271
|
-
print(stats["network"]["quality"]) # EXCELLENT / GOOD / FAIR / POOR
|
|
284
|
+
print(stats["network"]["quality"]) # EXCELLENT / GOOD / FAIR / POOR (UNKNOWN until enough samples)
|
|
272
285
|
print(stats["network"]["latency_ms"]) # Average round-trip time
|
|
273
286
|
print(stats["network"]["jitter_ms"]) # Latency variance
|
|
274
|
-
print(stats["network"]["packet_loss"]) # Estimated packet loss
|
|
287
|
+
print(stats["network"]["packet_loss"]) # Estimated packet loss (%)
|
|
275
288
|
```
|
|
276
289
|
|
|
277
290
|
### Connection Pool
|
|
@@ -83,6 +83,9 @@ client.run_forever()
|
|
|
83
83
|
| `reconnect` | ReconnectConfig | default config | Reconnection strategy |
|
|
84
84
|
| `extra_headers` | dict[str, str] | None | Additional HTTP headers for the handshake |
|
|
85
85
|
| `queue_size` | int | 1000 | Max events buffered for the async iterator |
|
|
86
|
+
| `encryption` | bool | False | Enable E2E encryption (ECDH P-256 + AES-GCM-256; requires the `[crypto]` extra) |
|
|
87
|
+
| `endpoints` | list[str] | None | Additional endpoints for the built-in connection pool / failover |
|
|
88
|
+
| `load_balancing` | LoadBalancingStrategy | WEIGHTED_RANDOM | Endpoint selection strategy when `endpoints` is set |
|
|
86
89
|
|
|
87
90
|
The `connect(url, **kwargs)` factory returns an `AsyncWSEClient` configured as an async context manager.
|
|
88
91
|
|
|
@@ -155,6 +158,9 @@ class WSEEvent:
|
|
|
155
158
|
priority: int | None = None # Message priority (see MessagePriority)
|
|
156
159
|
correlation_id: str | None = None # Request correlation ID
|
|
157
160
|
signature: str | None = None # Message signature (if signed)
|
|
161
|
+
topic: str | None = None # Recovery stamp: topic ("tp" field)
|
|
162
|
+
epoch: str | None = None # Recovery stamp: buffer epoch, 8-hex ("e")
|
|
163
|
+
offset: int | None = None # Recovery stamp: per-topic offset ("o")
|
|
158
164
|
```
|
|
159
165
|
|
|
160
166
|
## Features
|
|
@@ -206,7 +212,7 @@ ECDH P-256 key exchange with AES-GCM-256 encryption. Requires the `cryptography`
|
|
|
206
212
|
pip install wse-client[crypto]
|
|
207
213
|
```
|
|
208
214
|
|
|
209
|
-
Key exchange happens automatically during the WebSocket handshake. All messages are encrypted with per-connection session keys derived via HKDF-SHA256. Wire format is the `E:` prefix + 12-byte IV + ciphertext + 16-byte auth tag, compatible with the TS client and Rust server.
|
|
215
|
+
Enable it with `AsyncWSEClient(url, encryption=True)` (it is off by default). Key exchange then happens automatically during the WebSocket handshake. All messages are encrypted with per-connection session keys derived via HKDF-SHA256. Wire format is the `E:` prefix + 12-byte IV + ciphertext + 16-byte auth tag, compatible with the TS client and Rust server.
|
|
210
216
|
|
|
211
217
|
### Circuit Breaker
|
|
212
218
|
|
|
@@ -218,9 +224,16 @@ States: CLOSED (normal) -> OPEN (blocking) -> HALF_OPEN (probing) -> CLOSED (rec
|
|
|
218
224
|
|
|
219
225
|
Client-side token bucket rate limiter (1000 tokens, 100/sec refill). Prevents message flooding and coordinates with the server's rate limit feedback (`rate_limit_warning` at 20% capacity).
|
|
220
226
|
|
|
221
|
-
###
|
|
227
|
+
### Idempotent delivery & recovery
|
|
222
228
|
|
|
223
|
-
|
|
229
|
+
Stamped topic messages carry a per-message `(topic, epoch, offset)` (`tp`/`e`/`o`).
|
|
230
|
+
Dedup and ordering are driven by the per-topic `(epoch, offset)`, which is
|
|
231
|
+
authoritative and survives reconnects: a duplicate (offset already seen on the
|
|
232
|
+
same epoch) is dropped, an in-order message is delivered, and an offset gap
|
|
233
|
+
triggers automatic recovery from the last in-order position. An epoch change
|
|
234
|
+
(server restart) re-baselines the topic. Unstamped messages fall back to a
|
|
235
|
+
sliding-window id dedup (10,000-entry cache). The server's global `seq` is a
|
|
236
|
+
diagnostic only — it is not used for ordering.
|
|
224
237
|
|
|
225
238
|
### Network Quality Monitoring
|
|
226
239
|
|
|
@@ -228,10 +241,10 @@ Real-time network quality assessment based on PING/PONG round-trip measurements:
|
|
|
228
241
|
|
|
229
242
|
```python
|
|
230
243
|
stats = client.get_stats()
|
|
231
|
-
print(stats["network"]["quality"]) # EXCELLENT / GOOD / FAIR / POOR
|
|
244
|
+
print(stats["network"]["quality"]) # EXCELLENT / GOOD / FAIR / POOR (UNKNOWN until enough samples)
|
|
232
245
|
print(stats["network"]["latency_ms"]) # Average round-trip time
|
|
233
246
|
print(stats["network"]["jitter_ms"]) # Latency variance
|
|
234
|
-
print(stats["network"]["packet_loss"]) # Estimated packet loss
|
|
247
|
+
print(stats["network"]["packet_loss"]) # Estimated packet loss (%)
|
|
235
248
|
```
|
|
236
249
|
|
|
237
250
|
### Connection Pool
|
|
@@ -153,19 +153,26 @@ class TestSystemHandlers:
|
|
|
153
153
|
client._connection.handle_server_ready.assert_called_once_with("srv-123")
|
|
154
154
|
|
|
155
155
|
def test_server_hello_stores_features(self, client):
|
|
156
|
+
# Limits are nested under "limits" with capacity/refill (the real server
|
|
157
|
+
# wire shape, server.rs build_server_hello), and ping_interval is top-level.
|
|
156
158
|
event = WSEEvent(
|
|
157
159
|
type="server_hello",
|
|
158
160
|
payload={
|
|
159
161
|
"server_version": "2.0",
|
|
160
162
|
"features": {"compression": True, "encryption": True},
|
|
161
|
-
"
|
|
162
|
-
|
|
163
|
+
"limits": {
|
|
164
|
+
"max_message_size": 2_000_000,
|
|
165
|
+
"rate_limit_capacity": 500,
|
|
166
|
+
"rate_limit_refill": 100,
|
|
167
|
+
},
|
|
168
|
+
"ping_interval": 25_000,
|
|
163
169
|
},
|
|
164
170
|
)
|
|
165
171
|
client._handle_server_hello(event)
|
|
166
172
|
assert client._server_features == {"compression": True, "encryption": True}
|
|
167
173
|
assert client._server_max_message_size == 2_000_000
|
|
168
174
|
assert client._server_rate_limit == 500
|
|
175
|
+
assert client._server_ping_interval_ms == 25_000
|
|
169
176
|
|
|
170
177
|
def test_error_handler_logs_auth(self, client):
|
|
171
178
|
event = WSEEvent(
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# =============================================================================
|
|
2
|
+
# WSE Python Client -- Connection regression tests
|
|
3
|
+
# =============================================================================
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
import asyncio
|
|
8
|
+
|
|
9
|
+
import pytest
|
|
10
|
+
|
|
11
|
+
from wse_client.connection import ConnectionManager
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
@pytest.mark.asyncio
|
|
15
|
+
async def test_force_reconnect_from_heartbeat_does_not_zombie() -> None:
|
|
16
|
+
"""_force_reconnect is invoked from inside _heartbeat_loop on idle timeout.
|
|
17
|
+
|
|
18
|
+
Regression: it used to cancel-and-await self._heartbeat_task -- i.e. the
|
|
19
|
+
CURRENT task -- so a CancelledError fired inside _force_reconnect before
|
|
20
|
+
_schedule_reconnect() ran, leaving the socket open and no reconnect
|
|
21
|
+
scheduled (a permanent zombie). The current task must be skipped so the
|
|
22
|
+
reconnect is always scheduled.
|
|
23
|
+
"""
|
|
24
|
+
conn = ConnectionManager("ws://localhost:5006/wse", token="t")
|
|
25
|
+
scheduled: list[bool] = []
|
|
26
|
+
# Stub out the actual reconnect scheduling; we only assert it is reached.
|
|
27
|
+
conn._schedule_reconnect = lambda: scheduled.append(True) # type: ignore[method-assign]
|
|
28
|
+
conn._ws = None
|
|
29
|
+
conn._ws_cm = None
|
|
30
|
+
|
|
31
|
+
async def fake_heartbeat() -> None:
|
|
32
|
+
# Mirrors the real path: the heartbeat task itself calls _force_reconnect.
|
|
33
|
+
await conn._force_reconnect()
|
|
34
|
+
|
|
35
|
+
task = asyncio.ensure_future(fake_heartbeat())
|
|
36
|
+
# The task IS the heartbeat task -- the exact self-cancel scenario.
|
|
37
|
+
conn._heartbeat_task = task
|
|
38
|
+
|
|
39
|
+
# Must complete promptly (no self-cancel hang) and schedule the reconnect.
|
|
40
|
+
await asyncio.wait_for(task, timeout=1.0)
|
|
41
|
+
assert scheduled == [True], "reconnect must be scheduled (no zombie)"
|
|
42
|
+
assert conn._heartbeat_task is None
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
"""Tests for event sequencer."""
|
|
2
|
+
|
|
3
|
+
from wse_client.event_sequencer import EventSequencer
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class TestDuplicateDetection:
|
|
7
|
+
def test_new_event_not_duplicate(self):
|
|
8
|
+
seq = EventSequencer()
|
|
9
|
+
assert seq.is_duplicate("evt-1") is False
|
|
10
|
+
|
|
11
|
+
def test_same_id_is_duplicate(self):
|
|
12
|
+
seq = EventSequencer()
|
|
13
|
+
seq.is_duplicate("evt-1")
|
|
14
|
+
assert seq.is_duplicate("evt-1") is True
|
|
15
|
+
|
|
16
|
+
def test_different_ids_not_duplicate(self):
|
|
17
|
+
seq = EventSequencer()
|
|
18
|
+
seq.is_duplicate("evt-1")
|
|
19
|
+
assert seq.is_duplicate("evt-2") is False
|
|
20
|
+
|
|
21
|
+
def test_window_eviction(self):
|
|
22
|
+
seq = EventSequencer(window_size=3)
|
|
23
|
+
seq.is_duplicate("a")
|
|
24
|
+
seq.is_duplicate("b")
|
|
25
|
+
seq.is_duplicate("c")
|
|
26
|
+
seq.is_duplicate("d") # "a" should be evicted
|
|
27
|
+
# "a" was evicted, so it looks new
|
|
28
|
+
assert seq.is_duplicate("a") is False
|
|
29
|
+
|
|
30
|
+
def test_stats_track_duplicates(self):
|
|
31
|
+
seq = EventSequencer()
|
|
32
|
+
seq.is_duplicate("x")
|
|
33
|
+
seq.is_duplicate("x")
|
|
34
|
+
seq.is_duplicate("x")
|
|
35
|
+
stats = seq.get_stats()
|
|
36
|
+
assert stats["duplicates_detected"] == 2
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
class TestReset:
|
|
40
|
+
def test_reset_clears_state(self):
|
|
41
|
+
seq = EventSequencer()
|
|
42
|
+
seq.is_duplicate("x")
|
|
43
|
+
seq.check_topic_stamp("room", "0000000a", 5)
|
|
44
|
+
seq.reset()
|
|
45
|
+
stats = seq.get_stats()
|
|
46
|
+
assert stats["current_sequence"] == 0
|
|
47
|
+
assert stats["duplicate_window_size"] == 0
|
|
48
|
+
assert stats["topic_positions"] == 0
|
|
49
|
+
assert seq.topic_position("room") is None
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class TestTopicStamp:
|
|
53
|
+
"""Per-topic (epoch, offset) idempotent dedup + gap detection."""
|
|
54
|
+
|
|
55
|
+
def test_new_topic_delivers_and_baselines(self):
|
|
56
|
+
seq = EventSequencer()
|
|
57
|
+
assert seq.check_topic_stamp("room", "0000000a", 5) == "deliver"
|
|
58
|
+
assert seq.topic_position("room") == ("0000000a", 5)
|
|
59
|
+
|
|
60
|
+
def test_in_order_advances(self):
|
|
61
|
+
seq = EventSequencer()
|
|
62
|
+
seq.check_topic_stamp("room", "0000000a", 5)
|
|
63
|
+
assert seq.check_topic_stamp("room", "0000000a", 6) == "deliver"
|
|
64
|
+
assert seq.topic_position("room") == ("0000000a", 6)
|
|
65
|
+
|
|
66
|
+
def test_duplicate_dropped(self):
|
|
67
|
+
seq = EventSequencer()
|
|
68
|
+
seq.check_topic_stamp("room", "0000000a", 5)
|
|
69
|
+
seq.check_topic_stamp("room", "0000000a", 6)
|
|
70
|
+
# Re-seeing an already-delivered offset (e.g. replay overlap) is a dup.
|
|
71
|
+
assert seq.check_topic_stamp("room", "0000000a", 6) == "duplicate"
|
|
72
|
+
assert seq.check_topic_stamp("room", "0000000a", 3) == "duplicate"
|
|
73
|
+
assert seq.topic_position("room") == ("0000000a", 6)
|
|
74
|
+
|
|
75
|
+
def test_gap_does_not_advance(self):
|
|
76
|
+
seq = EventSequencer()
|
|
77
|
+
seq.check_topic_stamp("room", "0000000a", 5)
|
|
78
|
+
# Jump from 5 to 9 -> gap; position must stay at 5 so recovery from 5
|
|
79
|
+
# replays 6..9 in order without them being deduped.
|
|
80
|
+
assert seq.check_topic_stamp("room", "0000000a", 9) == "gap"
|
|
81
|
+
assert seq.topic_position("room") == ("0000000a", 5)
|
|
82
|
+
# The replayed in-order messages then advance contiguously.
|
|
83
|
+
assert seq.check_topic_stamp("room", "0000000a", 6) == "deliver"
|
|
84
|
+
|
|
85
|
+
def test_epoch_change_rebaselines(self):
|
|
86
|
+
seq = EventSequencer()
|
|
87
|
+
seq.check_topic_stamp("room", "0000000a", 100)
|
|
88
|
+
# New epoch (server restart): accept and reset, regardless of offset.
|
|
89
|
+
assert seq.check_topic_stamp("room", "0000000b", 0) == "deliver"
|
|
90
|
+
assert seq.topic_position("room") == ("0000000b", 0)
|
|
91
|
+
|
|
92
|
+
def test_positions_survive_full_reset_only(self):
|
|
93
|
+
seq = EventSequencer()
|
|
94
|
+
seq.check_topic_stamp("room", "0000000a", 5)
|
|
95
|
+
seq.reset()
|
|
96
|
+
assert seq.topic_position("room") is None
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "2.4.0"
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
# =============================================================================
|
|
4
4
|
#
|
|
5
5
|
# Primary public API. Async context manager, async iterator, callbacks.
|
|
6
|
-
# Port of client/hooks/useWSE.ts + client/services/MessageProcessor.ts.
|
|
6
|
+
# Port of ts-client/hooks/useWSE.ts + client/services/MessageProcessor.ts.
|
|
7
7
|
# =============================================================================
|
|
8
8
|
|
|
9
9
|
from __future__ import annotations
|
|
@@ -153,15 +153,19 @@ class AsyncWSEClient:
|
|
|
153
153
|
self._server_features: dict[str, Any] = {}
|
|
154
154
|
self._server_max_message_size: int | None = None
|
|
155
155
|
self._server_rate_limit: int | None = None
|
|
156
|
+
self._server_ping_interval_ms: int | None = None
|
|
156
157
|
|
|
157
158
|
self._background_tasks: set[asyncio.Task[Any]] = set()
|
|
158
159
|
|
|
159
160
|
# Snapshot dedup
|
|
160
161
|
self._snapshot_requested = False
|
|
161
162
|
|
|
162
|
-
# Recovery state: topic -> (epoch, offset)
|
|
163
|
+
# Recovery state: topic -> (epoch, offset) -- last position confirmed
|
|
164
|
+
# delivered in order. Advanced per-message; persists across reconnects.
|
|
163
165
|
self._recovery_state: dict[str, tuple[str, int]] = {}
|
|
164
166
|
self._server_recovery_enabled = False
|
|
167
|
+
# Topics with a recovery request in flight (one at a time, anti-loop).
|
|
168
|
+
self._recovery_in_flight: set[str] = set()
|
|
165
169
|
|
|
166
170
|
# Reconnect config for later use
|
|
167
171
|
self._reconnect_cfg = reconnect
|
|
@@ -737,21 +741,67 @@ class AsyncWSEClient:
|
|
|
737
741
|
self._process_event(event)
|
|
738
742
|
|
|
739
743
|
def _process_event(self, event: WSEEvent) -> None:
|
|
740
|
-
"""Dedup
|
|
741
|
-
|
|
742
|
-
|
|
744
|
+
"""Dedup + gap-detect, handle system events, then dispatch.
|
|
745
|
+
|
|
746
|
+
Stamped topic messages (tp/e/o) are deduped and ordered by per-topic
|
|
747
|
+
(epoch, offset) -- authoritative and reconnect-safe. The server's `seq`
|
|
748
|
+
is a process-global counter, NOT a per-topic order, so it must not drive
|
|
749
|
+
reordering: doing so buffered control messages such as server_ready
|
|
750
|
+
(which carries seq=1 while the client expected 0) and stalled the
|
|
751
|
+
handshake. Unstamped messages fall back to id-based dedup.
|
|
752
|
+
"""
|
|
753
|
+
if event.topic and event.epoch and event.offset is not None:
|
|
754
|
+
verdict = self._sequencer.check_topic_stamp(
|
|
755
|
+
event.topic, event.epoch, event.offset
|
|
756
|
+
)
|
|
757
|
+
if verdict == "duplicate":
|
|
758
|
+
return
|
|
759
|
+
if verdict == "gap":
|
|
760
|
+
# Recover the whole missed range from the last in-order position
|
|
761
|
+
# (still in _recovery_state); drop this out-of-order copy -- the
|
|
762
|
+
# recovery replay re-delivers it in order.
|
|
763
|
+
self._on_recovery_gap(event.topic)
|
|
764
|
+
return
|
|
765
|
+
# In order (or new/changed epoch): advance and deliver.
|
|
766
|
+
self._recovery_state[event.topic] = (event.epoch, event.offset)
|
|
767
|
+
elif event.id and self._sequencer.is_duplicate(event.id):
|
|
743
768
|
return
|
|
744
769
|
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
770
|
+
self._dispatch_event(event)
|
|
771
|
+
|
|
772
|
+
def _on_recovery_gap(self, topic: str) -> None:
|
|
773
|
+
"""A per-topic offset gap was detected -- request recovery from the last
|
|
774
|
+
in-order position, guarded against re-entrant loops (one in-flight
|
|
775
|
+
recovery per topic)."""
|
|
776
|
+
if topic in self._recovery_in_flight:
|
|
752
777
|
return
|
|
778
|
+
self._recovery_in_flight.add(topic)
|
|
779
|
+
self._fire_task(self._recover_topic(topic))
|
|
753
780
|
|
|
754
|
-
|
|
781
|
+
async def _recover_topic(self, topic: str) -> None:
|
|
782
|
+
"""Send a recovery request for an already-subscribed topic (gap fill).
|
|
783
|
+
|
|
784
|
+
subscribe() can't be reused here because it filters already-subscribed
|
|
785
|
+
topics; this sends the recovery subscription_update directly from the
|
|
786
|
+
stored (epoch, offset)."""
|
|
787
|
+
try:
|
|
788
|
+
state = self._recovery_state.get(topic)
|
|
789
|
+
if not self._server_recovery_enabled or state is None:
|
|
790
|
+
return
|
|
791
|
+
payload = {
|
|
792
|
+
"action": "subscribe",
|
|
793
|
+
"topics": [topic],
|
|
794
|
+
"recover": True,
|
|
795
|
+
"recovery": {topic: {"epoch": state[0], "offset": state[1]}},
|
|
796
|
+
}
|
|
797
|
+
msg = self._codec.encode(
|
|
798
|
+
"subscription_update", payload, priority=MessagePriority.HIGH
|
|
799
|
+
)
|
|
800
|
+
await self._connection.send(msg)
|
|
801
|
+
except Exception as exc:
|
|
802
|
+
logger.debug("recovery request for '%s' failed: %s", topic, exc)
|
|
803
|
+
finally:
|
|
804
|
+
self._recovery_in_flight.discard(topic)
|
|
755
805
|
|
|
756
806
|
def _dispatch_event(self, event: WSEEvent) -> None:
|
|
757
807
|
"""Handle system events, invoke callbacks, enqueue for iterator."""
|
|
@@ -873,13 +923,24 @@ class AsyncWSEClient:
|
|
|
873
923
|
p = event.payload
|
|
874
924
|
self._server_features = p.get("features", {})
|
|
875
925
|
|
|
876
|
-
|
|
877
|
-
|
|
926
|
+
# Server-enforced limits are nested under "limits" (max_message_size,
|
|
927
|
+
# rate_limit_capacity, rate_limit_refill). They were read at the payload
|
|
928
|
+
# top level before, so neither value was ever populated.
|
|
929
|
+
limits = p.get("limits", {})
|
|
930
|
+
if not isinstance(limits, dict):
|
|
931
|
+
limits = {}
|
|
932
|
+
|
|
933
|
+
max_msg_size = limits.get("max_message_size")
|
|
934
|
+
if isinstance(max_msg_size, int):
|
|
878
935
|
self._server_max_message_size = max_msg_size
|
|
879
936
|
|
|
880
|
-
|
|
881
|
-
if
|
|
882
|
-
self._server_rate_limit = int(
|
|
937
|
+
rate_cap = limits.get("rate_limit_capacity")
|
|
938
|
+
if isinstance(rate_cap, (int, float)):
|
|
939
|
+
self._server_rate_limit = int(rate_cap)
|
|
940
|
+
|
|
941
|
+
ping_interval = p.get("ping_interval")
|
|
942
|
+
if isinstance(ping_interval, (int, float)) and ping_interval > 0:
|
|
943
|
+
self._server_ping_interval_ms = int(ping_interval)
|
|
883
944
|
|
|
884
945
|
# Complete ECDH key exchange if server confirmed encryption
|
|
885
946
|
if (
|
|
@@ -912,17 +973,28 @@ class AsyncWSEClient:
|
|
|
912
973
|
# Store recovery positions from server response
|
|
913
974
|
recovery = p.get("recovery", {})
|
|
914
975
|
for topic, info in recovery.items():
|
|
915
|
-
if isinstance(info, dict):
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
|
|
925
|
-
|
|
976
|
+
if not isinstance(info, dict):
|
|
977
|
+
continue
|
|
978
|
+
epoch = info.get("epoch")
|
|
979
|
+
offset = info.get("offset")
|
|
980
|
+
if epoch is None or offset is None:
|
|
981
|
+
continue
|
|
982
|
+
self._recovery_state[topic] = (str(epoch), int(offset))
|
|
983
|
+
# When the server could NOT recover (history evicted, or epoch
|
|
984
|
+
# changed on a server restart), resync the dedup position FORWARD to
|
|
985
|
+
# the server's current position. Otherwise the next live message
|
|
986
|
+
# looks like a gap and triggers recovery again -- forever. The
|
|
987
|
+
# unrecoverable gap is accepted. `recovered` defaults True so the
|
|
988
|
+
# behavior is unchanged when the server omits the flag.
|
|
989
|
+
if not info.get("recovered", True):
|
|
990
|
+
self._sequencer.set_topic_position(topic, str(epoch), int(offset))
|
|
991
|
+
logger.debug(
|
|
992
|
+
"Recovery position for %s: epoch=%s offset=%d recovered=%s",
|
|
993
|
+
topic,
|
|
994
|
+
epoch,
|
|
995
|
+
offset,
|
|
996
|
+
info.get("recovered", True),
|
|
997
|
+
)
|
|
926
998
|
|
|
927
999
|
def _handle_error(self, event: WSEEvent) -> None:
|
|
928
1000
|
"""Handle server error with code classification (matches TS error handler)."""
|
|
@@ -1115,15 +1187,19 @@ class AsyncWSEClient:
|
|
|
1115
1187
|
if self._server_ready_event is not None:
|
|
1116
1188
|
self._server_ready_event.clear()
|
|
1117
1189
|
self._snapshot_requested = False
|
|
1118
|
-
|
|
1190
|
+
# Do NOT reset the sequencer on reconnect: per-topic (epoch, offset)
|
|
1191
|
+
# positions and the dedup window must survive so replayed/duplicate
|
|
1192
|
+
# messages are recognised. A full reset only happens on a new session.
|
|
1119
1193
|
elif state == ConnectionState.CONNECTED:
|
|
1120
1194
|
pass # record_ping() is called per-heartbeat via on_ping_sent
|
|
1121
|
-
elif state
|
|
1195
|
+
elif state in (ConnectionState.DISCONNECTED, ConnectionState.ERROR):
|
|
1122
1196
|
if self._server_ready_event is not None:
|
|
1123
1197
|
self._server_ready_event.clear()
|
|
1124
|
-
#
|
|
1125
|
-
#
|
|
1126
|
-
#
|
|
1198
|
+
# Wake the async iterator on ANY terminal state. ERROR (circuit
|
|
1199
|
+
# breaker open / auth failure / rate limited -- all non-retrying)
|
|
1200
|
+
# previously pushed no sentinel, so `async for` consumers blocked
|
|
1201
|
+
# forever once the breaker tripped. DISCONNECTED is the normal/going-
|
|
1202
|
+
# away close. Transient errors go through RECONNECTING, not here.
|
|
1127
1203
|
# Skip if disconnect() already enqueued the sentinel.
|
|
1128
1204
|
if not self._disconnecting and self._event_queue is not None:
|
|
1129
1205
|
try:
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
# =============================================================================
|
|
4
4
|
#
|
|
5
5
|
# WebSocket lifecycle management: connect, auth, heartbeat, reconnect.
|
|
6
|
-
# Port of client/services/ConnectionManager.ts.
|
|
6
|
+
# Port of ts-client/services/ConnectionManager.ts.
|
|
7
7
|
# =============================================================================
|
|
8
8
|
|
|
9
9
|
from __future__ import annotations
|
|
@@ -681,15 +681,26 @@ class ConnectionManager:
|
|
|
681
681
|
|
|
682
682
|
# Cancel tasks FIRST (before closing socket) to avoid spurious
|
|
683
683
|
# exceptions in _recv_loop triggering unintended reconnect paths.
|
|
684
|
+
#
|
|
685
|
+
# CRITICAL: never cancel-and-await the CURRENT task. _force_reconnect is
|
|
686
|
+
# called from inside _heartbeat_loop on idle timeout; cancelling
|
|
687
|
+
# self._heartbeat_task there cancels THIS coroutine, and the awaited
|
|
688
|
+
# gather then raises CancelledError into _force_reconnect before
|
|
689
|
+
# _schedule_reconnect() runs -- the socket is never closed and the
|
|
690
|
+
# reconnect is never scheduled, leaving a permanent zombie. Skip the
|
|
691
|
+
# current task (it returns on its own right after this call) and only
|
|
692
|
+
# cancel+await the others.
|
|
693
|
+
current = asyncio.current_task()
|
|
684
694
|
tasks_to_await: list[asyncio.Task[None]] = []
|
|
685
|
-
if self._heartbeat_task:
|
|
695
|
+
if self._heartbeat_task is not None and self._heartbeat_task is not current:
|
|
686
696
|
self._heartbeat_task.cancel()
|
|
687
697
|
tasks_to_await.append(self._heartbeat_task)
|
|
688
|
-
|
|
689
|
-
if self._recv_task:
|
|
698
|
+
if self._recv_task is not None and self._recv_task is not current:
|
|
690
699
|
self._recv_task.cancel()
|
|
691
700
|
tasks_to_await.append(self._recv_task)
|
|
692
|
-
|
|
701
|
+
# Drop references regardless; the current task exits after this returns.
|
|
702
|
+
self._heartbeat_task = None
|
|
703
|
+
self._recv_task = None
|
|
693
704
|
if tasks_to_await:
|
|
694
705
|
await asyncio.gather(*tasks_to_await, return_exceptions=True)
|
|
695
706
|
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
# =============================================================================
|
|
4
4
|
#
|
|
5
5
|
# Multi-endpoint management with health scoring and load balancing.
|
|
6
|
-
# Port of client/services/ConnectionPool.ts.
|
|
6
|
+
# Port of ts-client/services/ConnectionPool.ts.
|
|
7
7
|
# =============================================================================
|
|
8
8
|
|
|
9
9
|
from __future__ import annotations
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# =============================================================================
|
|
2
|
+
# WSE Python Client -- Event Sequencer
|
|
3
|
+
# =============================================================================
|
|
4
|
+
#
|
|
5
|
+
# Idempotent delivery: id dedup + per-topic (epoch, offset) dedup/gap detection.
|
|
6
|
+
# Port of ts-client/services/EventSequencer.ts.
|
|
7
|
+
# =============================================================================
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import time
|
|
12
|
+
|
|
13
|
+
from .constants import DUPLICATE_MAX_AGE, SEQUENCE_WINDOW_SIZE
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class EventSequencer:
|
|
17
|
+
"""Idempotent delivery: id dedup + per-topic (epoch, offset) dedup/gap detection.
|
|
18
|
+
|
|
19
|
+
Tracks seen message IDs in a sliding window (for unstamped messages) and the
|
|
20
|
+
last-seen (epoch, offset) per topic (the authoritative dedup/ordering for
|
|
21
|
+
stamped messages). Also owns the client's outbound send sequence counter.
|
|
22
|
+
|
|
23
|
+
Args:
|
|
24
|
+
window_size: Dedup window size (default 10 000).
|
|
25
|
+
max_age: Seconds before expiring old entries (default 300).
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
def __init__(
|
|
29
|
+
self,
|
|
30
|
+
window_size: int = SEQUENCE_WINDOW_SIZE,
|
|
31
|
+
max_age: float = DUPLICATE_MAX_AGE,
|
|
32
|
+
) -> None:
|
|
33
|
+
self._window_size = window_size
|
|
34
|
+
self._max_age = max_age
|
|
35
|
+
|
|
36
|
+
self._seen_ids: dict[str, float] = {}
|
|
37
|
+
self._sequence = 0
|
|
38
|
+
self._cleanup_counter = 0
|
|
39
|
+
self._duplicates_detected = 0
|
|
40
|
+
# Per-topic last-seen recovery position: topic -> (epoch, offset). The
|
|
41
|
+
# AUTHORITATIVE dedup/ordering for stamped messages; survives reconnects
|
|
42
|
+
# within an epoch (not cleared on reconnect). Replaces the old seq-based
|
|
43
|
+
# reorder buffer, which the server's global seq made unsound.
|
|
44
|
+
self._topic_positions: dict[str, tuple[str, int]] = {}
|
|
45
|
+
|
|
46
|
+
def get_next_sequence(self) -> int:
|
|
47
|
+
self._sequence += 1
|
|
48
|
+
return self._sequence
|
|
49
|
+
|
|
50
|
+
@property
|
|
51
|
+
def current_sequence(self) -> int:
|
|
52
|
+
return self._sequence
|
|
53
|
+
|
|
54
|
+
def is_duplicate(self, event_id: str) -> bool:
|
|
55
|
+
"""Check if event ID was already seen. Registers it if new."""
|
|
56
|
+
self._cleanup_counter += 1
|
|
57
|
+
if self._cleanup_counter >= 100:
|
|
58
|
+
self._cleanup_old_entries()
|
|
59
|
+
self._cleanup_counter = 0
|
|
60
|
+
|
|
61
|
+
if event_id in self._seen_ids:
|
|
62
|
+
self._duplicates_detected += 1
|
|
63
|
+
return True
|
|
64
|
+
|
|
65
|
+
self._seen_ids[event_id] = time.monotonic()
|
|
66
|
+
|
|
67
|
+
# Evict oldest if window full
|
|
68
|
+
if len(self._seen_ids) > self._window_size:
|
|
69
|
+
oldest_key = min(self._seen_ids, key=self._seen_ids.get) # type: ignore[arg-type]
|
|
70
|
+
del self._seen_ids[oldest_key]
|
|
71
|
+
|
|
72
|
+
return False
|
|
73
|
+
|
|
74
|
+
def check_topic_stamp(self, topic: str, epoch: str, offset: int) -> str:
|
|
75
|
+
"""Idempotent dedup + gap detection by per-topic ``(epoch, offset)``.
|
|
76
|
+
|
|
77
|
+
Returns one of:
|
|
78
|
+
``"duplicate"`` -- already delivered (offset <= last seen on the same
|
|
79
|
+
epoch); the caller should drop it. This is what makes replay /
|
|
80
|
+
reconnect overlap safe independently of the id window.
|
|
81
|
+
``"gap"`` -- the offset jumped ahead of the expected next; the caller
|
|
82
|
+
should still deliver it but trigger recovery to fill the hole.
|
|
83
|
+
``"deliver"`` -- the next in order, or the first message on a new or
|
|
84
|
+
changed epoch (server restart -- old offsets are meaningless).
|
|
85
|
+
"""
|
|
86
|
+
prev = self._topic_positions.get(topic)
|
|
87
|
+
if prev is None or prev[0] != epoch:
|
|
88
|
+
# New topic, or epoch change (server restart): accept and (re)baseline.
|
|
89
|
+
self._topic_positions[topic] = (epoch, offset)
|
|
90
|
+
return "deliver"
|
|
91
|
+
last = prev[1]
|
|
92
|
+
if offset <= last:
|
|
93
|
+
return "duplicate"
|
|
94
|
+
if offset == last + 1:
|
|
95
|
+
self._topic_positions[topic] = (epoch, offset)
|
|
96
|
+
return "deliver"
|
|
97
|
+
# Gap: do NOT advance. The caller recovers from `last`, which replays the
|
|
98
|
+
# whole missed range (last+1 .. head) in order; advancing here would make
|
|
99
|
+
# those replayed messages look like duplicates and they'd be dropped.
|
|
100
|
+
return "gap"
|
|
101
|
+
|
|
102
|
+
def topic_position(self, topic: str) -> tuple[str, int] | None:
|
|
103
|
+
"""Last-seen ``(epoch, offset)`` for a topic, for recovery requests."""
|
|
104
|
+
return self._topic_positions.get(topic)
|
|
105
|
+
|
|
106
|
+
def set_topic_position(self, topic: str, epoch: str, offset: int) -> None:
|
|
107
|
+
"""Set a topic's position (e.g. from a subscription_update reply)."""
|
|
108
|
+
self._topic_positions[topic] = (epoch, offset)
|
|
109
|
+
|
|
110
|
+
def _cleanup_old_entries(self) -> None:
|
|
111
|
+
now = time.monotonic()
|
|
112
|
+
cutoff = now - self._max_age
|
|
113
|
+
expired = [k for k, v in self._seen_ids.items() if v < cutoff]
|
|
114
|
+
for k in expired:
|
|
115
|
+
del self._seen_ids[k]
|
|
116
|
+
|
|
117
|
+
def get_stats(self) -> dict:
|
|
118
|
+
return {
|
|
119
|
+
"current_sequence": self._sequence,
|
|
120
|
+
"duplicate_window_size": len(self._seen_ids),
|
|
121
|
+
"topic_positions": len(self._topic_positions),
|
|
122
|
+
"duplicates_detected": self._duplicates_detected,
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
def reset(self) -> None:
|
|
126
|
+
"""Full reset for a NEW session (e.g. token change) -- clears per-topic
|
|
127
|
+
positions too. NOT to be called on a transient reconnect, which must keep
|
|
128
|
+
positions so (epoch, offset) dedup spans the reconnect."""
|
|
129
|
+
self._seen_ids.clear()
|
|
130
|
+
self._sequence = 0
|
|
131
|
+
self._duplicates_detected = 0
|
|
132
|
+
self._cleanup_counter = 0
|
|
133
|
+
self._topic_positions.clear()
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
# =============================================================================
|
|
4
4
|
#
|
|
5
5
|
# Latency / jitter / packet loss analysis -> connection quality.
|
|
6
|
-
# Port of client/services/NetworkMonitor.ts.
|
|
6
|
+
# Port of ts-client/services/NetworkMonitor.ts.
|
|
7
7
|
# =============================================================================
|
|
8
8
|
|
|
9
9
|
from __future__ import annotations
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
# =============================================================================
|
|
4
4
|
#
|
|
5
5
|
# Buffers outgoing messages when the connection is down and flushes them
|
|
6
|
-
# (in priority order) on reconnect. Port of client/services/OfflineQueue.ts.
|
|
6
|
+
# (in priority order) on reconnect. Port of ts-client/services/OfflineQueue.ts.
|
|
7
7
|
#
|
|
8
8
|
# In-memory implementation - Python processes don't need persistence across
|
|
9
9
|
# restarts the way browser tabs need IndexedDB.
|
|
@@ -293,6 +293,14 @@ class MessageCodec:
|
|
|
293
293
|
# Category: prefer wire prefix, fall back to "c" field in JSON
|
|
294
294
|
cat = category.value if category else parsed.get("c")
|
|
295
295
|
|
|
296
|
+
# Recovery stamp (present on stamped topic publications): topic / epoch /
|
|
297
|
+
# offset, accepted under the short wire keys with long-name fallbacks.
|
|
298
|
+
topic = parsed.get("tp") or parsed.get("topic")
|
|
299
|
+
epoch = parsed.get("e") or parsed.get("epoch")
|
|
300
|
+
offset = parsed.get("o")
|
|
301
|
+
if offset is None:
|
|
302
|
+
offset = parsed.get("offset")
|
|
303
|
+
|
|
296
304
|
return WSEEvent(
|
|
297
305
|
type=t,
|
|
298
306
|
payload=p if isinstance(p, dict) else {"data": p},
|
|
@@ -304,4 +312,7 @@ class MessageCodec:
|
|
|
304
312
|
priority=parsed.get("pri"),
|
|
305
313
|
correlation_id=parsed.get("cid"),
|
|
306
314
|
signature=parsed.get("sig"),
|
|
315
|
+
topic=topic if isinstance(topic, str) else None,
|
|
316
|
+
epoch=str(epoch) if epoch is not None else None,
|
|
317
|
+
offset=int(offset) if isinstance(offset, int) else None,
|
|
307
318
|
)
|
|
@@ -100,13 +100,20 @@ class WSEEvent:
|
|
|
100
100
|
type: Event type string, e.g. ``"notifications"``, ``"price_update"``.
|
|
101
101
|
payload: Event data as a dict.
|
|
102
102
|
id: Unique message UUID for deduplication.
|
|
103
|
-
sequence:
|
|
103
|
+
sequence: Server global sequence number (diagnostic only; ordering
|
|
104
|
+
and dedup are per-topic via epoch/offset).
|
|
104
105
|
timestamp: ISO-8601 timestamp from the server.
|
|
105
106
|
version: Wire protocol version (default 1).
|
|
106
107
|
category: ``"WSE"`` (system), ``"S"`` (snapshot), ``"U"`` (update).
|
|
107
108
|
priority: Numeric priority (see :class:`MessagePriority`).
|
|
108
109
|
correlation_id: Links a request to its response.
|
|
109
110
|
signature: HMAC-SHA256 hex signature when message signing is on.
|
|
111
|
+
topic: Recovery stamp -- the topic this message was published to (``tp``).
|
|
112
|
+
epoch: Recovery stamp -- the topic buffer epoch as an 8-hex string (``e``).
|
|
113
|
+
offset: Recovery stamp -- the per-topic monotonic offset (``o``). Together
|
|
114
|
+
with ``epoch`` this drives idempotent dedup, gap detection, and
|
|
115
|
+
recovery from the last-seen position. Present only on stamped topic
|
|
116
|
+
publications (absent on control/system messages).
|
|
110
117
|
"""
|
|
111
118
|
|
|
112
119
|
type: str
|
|
@@ -119,6 +126,9 @@ class WSEEvent:
|
|
|
119
126
|
priority: int | None = None
|
|
120
127
|
correlation_id: str | None = None
|
|
121
128
|
signature: str | None = None
|
|
129
|
+
topic: str | None = None
|
|
130
|
+
epoch: str | None = None
|
|
131
|
+
offset: int | None = None
|
|
122
132
|
|
|
123
133
|
|
|
124
134
|
@dataclass
|
|
@@ -1,97 +0,0 @@
|
|
|
1
|
-
"""Tests for event sequencer."""
|
|
2
|
-
|
|
3
|
-
from wse_client.event_sequencer import EventSequencer
|
|
4
|
-
from wse_client.types import WSEEvent
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
def _evt(type: str = "test", seq: int | None = None, id: str | None = None) -> WSEEvent:
|
|
8
|
-
return WSEEvent(type=type, payload={}, id=id, sequence=seq)
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
class TestDuplicateDetection:
|
|
12
|
-
def test_new_event_not_duplicate(self):
|
|
13
|
-
seq = EventSequencer()
|
|
14
|
-
assert seq.is_duplicate("evt-1") is False
|
|
15
|
-
|
|
16
|
-
def test_same_id_is_duplicate(self):
|
|
17
|
-
seq = EventSequencer()
|
|
18
|
-
seq.is_duplicate("evt-1")
|
|
19
|
-
assert seq.is_duplicate("evt-1") is True
|
|
20
|
-
|
|
21
|
-
def test_different_ids_not_duplicate(self):
|
|
22
|
-
seq = EventSequencer()
|
|
23
|
-
seq.is_duplicate("evt-1")
|
|
24
|
-
assert seq.is_duplicate("evt-2") is False
|
|
25
|
-
|
|
26
|
-
def test_window_eviction(self):
|
|
27
|
-
seq = EventSequencer(window_size=3)
|
|
28
|
-
seq.is_duplicate("a")
|
|
29
|
-
seq.is_duplicate("b")
|
|
30
|
-
seq.is_duplicate("c")
|
|
31
|
-
seq.is_duplicate("d") # "a" should be evicted
|
|
32
|
-
# "a" was evicted, so it looks new
|
|
33
|
-
assert seq.is_duplicate("a") is False
|
|
34
|
-
|
|
35
|
-
def test_stats_track_duplicates(self):
|
|
36
|
-
seq = EventSequencer()
|
|
37
|
-
seq.is_duplicate("x")
|
|
38
|
-
seq.is_duplicate("x")
|
|
39
|
-
seq.is_duplicate("x")
|
|
40
|
-
stats = seq.get_stats()
|
|
41
|
-
assert stats["duplicates_detected"] == 2
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
class TestSequenceOrdering:
|
|
45
|
-
def test_in_order_delivery(self):
|
|
46
|
-
seq = EventSequencer()
|
|
47
|
-
e1 = _evt(seq=0)
|
|
48
|
-
result = seq.process_sequenced_event(0, e1)
|
|
49
|
-
assert result is not None
|
|
50
|
-
assert len(result) == 1
|
|
51
|
-
assert result[0] is e1
|
|
52
|
-
|
|
53
|
-
def test_out_of_order_buffered(self):
|
|
54
|
-
seq = EventSequencer()
|
|
55
|
-
e2 = _evt("second", seq=1)
|
|
56
|
-
# Seq 1 arrives before seq 0
|
|
57
|
-
result = seq.process_sequenced_event(1, e2)
|
|
58
|
-
assert result is None # Buffered
|
|
59
|
-
|
|
60
|
-
def test_buffered_events_delivered_in_order(self):
|
|
61
|
-
seq = EventSequencer()
|
|
62
|
-
e1 = _evt("second", seq=1)
|
|
63
|
-
e0 = _evt("first", seq=0)
|
|
64
|
-
|
|
65
|
-
seq.process_sequenced_event(1, e1) # Buffered
|
|
66
|
-
result = seq.process_sequenced_event(0, e0)
|
|
67
|
-
|
|
68
|
-
assert result is not None
|
|
69
|
-
assert len(result) == 2
|
|
70
|
-
assert result[0].type == "first"
|
|
71
|
-
assert result[1].type == "second"
|
|
72
|
-
|
|
73
|
-
def test_large_gap_resets(self):
|
|
74
|
-
seq = EventSequencer(max_out_of_order=5)
|
|
75
|
-
e100 = _evt(seq=100)
|
|
76
|
-
result = seq.process_sequenced_event(100, e100)
|
|
77
|
-
# Gap > 5, so it resets and delivers
|
|
78
|
-
assert result is not None
|
|
79
|
-
assert len(result) == 1
|
|
80
|
-
|
|
81
|
-
def test_old_sequence_skipped(self):
|
|
82
|
-
seq = EventSequencer()
|
|
83
|
-
seq.process_sequenced_event(0, _evt(seq=0))
|
|
84
|
-
seq.process_sequenced_event(1, _evt(seq=1))
|
|
85
|
-
# Seq 0 again (already delivered)
|
|
86
|
-
result = seq.process_sequenced_event(0, _evt(seq=0))
|
|
87
|
-
assert result is None
|
|
88
|
-
|
|
89
|
-
def test_reset(self):
|
|
90
|
-
seq = EventSequencer()
|
|
91
|
-
seq.is_duplicate("x")
|
|
92
|
-
seq.process_sequenced_event(0, _evt(seq=0))
|
|
93
|
-
seq.reset()
|
|
94
|
-
stats = seq.get_stats()
|
|
95
|
-
assert stats["current_sequence"] == 0
|
|
96
|
-
assert stats["expected_sequence"] == 0
|
|
97
|
-
assert stats["duplicate_window_size"] == 0
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
__version__ = "2.3.2"
|
|
@@ -1,143 +0,0 @@
|
|
|
1
|
-
# =============================================================================
|
|
2
|
-
# WSE Python Client -- Event Sequencer
|
|
3
|
-
# =============================================================================
|
|
4
|
-
#
|
|
5
|
-
# Duplicate detection and out-of-order event buffering.
|
|
6
|
-
# Port of client/services/EventSequencer.ts.
|
|
7
|
-
# =============================================================================
|
|
8
|
-
|
|
9
|
-
from __future__ import annotations
|
|
10
|
-
|
|
11
|
-
import time
|
|
12
|
-
|
|
13
|
-
from .constants import DUPLICATE_MAX_AGE, MAX_OUT_OF_ORDER, SEQUENCE_WINDOW_SIZE
|
|
14
|
-
from .types import WSEEvent
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
class EventSequencer:
|
|
18
|
-
"""Duplicate detection and out-of-order event reordering.
|
|
19
|
-
|
|
20
|
-
Tracks seen message IDs in a sliding window and buffers events
|
|
21
|
-
that arrive ahead of their expected sequence number.
|
|
22
|
-
|
|
23
|
-
Args:
|
|
24
|
-
window_size: Dedup window size (default 10 000).
|
|
25
|
-
max_out_of_order: Max sequence gap before resetting (default 100).
|
|
26
|
-
max_age: Seconds before expiring old entries (default 300).
|
|
27
|
-
"""
|
|
28
|
-
|
|
29
|
-
def __init__(
|
|
30
|
-
self,
|
|
31
|
-
window_size: int = SEQUENCE_WINDOW_SIZE,
|
|
32
|
-
max_out_of_order: int = MAX_OUT_OF_ORDER,
|
|
33
|
-
max_age: float = DUPLICATE_MAX_AGE,
|
|
34
|
-
) -> None:
|
|
35
|
-
self._window_size = window_size
|
|
36
|
-
self._max_out_of_order = max_out_of_order
|
|
37
|
-
self._max_age = max_age
|
|
38
|
-
|
|
39
|
-
self._seen_ids: dict[str, float] = {}
|
|
40
|
-
self._expected_sequence = 0
|
|
41
|
-
self._out_of_order_buffer: dict[int, tuple[WSEEvent, float]] = {}
|
|
42
|
-
self._sequence = 0
|
|
43
|
-
self._cleanup_counter = 0
|
|
44
|
-
self._duplicates_detected = 0
|
|
45
|
-
|
|
46
|
-
def get_next_sequence(self) -> int:
|
|
47
|
-
self._sequence += 1
|
|
48
|
-
return self._sequence
|
|
49
|
-
|
|
50
|
-
@property
|
|
51
|
-
def current_sequence(self) -> int:
|
|
52
|
-
return self._sequence
|
|
53
|
-
|
|
54
|
-
def is_duplicate(self, event_id: str) -> bool:
|
|
55
|
-
"""Check if event ID was already seen. Registers it if new."""
|
|
56
|
-
self._cleanup_counter += 1
|
|
57
|
-
if self._cleanup_counter >= 100:
|
|
58
|
-
self._cleanup_old_entries()
|
|
59
|
-
self._cleanup_counter = 0
|
|
60
|
-
|
|
61
|
-
if event_id in self._seen_ids:
|
|
62
|
-
self._duplicates_detected += 1
|
|
63
|
-
return True
|
|
64
|
-
|
|
65
|
-
self._seen_ids[event_id] = time.monotonic()
|
|
66
|
-
|
|
67
|
-
# Evict oldest if window full
|
|
68
|
-
if len(self._seen_ids) > self._window_size:
|
|
69
|
-
oldest_key = min(self._seen_ids, key=self._seen_ids.get) # type: ignore[arg-type]
|
|
70
|
-
del self._seen_ids[oldest_key]
|
|
71
|
-
|
|
72
|
-
return False
|
|
73
|
-
|
|
74
|
-
def record_sequence(self, seq: int) -> None:
|
|
75
|
-
if seq >= self._expected_sequence:
|
|
76
|
-
self._expected_sequence = seq + 1
|
|
77
|
-
|
|
78
|
-
def process_sequenced_event(
|
|
79
|
-
self, seq: int, event: WSEEvent
|
|
80
|
-
) -> list[WSEEvent] | None:
|
|
81
|
-
"""Process event with sequence number. Returns ordered events or None."""
|
|
82
|
-
# If sequence matches expected, deliver it plus any buffered followers
|
|
83
|
-
if seq == self._expected_sequence:
|
|
84
|
-
result = [event]
|
|
85
|
-
self._expected_sequence = seq + 1
|
|
86
|
-
|
|
87
|
-
# Drain consecutive buffered events
|
|
88
|
-
while self._expected_sequence in self._out_of_order_buffer:
|
|
89
|
-
buffered, _ts = self._out_of_order_buffer.pop(self._expected_sequence)
|
|
90
|
-
result.append(buffered)
|
|
91
|
-
self._expected_sequence += 1
|
|
92
|
-
|
|
93
|
-
return result
|
|
94
|
-
|
|
95
|
-
# Future sequence: buffer if gap is within limit
|
|
96
|
-
gap = seq - self._expected_sequence
|
|
97
|
-
if 0 < gap <= self._max_out_of_order:
|
|
98
|
-
self._out_of_order_buffer[seq] = (event, time.monotonic())
|
|
99
|
-
self._cleanup_stale_buffer()
|
|
100
|
-
return None
|
|
101
|
-
|
|
102
|
-
# Gap too large: reset and deliver
|
|
103
|
-
if gap > self._max_out_of_order:
|
|
104
|
-
self._out_of_order_buffer.clear()
|
|
105
|
-
self._expected_sequence = seq + 1
|
|
106
|
-
return [event]
|
|
107
|
-
|
|
108
|
-
# Old sequence (already delivered): skip
|
|
109
|
-
return None
|
|
110
|
-
|
|
111
|
-
def _cleanup_old_entries(self) -> None:
|
|
112
|
-
now = time.monotonic()
|
|
113
|
-
cutoff = now - self._max_age
|
|
114
|
-
expired = [k for k, v in self._seen_ids.items() if v < cutoff]
|
|
115
|
-
for k in expired:
|
|
116
|
-
del self._seen_ids[k]
|
|
117
|
-
|
|
118
|
-
def _cleanup_stale_buffer(self) -> None:
|
|
119
|
-
"""Remove out-of-order buffered events older than max_age."""
|
|
120
|
-
now = time.monotonic()
|
|
121
|
-
cutoff = now - self._max_age
|
|
122
|
-
expired = [
|
|
123
|
-
seq for seq, (_, ts) in self._out_of_order_buffer.items() if ts < cutoff
|
|
124
|
-
]
|
|
125
|
-
for seq in expired:
|
|
126
|
-
del self._out_of_order_buffer[seq]
|
|
127
|
-
|
|
128
|
-
def get_stats(self) -> dict:
|
|
129
|
-
return {
|
|
130
|
-
"current_sequence": self._sequence,
|
|
131
|
-
"expected_sequence": self._expected_sequence,
|
|
132
|
-
"duplicate_window_size": len(self._seen_ids),
|
|
133
|
-
"out_of_order_buffer_size": len(self._out_of_order_buffer),
|
|
134
|
-
"duplicates_detected": self._duplicates_detected,
|
|
135
|
-
}
|
|
136
|
-
|
|
137
|
-
def reset(self) -> None:
|
|
138
|
-
self._seen_ids.clear()
|
|
139
|
-
self._out_of_order_buffer.clear()
|
|
140
|
-
self._expected_sequence = 0
|
|
141
|
-
self._sequence = 0
|
|
142
|
-
self._duplicates_detected = 0
|
|
143
|
-
self._cleanup_counter = 0
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|