offline-protocol-sdk 0.28.0__py3-none-win_amd64.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. offline_protocol_sdk/__init__.py +22 -0
  2. offline_protocol_sdk/_callback_reentrancy.py +64 -0
  3. offline_protocol_sdk/address_declaration.py +207 -0
  4. offline_protocol_sdk/ble_manager.py +595 -0
  5. offline_protocol_sdk/ble_peripheral.py +673 -0
  6. offline_protocol_sdk/dnssd_bridge.py +614 -0
  7. offline_protocol_sdk/gateway_attach_policy.py +437 -0
  8. offline_protocol_sdk/gateway_manager.py +1217 -0
  9. offline_protocol_sdk/gateway_verdict_tracker.py +97 -0
  10. offline_protocol_sdk/internet_manager.py +1444 -0
  11. offline_protocol_sdk/legacy_store_adoption.py +184 -0
  12. offline_protocol_sdk/local_api/__init__.py +34 -0
  13. offline_protocol_sdk/local_api/authz.py +180 -0
  14. offline_protocol_sdk/local_api/cli.py +171 -0
  15. offline_protocol_sdk/local_api/codec.py +210 -0
  16. offline_protocol_sdk/local_api/dispatch.py +537 -0
  17. offline_protocol_sdk/local_api/mux.py +239 -0
  18. offline_protocol_sdk/local_api/server.py +546 -0
  19. offline_protocol_sdk/local_api/session.py +86 -0
  20. offline_protocol_sdk/local_api/table.py +849 -0
  21. offline_protocol_sdk/offline_protocol.py +13508 -0
  22. offline_protocol_sdk/peer_stream_manager.py +1303 -0
  23. offline_protocol_sdk/presence_watch_policy.py +102 -0
  24. offline_protocol_sdk/protocol_manager.py +1108 -0
  25. offline_protocol_sdk/relay_answer_prefixes.py +61 -0
  26. offline_protocol_sdk/secure_storage.py +551 -0
  27. offline_protocol_sdk/services.py +195 -0
  28. offline_protocol_sdk/state_storage.py +452 -0
  29. offline_protocol_sdk/storage_namespace.py +33 -0
  30. offline_protocol_sdk/transport_manager.py +138 -0
  31. offline_protocol_sdk/uniffi.dll +0 -0
  32. offline_protocol_sdk-0.28.0.dist-info/METADATA +519 -0
  33. offline_protocol_sdk-0.28.0.dist-info/RECORD +40 -0
  34. offline_protocol_sdk-0.28.0.dist-info/WHEEL +5 -0
  35. offline_protocol_sdk-0.28.0.dist-info/entry_points.txt +2 -0
  36. offline_protocol_sdk-0.28.0.dist-info/licenses/EXPORT.md +68 -0
  37. offline_protocol_sdk-0.28.0.dist-info/licenses/LICENSE +661 -0
  38. offline_protocol_sdk-0.28.0.dist-info/licenses/LICENSE-COMMERCIAL.md +89 -0
  39. offline_protocol_sdk-0.28.0.dist-info/licenses/THIRD-PARTY-NOTICES.md +6645 -0
  40. offline_protocol_sdk-0.28.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,1444 @@
