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,1217 @@
1
+ """A gateway daemon client for the ``reticulum`` transport slot.
2
+
3
+ Speaks the gateway-daemon contract (``docs/spec/gateway-contract.md``) over
4
+ TCP to a daemon on local IP: newline-delimited JSON, an attach that binds
5
+ the session to this device's address, one verdict per submitted frame, and
6
+ presence for the peers the core is waiting to hear about. What answers on
7
+ the far end is a daemon built to that contract; this module is the device
8
+ half.
9
+
10
+ A port of ``ReticulumManager.swift`` (the port source) and
11
+ ``ReticulumManager.kt``, over asyncio. The decisions and frame shapes live
12
+ in ``gateway_attach_policy.py``; what is here is the socket, the tasks and
13
+ the lifecycle.
14
+
15
+ Invariants this manager keeps, each of which was a defect on some earlier
16
+ client of this contract:
17
+
18
+ * **The carrier is announced only for a bound session, and in the
19
+ contract's order.** ``reticulum_status_changed(True)`` is called from one
20
+ place, on ``StatusUpdate(connected)``, and only after the gateway echoed
21
+ our own address back. Its capabilities are handed to the core on their own
22
+ frame, which the contract puts before the announcement, so on a conforming
23
+ gateway the flush the announcement triggers sees them. A session the
24
+ gateway never bound is verdict-only on the other side: it may submit and
25
+ be told ``attach_required``, and nothing addressed to this device ever
26
+ arrives over it. Offering that to the selector would be offering a
27
+ transport that can only refuse.
28
+ * **The write is not the outcome.** A frame is confirmed or failed on the
29
+ gateway's verdict, correlated by id, never on the socket write. Confirming
30
+ on the write is what the first bridges did, and it is why
31
+ ``recipient_unreachable``, the one verdict that parks a message and offers
32
+ it to the mesh, never reached the core from them.
33
+ * **Every frame in flight is owed an outcome.** A connection that closes
34
+ fails what it was carrying, and a gateway that answers nothing is failed
35
+ at the verdict timeout, which stays under the core's own expiry.
36
+ * **A session generation is checked after every suspension.** Each socket
37
+ claims a fresh generation and every handler captures it, because an
38
+ ``await`` can resume after the socket that carried the frame is gone and
39
+ its successor is up. A stale ``StatusUpdate(connected)`` acted on then
40
+ would announce the successor before the gateway bound it; a stale
41
+ ``Challenge`` would sign the old challenge onto the new socket.
42
+ * **The reconnect ladder resets only on a bound and announced session.** A
43
+ TCP open proves that something is listening; the handshake that follows
44
+ has four places left to fail. Reset on the open, a refusing gateway was
45
+ retried at the floor forever.
46
+
47
+ The module names no signing domain: the proof is built in the core behind
48
+ ``gateway_address_declaration``, and a Rust guard reads this file to keep
49
+ it that way.
50
+ """
51
+
52
+ from __future__ import annotations
53
+
54
+ import asyncio
55
+ import base64
56
+ import binascii
57
+ import json
58
+ import logging
59
+ import time
60
+ from typing import Any, Coroutine
61
+
62
+ from . import gateway_attach_policy as policy
63
+ from .gateway_verdict_tracker import GatewayVerdictTracker
64
+ from .presence_watch_policy import DEFAULT_TICK_INTERVAL, PresenceWatchPolicy
65
+ from .transport_manager import TransportError, TransportManager, TransportState
66
+
67
+ logger = logging.getLogger(__name__)
68
+
69
+ #: Fallback drain cadence, in seconds. The primary send path is the core's
70
+ #: wake (``on_messages_available``); this tick is what runs the verdict
71
+ #: sweep and catches a wake that was lost to a pause.
72
+ MESSAGE_POLL_INTERVAL = 5.0
73
+ RECONNECT_INITIAL_DELAY = 1.0
74
+ RECONNECT_MAX_DELAY = 30.0
75
+ RECONNECT_BACKOFF_MULTIPLIER = 2.0
76
+ #: Seconds the TCP open may take. Long, because the address may be a
77
+ #: gateway box on venue Wi-Fi rather than this host; the attach that follows
78
+ #: has its own, much shorter, deadline.
79
+ CONNECTION_TIMEOUT = 60.0
80
+ MAX_CONSECUTIVE_FAILURES = 3
81
+ #: Frames handed to the gateway per drain pass, before yielding.
82
+ MAX_BATCH_SIZE = 10
83
+ DEFAULT_DAEMON_ADDRESS = "localhost:4242"
84
+
85
+ _LOCALHOST_ALIASES = frozenset({"localhost", "127.0.0.1", "::1"})
86
+
87
+
88
+ def parse_daemon_address(daemon_address: str) -> tuple[str, int]:
89
+ """``host:port``, ``[v6]:port``, or a bare host with the default port."""
90
+ text = daemon_address.strip() or DEFAULT_DAEMON_ADDRESS
91
+ default_port = int(DEFAULT_DAEMON_ADDRESS.rsplit(":", 1)[1])
92
+ if text.startswith("["):
93
+ host, _, rest = text[1:].partition("]")
94
+ port_text = rest[1:] if rest.startswith(":") else ""
95
+ elif text.count(":") == 1:
96
+ host, _, port_text = text.partition(":")
97
+ else:
98
+ host, port_text = text, ""
99
+ host = host or "localhost"
100
+ if not port_text:
101
+ return host, default_port
102
+ try:
103
+ port = int(port_text)
104
+ except ValueError:
105
+ raise ValueError(f"daemon address {daemon_address!r} has no numeric port") from None
106
+ if not 0 < port < 65536:
107
+ raise ValueError(f"daemon address {daemon_address!r} has an out-of-range port")
108
+ return host, port
109
+
110
+
111
+ class GatewayManager(TransportManager):
112
+ """The gateway-daemon client behind the ``reticulum`` slot.
113
+
114
+ Parameters
115
+ ----------
116
+ protocol:
117
+ The ``OfflineProtocol`` UniFFI instance.
118
+ device_id:
119
+ What ``Identify`` carries when this device has no address yet. The
120
+ address is used once there is one; only ``DeclareAddress`` binds
121
+ either way.
122
+
123
+ Configure with :meth:`configure` and start after
124
+ ``ProtocolManager.start()``, once this device has an identity to
125
+ declare; ``ProtocolManager.stop()`` stops it with everything else.
126
+ """
127
+
128
+ transport_id = "reticulum"
129
+ transport_name = "Gateway daemon (the reticulum slot)"
130
+
131
+ def __init__(self, protocol: Any, device_id: str) -> None:
132
+ super().__init__()
133
+ self._protocol = protocol
134
+ self._device_id = device_id
135
+ self._daemon_host = "localhost"
136
+ self._daemon_port = 4242
137
+ self._auto_reconnect = True
138
+ self._max_reconnect_attempts = 0
139
+ self._configured = False
140
+
141
+ self._loop: asyncio.AbstractEventLoop | None = None
142
+ self._reader: asyncio.StreamReader | None = None
143
+ self._writer: asyncio.StreamWriter | None = None
144
+
145
+ # Which gateway session the current socket belongs to. Bumped when a
146
+ # connect claims the flags and on every retire, so a socket never
147
+ # shares a number with the one it replaces.
148
+ self._generation = 0
149
+ self._connected = False
150
+ self._connecting = False
151
+ # True once the gateway has echoed our own address back. This, not
152
+ # the TCP connection, is what makes the carrier usable.
153
+ self._bound = False
154
+ self._paused = False
155
+
156
+ self._reconnect_attempts = 0
157
+ self._current_reconnect_delay = RECONNECT_INITIAL_DELAY
158
+ self._consecutive_send_failures = 0
159
+
160
+ self._verdicts = GatewayVerdictTracker()
161
+ self._presence_watch = PresenceWatchPolicy()
162
+
163
+ self._recv_task: asyncio.Task[None] | None = None
164
+ self._poll_task: asyncio.Task[None] | None = None
165
+ self._presence_task: asyncio.Task[None] | None = None
166
+ self._connect_task: asyncio.Task[None] | None = None
167
+ self._drain_task: asyncio.Task[None] | None = None
168
+ self._drain_again = False
169
+ self._drain_lock = asyncio.Lock()
170
+ self._reconnect_handle: asyncio.TimerHandle | None = None
171
+ self._attach_timeout_handle: asyncio.TimerHandle | None = None
172
+
173
+ self._messages_sent = 0
174
+ self._messages_received = 0
175
+
176
+ # -- configuration --------------------------------------------------------
177
+
178
+ def configure(
179
+ self,
180
+ daemon_address: str = DEFAULT_DAEMON_ADDRESS,
181
+ auto_reconnect: bool = True,
182
+ max_reconnect_attempts: int = 0,
183
+ ) -> None:
184
+ """Where the daemon listens, as ``host:port`` (default
185
+ ``localhost:4242``). ``max_reconnect_attempts`` of 0 means
186
+ unbounded."""
187
+ self._daemon_host, self._daemon_port = parse_daemon_address(daemon_address)
188
+ self._auto_reconnect = auto_reconnect
189
+ self._max_reconnect_attempts = max_reconnect_attempts
190
+ if self._daemon_host not in _LOCALHOST_ALIASES:
191
+ # The TCP link is unencrypted: the daemon sees ciphertext and
192
+ # routing metadata either way, but a non-local link exposes the
193
+ # attach and the verdicts to the path.
194
+ self._emit_diagnostic(
195
+ "warning",
196
+ "Gateway daemon is not on localhost; the TCP connection is unencrypted",
197
+ {"daemon_host": self._daemon_host},
198
+ )
199
+ self._configured = True
200
+ self._emit_diagnostic(
201
+ "info",
202
+ "Gateway transport configured",
203
+ {
204
+ "daemon_host": self._daemon_host,
205
+ "daemon_port": self._daemon_port,
206
+ "auto_reconnect": auto_reconnect,
207
+ "max_reconnect_attempts": max_reconnect_attempts,
208
+ },
209
+ )
210
+
211
+ @property
212
+ def bound(self) -> bool:
213
+ """True while the gateway holds this session bound to our address."""
214
+ return self._bound
215
+
216
+ # -- TransportManager interface -------------------------------------------
217
+
218
+ def is_available(self) -> bool:
219
+ # Only after configure(), so the selector is never offered an
220
+ # unconfigured gateway transport.
221
+ return self._configured
222
+
223
+ async def start(self) -> None:
224
+ if self._state in (TransportState.RUNNING, TransportState.STARTING):
225
+ raise TransportError("Gateway transport is already running")
226
+ if not self._configured:
227
+ raise TransportError(
228
+ "Daemon address not configured. Call configure(daemon_address=...) first."
229
+ )
230
+ self._loop = asyncio.get_running_loop()
231
+ # An explicit start() means "run": a pause() from a previous session
232
+ # must not leave this fresh transport connected-but-mute.
233
+ self._paused = False
234
+ self._emit_diagnostic(
235
+ "info",
236
+ "Starting gateway transport",
237
+ {"device_id": self._device_id, "daemon": f"{self._daemon_host}:{self._daemon_port}"},
238
+ )
239
+ self._update_state(TransportState.STARTING)
240
+ self._spawn_connect()
241
+
242
+ async def stop(self) -> None:
243
+ # STOPPING too: a stop() cancelled part-way (a shutdown deadline)
244
+ # leaves the transport there, and a retry that returned at once would
245
+ # leave it half torn down for good. Every step below is idempotent.
246
+ if self._state not in (
247
+ TransportState.RUNNING,
248
+ TransportState.STARTING,
249
+ TransportState.STOPPING,
250
+ ):
251
+ return
252
+ self._update_state(TransportState.STOPPING)
253
+
254
+ if self._reconnect_handle is not None:
255
+ self._reconnect_handle.cancel()
256
+ self._reconnect_handle = None
257
+ pending = [
258
+ task
259
+ for task in (
260
+ self._connect_task,
261
+ self._drain_task,
262
+ self._poll_task,
263
+ self._presence_task,
264
+ )
265
+ if task is not None and not task.done()
266
+ ]
267
+ for task in (self._connect_task, self._drain_task):
268
+ if task is not None and not task.done():
269
+ task.cancel()
270
+ self._connect_task = None
271
+ self._drain_task = None
272
+
273
+ self._stop_polling()
274
+ # Closes the socket and retires the session: every id in flight is
275
+ # failed with a reason, the presence watch stops, the attach timeout
276
+ # is disarmed.
277
+ recv = self._disconnect("Disconnected")
278
+ if recv is not None:
279
+ pending.append(recv)
280
+ if pending:
281
+ await asyncio.gather(*pending, return_exceptions=True)
282
+
283
+ # Told to the core after the session is retired, in the order the
284
+ # Swift manager keeps: the false lands after any true this session
285
+ # announced, which is the correct final answer.
286
+ try:
287
+ self._protocol.reticulum_status_changed(is_connected=False)
288
+ except Exception:
289
+ logger.debug("reticulum_status_changed(False) failed", exc_info=True)
290
+
291
+ self._update_state(TransportState.STOPPED)
292
+ self._emit_diagnostic("info", "Gateway transport stopped")
293
+
294
+ async def pause(self) -> None:
295
+ # Set before the tasks are cancelled, and read by every path that
296
+ # would re-arm them: the reconnect edge and the core's wake.
297
+ self._paused = True
298
+ self._stop_polling()
299
+ # A backgrounded host must not keep spending on presence ticks; the
300
+ # watchlist is rebuilt from the core after resume().
301
+ self._stop_presence_watch()
302
+
303
+ async def resume(self) -> None:
304
+ self._paused = False
305
+ if self._state == TransportState.RUNNING and self._connected:
306
+ self._start_polling()
307
+ # Only a bound session has anyone to ask. An unbound one is not
308
+ # announced as a carrier either, so nothing waits on its answers.
309
+ if self._bound:
310
+ self._start_presence_watch()
311
+ # Drains whatever queued during the pause: the core does not
312
+ # re-issue its wake for messages it already announced.
313
+ self._schedule_drain()
314
+
315
+ def get_metrics(self) -> dict[str, Any]:
316
+ return {
317
+ "messages_sent": self._messages_sent,
318
+ "messages_received": self._messages_received,
319
+ "in_flight": self._verdicts.count,
320
+ "is_connected": self._connected,
321
+ "is_bound": self._bound,
322
+ "reconnect_attempts": self._reconnect_attempts,
323
+ }
324
+
325
+ # -- the core's wake ------------------------------------------------------
326
+
327
+ def on_messages_available(self) -> None:
328
+ """``ReticulumTransportCallback.on_messages_available``: the core
329
+ queued a frame for this carrier.
330
+
331
+ The *primary* send path; the poll tick is the fallback. Invoked from
332
+ a Rust callback thread, so the drain is scheduled onto the event
333
+ loop rather than run here. Carries the pause check itself: without
334
+ it a paused transport still drained a batch per wake for as long as
335
+ the core kept announcing. The frames are not lost; they stay queued
336
+ in the core and ``resume()`` drains them.
337
+ """
338
+ if self._paused:
339
+ return
340
+ self._schedule_drain()
341
+
342
+ def _schedule_drain(self) -> None:
343
+ loop = self._loop
344
+ if loop is not None and not loop.is_closed() and loop.is_running():
345
+ loop.call_soon_threadsafe(self._drain_soon)
346
+
347
+ def _drain_soon(self) -> None:
348
+ if self._drain_task is not None and not self._drain_task.done():
349
+ # One drain at a time; a wake that lands mid-drain runs another
350
+ # pass afterwards rather than a second concurrent one.
351
+ self._drain_again = True
352
+ return
353
+ self._drain_task = self._spawn(self._drain_until_quiet())
354
+
355
+ async def _drain_until_quiet(self) -> None:
356
+ while True:
357
+ self._drain_again = False
358
+ await self._poll_and_send()
359
+ if not self._drain_again:
360
+ return
361
+
362
+ # -- connection management ------------------------------------------------
363
+
364
+ def _spawn(self, coro: Coroutine[Any, Any, None]) -> asyncio.Task[None]:
365
+ return asyncio.ensure_future(coro)
366
+
367
+ def _spawn_connect(self) -> None:
368
+ if self._connect_task is not None and not self._connect_task.done():
369
+ return
370
+ self._connect_task = self._spawn(self._connect())
371
+
372
+ async def _connect(self) -> None:
373
+ # The attempt takes a fresh session generation as it claims the
374
+ # flags, so a socket never shares a number with the one it replaces
375
+ # even if nothing retired the predecessor in between.
376
+ if self._connecting or self._connected:
377
+ return
378
+ self._connecting = True
379
+ self._generation += 1
380
+ generation = self._generation
381
+
382
+ self._emit_diagnostic(
383
+ "info",
384
+ "Connecting to the gateway daemon",
385
+ {"host": self._daemon_host, "port": self._daemon_port},
386
+ )
387
+ try:
388
+ reader, writer = await asyncio.wait_for(
389
+ asyncio.open_connection(
390
+ self._daemon_host,
391
+ self._daemon_port,
392
+ limit=policy.MAX_LINE_BYTES,
393
+ ),
394
+ timeout=CONNECTION_TIMEOUT,
395
+ )
396
+ except asyncio.CancelledError:
397
+ raise
398
+ except Exception as exc:
399
+ self._emit_diagnostic("error", "Gateway connection failed", {"error": str(exc)})
400
+ self._handle_connection_closed(generation, exc)
401
+ return
402
+
403
+ # The claim refuses a late open for a session a stop() or a timeout
404
+ # already retired; either way the socket is stray.
405
+ if self._generation != generation:
406
+ writer.close()
407
+ return
408
+ self._connected = True
409
+ self._connecting = False
410
+ self._reader, self._writer = reader, writer
411
+ self._consecutive_send_failures = 0
412
+ # Not a backoff reset. A TCP open proves only that something is
413
+ # listening; the handshake that follows has four places left to
414
+ # fail, and every one of them reconnects. Reset here, a refusing
415
+ # gateway was retried at the floor forever, with a challenge, a
416
+ # signature and two events spent per turn, and
417
+ # `max_reconnect_attempts` never tripped because the count went back
418
+ # to zero each time. The reset lives in `_complete_attach`, on the
419
+ # bound session.
420
+ self._emit_diagnostic("info", "Connected to the gateway daemon")
421
+
422
+ self._recv_task = self._spawn(self._receive_loop(reader, generation))
423
+
424
+ # `device_id` is this device's address where there is one. The first
425
+ # clients sent the profile, a local storage-namespace selector that
426
+ # is not an identity in any namespace the gateway knows; it was
427
+ # logged and never routed on. Only `DeclareAddress` binds either way.
428
+ identity = self._local_address() or self._device_id
429
+ if not await self._write_line(policy.identify_json(identity), generation):
430
+ self._handle_connection_closed(generation, None)
431
+ return
432
+ # Checked again after the write suspended: a session retired in
433
+ # between belongs to nothing this attempt should touch.
434
+ if self._generation != generation:
435
+ return
436
+ self._arm_attach_timeout(generation)
437
+
438
+ # A stop() that landed while this connection was being established
439
+ # has already told the core we are down and moved to STOPPED.
440
+ # Announcing now would put the state back to RUNNING against a
441
+ # transport nothing will ever tear down again. The socket is stray.
442
+ if self._state in (TransportState.STOPPING, TransportState.STOPPED):
443
+ self._disconnect("Disconnected")
444
+ return
445
+ self._update_state(TransportState.RUNNING)
446
+ # Skipped while paused: a daemon that drops and reconnects during a
447
+ # background stay reaches here, and this is the durable half of what
448
+ # `_paused` closes. No status flip here: the carrier is announced in
449
+ # `_complete_attach`, on a bound session.
450
+ if not self._paused:
451
+ self._start_polling()
452
+
453
+ def _disconnect(self, reason: str) -> asyncio.Task[None] | None:
454
+ """Closes the socket and ends the session it carried. Returns the
455
+ receive task, if one is still running, for the caller to await."""
456
+ recv = self._close_socket()
457
+ self._connected = False
458
+ self._connecting = False
459
+ self._retire_session(reason)
460
+ return recv
461
+
462
+ def _close_socket(self) -> asyncio.Task[None] | None:
463
+ writer = self._writer
464
+ self._reader = None
465
+ self._writer = None
466
+ if writer is not None:
467
+ try:
468
+ writer.close()
469
+ except Exception:
470
+ logger.debug("closing the gateway socket raised", exc_info=True)
471
+ recv = self._recv_task
472
+ self._recv_task = None
473
+ if recv is not None and not recv.done() and recv is not asyncio.current_task():
474
+ recv.cancel()
475
+ return recv
476
+ return None
477
+
478
+ def _retire_session(self, reason: str) -> None:
479
+ """Ends the gateway session the current socket carried, whether this
480
+ side is closing the socket or the socket has already gone.
481
+
482
+ Shared by every close path so that all of them run it. Before it
483
+ was shared, a daemon-side drop ran none of it: the session stayed
484
+ bound for the successor to inherit, which defeated the attach
485
+ timeout, the presence watch kept writing to a dead socket, and the
486
+ ids in flight were never failed, so the core waited out its own
487
+ expiry on each.
488
+ """
489
+ self._generation += 1
490
+ self._bound = False
491
+ self._cancel_attach_timeout()
492
+ self._stop_presence_watch()
493
+ self._fail_in_flight(reason)
494
+
495
+ def _handle_connection_closed(self, generation: int, error: BaseException | None) -> None:
496
+ """Ends the session ``generation`` names, if it is still the current
497
+ one. A report for a session that is already over is dropped before
498
+ it touches the flags: a stale close would otherwise clear
499
+ ``_connected`` under a healthy successor, tell the core the
500
+ transport is down, and start a reconnect ladder against it."""
501
+ if self._generation != generation:
502
+ return
503
+ was_connected = self._connected
504
+ was_connecting = self._connecting
505
+ self._connected = False
506
+ self._connecting = False
507
+ if not (was_connected or was_connecting):
508
+ return
509
+
510
+ # The socket goes now, not when the reconnect fires. A refused or
511
+ # mismatched session is still open on the gateway's side and it
512
+ # keeps sending on it, including, after its grace, the
513
+ # `StatusUpdate(connected)` of a session it never bound.
514
+ self._close_socket()
515
+ self._retire_session("Connection lost")
516
+ self._stop_polling()
517
+
518
+ self._emit_diagnostic(
519
+ "warning",
520
+ "Gateway daemon disconnected",
521
+ {"error": str(error) if error else "none", "was_connected": was_connected},
522
+ )
523
+ try:
524
+ self._protocol.reticulum_status_changed(is_connected=False)
525
+ except Exception:
526
+ logger.debug("reticulum_status_changed(False) failed", exc_info=True)
527
+
528
+ if self._auto_reconnect and self._state not in (
529
+ TransportState.STOPPING,
530
+ TransportState.STOPPED,
531
+ ):
532
+ self._schedule_reconnect()
533
+ else:
534
+ self._update_state(TransportState.STOPPED)
535
+
536
+ def _schedule_reconnect(self) -> None:
537
+ if not self._auto_reconnect:
538
+ return
539
+ if (
540
+ self._max_reconnect_attempts > 0
541
+ and self._reconnect_attempts >= self._max_reconnect_attempts
542
+ ):
543
+ self._emit_diagnostic(
544
+ "error",
545
+ "Max reconnect attempts reached",
546
+ {"attempts": self._reconnect_attempts, "max_attempts": self._max_reconnect_attempts},
547
+ )
548
+ self._update_state(TransportState.STOPPED)
549
+ return
550
+
551
+ self._reconnect_attempts += 1
552
+ delay = self._current_reconnect_delay
553
+ self._current_reconnect_delay = min(
554
+ self._current_reconnect_delay * RECONNECT_BACKOFF_MULTIPLIER,
555
+ RECONNECT_MAX_DELAY,
556
+ )
557
+ self._update_state(TransportState.STARTING)
558
+ self._emit_diagnostic(
559
+ "info",
560
+ "Scheduling reconnect to the gateway daemon",
561
+ {"attempt": self._reconnect_attempts, "delay_seconds": delay},
562
+ )
563
+ loop = self._loop
564
+ if loop is None or loop.is_closed() or not loop.is_running():
565
+ self._emit_diagnostic("warning", "No running event loop for reconnect")
566
+ self._update_state(TransportState.STOPPED)
567
+ return
568
+ if self._reconnect_handle is not None:
569
+ self._reconnect_handle.cancel()
570
+ self._reconnect_handle = loop.call_later(delay, self._reconnect_now)
571
+
572
+ def _reconnect_now(self) -> None:
573
+ self._reconnect_handle = None
574
+ if self._state in (TransportState.STOPPING, TransportState.STOPPED):
575
+ return
576
+ self._spawn_connect()
577
+
578
+ # -- the attach timeout ---------------------------------------------------
579
+
580
+ def _arm_attach_timeout(self, generation: int) -> None:
581
+ """Bounds the handshake. Disarmed by ``StatusUpdate(connected)`` and
582
+ by a teardown, and by nothing else: it is not gated on the bind,
583
+ because a gateway that binds and then never announces is exactly
584
+ the wedge this exists to end."""
585
+ self._cancel_attach_timeout()
586
+ loop = self._loop
587
+ if loop is None:
588
+ return
589
+ self._attach_timeout_handle = loop.call_later(
590
+ policy.ATTACH_TIMEOUT, self._attach_timed_out, generation
591
+ )
592
+
593
+ def _cancel_attach_timeout(self) -> None:
594
+ handle = self._attach_timeout_handle
595
+ self._attach_timeout_handle = None
596
+ if handle is not None:
597
+ handle.cancel()
598
+
599
+ def _attach_timed_out(self, generation: int) -> None:
600
+ self._attach_timeout_handle = None
601
+ if not self._connected or self._generation != generation:
602
+ return
603
+ self._emit_diagnostic("error", "Gateway attach timed out before StatusUpdate(connected)")
604
+ self._handle_connection_closed(generation, None)
605
+
606
+ # -- receiving --------------------------------------------------------------
607
+
608
+ async def _receive_loop(self, reader: asyncio.StreamReader, generation: int) -> None:
609
+ """Reads frames off ``reader`` for the session ``generation`` names.
610
+
611
+ The generation is the one this socket was armed under: a handler
612
+ that closes the session ends the segment, and the lines after it
613
+ belong to a socket this side has retired.
614
+ """
615
+ try:
616
+ while self._generation == generation:
617
+ try:
618
+ line = await reader.readline()
619
+ except (asyncio.LimitOverrunError, ValueError):
620
+ # A partial line past the cap cannot be resynchronised:
621
+ # its tail would be read as a fresh line, so every frame
622
+ # after it is garbage. The connection goes instead.
623
+ self._emit_diagnostic(
624
+ "error",
625
+ "Over-long line from the gateway",
626
+ {"limit": policy.MAX_LINE_BYTES},
627
+ )
628
+ self._handle_connection_closed(generation, None)
629
+ return
630
+ except asyncio.CancelledError:
631
+ raise
632
+ except Exception as exc:
633
+ self._handle_connection_closed(generation, exc)
634
+ return
635
+ if not line:
636
+ self._handle_connection_closed(generation, None)
637
+ return
638
+ if self._generation != generation:
639
+ return
640
+ stripped = line.strip()
641
+ if not stripped:
642
+ continue
643
+ try:
644
+ await self._process_line(stripped, generation)
645
+ except asyncio.CancelledError:
646
+ raise
647
+ except Exception as exc:
648
+ # A handler that raises must not end this task quietly.
649
+ # Ended quietly, nothing retires the session: the flags
650
+ # stay up, the poll loop keeps submitting, every frame
651
+ # fails at the verdict timeout, and nothing addressed to
652
+ # this device is delivered again until stop(). The
653
+ # remote-triggerable causes are handled per field
654
+ # (`utf8_bytes`); this is the net for the rest, and the
655
+ # ladder brings a fresh session.
656
+ self._emit_diagnostic(
657
+ "error",
658
+ "Gateway frame handler raised",
659
+ {"error": str(exc), "type": type(exc).__name__},
660
+ )
661
+ self._handle_connection_closed(generation, exc)
662
+ return
663
+ except asyncio.CancelledError:
664
+ return
665
+
666
+ async def _process_line(self, line: bytes, generation: int) -> None:
667
+ try:
668
+ frame = json.loads(line)
669
+ except (json.JSONDecodeError, UnicodeDecodeError):
670
+ frame = None
671
+ if not isinstance(frame, dict) or not isinstance(frame.get("type"), str):
672
+ self._emit_diagnostic(
673
+ "warning",
674
+ "Received non-JSON data from the gateway daemon, skipping",
675
+ {"size": len(line)},
676
+ )
677
+ return
678
+ frame_type = frame["type"]
679
+
680
+ if frame_type == "MessageReceived":
681
+ self._handle_message_received(frame)
682
+ elif frame_type == "Challenge":
683
+ await self._handle_challenge(frame, generation)
684
+ elif frame_type == "AddressDeclared":
685
+ self._handle_address_declared(frame, generation)
686
+ elif frame_type == "AddressError":
687
+ self._handle_address_error(frame, generation)
688
+ elif frame_type == "Capabilities":
689
+ # Before the status flip, never after: the flush that flip
690
+ # triggers has to see them.
691
+ tokens = policy.capability_tokens(frame)
692
+ try:
693
+ self._protocol.reticulum_gateway_capabilities(capabilities=tokens)
694
+ except Exception as exc:
695
+ self._emit_diagnostic(
696
+ "error", "Gateway capability injection failed", {"error": str(exc)}
697
+ )
698
+ elif frame_type in ("MessageSent", "DeliveryError"):
699
+ self._handle_verdict(frame, frame_type)
700
+ elif frame_type == "PresenceStatus":
701
+ self._handle_presence(frame)
702
+ elif frame_type == "StatusUpdate":
703
+ status = frame.get("status")
704
+ self._emit_diagnostic("debug", "Gateway daemon status update", {"status": status})
705
+ if status == "connected":
706
+ # The gateway's half of the handshake is done, whatever is
707
+ # decided below about ours.
708
+ self._cancel_attach_timeout()
709
+ self._complete_attach(generation)
710
+ else:
711
+ self._emit_diagnostic("debug", "Unknown gateway message type", {"type": frame_type})
712
+
713
+ # -- the gateway handshake ------------------------------------------------
714
+
715
+ async def _handle_challenge(self, frame: dict[str, Any], generation: int) -> None:
716
+ """Signs the gateway's challenge and declares this device's address.
717
+
718
+ The signing happens in the core: this hands it the challenge and
719
+ gets back the three fields ``DeclareAddress`` carries. A failure
720
+ here is not retried on this connection: the gateway spends a
721
+ challenge per connection, and the next reconnect gets a fresh one.
722
+ """
723
+ outcome = policy.decode_challenge(frame)
724
+ if isinstance(outcome, policy.Skip):
725
+ self._emit_diagnostic(
726
+ "warning", "Cannot declare an address to the gateway", {"reason": outcome.reason}
727
+ )
728
+ self._handle_connection_closed(generation, None)
729
+ return
730
+ try:
731
+ declaration = self._protocol.gateway_address_declaration(list(outcome.challenge))
732
+ except Exception as exc:
733
+ # No identity yet, or a challenge the core refused to sign.
734
+ # Either way this connection can only ever be verdict-only, so
735
+ # it is not worth holding open.
736
+ self._emit_diagnostic(
737
+ "warning",
738
+ "Cannot build the address declaration",
739
+ {"reason": policy.SkipReason.SIGNING_FAILED, "error": str(exc)},
740
+ )
741
+ self._handle_connection_closed(generation, None)
742
+ return
743
+ line = policy.declaration_json(
744
+ declaration.address, bytes(declaration.public_key), bytes(declaration.signature)
745
+ )
746
+ if self._generation != generation:
747
+ return
748
+ if not await self._write_line(line, generation):
749
+ # A write that fails leaves no frame for the gateway to answer,
750
+ # and waiting out the attach timeout to learn that is ten
751
+ # seconds of a carrier the selector has been told nothing about.
752
+ self._emit_diagnostic("error", "Failed to write the address declaration")
753
+ self._handle_connection_closed(generation, None)
754
+
755
+ def _handle_address_declared(self, frame: dict[str, Any], generation: int) -> None:
756
+ """Checks what the gateway says it bound against what we hold.
757
+
758
+ Both answers go to the core, which owns the security warning; what
759
+ is decided here is narrower and is the manager's own: whether this
760
+ carrier can be offered to the selector at all.
761
+ """
762
+ declared = frame.get("address")
763
+ # Bounded before it reaches the core: the echo is remote-chosen and
764
+ # the line it arrived on may be a mebibyte.
765
+ encoded = policy.utf8_bytes(declared) if isinstance(declared, str) else None
766
+ if not declared or encoded is None or len(encoded) > policy.MAX_ADDRESS_BYTES:
767
+ self._emit_diagnostic(
768
+ "warning", "Invalid AddressDeclared: missing, over-long or unencodable address"
769
+ )
770
+ return
771
+ if self._generation != generation:
772
+ return
773
+ try:
774
+ self._protocol.reticulum_address_declared(address=declared)
775
+ except Exception:
776
+ logger.debug("reticulum_address_declared failed", exc_info=True)
777
+
778
+ outcome = policy.binding_outcome(declared, self._local_address())
779
+ if outcome is policy.BindingOutcome.BOUND:
780
+ # One step with the generation check: a teardown landing between
781
+ # a check and a set leaves the successor bound on an echo it
782
+ # never received.
783
+ if self._generation != generation:
784
+ return
785
+ self._bound = True
786
+ self._emit_diagnostic("info", "Gateway bound this session to our address")
787
+ else:
788
+ # The core has already reported this as a security warning. Here
789
+ # it costs the connection: a gateway that bound an address we do
790
+ # not control will attribute our frames to an identity we cannot
791
+ # prove and answer presence about someone else, and reconnecting
792
+ # is the only thing this side can do that might land somewhere
793
+ # honest.
794
+ self._emit_diagnostic("error", "Gateway bound a session to an address we do not hold")
795
+ self._handle_connection_closed(generation, None)
796
+
797
+ def _handle_address_error(self, frame: dict[str, Any], generation: int) -> None:
798
+ """The gateway refused the declaration, so this session can only be
799
+ told verdicts. The carrier is never announced; the connection goes
800
+ and the existing backoff decides when to try again."""
801
+ reason = frame.get("reason")
802
+ if not isinstance(reason, str) or not reason:
803
+ reason = "unspecified"
804
+ try:
805
+ self._protocol.reticulum_address_declaration_refused(reason=reason)
806
+ except Exception:
807
+ logger.debug("reticulum_address_declaration_refused failed", exc_info=True)
808
+ self._emit_diagnostic(
809
+ "warning",
810
+ "Gateway refused the address declaration",
811
+ {"reason": policy.bounded_reason(reason)},
812
+ )
813
+ self._handle_connection_closed(generation, None)
814
+
815
+ def _complete_attach(self, generation: int) -> None:
816
+ """Announces the carrier once the gateway has bound this session.
817
+
818
+ Called on ``StatusUpdate(connected)``, which the contract puts after
819
+ ``AddressDeclared`` and after ``Capabilities``, so by the time the
820
+ core is told this transport is available it has already been told
821
+ what the gateway can do, and the flush the false-to-true edge
822
+ triggers sees them.
823
+
824
+ A session the gateway refused to bind never reaches here: the
825
+ refusal closes the connection instead.
826
+ """
827
+ if self._generation != generation:
828
+ return
829
+ if not self._bound:
830
+ # A gateway that announces before it binds is not speaking the
831
+ # contract, and a session it never binds is verdict-only.
832
+ # Closing is the one action that can end somewhere usable.
833
+ self._emit_diagnostic("error", "Gateway reported connected before binding the session")
834
+ self._handle_connection_closed(generation, None)
835
+ return
836
+ if not self._connected or self._state in (
837
+ TransportState.STOPPING,
838
+ TransportState.STOPPED,
839
+ ):
840
+ return
841
+ try:
842
+ self._protocol.reticulum_status_changed(is_connected=True)
843
+ except Exception as exc:
844
+ self._emit_diagnostic("error", "Protocol notify failed", {"error": str(exc)})
845
+ # The gateway bound and announced this session: this, not the TCP
846
+ # open, is what proves the connection good and earns a backoff
847
+ # reset.
848
+ self._reconnect_attempts = 0
849
+ self._current_reconnect_delay = RECONNECT_INITIAL_DELAY
850
+ if self._paused:
851
+ return
852
+ self._start_presence_watch()
853
+ self._schedule_drain()
854
+
855
+ # -- verdicts ---------------------------------------------------------------
856
+
857
+ def _handle_verdict(self, frame: dict[str, Any], frame_type: str) -> None:
858
+ """Settles one submitted frame on the gateway's answer."""
859
+ verdict = policy.parse_verdict(frame, frame_type)
860
+ if verdict is None:
861
+ self._emit_diagnostic(
862
+ "warning", "Verdict with no message_id, ignored", {"type": frame_type}
863
+ )
864
+ return
865
+ if not self._verdicts.settle(verdict.message_id):
866
+ # Already settled: a duplicate, or an answer to a frame this
867
+ # connection timed out on. Reporting it again would settle an id
868
+ # the core has moved past.
869
+ return
870
+ report = policy.verdict_report(verdict)
871
+ # The three core calls below are wrapped for one exception only. A
872
+ # lone surrogate in a field the parser did not already sanitise is
873
+ # refused by the FFI as it lowers the string, and a gateway can put
874
+ # one in any field, so that costs the frame and never the session.
875
+ # Anything else the core raises is a core in a state this manager
876
+ # cannot reason about, and it propagates to the receive loop, which
877
+ # closes the session: re-attaching fails every id in flight, so the
878
+ # core hears an outcome for each rather than waiting out its expiry.
879
+ try:
880
+ if report.confirmed:
881
+ self._protocol.reticulum_confirm_sent(message_id=verdict.message_id)
882
+ else:
883
+ # Verbatim. The core classifies on the token and discards
884
+ # the rest at that boundary, so nothing here needs to
885
+ # understand the gateway's wording.
886
+ self._protocol.reticulum_send_failed_with_reason(
887
+ message_id=verdict.message_id, reason=report.reason
888
+ )
889
+ recipient = verdict.recipient
890
+ if report.watch_recipient and recipient and not self._is_self_peer(recipient):
891
+ # Watch them: the gateway pushes a PresenceStatus when a
892
+ # watched peer attaches, and that answer is what
893
+ # un-parks the message this verdict just parked. And
894
+ # feed the verdict in as presence: the core parks on the
895
+ # verdict already; this is what emits the
896
+ # `presence_updated(offline)` an app renders a header
897
+ # from, labelled with the carrier that answered. Never
898
+ # for self: the core drops that too, but a malformed
899
+ # self-addressed frame should not cost a watch slot.
900
+ self._presence_watch.watch(recipient, self._now_ms())
901
+ self._protocol.reticulum_peer_presence(
902
+ peer_id=recipient, online=False, last_seen_ms=None
903
+ )
904
+ except UnicodeEncodeError:
905
+ self._emit_diagnostic(
906
+ "warning", "Verdict with an unencodable field, dropped", {"type": frame_type}
907
+ )
908
+ # A verdict frees an in-flight slot, so the next frame goes out on
909
+ # it. Unless paused: with eight in flight, a paused transport would
910
+ # otherwise drain a batch per answer for the whole background stay.
911
+ if self._paused:
912
+ return
913
+ self._schedule_drain()
914
+
915
+ def _fail_in_flight(self, reason: str) -> None:
916
+ """Fails every outstanding frame with ``reason``, on a connection
917
+ going away or on a gateway that answered nothing."""
918
+ for message_id in self._verdicts.drain_all():
919
+ try:
920
+ self._protocol.reticulum_send_failed_with_reason(
921
+ message_id=message_id, reason=reason
922
+ )
923
+ except Exception:
924
+ logger.debug("reticulum_send_failed_with_reason failed", exc_info=True)
925
+
926
+ def _settle_locally(self, message_id: str, reason: str) -> None:
927
+ """Settles a frame that never reached the gateway, so no verdict is
928
+ coming for it. Only reports to the core if this call is the one
929
+ that took the id out of flight."""
930
+ if not self._verdicts.settle(message_id):
931
+ return
932
+ try:
933
+ self._protocol.reticulum_send_failed_with_reason(message_id=message_id, reason=reason)
934
+ except Exception:
935
+ logger.debug("reticulum_send_failed_with_reason failed", exc_info=True)
936
+
937
+ def _sweep_expired_verdicts(self) -> None:
938
+ """Fails frames the gateway never answered.
939
+
940
+ The contract says a gateway MUST answer every submission, and
941
+ silence is the one failure the core cannot see: it holds the frame
942
+ in pending confirmation until its own 120 s expiry and counts it a
943
+ failure then. Failing it here, at 60 s, puts it back on the retry
944
+ ladder while the core still considers it live, which is why this
945
+ timeout has to stay the shorter of the two.
946
+ """
947
+ stale = self._verdicts.expired(self._now_seconds(), policy.VERDICT_TIMEOUT)
948
+ if not stale:
949
+ return
950
+ self._emit_diagnostic(
951
+ "warning", "Gateway did not answer for submitted frames", {"count": len(stale)}
952
+ )
953
+ for message_id in stale:
954
+ try:
955
+ self._protocol.reticulum_send_failed_with_reason(
956
+ message_id=message_id, reason=policy.GATEWAY_SILENT
957
+ )
958
+ except Exception:
959
+ logger.debug("reticulum_send_failed_with_reason failed", exc_info=True)
960
+
961
+ # -- inbound frames -------------------------------------------------------
962
+
963
+ def _handle_message_received(self, frame: dict[str, Any]) -> None:
964
+ sender = frame.get("sender")
965
+ content = frame.get("content")
966
+ if (
967
+ not isinstance(sender, str)
968
+ or not sender
969
+ or policy.utf8_bytes(sender) is None
970
+ or not isinstance(content, str)
971
+ ):
972
+ self._emit_diagnostic(
973
+ "warning", "Invalid MessageReceived: missing or unencodable sender, or no content"
974
+ )
975
+ return
976
+ data: bytes | None
977
+ if frame.get("encoding") == "base64":
978
+ try:
979
+ data = base64.b64decode(content, validate=True)
980
+ except (binascii.Error, ValueError):
981
+ self._emit_diagnostic("warning", "Invalid MessageReceived: malformed base64")
982
+ return
983
+ else:
984
+ data = policy.utf8_bytes(content)
985
+ if data is None:
986
+ self._emit_diagnostic("warning", "Invalid MessageReceived: unencodable content")
987
+ return
988
+ try:
989
+ self._protocol.reticulum_message_received(sender_id=sender, data=list(data))
990
+ self._messages_received += 1
991
+ except Exception as exc:
992
+ self._emit_diagnostic(
993
+ "error", "Error processing a gateway-delivered frame", {"error": str(exc)}
994
+ )
995
+
996
+ def _handle_presence(self, frame: dict[str, Any]) -> None:
997
+ answer = policy.parse_presence(frame)
998
+ if answer is None:
999
+ self._emit_diagnostic("warning", "Invalid PresenceStatus, ignored")
1000
+ return
1001
+ if answer.online:
1002
+ self._presence_watch.unwatch(answer.peer)
1003
+ try:
1004
+ self._protocol.reticulum_peer_presence(
1005
+ peer_id=answer.peer, online=answer.online, last_seen_ms=answer.last_seen_ms
1006
+ )
1007
+ except Exception:
1008
+ logger.debug("reticulum_peer_presence failed", exc_info=True)
1009
+
1010
+ # -- presence watch -------------------------------------------------------
1011
+
1012
+ def _start_presence_watch(self) -> None:
1013
+ # Bound as well as unpaused: a stop() that lands between the status
1014
+ # flip and this call has already cleared the bind, and a tick armed
1015
+ # past it would ask a stopped transport's questions.
1016
+ if self._paused or not self._bound:
1017
+ return
1018
+ self._stop_presence_watch(clear=False)
1019
+ self._presence_task = self._spawn(self._presence_loop(self._generation))
1020
+
1021
+ def _stop_presence_watch(self, clear: bool = True) -> None:
1022
+ task = self._presence_task
1023
+ self._presence_task = None
1024
+ if task is not None and not task.done() and task is not asyncio.current_task():
1025
+ task.cancel()
1026
+ if clear:
1027
+ self._presence_watch.clear()
1028
+
1029
+ async def _presence_loop(self, generation: int) -> None:
1030
+ try:
1031
+ while self._generation == generation and self._bound and not self._paused:
1032
+ await asyncio.sleep(DEFAULT_TICK_INTERVAL)
1033
+ if self._generation != generation or not self._bound or self._paused:
1034
+ return
1035
+ await self._presence_tick(generation)
1036
+ except asyncio.CancelledError:
1037
+ return
1038
+
1039
+ async def _presence_tick(self, generation: int) -> None:
1040
+ """Asks the gateway about the peers the core is waiting to hear
1041
+ about. One frame for the whole batch. The core owns the list, every
1042
+ peer with an undelivered welcome and every recipient of a parked
1043
+ message, so the app is not asked to maintain one."""
1044
+ try:
1045
+ core_watchlist = list(self._protocol.reticulum_presence_watchlist())
1046
+ except Exception:
1047
+ logger.debug("reticulum_presence_watchlist failed", exc_info=True)
1048
+ core_watchlist = []
1049
+ self_address = self._local_address()
1050
+ candidates = [
1051
+ peer
1052
+ for peer in core_watchlist
1053
+ if peer and peer != self._device_id and peer != self_address
1054
+ ]
1055
+ peers = self._presence_watch.peers_to_query(candidates, self._now_ms())
1056
+ line = policy.check_presence_json(peers)
1057
+ if line is None:
1058
+ return
1059
+ await self._write_line(line, generation)
1060
+
1061
+ # -- sending ----------------------------------------------------------------
1062
+
1063
+ def _start_polling(self) -> None:
1064
+ # The pause gate lives here, at the one function that can violate
1065
+ # it, and not at the call sites.
1066
+ if self._paused:
1067
+ return
1068
+ self._stop_polling()
1069
+ self._poll_task = self._spawn(self._poll_loop(self._generation))
1070
+
1071
+ def _stop_polling(self) -> None:
1072
+ task = self._poll_task
1073
+ self._poll_task = None
1074
+ if task is not None and not task.done() and task is not asyncio.current_task():
1075
+ task.cancel()
1076
+
1077
+ async def _poll_loop(self, generation: int) -> None:
1078
+ try:
1079
+ while self._generation == generation and not self._paused:
1080
+ await self._poll_and_send()
1081
+ await asyncio.sleep(MESSAGE_POLL_INTERVAL)
1082
+ except asyncio.CancelledError:
1083
+ return
1084
+
1085
+ async def _poll_and_send(self) -> None:
1086
+ async with self._drain_lock:
1087
+ if not self._bound or self._paused:
1088
+ return
1089
+ self._sweep_expired_verdicts()
1090
+ generation = self._generation
1091
+ sent = 0
1092
+ while sent < MAX_BATCH_SIZE and self._bound and self._generation == generation:
1093
+ # Bounded by what is unanswered, not only by the batch: a
1094
+ # gateway that is slow to answer must not have the whole
1095
+ # outbox handed to it, because every id in flight is one the
1096
+ # core cannot retry until it is settled.
1097
+ if self._verdicts.count >= policy.MAX_IN_FLIGHT:
1098
+ return
1099
+ try:
1100
+ message = self._protocol.reticulum_get_next_message()
1101
+ except Exception as exc:
1102
+ logger.warning("Unexpected error polling outgoing messages: %s", exc)
1103
+ return
1104
+ if message is None:
1105
+ return
1106
+ # The core re-queues an unconfirmed frame under the same id
1107
+ # after its own acknowledgement timeout, and a verdict can
1108
+ # honestly take longer than that over a radio backbone.
1109
+ # Sending it again would forward the frame twice and, when
1110
+ # this copy timed out, fail an id the gateway had already
1111
+ # confirmed. Popping it was enough: the core's pending entry
1112
+ # is refreshed by the pop.
1113
+ if not self._verdicts.begin(message.message_id, self._now_seconds()):
1114
+ continue
1115
+ await self._send_message(message, generation)
1116
+ sent += 1
1117
+
1118
+ async def _send_message(self, message: Any, generation: int) -> None:
1119
+ """Writes one frame. **The write is not the outcome.**
1120
+
1121
+ A successful write means the gateway has the bytes, which says
1122
+ nothing about whether it could forward them; the answer arrives
1123
+ later as a ``MessageSent`` or a ``DeliveryError`` and is settled in
1124
+ :meth:`_handle_verdict`. A *failed* write is settled here, because
1125
+ there is no frame on the wire for the gateway to answer about.
1126
+ """
1127
+ message_id = message.message_id
1128
+ recipient = message.recipient_id
1129
+ if not self._bound or self._writer is None:
1130
+ self._emit_diagnostic(
1131
+ "warning",
1132
+ "Cannot send message: not attached",
1133
+ {"message_id": message_id, "recipient_id": recipient},
1134
+ )
1135
+ self._settle_locally(message_id, "Not attached to a gateway")
1136
+ return
1137
+ # Sanitised the way the gateway sanitises it: an id it would refuse
1138
+ # is replaced *there* by one it mints, and the verdict then comes
1139
+ # back under a name nothing here is waiting on.
1140
+ wire_id = policy.sanitize_message_id(message_id)
1141
+ if wire_id is None:
1142
+ self._emit_diagnostic("error", "Message id the gateway would refuse", {"message_id": message_id})
1143
+ self._settle_locally(message_id, "Unserializable frame")
1144
+ return
1145
+ content = base64.b64encode(bytes(message.data)).decode("ascii")
1146
+ line = policy.send_message_json(wire_id, recipient, content, message.reply_to_msg)
1147
+ if await self._write_line(line, generation):
1148
+ self._consecutive_send_failures = 0
1149
+ self._messages_sent += 1
1150
+ self._emit_diagnostic(
1151
+ "debug",
1152
+ "Message submitted to the gateway",
1153
+ {"message_id": message_id, "recipient_id": recipient, "content_length": len(content)},
1154
+ )
1155
+ return
1156
+ self._consecutive_send_failures += 1
1157
+ self._settle_locally(message_id, "Write failed")
1158
+ self._emit_diagnostic(
1159
+ "error",
1160
+ "Failed to write a message to the gateway",
1161
+ {
1162
+ "message_id": message_id,
1163
+ "recipient_id": recipient,
1164
+ "consecutive_failures": self._consecutive_send_failures,
1165
+ },
1166
+ )
1167
+ if self._consecutive_send_failures >= MAX_CONSECUTIVE_FAILURES:
1168
+ self._emit_diagnostic(
1169
+ "warning",
1170
+ "Too many consecutive send failures, triggering reconnect",
1171
+ {"failures": self._consecutive_send_failures},
1172
+ )
1173
+ self._handle_connection_closed(generation, None)
1174
+
1175
+ async def _write_line(self, text: str, generation: int) -> bool:
1176
+ """Writes one frame on the socket the session ``generation`` names.
1177
+ True when the bytes reached the kernel; a stale generation or a
1178
+ failed write is False, and the caller decides what that costs."""
1179
+ writer = self._writer
1180
+ if writer is None or self._generation != generation:
1181
+ return False
1182
+ try:
1183
+ writer.write(text.encode("utf-8") + b"\n")
1184
+ await writer.drain()
1185
+ except asyncio.CancelledError:
1186
+ raise
1187
+ except Exception as exc:
1188
+ logger.debug("gateway write failed: %s", exc)
1189
+ return False
1190
+ return True
1191
+
1192
+ # -- helpers ----------------------------------------------------------------
1193
+
1194
+ def _local_address(self) -> str | None:
1195
+ try:
1196
+ address = self._protocol.local_address()
1197
+ except Exception:
1198
+ return None
1199
+ return address or None
1200
+
1201
+ def _is_self_peer(self, peer_id: str) -> bool:
1202
+ if not peer_id:
1203
+ return False
1204
+ if peer_id == self._device_id:
1205
+ return True
1206
+ return peer_id == self._local_address()
1207
+
1208
+ @staticmethod
1209
+ def _now_seconds() -> float:
1210
+ # Monotonic, like every tracker and watch call in the relay manager:
1211
+ # a wall-clock step (an NTP correction after airplane mode) must not
1212
+ # fail every frame in flight as unanswered.
1213
+ return time.monotonic()
1214
+
1215
+ @staticmethod
1216
+ def _now_ms() -> int:
1217
+ return int(time.monotonic() * 1000)