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.
- offline_protocol_sdk/__init__.py +22 -0
- offline_protocol_sdk/_callback_reentrancy.py +64 -0
- offline_protocol_sdk/address_declaration.py +207 -0
- offline_protocol_sdk/ble_manager.py +595 -0
- offline_protocol_sdk/ble_peripheral.py +673 -0
- offline_protocol_sdk/dnssd_bridge.py +614 -0
- offline_protocol_sdk/gateway_attach_policy.py +437 -0
- offline_protocol_sdk/gateway_manager.py +1217 -0
- offline_protocol_sdk/gateway_verdict_tracker.py +97 -0
- offline_protocol_sdk/internet_manager.py +1444 -0
- offline_protocol_sdk/legacy_store_adoption.py +184 -0
- offline_protocol_sdk/local_api/__init__.py +34 -0
- offline_protocol_sdk/local_api/authz.py +180 -0
- offline_protocol_sdk/local_api/cli.py +171 -0
- offline_protocol_sdk/local_api/codec.py +210 -0
- offline_protocol_sdk/local_api/dispatch.py +537 -0
- offline_protocol_sdk/local_api/mux.py +239 -0
- offline_protocol_sdk/local_api/server.py +546 -0
- offline_protocol_sdk/local_api/session.py +86 -0
- offline_protocol_sdk/local_api/table.py +849 -0
- offline_protocol_sdk/offline_protocol.py +13508 -0
- offline_protocol_sdk/peer_stream_manager.py +1303 -0
- offline_protocol_sdk/presence_watch_policy.py +102 -0
- offline_protocol_sdk/protocol_manager.py +1108 -0
- offline_protocol_sdk/relay_answer_prefixes.py +61 -0
- offline_protocol_sdk/secure_storage.py +551 -0
- offline_protocol_sdk/services.py +195 -0
- offline_protocol_sdk/state_storage.py +452 -0
- offline_protocol_sdk/storage_namespace.py +33 -0
- offline_protocol_sdk/transport_manager.py +138 -0
- offline_protocol_sdk/uniffi.dll +0 -0
- offline_protocol_sdk-0.28.0.dist-info/METADATA +519 -0
- offline_protocol_sdk-0.28.0.dist-info/RECORD +40 -0
- offline_protocol_sdk-0.28.0.dist-info/WHEEL +5 -0
- offline_protocol_sdk-0.28.0.dist-info/entry_points.txt +2 -0
- offline_protocol_sdk-0.28.0.dist-info/licenses/EXPORT.md +68 -0
- offline_protocol_sdk-0.28.0.dist-info/licenses/LICENSE +661 -0
- offline_protocol_sdk-0.28.0.dist-info/licenses/LICENSE-COMMERCIAL.md +89 -0
- offline_protocol_sdk-0.28.0.dist-info/licenses/THIRD-PARTY-NOTICES.md +6645 -0
- 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)
|