1
+ """Internet transport manager using WebSocket.
2
+
3
+ Mirrors ``InternetManager.swift`` / ``InternetManager.kt`` — connects to a
4
+ relay server for internet-based message routing and drives the UniFFI
5
+ ``OfflineProtocol`` internet transport methods.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import asyncio
11
+ import base64
12
+ import json
13
+ import logging
14
+ import time
15
+ import uuid
16
+ from collections import deque
17
+ from typing import Any, Coroutine
18
+
19
+ import websockets
20
+ from websockets.asyncio.client import ClientConnection
21
+
22
+ from . import address_declaration
23
+ from .relay_answer_prefixes import attributable_actor
24
+ from .transport_manager import TransportError, TransportManager, TransportState
25
+
26
+ logger = logging.getLogger(__name__)
27
+
28
+ # -- Constants (matching iOS InternetManager.swift) ---------------------------
29
+
30
+ _MESSAGE_POLL_INTERVAL = 0.1 # idle send poll, 100 ms
31
+ _RECONNECT_INITIAL_DELAY = 1.0 # seconds
32
+ _RECONNECT_MAX_DELAY = 30.0
33
+ _RECONNECT_BACKOFF_MULTIPLIER = 2.0
34
+ _PING_INTERVAL = 10.0 # seconds
35
+ _CONNECTION_TIMEOUT = 10.0
36
+ _MAX_CONSECUTIVE_FAILURES = 2
37
+ _MAX_CONCURRENT_SENDS = 50
38
+
39
+ # In-flight tracker tuning (mirrors iOS/Android RecipientInFlightTracker).
40
+ _RIFT_TTL_MS = 60_000
41
+ _RIFT_MAX_PER_RECIPIENT = 32
42
+
43
+ # -- Constants (Python only) --------------------------------------------------
44
+ # The send loop here is activity-adaptive (see _poll_outgoing_loop); the
45
+ # Swift/Kotlin managers still poll at the fixed _MESSAGE_POLL_INTERVAL.
46
+
47
+ # Floor of the send loop's backoff ramp: the wait after activity, doubling on
48
+ # every quiet pass until it reaches _MESSAGE_POLL_INTERVAL.
49
+ _SEND_MIN_POLL_INTERVAL = 0.002 # 2 ms
50
+ # The in-flight sweep in _poll_and_send_messages was sized for the old fixed
51
+ # 10 Hz tick; the adaptive loop can drain at event-loop speed during a burst,
52
+ # so the sweep is gated back to that original cadence.
53
+ _PRUNE_MIN_INTERVAL_MS = 100
54
+
55
+
56
+ class _RecipientInFlightTracker:
57
+ """Python port of the iOS/Android ``RecipientInFlightTracker``.
58
+
59
+ Tracks wire-level in-flight message ids per recipient so the relay's
60
+ recipient-keyed failure signal — ``DeliveryError``, which on older relays
61
+ carries no ``message_id`` — can be correlated back to the SDK message ids
62
+ still awaiting an outcome. On a relay new enough to echo the outbox id we
63
+ resolve delivered frames precisely on ``MessageSent`` and fail the exact id
64
+ on ``DeliveryError``; on an older relay we fall back to failing every live
65
+ in-flight id for the recipient. "Everything in flight to an offline peer
66
+ failed" is safe by construction. Runs on the single asyncio loop, so no lock
67
+ is needed (unlike the mobile bridges).
68
+ """
69
+
70
+ def __init__(self, ttl_ms: int = _RIFT_TTL_MS, max_per_recipient: int = _RIFT_MAX_PER_RECIPIENT) -> None:
71
+ self._ttl_ms = ttl_ms
72
+ self._max = max_per_recipient
73
+ self._by_recipient: dict[str, deque[tuple[str, int]]] = {}
74
+
75
+ def record_sent(self, recipient: str, message_id: str, now_ms: int) -> None:
76
+ if not recipient or not message_id:
77
+ return
78
+ q = self._by_recipient.setdefault(recipient, deque())
79
+ q.append((message_id, now_ms))
80
+ while len(q) > self._max:
81
+ q.popleft()
82
+
83
+ def resolve_on_relay_accepted(self, recipient: str, message_id: str | None, now_ms: int) -> None:
84
+ """Relay ``MessageSent``: it accepted/forwarded a frame, so that frame
85
+ must not be swept into a later recipient-keyed ``DeliveryError`` (which
86
+ would false-fail a delivered message). Remove the exact id when the relay
87
+ echoed ours; otherwise (older relay / relay-minted id) drop the oldest as
88
+ a best-effort guess, bounded by the TTL and by the DeliveryError sweep."""
89
+ if not recipient:
90
+ return
91
+ q = self._by_recipient.get(recipient)
92
+ if q is None:
93
+ return
94
+ while q and now_ms - q[0][1] > self._ttl_ms:
95
+ q.popleft()
96
+ exact = False
97
+ if message_id:
98
+ q2 = deque((m, t) for (m, t) in q if m != message_id)
99
+ exact = len(q2) != len(q)
100
+ q = q2
101
+ self._by_recipient[recipient] = q
102
+ if not exact and q:
103
+ q.popleft()
104
+ if not q:
105
+ self._by_recipient.pop(recipient, None)
106
+
107
+ def unrecord(self, recipient: str, message_id: str) -> None:
108
+ """Undo a ``record_sent`` when the write never reached the wire.
109
+
110
+ The entry is recorded BEFORE ``await ws.send`` so a fast relay
111
+ ``DeliveryError`` interleaved on the recv task finds it; when the send
112
+ instead raises, the frame did not go out and its optimistic entry must
113
+ be taken back, or a later recipient-keyed ``DeliveryError`` would
114
+ false-fail a message that was never in flight. Mirrors the iOS/Android
115
+ failure-completion ``unrecord``."""
116
+ if not recipient or not message_id:
117
+ return
118
+ q = self._by_recipient.get(recipient)
119
+ if q is None:
120
+ return
121
+ # Remove the newest matching id (the one this call just recorded),
122
+ # leaving any older same-id retry entry intact.
123
+ for i in range(len(q) - 1, -1, -1):
124
+ if q[i][0] == message_id:
125
+ del q[i]
126
+ break
127
+ if not q:
128
+ self._by_recipient.pop(recipient, None)
129
+
130
+ def drain_recipient(self, recipient: str, now_ms: int) -> list[str]:
131
+ """Remove and return every live (non-expired) in-flight id for a peer."""
132
+ q = self._by_recipient.pop(recipient, None)
133
+ if q is None:
134
+ return []
135
+ return [m for (m, t) in q if now_ms - t <= self._ttl_ms]
136
+
137
+ def prune(self, now_ms: int) -> None:
138
+ for r in list(self._by_recipient.keys()):
139
+ q = self._by_recipient[r]
140
+ while q and now_ms - q[0][1] > self._ttl_ms:
141
+ q.popleft()
142
+ if not q:
143
+ self._by_recipient.pop(r, None)
144
+
145
+ def clear(self) -> None:
146
+ self._by_recipient.clear()
147
+
148
+
149
+ class InternetManager(TransportManager):
150
+ """WebSocket-based internet transport.
151
+
152
+ Connects to a relay server, authenticates, and then continuously:
153
+ * receives incoming messages and feeds them to the Rust protocol core
154
+ * polls the protocol core for outgoing messages and sends them over WS
155
+
156
+ Parameters
157
+ ----------
158
+ protocol:
159
+ The ``OfflineProtocol`` UniFFI instance.
160
+ device_id:
161
+ The local device identifier (used for auth fallback and message routing).
162
+ server_url:
163
+ WebSocket URL of the relay server (e.g. ``ws://relay.example.com``).
164
+ auth_token:
165
+ Optional auth token (falls back to *device_id* if ``None``).
166
+ auto_reconnect:
167
+ Whether to reconnect on disconnection.
168
+ max_reconnect_attempts:
169
+ 0 means infinite.
170
+ app_id:
171
+ The configured application id (``ProtocolConfig.app_id``), stamped on
172
+ every frame this manager synthesizes for the core. Keyword-only and
173
+ required: it once defaulted to a fixed literal, so a manager built
174
+ without it stamped a foreign id on every relay answer and legacy DM.
175
+ """
176
+
177
+ transport_id = "internet"
178
+ transport_name = "Internet (WebSocket)"
179
+
180
+ def __init__(
181
+ self,
182
+ protocol: Any,
183
+ device_id: str,
184
+ server_url: str | None = None,
185
+ auth_token: str | None = None,
186
+ auto_reconnect: bool = True,
187
+ max_reconnect_attempts: int = 0,
188
+ *,
189
+ app_id: str,
190
+ ) -> None:
191
+ super().__init__()
192
+ self._protocol = protocol
193
+ self._device_id = device_id
194
+ self._app_id = app_id
195
+ self._server_url = server_url
196
+ self._auth_token = auth_token
197
+ self._auto_reconnect = auto_reconnect
198
+ self._max_reconnect_attempts = max_reconnect_attempts
199
+
200
+ # Connection state
201
+ self._ws: ClientConnection | None = None
202
+ self._connected = False
203
+ self._authenticated = False
204
+
205
+ # Reconnection state
206
+ self._reconnect_attempts = 0
207
+ self._current_reconnect_delay = _RECONNECT_INITIAL_DELAY
208
+
209
+ # Failure tracking for DORS
210
+ self._consecutive_send_failures = 0
211
+ self._consecutive_ping_failures = 0
212
+
213
+ # Metrics
214
+ self._bytes_sent: int = 0
215
+ self._bytes_received: int = 0
216
+ self._messages_sent: int = 0
217
+ self._messages_received: int = 0
218
+
219
+ # Event loop — captured in start() for thread-safe scheduling
220
+ self._loop: asyncio.AbstractEventLoop | None = None
221
+
222
+ # Async tasks
223
+ self._recv_task: asyncio.Task[None] | None = None
224
+ self._poll_task: asyncio.Task[None] | None = None
225
+ self._ping_task: asyncio.Task[None] | None = None
226
+ self._send_tasks: set[asyncio.Task[None]] = set()
227
+ # Fire-and-forget tasks scheduled from `_process_received` (auth /
228
+ # connection-closed fallouts). Retained here so the event loop's
229
+ # weak task table cannot GC them mid-execution.
230
+ self._process_tasks: set[asyncio.Task[None]] = set()
231
+ self._send_semaphore: asyncio.Semaphore = asyncio.Semaphore(_MAX_CONCURRENT_SENDS)
232
+ # Set by the receive loop on every inbound frame; the send loop waits
233
+ # on it, so a reply the core queued while handling that frame ships
234
+ # immediately instead of waiting out a poll interval.
235
+ self._send_wake: asyncio.Event = asyncio.Event()
236
+ # Correlates the relay's recipient-keyed DeliveryError back to in-flight
237
+ # sends (parity with the iOS/Android bridges).
238
+ self._inflight = _RecipientInFlightTracker()
239
+ # Gate for the tracker sweep in _poll_and_send_messages (see
240
+ # _PRUNE_MIN_INTERVAL_MS).
241
+ self._last_prune_ms: int = 0
242
+ self._reconnect_handle: asyncio.TimerHandle | None = None
243
+
244
+ # Re-entrancy guard for `_handle_connection_closed`. Set synchronously
245
+ # at the top of the coroutine so a second caller reaching it before
246
+ # the first returns (e.g. AuthError process-task + recv-loop
247
+ # ConnectionClosed both racing) deduplicates without relying on the
248
+ # state-machine guard, which does not fire during reconnect
249
+ # (state == STARTING).
250
+ self._teardown_in_progress: bool = False
251
+
252
+ # -- configuration --------------------------------------------------------
253
+
254
+ def configure(
255
+ self,
256
+ server_url: str,
257
+ auto_reconnect: bool = True,
258
+ max_reconnect_attempts: int = 0,
259
+ ) -> None:
260
+ self._server_url = server_url
261
+ self._auto_reconnect = auto_reconnect
262
+ self._max_reconnect_attempts = max_reconnect_attempts
263
+ self._emit_diagnostic("info", "Internet transport configured", {
264
+ "server_url": server_url,
265
+ "auto_reconnect": auto_reconnect,
266
+ })
267
+
268
+ def set_auth_token(self, token: str | None) -> None:
269
+ self._auth_token = token
270
+ self._emit_diagnostic("info", "Auth token updated", {
271
+ "has_token": token is not None,
272
+ })
273
+ if self._connected and self._ws is not None:
274
+ loop = self._loop
275
+ if loop is not None and not loop.is_closed() and loop.is_running():
276
+ loop.call_soon_threadsafe(
277
+ asyncio.ensure_future, self._send_authentication()
278
+ )
279
+
280
+ # -- TransportManager interface -------------------------------------------
281
+
282
+ def is_available(self) -> bool:
283
+ return self._server_url is not None
284
+
285
+ async def start(self) -> None:
286
+ if self._state == TransportState.RUNNING:
287
+ raise TransportError("Internet transport is already running")
288
+ if self._server_url is None:
289
+ raise TransportError(
290
+ "Server URL not configured. Call configure(server_url=...) first."
291
+ )
292
+ self._loop = asyncio.get_running_loop()
293
+ self._emit_diagnostic("info", "Starting Internet transport", {
294
+ "device_id": self._device_id,
295
+ "server_url": self._server_url,
296
+ })
297
+ self._update_state(TransportState.STARTING)
298
+ await self._connect()
299
+
300
+ async def stop(self) -> None:
301
+ # STOPPING too: a stop() cancelled part-way (a shutdown deadline)
302
+ # leaves the transport there, and a retry that returned at once would
303
+ # leave it half torn down for good. Every step below is idempotent.
304
+ if self._state not in (
305
+ TransportState.RUNNING,
306
+ TransportState.STARTING,
307
+ TransportState.STOPPING,
308
+ ):
309
+ return
310
+ self._update_state(TransportState.STOPPING)
311
+
312
+ # Cancel reconnect
313
+ if self._reconnect_handle is not None:
314
+ self._reconnect_handle.cancel()
315
+ self._reconnect_handle = None
316
+
317
+ # Cancel async tasks
318
+ for task in (self._recv_task, self._poll_task, self._ping_task):
319
+ if task is not None and not task.done():
320
+ task.cancel()
321
+ self._recv_task = self._poll_task = self._ping_task = None
322
+
323
+ # Cancel in-flight send tasks — snapshot to avoid "Set changed size
324
+ # during iteration" if done-callbacks fire concurrently.
325
+ pending_sends = list(self._send_tasks)
326
+ self._send_tasks.clear()
327
+ for task in pending_sends:
328
+ if not task.done():
329
+ task.cancel()
330
+
331
+ # Cancel in-flight process-received tasks (auth / close fallouts).
332
+ pending_process = list(self._process_tasks)
333
+ self._process_tasks.clear()
334
+ for task in pending_process:
335
+ if not task.done():
336
+ task.cancel()
337
+
338
+ # Close WebSocket
339
+ await self._disconnect()
340
+
341
+ # Notify protocol
342
+ try:
343
+ self._protocol.internet_status_changed(is_connected=False)
344
+ except Exception:
345
+ logger.debug("internet_status_changed(False) failed", exc_info=True)
346
+
347
+ self._update_state(TransportState.STOPPED)
348
+ self._emit_diagnostic("info", "Internet transport stopped")
349
+
350
+ def get_metrics(self) -> dict[str, Any]:
351
+ return {
352
+ "bytes_sent": self._bytes_sent,
353
+ "bytes_received": self._bytes_received,
354
+ "messages_sent": self._messages_sent,
355
+ "messages_received": self._messages_received,
356
+ "is_connected": self._connected,
357
+ "reconnect_attempts": self._reconnect_attempts,
358
+ }
359
+
360
+ # -- connection management ------------------------------------------------
361
+
362
+ async def _connect(self) -> None:
363
+ if self._connected or self._server_url is None:
364
+ return
365
+ try:
366
+ extra_headers = {"X-Device-ID": self._device_id}
367
+ self._ws = await asyncio.wait_for(
368
+ websockets.connect(
369
+ self._server_url,
370
+ additional_headers=extra_headers,
371
+ ),
372
+ timeout=_CONNECTION_TIMEOUT,
373
+ )
374
+ self._connected = True
375
+ self._authenticated = False
376
+ self._reconnect_attempts = 0
377
+ self._current_reconnect_delay = _RECONNECT_INITIAL_DELAY
378
+ self._consecutive_send_failures = 0
379
+ self._consecutive_ping_failures = 0
380
+
381
+ # Start receive loop BEFORE auth so it's always cleaned up on
382
+ # failure — prevents _recv_task staying None if auth throws.
383
+ self._recv_task = asyncio.ensure_future(self._receive_loop())
384
+
385
+ self._emit_diagnostic("info", "WebSocket connected, authenticating...")
386
+ await self._send_authentication()
387
+
388
+ except Exception as exc:
389
+ self._emit_diagnostic("error", "WebSocket connection failed", {
390
+ "error": str(exc),
391
+ })
392
+ await self._handle_connection_closed(exc)
393
+
394
+ async def _disconnect(self) -> None:
395
+ if self._ws is not None:
396
+ try:
397
+ await self._ws.close()
398
+ except Exception:
399
+ pass
400
+ self._ws = None
401
+ self._connected = False
402
+ self._authenticated = False
403
+
404
+ async def _send_authentication(self) -> None:
405
+ if self._ws is None:
406
+ return
407
+ token = self._auth_token or self._device_id
408
+ auth_msg = json.dumps({"type": "Authenticate", "token": token})
409
+ try:
410
+ await self._ws.send(auth_msg)
411
+ self._emit_diagnostic("debug", "Auth message sent", {
412
+ "user_id": self._device_id,
413
+ })
414
+ except Exception as exc:
415
+ self._emit_diagnostic("error", f"Failed to send auth: {exc}")
416
+
417
+ async def _safe_handle_authenticated(
418
+ self,
419
+ user_id: str,
420
+ username: str | None,
421
+ capabilities: Any,
422
+ address_challenge: str | None,
423
+ ws: ClientConnection | None,
424
+ ) -> None:
425
+ """Wrapper that catches exceptions to prevent stuck STARTING state."""
426
+ try:
427
+ await self._handle_authenticated(
428
+ user_id, username, capabilities, address_challenge, ws
429
+ )
430
+ except Exception as exc:
431
+ self._emit_diagnostic("error", f"Authentication handler failed: {exc}")
432
+ await self._handle_connection_closed(exc)
433
+
434
+ async def _safe_handle_connection_closed(self, error: Exception | None) -> None:
435
+ """Wrapper that catches exceptions from connection-closed handling."""
436
+ try:
437
+ await self._handle_connection_closed(error)
438
+ except Exception as exc:
439
+ self._emit_diagnostic("error", f"Connection-closed handler failed: {exc}")
440
+
441
+ async def _handle_authenticated(
442
+ self,
443
+ user_id: str,
444
+ username: str | None,
445
+ capabilities: Any,
446
+ address_challenge: str | None,
447
+ ws: ClientConnection | None,
448
+ ) -> None:
449
+ self._authenticated = True
450
+ self._update_state(TransportState.RUNNING)
451
+
452
+ self._emit_diagnostic("info", "Authenticated with relay server", {
453
+ "user_id": user_id,
454
+ "username": username or self._device_id,
455
+ })
456
+
457
+ # The order of the three steps below is load-bearing, and mirrors the
458
+ # same block in the Swift and Kotlin managers.
459
+ #
460
+ # The address declaration MUST precede the status flip. The relay
461
+ # attributes each inbound frame by whatever this connection has proved
462
+ # at the moment it reads that frame, and never re-stamps retroactively,
463
+ # so a send that leaves before the declaration is attributed by account
464
+ # name for good. Its `Message.sender` (an address) then fails the
465
+ # receiver's `validate_transport_sender` at hop 0, which drops exactly
466
+ # the `__MLS_KEY_PKG__` / `__MLS_WELCOME__` frames a new session needs.
467
+ # The flush the status flip performs is what produces those sends, so
468
+ # the declaration goes out first and WebSocket frame order does the
469
+ # rest.
470
+ await self._maybe_declare_address(
471
+ username, capabilities, address_challenge, ws
472
+ )
473
+
474
+ # Capabilities MUST also reach the SDK before the status flip: the
475
+ # flush reads the group broadcast gate's capability set. The list is
476
+ # injected even when empty, so a stale set from a previous relay can
477
+ # never leak across connections.
478
+ try:
479
+ self._protocol.internet_relay_capabilities(
480
+ capabilities=capabilities if isinstance(capabilities, list) else []
481
+ )
482
+ except Exception as exc:
483
+ self._emit_diagnostic("error", f"Relay capability injection failed: {exc}")
484
+
485
+ # Notify protocol: this is what triggers the outbox flush.
486
+ try:
487
+ self._protocol.internet_status_changed(is_connected=True)
488
+ except Exception as exc:
489
+ self._emit_diagnostic("error", f"Protocol notify failed: {exc}")
490
+
491
+ # Cancel any existing poll/ping tasks before creating new ones
492
+ # (guards against duplicate Authenticated messages from the server)
493
+ for task in (self._poll_task, self._ping_task):
494
+ if task is not None and not task.done():
495
+ task.cancel()
496
+
497
+ # Start polling and ping tasks
498
+ self._poll_task = asyncio.ensure_future(self._poll_outgoing_loop())
499
+ self._ping_task = asyncio.ensure_future(self._ping_loop())
500
+
501
+ # Immediate flush. The poll drains the internet send queue the status
502
+ # flip just filled, so messages queued while disconnected go out now
503
+ # rather than on the next timer tick.
504
+ self._poll_and_send_messages()
505
+
506
+ async def _maybe_declare_address(
507
+ self,
508
+ username: str | None,
509
+ capabilities: Any,
510
+ address_challenge: str | None,
511
+ ws: ClientConnection | None,
512
+ ) -> None:
513
+ """Answer the relay's address challenge with a signed ``DeclareAddress``.
514
+
515
+ No-op unless the relay advertised ``address_routing_v1`` and sent a
516
+ well-formed challenge, so relays without the capability are unaffected.
517
+
518
+ Never raises into the auth path. An undeclared connection is a working
519
+ connection: the relay simply attributes it the legacy way, which is how
520
+ it behaved before addresses existed. Failing the connection over a
521
+ refused declaration would turn a degraded path into no path.
522
+
523
+ Nothing waits on the relay's answer. The relay binds the address before
524
+ it reads the next frame off the socket, so ordering is established by
525
+ the write alone; ``AddressDeclared`` and ``AddressError`` are reported
526
+ when they arrive but gate nothing.
527
+ """
528
+ outcome = address_declaration.decide(capabilities, address_challenge, username)
529
+ if isinstance(outcome, address_declaration.Skip):
530
+ self._emit_diagnostic(
531
+ "debug",
532
+ "Not declaring an address to the relay",
533
+ {"reason": outcome.reason},
534
+ )
535
+ return
536
+
537
+ # The declaration belongs to the connection that was handed the
538
+ # challenge. A socket replaced between that frame's arrival and this
539
+ # coroutine has its own `Authenticated`, carrying its own challenge,
540
+ # already on the way.
541
+ if ws is None or ws is not self._ws:
542
+ self._emit_diagnostic(
543
+ "debug",
544
+ "Not declaring an address to the relay",
545
+ {"reason": address_declaration.Reason.CONNECTION_REPLACED},
546
+ )
547
+ return
548
+
549
+ # The address the core compares the relay's answer against, so the
550
+ # declaration must carry this value and not a locally re-derived one.
551
+ # Absent before `initialize_mls`: an app running with encryption
552
+ # disabled stays in account-name space by construction, which is a
553
+ # clean skip rather than a failure.
554
+ try:
555
+ address = self._protocol.local_address()
556
+ except Exception:
557
+ address = None
558
+ if not address:
559
+ self._emit_diagnostic(
560
+ "debug",
561
+ "Not declaring an address to the relay",
562
+ {"reason": address_declaration.Reason.ADDRESS_UNAVAILABLE},
563
+ )
564
+ return
565
+
566
+ try:
567
+ payload = address_declaration.proof_payload(
568
+ outcome.account, outcome.challenge
569
+ )
570
+ public_key = bytes(self._protocol.get_identity_public_key())
571
+ signature = bytes(self._protocol.sign_data(list(payload)))
572
+ frame = address_declaration.declaration_json(
573
+ address, public_key, signature
574
+ )
575
+ except Exception as exc:
576
+ self._emit_diagnostic(
577
+ "error",
578
+ f"Could not sign the address declaration: {exc}",
579
+ {"reason": address_declaration.Reason.SIGNING_FAILED},
580
+ )
581
+ return
582
+
583
+ try:
584
+ await ws.send(frame)
585
+ except Exception as exc:
586
+ self._emit_diagnostic(
587
+ "warning", f"Address declaration write failed: {exc}"
588
+ )
589
+ return
590
+
591
+ self._emit_diagnostic(
592
+ "info", "Sent DeclareAddress to relay", {"address": address}
593
+ )
594
+
595
+ async def _handle_connection_closed(self, error: Exception | None) -> None:
596
+ # Re-entrancy guard. On AuthError + WS-close, two paths race here:
597
+ # the fire-and-forget process-task from `_process_received` and the
598
+ # recv-loop's `except ConnectionClosed` branch. The state-machine
599
+ # guard below only fires when STOPPING/STOPPED, not during reconnect
600
+ # (STARTING). The flag is set synchronously before any await, so
601
+ # whichever caller gets here second returns immediately.
602
+ if self._teardown_in_progress:
603
+ return
604
+ if (
605
+ not self._connected
606
+ and not self._authenticated
607
+ and self._state in (TransportState.STOPPING, TransportState.STOPPED)
608
+ ):
609
+ return # already handled post-stop
610
+
611
+ self._teardown_in_progress = True
612
+ try:
613
+ was_connected = self._connected
614
+ self._connected = False
615
+ self._authenticated = False
616
+
617
+ # The socket died: forget in-flight correlations. Anything still
618
+ # unresolved is owned by the transport/core retry machinery now, and
619
+ # a fresh connection re-records from scratch.
620
+ self._inflight.clear()
621
+
622
+ # Cancel recv/poll/ping tasks. Skip whichever (if any) is the
623
+ # task currently running this coroutine — any task in the cancel
624
+ # list can itself be the caller (recv-loop on ConnectionClosed,
625
+ # ping-loop on repeated failure, send task on repeated send
626
+ # failure). Self-cancel would surface CancelledError mid-await;
627
+ # the running task exits naturally once this coroutine returns.
628
+ current = asyncio.current_task()
629
+ for task in (self._recv_task, self._poll_task, self._ping_task):
630
+ if task is not None and task is not current and not task.done():
631
+ task.cancel()
632
+ self._recv_task = self._poll_task = self._ping_task = None
633
+
634
+ # Close the WebSocket now that no loop is reading from it.
635
+ # Without this, the old socket would stay open across a
636
+ # reconnect, and `_connect` would overwrite `self._recv_task` —
637
+ # leaving a zombie recv loop draining the previous connection.
638
+ await self._disconnect()
639
+
640
+ if was_connected:
641
+ try:
642
+ self._protocol.internet_status_changed(is_connected=False)
643
+ except Exception:
644
+ logger.debug("internet_status_changed(False) failed", exc_info=True)
645
+
646
+ self._emit_diagnostic("warning", "WebSocket disconnected", {
647
+ "error": str(error) if error else "none",
648
+ })
649
+
650
+ if (
651
+ self._auto_reconnect
652
+ and self._state not in (TransportState.STOPPING, TransportState.STOPPED)
653
+ ):
654
+ self._schedule_reconnect()
655
+ else:
656
+ self._update_state(TransportState.STOPPED)
657
+ finally:
658
+ self._teardown_in_progress = False
659
+
660
+ def _schedule_reconnect(self) -> None:
661
+ if not self._auto_reconnect:
662
+ return
663
+ if (
664
+ self._max_reconnect_attempts > 0
665
+ and self._reconnect_attempts >= self._max_reconnect_attempts
666
+ ):
667
+ self._emit_diagnostic("error", "Max reconnect attempts reached")
668
+ self._update_state(TransportState.STOPPED)
669
+ return
670
+
671
+ self._reconnect_attempts += 1
672
+ delay = self._current_reconnect_delay
673
+ self._current_reconnect_delay = min(
674
+ self._current_reconnect_delay * _RECONNECT_BACKOFF_MULTIPLIER,
675
+ _RECONNECT_MAX_DELAY,
676
+ )
677
+
678
+ # Transition to STARTING so callers see a consistent state while
679
+ # waiting for the reconnect timer (avoids RUNNING + _connected=False).
680
+ self._update_state(TransportState.STARTING)
681
+
682
+ self._emit_diagnostic("info", "Scheduling reconnect", {
683
+ "attempt": self._reconnect_attempts,
684
+ "delay_seconds": delay,
685
+ })
686
+
687
+ loop = self._loop
688
+ if loop is None or loop.is_closed() or not loop.is_running():
689
+ self._emit_diagnostic("warning", "No running event loop for reconnect")
690
+ self._update_state(TransportState.STOPPED)
691
+ return
692
+
693
+ # Cancel any prior handle before overwriting so concurrent
694
+ # `_schedule_reconnect` callers don't orphan a timer that would still
695
+ # fire and race a second `_connect()` against the first.
696
+ if self._reconnect_handle is not None:
697
+ self._reconnect_handle.cancel()
698
+ self._reconnect_handle = loop.call_later(
699
+ delay,
700
+ lambda: asyncio.ensure_future(self._connect()),
701
+ )
702
+
703
+ # -- receive loop ---------------------------------------------------------
704
+
705
+ async def _receive_loop(self) -> None:
706
+ """Continuously receive messages from the WebSocket."""
707
+ try:
708
+ if self._ws is None:
709
+ return
710
+ async for raw in self._ws:
711
+ if isinstance(raw, bytes):
712
+ data = raw
713
+ else:
714
+ data = raw.encode("utf-8")
715
+ self._bytes_received += len(data)
716
+ # Wake the send loop before dispatch: the handlers below feed
717
+ # the core synchronously, so by the time the send loop runs,
718
+ # any reply this frame produces is typically already queued.
719
+ # Replies queued later (from a worker thread) are covered by
720
+ # the loop's backoff ramp re-arming from its floor.
721
+ self._send_wake.set()
722
+ self._process_received(data)
723
+ except websockets.ConnectionClosed:
724
+ await self._handle_connection_closed(None)
725
+ except asyncio.CancelledError:
726
+ return
727
+ except Exception as exc:
728
+ await self._handle_connection_closed(exc)
729
+
730
+ def _spawn_process_task(self, coro: Coroutine[Any, Any, None]) -> None:
731
+ """Schedule a fire-and-forget coroutine and retain a strong ref.
732
+
733
+ asyncio only holds weak references to tasks, so an untracked
734
+ ``ensure_future`` can be GC'd mid-await. `_process_tasks` keeps the
735
+ reference alive until completion.
736
+ """
737
+ task = asyncio.ensure_future(coro)
738
+ self._process_tasks.add(task)
739
+ task.add_done_callback(self._process_tasks.discard)
740
+
741
+ def _process_received(self, data: bytes) -> None:
742
+ """Dispatch an incoming WebSocket frame to the protocol core."""
743
+ try:
744
+ msg = json.loads(data)
745
+ except json.JSONDecodeError:
746
+ self._emit_diagnostic("warning", "Non-JSON message received")
747
+ return
748
+
749
+ msg_type = msg.get("type")
750
+ if msg_type is None:
751
+ return
752
+
753
+ if msg_type == "Authenticated":
754
+ user_id = msg.get("user_id", self._device_id)
755
+ # RAW, with no `device_id` fallback: this name goes into the signed
756
+ # address proof, and the relay verifies it against the account name
757
+ # *it* resolved. Signing a locally-chosen substitute produces a
758
+ # signature that cannot verify and, in the relay's logs, is
759
+ # indistinguishable from an attack. The fallback lives at the
760
+ # display sites instead.
761
+ username = msg.get("username")
762
+ capabilities = msg.get("capabilities", [])
763
+ address_challenge = msg.get("address_challenge")
764
+ # The socket this frame arrived on. `_process_received` runs inline
765
+ # in the receive loop, so `_ws` here is that socket; by the time the
766
+ # spawned task runs it may not be.
767
+ self._spawn_process_task(
768
+ self._safe_handle_authenticated(
769
+ user_id, username, capabilities, address_challenge, self._ws
770
+ )
771
+ )
772
+
773
+ elif msg_type == "AddressDeclared":
774
+ # The relay bound this connection to the address we proved. From its
775
+ # next inbound frame on, it attributes us by address instead of
776
+ # account name. Informational: the binding took effect before the
777
+ # relay answered (its frame loop is sequential), so nothing waits on
778
+ # this.
779
+ #
780
+ # The echo goes to the SDK, which is where the lockstep check lives:
781
+ # it compares the bound address against `local_address()` and
782
+ # reports a disagreement as RELAY_ADDRESS_BINDING_MISMATCH. A
783
+ # dedicated entry point, not message-plane injection, so an
784
+ # acknowledgement cannot be synthesized through the notification
785
+ # ciphertext injector.
786
+ declared_address = msg.get("address", "")
787
+ try:
788
+ self._protocol.internet_address_declared(address=declared_address)
789
+ except Exception as exc:
790
+ logger.debug("internet_address_declared failed: %s", exc)
791
+ self._emit_diagnostic(
792
+ "info",
793
+ "Relay accepted the address declaration",
794
+ {"address": declared_address},
795
+ )
796
+
797
+ elif msg_type == "AddressError":
798
+ # The refusal frame is `AddressError` (relay `ServerMessage`), not
799
+ # the name of the FFI entry point it feeds. Non-fatal by contract:
800
+ # the connection stays authenticated and keeps working in
801
+ # account-name space. No retry here, because a refusal is either
802
+ # permanent for this connection (bad material, or a different
803
+ # address already declared) or means this socket was displaced by a
804
+ # newer login, in which case the successor declares for itself. The
805
+ # next reconnect re-declares from scratch.
806
+ reason = msg.get("reason", "Unknown error")
807
+ try:
808
+ self._protocol.internet_address_declaration_refused(reason=reason)
809
+ except Exception as exc:
810
+ logger.debug("internet_address_declaration_refused failed: %s", exc)
811
+ self._emit_diagnostic(
812
+ "error",
813
+ "Relay refused the address declaration; staying in account-name space",
814
+ {"reason": reason},
815
+ )
816
+
817
+ elif msg_type == "AuthError":
818
+ reason = msg.get("reason", "Unknown")
819
+ self._emit_diagnostic("error", f"Auth failed: {reason}")
820
+ self._spawn_process_task(self._safe_handle_connection_closed(None))
821
+
822
+ elif msg_type == "MessageReceived":
823
+ self._handle_incoming_message(msg)
824
+
825
+ elif msg_type == "ConnectionRequestReceived":
826
+ self._handle_connection_request(msg)
827
+
828
+ elif msg_type == "ConnectionAccepted":
829
+ self._handle_connection_accepted(msg)
830
+
831
+ elif msg_type == "ConnectionRejected":
832
+ self._handle_connection_rejected(msg)
833
+
834
+ elif msg_type == "MessageSent":
835
+ # The relay accepted/forwarded this frame (or push-poked an offline
836
+ # recipient) — either way it is no longer in flight and must not be
837
+ # swept into a later recipient-keyed DeliveryError, which would
838
+ # false-fail a delivered message. Resolve it out of the in-flight
839
+ # tracker (by exact id when the relay echoed ours, else best-effort
840
+ # oldest). Not a delivery guarantee, so we do not touch presence.
841
+ recipient = msg.get("recipient", "")
842
+ message_id = msg.get("message_id")
843
+ if recipient:
844
+ self._inflight.resolve_on_relay_accepted(
845
+ recipient,
846
+ message_id if message_id else None,
847
+ self._now_ms(),
848
+ )
849
+ # ``pushed: true``: the relay had no live socket for the recipient
850
+ # and handed the ciphertext to a device push — the fact a
851
+ # DeliveryError carries (the recipient is not on the relay) with
852
+ # the frame possibly delivered by the push. ``stored: true`` (relay
853
+ # capability ``mailbox_v1``) adds that the relay's mailbox holds
854
+ # the frame and re-sends it on the recipient's next connection, so
855
+ # the park needs no reachability probe. Older relays omit both,
856
+ # which reads as neither.
857
+ if msg.get("pushed") is True and message_id:
858
+ self._park_pushed_message(
859
+ recipient, message_id, msg.get("stored") is True
860
+ )
861
+
862
+ elif msg_type == "DeliveryError":
863
+ recipient = msg.get("recipient", "")
864
+ message_id = msg.get("message_id")
865
+ reason = msg.get("reason", "unknown")
866
+ self._emit_diagnostic("warning", "Delivery failed", {
867
+ "recipient": recipient,
868
+ "reason": reason,
869
+ })
870
+ # The relay's authoritative "recipient offline" signal. Feed it back
871
+ # into the core tagged with the "recipient_unreachable" prefix the
872
+ # engine classifies on (see SEND_FAIL_REASON_RECIPIENT_UNREACHABLE)
873
+ # so the message is parked on the escalating reachability probe
874
+ # instead of re-sent ~once/second forever (which would exceed the
875
+ # relay's per-connection rate limit and flap the connection).
876
+ #
877
+ # Correlate by RECIPIENT, matching the iOS/Android bridges: the relay
878
+ # is recipient-keyed and older relays send no message_id at all, so
879
+ # we fail every live in-flight id for this recipient (delivered ones
880
+ # were already resolved out on their MessageSent). On a relay new
881
+ # enough to echo the outbox id we additionally fail that exact id in
882
+ # case it was never recorded. Then feed presence-offline so the core
883
+ # parks welcomes and starts watching for the peer's return.
884
+ #
885
+ # ``stored: true`` (relay capability ``mailbox_v1``) makes this a
886
+ # deferral rather than a loss: the mailbox holds the frame for the
887
+ # recipient's next connection, so that id is reported under
888
+ # ``relay_stored`` — the same verdict, parked without a probe the
889
+ # relay's own redelivery makes pointless. It names one message, so
890
+ # the recipient's other drained frames keep the unreachable prefix.
891
+ now = self._now_ms()
892
+ stored_id = message_id if (msg.get("stored") is True and message_id) else None
893
+ failed_ids = self._inflight.drain_recipient(recipient, now) if recipient else []
894
+ if message_id and message_id not in failed_ids:
895
+ failed_ids.append(message_id)
896
+ for mid in failed_ids:
897
+ try:
898
+ self._protocol.internet_send_failed_with_reason(
899
+ message_id=mid,
900
+ reason=(
901
+ "relay_stored"
902
+ if mid == stored_id
903
+ else f"recipient_unreachable: {reason}"
904
+ ),
905
+ )
906
+ except Exception as exc:
907
+ logger.debug(
908
+ "internet_send_failed_with_reason failed: %s", exc
909
+ )
910
+ if recipient:
911
+ try:
912
+ self._protocol.internet_peer_presence(
913
+ peer_id=recipient, online=False, last_seen_ms=None
914
+ )
915
+ except Exception as exc:
916
+ logger.debug("internet_peer_presence(offline) failed: %s", exc)
917
+
918
+ elif msg_type in (
919
+ "GroupCreated",
920
+ "GroupMessageReceived",
921
+ "GroupMemberAdded",
922
+ "GroupMemberRemoved",
923
+ "GroupError",
924
+ ):
925
+ self._handle_group_message(msg_type, msg)
926
+
927
+ elif msg_type == "GroupMessageSent":
928
+ # The relay's settled per-recipient delivery report for a group
929
+ # broadcast. It goes to the dedicated report entry point, never
930
+ # the message plane, so the report path cannot be forged through
931
+ # the notification injector below.
932
+ try:
933
+ self._protocol.internet_group_report_received(report_json=json.dumps(msg))
934
+ except Exception as exc:
935
+ self._emit_diagnostic("warning", f"Group delivery report rejected: {exc}")
936
+
937
+ else:
938
+ self._emit_diagnostic("debug", f"Unhandled relay message type: {msg_type}")
939
+
940
+ def _park_pushed_message(
941
+ self, recipient: str, message_id: str, stored: bool = False
942
+ ) -> None:
943
+ """Parks the one frame the relay answered ``MessageSent { pushed: true }`` for.
944
+
945
+ A port of ``parkPushedMessage`` in the iOS and Android bridges, and the
946
+ narrower sibling of the DeliveryError path above. The relay named
947
+ exactly one frame, so only that id is reported and the recipient's
948
+ other in-flight frames are left alone. The reason is the exact
949
+ ``relay_pushed`` token, not a ``recipient_unreachable`` tail: that
950
+ prefix fast-fails connection requests and fails Welcomes, while
951
+ ``relay_pushed`` parks a plain DM, leaves both of those alone and tells
952
+ the app nothing, since the push may have delivered the frame.
953
+
954
+ The id is the one the relay echoed, never the tracker's fallback guess:
955
+ push outcomes come back out of order, so the oldest frame in flight is
956
+ the least likely to be the pushed one. An echo that names none of our
957
+ frames parks nothing, because the core ignores an id with no outbox
958
+ entry.
959
+
960
+ ``stored`` is the relay adding that its mailbox holds the frame, which
961
+ swaps the token for ``relay_pushed_stored``: the same park, minus the
962
+ reachability probe the core would otherwise schedule, since the relay
963
+ re-sends the held copy itself.
964
+ """
965
+ token = "relay_pushed_stored" if stored else "relay_pushed"
966
+ try:
967
+ self._protocol.internet_send_failed_with_reason(
968
+ message_id=message_id, reason=token
969
+ )
970
+ except Exception as exc:
971
+ logger.debug("internet_send_failed_with_reason(%s) failed: %s", token, exc)
972
+ if recipient:
973
+ try:
974
+ self._protocol.internet_peer_presence(
975
+ peer_id=recipient, online=False, last_seen_ms=None
976
+ )
977
+ except Exception as exc:
978
+ logger.debug("internet_peer_presence(offline) failed: %s", exc)
979
+ self._emit_diagnostic("info", "Relay pushed message to offline recipient; parked", {
980
+ "recipient": recipient,
981
+ "messageId": message_id,
982
+ "stored": stored,
983
+ })
984
+
985
+ # -- incoming message handlers --------------------------------------------
986
+
987
+ def _handle_incoming_message(self, msg: dict[str, Any]) -> None:
988
+ sender_id = msg.get("sender", "")
989
+ content = msg.get("content", "")
990
+ message_id = msg.get("message_id")
991
+ reply_to_msg = msg.get("reply_to_msg")
992
+
993
+ if not sender_id:
994
+ return
995
+
996
+ self._messages_received += 1
997
+
998
+ # Try to parse content as full Message JSON, otherwise wrap it
999
+ is_full_message = False
1000
+ message_dict: dict[str, Any] = {}
1001
+ try:
1002
+ content_json = json.loads(content)
1003
+ if isinstance(content_json, dict) and "sender" in content_json and "recipient" in content_json:
1004
+ message_dict = content_json
1005
+ if message_id and "id" not in message_dict:
1006
+ message_dict["id"] = message_id
1007
+ if reply_to_msg and "reply_to_msg" not in message_dict:
1008
+ message_dict["reply_to_msg"] = reply_to_msg
1009
+ is_full_message = True
1010
+ except json.JSONDecodeError:
1011
+ pass
1012
+ if not is_full_message:
1013
+ # A real peer transmitted this one and awaits the ACK.
1014
+ message_dict = self._build_internal_message(
1015
+ sender_id,
1016
+ content,
1017
+ message_id=message_id,
1018
+ reply_to_msg=reply_to_msg,
1019
+ requires_ack=True,
1020
+ )
1021
+
1022
+ data_bytes = json.dumps(message_dict).encode("utf-8")
1023
+ try:
1024
+ self._protocol.internet_message_received(
1025
+ sender_id=sender_id, data=list(data_bytes)
1026
+ )
1027
+ except Exception as exc:
1028
+ self._emit_diagnostic("error", f"Error feeding message to protocol: {exc}")
1029
+
1030
+ def _handle_connection_request(self, msg: dict[str, Any]) -> None:
1031
+ sender_id = msg.get("sender", "")
1032
+ if not sender_id:
1033
+ return
1034
+ sender_name = msg.get("sender_name", sender_id)
1035
+ payload = {"sender_name": sender_name}
1036
+ kp = msg.get("key_package")
1037
+ if kp is not None:
1038
+ payload["key_package"] = [b & 0xFF for b in kp]
1039
+ content = "__CONN_REQ__" + json.dumps(payload)
1040
+ data_bytes = json.dumps(
1041
+ self._build_internal_message(sender_id, content)
1042
+ ).encode("utf-8")
1043
+ try:
1044
+ self._protocol.internet_message_received(
1045
+ sender_id=sender_id, data=list(data_bytes)
1046
+ )
1047
+ except Exception as exc:
1048
+ self._emit_diagnostic("error", f"Error processing ConnectionRequest: {exc}")
1049
+
1050
+ def _handle_connection_accepted(self, msg: dict[str, Any]) -> None:
1051
+ accepted_by = msg.get("accepted_by") or msg.get("sender", "")
1052
+ if not accepted_by:
1053
+ return
1054
+ accepted_by_name = (
1055
+ msg.get("accepted_by_name") or msg.get("sender_name", accepted_by)
1056
+ )
1057
+ payload: dict[str, Any] = {"accepted_by_name": accepted_by_name}
1058
+ kp = msg.get("key_package")
1059
+ if kp is not None:
1060
+ payload["key_package"] = [b & 0xFF for b in kp]
1061
+ content = "__CONN_ACC__" + json.dumps(payload)
1062
+ data_bytes = json.dumps(
1063
+ self._build_internal_message(accepted_by, content)
1064
+ ).encode("utf-8")
1065
+ try:
1066
+ self._protocol.internet_message_received(
1067
+ sender_id=accepted_by, data=list(data_bytes)
1068
+ )
1069
+ except Exception as exc:
1070
+ self._emit_diagnostic("error", f"Error processing ConnectionAccepted: {exc}")
1071
+
1072
+ def _handle_connection_rejected(self, msg: dict[str, Any]) -> None:
1073
+ rejected_by = msg.get("rejected_by") or msg.get("sender", "")
1074
+ if not rejected_by:
1075
+ return
1076
+ content = "__CONN_REJ__"
1077
+ data_bytes = json.dumps(
1078
+ self._build_internal_message(rejected_by, content)
1079
+ ).encode("utf-8")
1080
+ try:
1081
+ self._protocol.internet_message_received(
1082
+ sender_id=rejected_by, data=list(data_bytes)
1083
+ )
1084
+ except Exception as exc:
1085
+ self._emit_diagnostic("error", f"Error processing ConnectionRejected: {exc}")
1086
+
1087
+ def _handle_group_message(self, msg_type: str, msg: dict[str, Any]) -> None:
1088
+ """Re-inject a relay group frame under the prefix the core handles.
1089
+
1090
+ A port of the group arms of the iOS and Android bridges' inbound
1091
+ switch. The prefixes are the core's (``prefixes.rs``); the relay's own
1092
+ names are not, and a frame under an unknown prefix is plaintext the
1093
+ core rejects when encryption is required.
1094
+
1095
+ ``GroupMessageReceived`` is the one that carries a message: the relay
1096
+ fans a phone's single broadcast out to every member as this frame and
1097
+ counts the socket write as delivered, so the sender never re-sends a
1098
+ per-member copy. It is attributed to its sender, since ``__GROUP_MSG__``
1099
+ is data plane (MLS authenticates it afterwards) and the attribution is
1100
+ the reachability signal for the relayed sender.
1101
+
1102
+ The others are relay answers (``relay_answer_prefixes``, mirroring the
1103
+ core's ``RELAY_ANSWER_PREFIXES``) and
1104
+ must reach the core unattributed: no peer sent them, so nothing can
1105
+ sign them, and the core's exemption from the control-frame signature
1106
+ gate only recognizes a frame with no transport peer identity. An
1107
+ attributed answer is dropped as unsigned.
1108
+ """
1109
+ group_id = msg.get("group_id") or ""
1110
+ if msg_type == "GroupMessageReceived":
1111
+ message_id = msg.get("message_id") or ""
1112
+ if not group_id or not message_id:
1113
+ return
1114
+ sender = msg.get("sender") or ""
1115
+ payload: dict[str, Any] = {
1116
+ "group_id": group_id,
1117
+ "sender": sender,
1118
+ "content": msg.get("content") or "",
1119
+ "timestamp": msg.get("timestamp") or "",
1120
+ "message_id": message_id,
1121
+ }
1122
+ if msg.get("reply_to_msg"):
1123
+ payload["reply_to_msg"] = msg["reply_to_msg"]
1124
+ if msg.get("forward_info"):
1125
+ payload["forward_info"] = msg["forward_info"]
1126
+ self._inject_group_frame(sender or None, "__GROUP_MSG__", payload)
1127
+ elif msg_type == "GroupCreated":
1128
+ if not group_id:
1129
+ return
1130
+ payload = {"group_id": group_id, "name": msg.get("name") or ""}
1131
+ self._inject_group_frame(None, "__GROUP_CREATED__", payload)
1132
+ elif msg_type in ("GroupMemberAdded", "GroupMemberRemoved"):
1133
+ if not group_id:
1134
+ return
1135
+ actor = "added_by" if msg_type == "GroupMemberAdded" else "removed_by"
1136
+ payload = {
1137
+ "group_id": group_id,
1138
+ "user_id": msg.get("user_id") or "",
1139
+ actor: msg.get(actor) or "",
1140
+ }
1141
+ prefix = (
1142
+ "__GROUP_MEMBER_ADDED__"
1143
+ if msg_type == "GroupMemberAdded"
1144
+ else "__GROUP_MEMBER_REMOVED__"
1145
+ )
1146
+ self._inject_group_frame(None, prefix, payload)
1147
+ elif msg_type == "GroupError":
1148
+ payload = {"reason": msg.get("reason") or "Unknown error"}
1149
+ # group_id lets the core revoke relay_synced so group sends fall
1150
+ # back to per-member delivery.
1151
+ if group_id:
1152
+ payload["group_id"] = group_id
1153
+ self._inject_group_frame(None, "__GROUP_ERROR__", payload)
1154
+
1155
+ def _inject_group_frame(
1156
+ self, actor: str | None, prefix: str, payload: dict[str, Any]
1157
+ ) -> None:
1158
+ """Feed ``prefix + json(payload)`` to the core as an inbound frame.
1159
+
1160
+ ``actor`` is both the FFI ``sender_id`` and the frame's ``sender``;
1161
+ ``None`` selects unattributed ingest, with the "relay" placeholder as
1162
+ the frame sender because the core rejects an empty one. A relay
1163
+ answer is forced unattributed here, whatever the caller passed: see
1164
+ ``relay_answer_prefixes``, which holds the pinned list.
1165
+ """
1166
+ actor = attributable_actor(prefix, actor)
1167
+ content = prefix + json.dumps(payload)
1168
+ data_bytes = json.dumps(
1169
+ self._build_internal_message(actor or "relay", content)
1170
+ ).encode("utf-8")
1171
+ try:
1172
+ self._protocol.internet_message_received(
1173
+ sender_id=actor or "", data=list(data_bytes)
1174
+ )
1175
+ except Exception as exc:
1176
+ self._emit_diagnostic("error", f"Error injecting {prefix}: {exc}")
1177
+
1178
+ def _build_internal_message(
1179
+ self,
1180
+ sender_id: str,
1181
+ content: str,
1182
+ *,
1183
+ message_id: str | None = None,
1184
+ reply_to_msg: str | None = None,
1185
+ requires_ack: bool = False,
1186
+ ) -> dict[str, Any]:
1187
+ """The full serialized ``Message`` for a frame the bridge synthesizes.
1188
+
1189
+ Mirrors ``LegacyRelayMessage.buildDict`` in the iOS and Android
1190
+ bridges. Every field the core's deserializer requires must be present
1191
+ and shaped as it expects: a missing ``id`` or ``timestamp``, or a
1192
+ capitalized ``priority``, makes the transport drop the frame silently.
1193
+ The recipient is our own address, because the core forwards rather
1194
+ than processes a frame addressed to anyone else, and the profile name
1195
+ is not an address.
1196
+ """
1197
+ message: dict[str, Any] = {
1198
+ "id": message_id or str(uuid.uuid4()),
1199
+ "sender": sender_id,
1200
+ "recipient": self._protocol.local_address() or self._device_id,
1201
+ "content": content,
1202
+ "app_id": self._app_id,
1203
+ "priority": "medium",
1204
+ "ttl": 8,
1205
+ "hop_count": 0,
1206
+ "requires_ack": requires_ack,
1207
+ "timestamp": int(time.time() * 1000),
1208
+ }
1209
+ if reply_to_msg:
1210
+ message["reply_to_msg"] = reply_to_msg
1211
+ return message
1212
+
1213
+ # -- outgoing message poll loop -------------------------------------------
1214
+
1215
+ async def _poll_outgoing_loop(self) -> None:
1216
+ """Drain the core's outbound queue, adaptively.
1217
+
1218
+ The core outbox is poll-only across the FFI, so some poll cadence is
1219
+ unavoidable. A fixed cadence puts up to a full interval in front of
1220
+ every frame (the dominant single-call latency), while a standing tight
1221
+ poll burns CPU on a quiet link. Three rules bound both costs:
1222
+
1223
+ * A drain that moved frames re-drains after one yield, so a burst
1224
+ empties at event-loop speed.
1225
+ * An empty drain waits on ``_send_wake`` (set by the receive loop on
1226
+ every inbound frame) with a timeout that doubles from
1227
+ ``_SEND_MIN_POLL_INTERVAL`` up to ``_MESSAGE_POLL_INTERVAL``. The
1228
+ wake ships a reply within milliseconds of the frame that provoked
1229
+ it; the doubling covers replies queued slightly later (from a
1230
+ worker thread) and converges to one poll per idle interval when
1231
+ the link is genuinely quiet.
1232
+ * When the send-concurrency slots are saturated the drain reports 0
1233
+ without touching the FFI, so backpressure ramps the wait up
1234
+ instead of busy-spinning; the next drain that moves frames resets
1235
+ it to the floor.
1236
+
1237
+ A locally-queued send with no inbound trigger still waits at most one
1238
+ idle interval, exactly as it did when the cadence was fixed.
1239
+ """
1240
+ try:
1241
+ delay = _MESSAGE_POLL_INTERVAL
1242
+ while self._connected and self._authenticated:
1243
+ self._send_wake.clear()
1244
+ drained = self._poll_and_send_messages()
1245
+ if drained > 0:
1246
+ # Yield once so the send tasks just created get scheduled,
1247
+ # then re-drain immediately.
1248
+ delay = _SEND_MIN_POLL_INTERVAL
1249
+ await asyncio.sleep(0)
1250
+ continue
1251
+ woken = await self._wait_for_send_wake(delay)
1252
+ delay = self._next_send_delay(delay, active=woken)
1253
+ except asyncio.CancelledError:
1254
+ return
1255
+
1256
+ async def _wait_for_send_wake(self, timeout: float) -> bool:
1257
+ """Wait until an inbound frame wakes the send loop, or *timeout* passes.
1258
+
1259
+ Returns True when woken (activity), False on a quiet timeout.
1260
+ """
1261
+ try:
1262
+ await asyncio.wait_for(self._send_wake.wait(), timeout=timeout)
1263
+ except asyncio.TimeoutError:
1264
+ return False
1265
+ return True
1266
+
1267
+ @staticmethod
1268
+ def _next_send_delay(prev: float, active: bool) -> float:
1269
+ """The send loop's next wait timeout after one empty drain pass.
1270
+
1271
+ Activity (an inbound-frame wake) resets the ramp to the floor so an
1272
+ imminently-queued reply is picked up within a few ms; each quiet pass
1273
+ doubles the wait, capped at the idle interval.
1274
+ """
1275
+ if active:
1276
+ return _SEND_MIN_POLL_INTERVAL
1277
+ return min(prev * 2.0, _MESSAGE_POLL_INTERVAL)
1278
+
1279
+ def _poll_and_send_messages(self) -> int:
1280
+ """Drain outgoing messages from the protocol and send them.
1281
+
1282
+ Only dequeues up to the number of available semaphore slots to
1283
+ prevent unbounded task creation when the protocol core has a large
1284
+ outbox. Remaining messages will be picked up on the next poll tick.
1285
+ Returns the number of frames drained this call so the caller can
1286
+ re-drain immediately under load instead of waiting a fixed interval.
1287
+ """
1288
+ # Drop in-flight tracker entries older than the TTL. Time-gated: the
1289
+ # adaptive send loop calls this at event-loop speed during a burst,
1290
+ # and the sweep, which walks every tracked recipient, was sized for
1291
+ # the old fixed 10 Hz tick.
1292
+ now_ms = self._now_ms()
1293
+ if now_ms - self._last_prune_ms >= _PRUNE_MIN_INTERVAL_MS:
1294
+ self._inflight.prune(now_ms)
1295
+ self._last_prune_ms = now_ms
1296
+
1297
+ # Limit to available concurrency slots to avoid creating thousands
1298
+ # of tasks that all block on the semaphore.
1299
+ available_slots = max(0, _MAX_CONCURRENT_SENDS - len(self._send_tasks))
1300
+ drained = 0
1301
+ while drained < available_slots:
1302
+ try:
1303
+ msg = self._protocol.internet_get_next_message()
1304
+ except (AttributeError, ReferenceError) as exc:
1305
+ logger.error("Protocol instance invalid: %s", exc)
1306
+ break
1307
+ except Exception as exc:
1308
+ logger.warning("Unexpected error polling outgoing messages: %s", exc)
1309
+ break
1310
+ if msg is None:
1311
+ break
1312
+
1313
+ message_id = msg.message_id
1314
+ recipient = msg.recipient_id
1315
+ data = bytes(msg.data)
1316
+
1317
+ task = asyncio.ensure_future(
1318
+ self._send_message(message_id, recipient, data)
1319
+ )
1320
+ self._send_tasks.add(task)
1321
+ task.add_done_callback(self._send_tasks.discard)
1322
+ drained += 1
1323
+
1324
+ return drained
1325
+
1326
+ @staticmethod
1327
+ def _now_ms() -> int:
1328
+ return int(time.monotonic() * 1000)
1329
+
1330
+ def _notify_send_failed(self, message_id: str, reason: str) -> None:
1331
+ """Best-effort notification to the protocol that a send failed."""
1332
+ try:
1333
+ self._protocol.internet_send_failed_with_reason(
1334
+ message_id=message_id, reason=reason
1335
+ )
1336
+ except Exception:
1337
+ try:
1338
+ self._protocol.internet_send_failed(message_id=message_id)
1339
+ except Exception:
1340
+ logger.debug("internet_send_failed also failed", exc_info=True)
1341
+
1342
+ async def _send_message(
1343
+ self, message_id: str, recipient: str, data: bytes
1344
+ ) -> None:
1345
+ ws = self._ws
1346
+ if ws is None or not self._connected:
1347
+ self._notify_send_failed(message_id, "Not connected")
1348
+ return
1349
+
1350
+ async with self._send_semaphore:
1351
+ # Re-check after yielding to the semaphore — connection may have
1352
+ # been torn down while we were waiting for a slot.
1353
+ ws = self._ws
1354
+ if ws is None or not self._connected:
1355
+ self._notify_send_failed(message_id, "Disconnected while waiting")
1356
+ return
1357
+
1358
+ recorded = False
1359
+ try:
1360
+ try:
1361
+ content = data.decode("utf-8")
1362
+ except UnicodeDecodeError:
1363
+ content = base64.b64encode(data).decode("ascii")
1364
+ # message_id is the core's outbox id, stable across retries
1365
+ # of the same logical message. The relay echoes it in
1366
+ # MessageReceived / MessageSent / DeliveryError and its push
1367
+ # payload, and uses it to suppress duplicate push
1368
+ # notifications when an un-ACKed message is retried against
1369
+ # a still-offline recipient. Older relays ignore the extra
1370
+ # field. Mirrors the Kotlin and Swift bridges.
1371
+ payload = json.dumps({
1372
+ "type": "SendMessage",
1373
+ "recipient": recipient,
1374
+ "content": content,
1375
+ "message_id": message_id,
1376
+ })
1377
+ # Record the wire send BEFORE awaiting it: `await ws.send` can
1378
+ # suspend (websockets drains under backpressure — the exact
1379
+ # high-load path this correlation exists for), and a relay
1380
+ # MessageSent/DeliveryError for this frame can be processed on
1381
+ # the recv task before we resume. The entry must already be
1382
+ # present so MessageSent resolves the exact id (rather than
1383
+ # best-effort popping a different still-stuck one) and a
1384
+ # DeliveryError finds it. If the send raises, the except path
1385
+ # unrecords it. Mirrors the iOS/Android record-before-write.
1386
+ if recipient and message_id:
1387
+ self._inflight.record_sent(recipient, message_id, self._now_ms())
1388
+ recorded = True
1389
+ await ws.send(payload)
1390
+ # The frame is on the wire now. From here `unrecord` must NOT
1391
+ # fire: the entry is genuinely in flight, and a later relay
1392
+ # DeliveryError needs it to fast-fail. Clear the flag before any
1393
+ # subsequent line (counters, the internet_confirm_sent FFI call)
1394
+ # can raise, so only a failure of `await ws.send` itself — where
1395
+ # the frame never left — takes the entry back.
1396
+ recorded = False
1397
+ self._bytes_sent += len(payload)
1398
+ self._messages_sent += 1
1399
+ self._consecutive_send_failures = 0
1400
+
1401
+ self._protocol.internet_confirm_sent(message_id=message_id)
1402
+
1403
+ except Exception as exc:
1404
+ # The frame never reached the wire; take back the optimistic
1405
+ # in-flight entry so a later recipient-keyed DeliveryError does
1406
+ # not false-fail a message that was never sent. (Only reachable
1407
+ # for a pre-wire failure; a post-wire raise leaves it in flight.)
1408
+ if recorded:
1409
+ self._inflight.unrecord(recipient, message_id)
1410
+ self._consecutive_send_failures += 1
1411
+ self._emit_diagnostic("error", f"Send failed: {exc}", {
1412
+ "message_id": message_id,
1413
+ "consecutive_failures": self._consecutive_send_failures,
1414
+ })
1415
+ self._notify_send_failed(message_id, str(exc))
1416
+
1417
+ if self._consecutive_send_failures >= _MAX_CONSECUTIVE_FAILURES:
1418
+ self._emit_diagnostic(
1419
+ "error", "Too many consecutive send failures, disconnecting"
1420
+ )
1421
+ await self._handle_connection_closed(exc)
1422
+
1423
+ # -- ping loop ------------------------------------------------------------
1424
+
1425
+ async def _ping_loop(self) -> None:
1426
+ """Send WebSocket pings at regular intervals."""
1427
+ try:
1428
+ while self._connected and self._authenticated:
1429
+ await asyncio.sleep(_PING_INTERVAL)
1430
+ if self._ws is not None:
1431
+ try:
1432
+ await self._ws.ping()
1433
+ self._consecutive_ping_failures = 0
1434
+ except Exception:
1435
+ self._consecutive_ping_failures += 1
1436
+ if self._consecutive_ping_failures >= _MAX_CONSECUTIVE_FAILURES:
1437
+ self._emit_diagnostic(
1438
+ "error",
1439
+ "Too many ping failures, disconnecting",
1440
+ )
1441
+ await self._handle_connection_closed(None)
1442
+ return
1443
+ except asyncio.CancelledError:
1444
+ return