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.
Files changed (38) hide show
  1. {wse_client-2.3.2 → wse_client-2.4.0}/PKG-INFO +19 -6
  2. {wse_client-2.3.2 → wse_client-2.4.0}/README.md +18 -5
  3. {wse_client-2.3.2 → wse_client-2.4.0}/pyproject.toml +1 -1
  4. {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_client.py +9 -2
  5. wse_client-2.4.0/tests/test_connection.py +42 -0
  6. wse_client-2.4.0/tests/test_event_sequencer.py +96 -0
  7. wse_client-2.4.0/wse_client/_version.py +1 -0
  8. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/client.py +110 -34
  9. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/connection.py +16 -5
  10. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/connection_pool.py +1 -1
  11. wse_client-2.4.0/wse_client/event_sequencer.py +133 -0
  12. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/network_monitor.py +1 -1
  13. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/offline_queue.py +1 -1
  14. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/protocol.py +11 -0
  15. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/types.py +11 -1
  16. wse_client-2.3.2/tests/test_event_sequencer.py +0 -97
  17. wse_client-2.3.2/wse_client/_version.py +0 -1
  18. wse_client-2.3.2/wse_client/event_sequencer.py +0 -143
  19. {wse_client-2.3.2 → wse_client-2.4.0}/.gitignore +0 -0
  20. {wse_client-2.3.2 → wse_client-2.4.0}/tests/conftest.py +0 -0
  21. {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_circuit_breaker.py +0 -0
  22. {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_compression.py +0 -0
  23. {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_connection_pool.py +0 -0
  24. {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_network_monitor.py +0 -0
  25. {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_protocol.py +0 -0
  26. {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_rate_limiter.py +0 -0
  27. {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_security.py +0 -0
  28. {wse_client-2.3.2 → wse_client-2.4.0}/tests/test_sync_client.py +0 -0
  29. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/__init__.py +0 -0
  30. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/_logging.py +0 -0
  31. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/circuit_breaker.py +0 -0
  32. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/compression.py +0 -0
  33. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/constants.py +0 -0
  34. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/errors.py +0 -0
  35. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/msgpack_handler.py +0 -0
  36. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/rate_limiter.py +0 -0
  37. {wse_client-2.3.2 → wse_client-2.4.0}/wse_client/security.py +0 -0
  38. {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.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
- ### Event Sequencing
267
+ ### Idempotent delivery & recovery
262
268
 
263
- Automatic duplicate detection via sliding window (10,000-entry dedup cache). Out-of-order event buffering with configurable gap tolerance (up to 100 sequence gap). Missed sequences trigger automatic gap recovery.
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 ratio
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
- ### Event Sequencing
227
+ ### Idempotent delivery & recovery
222
228
 
223
- Automatic duplicate detection via sliding window (10,000-entry dedup cache). Out-of-order event buffering with configurable gap tolerance (up to 100 sequence gap). Missed sequences trigger automatic gap recovery.
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 ratio
247
+ print(stats["network"]["packet_loss"]) # Estimated packet loss (%)
235
248
  ```
236
249
 
237
250
  ### Connection Pool
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "wse-client"
7
- version = "2.3.2"
7
+ version = "2.4.0"
8
8
  description = "Python client for WSE (WebSocket Engine) -- real-time event streaming"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -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
- "max_message_size": 2_000_000,
162
- "rate_limit": 500,
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, sequence, handle system events, then dispatch."""
741
- # Dedup
742
- if event.id and self._sequencer.is_duplicate(event.id):
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
- # Sequence
746
- if event.sequence is not None:
747
- ordered = self._sequencer.process_sequenced_event(event.sequence, event)
748
- if ordered is None:
749
- return # Buffered, not yet deliverable
750
- for evt in ordered:
751
- self._dispatch_event(evt)
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
- self._dispatch_event(event)
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
- max_msg_size = p.get("max_message_size")
877
- if max_msg_size and isinstance(max_msg_size, int):
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
- rate_limit = p.get("rate_limit")
881
- if rate_limit and isinstance(rate_limit, (int, float)):
882
- self._server_rate_limit = int(rate_limit)
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
- epoch = info.get("epoch")
917
- offset = info.get("offset")
918
- if epoch is not None and offset is not None:
919
- self._recovery_state[topic] = (str(epoch), int(offset))
920
- logger.debug(
921
- "Recovery position for %s: epoch=%s offset=%d",
922
- topic,
923
- epoch,
924
- offset,
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
- self._sequencer.reset()
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 == ConnectionState.DISCONNECTED:
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
- # Signal iterator to stop on terminal disconnect.
1125
- # DISCONNECTED only fires for permanent closes (normal close,
1126
- # going_away). Transient errors go through RECONNECTING, not here.
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
- self._heartbeat_task = None
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
- self._recv_task = None
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: Monotonic sequence number for ordering.
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