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,1108 @@
|
|
|
1
|
+
"""High-level protocol manager for desktop platforms.
|
|
2
|
+
|
|
3
|
+
Mirrors ``OfflineProtocolModule.swift`` / ``OfflineProtocolModule.kt`` —
|
|
4
|
+
wraps the UniFFI ``OfflineProtocol`` instance with transport managers, a
|
|
5
|
+
100 ms processing loop, event dispatch, and lifecycle management.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import asyncio
|
|
11
|
+
import base64
|
|
12
|
+
import binascii
|
|
13
|
+
import json
|
|
14
|
+
import logging
|
|
15
|
+
import os
|
|
16
|
+
import platform
|
|
17
|
+
import sys
|
|
18
|
+
from pathlib import Path
|
|
19
|
+
from typing import Any, Callable
|
|
20
|
+
|
|
21
|
+
from .offline_protocol import (
|
|
22
|
+
BleTransportCallback,
|
|
23
|
+
EventCallback,
|
|
24
|
+
MessagePriority,
|
|
25
|
+
MlsVerbosity,
|
|
26
|
+
NostrTransportCallback,
|
|
27
|
+
OfflineProtocol,
|
|
28
|
+
ProtocolConfig,
|
|
29
|
+
ProtocolError,
|
|
30
|
+
AppState,
|
|
31
|
+
ReticulumTransportCallback,
|
|
32
|
+
TelemetryConfig,
|
|
33
|
+
TelemetryOs,
|
|
34
|
+
TelemetryStats,
|
|
35
|
+
WifiDirectTransportCallback,
|
|
36
|
+
)
|
|
37
|
+
from .ble_manager import BleManager
|
|
38
|
+
from .ble_peripheral import BlePeripheral
|
|
39
|
+
from .gateway_manager import GatewayManager
|
|
40
|
+
from .internet_manager import InternetManager
|
|
41
|
+
from .peer_stream_manager import PeerStreamManager
|
|
42
|
+
from .secure_storage import SecureStorage
|
|
43
|
+
from .state_storage import _STATE_ROOT_ENV, AppStateStorage
|
|
44
|
+
from .storage_namespace import account_storage_namespace
|
|
45
|
+
|
|
46
|
+
logger = logging.getLogger(__name__)
|
|
47
|
+
|
|
48
|
+
# Processing loop interval (matches iOS/Android: 100 ms)
|
|
49
|
+
_PROCESS_INTERVAL = 0.1
|
|
50
|
+
# Maximum messages to drain per process tick (matches iOS maxMessagesPerProcessTick)
|
|
51
|
+
_MAX_MESSAGES_PER_TICK = 100
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
class _EventCallbackImpl(EventCallback):
|
|
55
|
+
"""Routes protocol events to Python callbacks."""
|
|
56
|
+
|
|
57
|
+
def __init__(self, handler: Callable[[dict[str, Any]], None] | None) -> None:
|
|
58
|
+
self._handler = handler
|
|
59
|
+
|
|
60
|
+
def on_event(self, event_json: str) -> None:
|
|
61
|
+
if self._handler is None:
|
|
62
|
+
return
|
|
63
|
+
try:
|
|
64
|
+
event = json.loads(event_json)
|
|
65
|
+
except json.JSONDecodeError:
|
|
66
|
+
event = {"raw": event_json}
|
|
67
|
+
self._handler(event)
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
class _BleTransportCallbackImpl(BleTransportCallback):
|
|
71
|
+
"""Bridges Rust BLE fragment-ready notifications to BLE managers."""
|
|
72
|
+
|
|
73
|
+
def __init__(
|
|
74
|
+
self,
|
|
75
|
+
ble_manager: BleManager | None,
|
|
76
|
+
ble_peripheral: BlePeripheral | None,
|
|
77
|
+
) -> None:
|
|
78
|
+
self._ble = ble_manager
|
|
79
|
+
self._peripheral = ble_peripheral
|
|
80
|
+
|
|
81
|
+
def on_fragments_available(self) -> None:
|
|
82
|
+
# The scanner and peripheral share a single fragment queue.
|
|
83
|
+
# Only let the scanner drain if it has connected clients;
|
|
84
|
+
# otherwise the scanner pops fragments it can't deliver,
|
|
85
|
+
# starving the peripheral.
|
|
86
|
+
scanner_has_clients = (
|
|
87
|
+
self._ble is not None
|
|
88
|
+
and bool(self._ble._clients)
|
|
89
|
+
)
|
|
90
|
+
if scanner_has_clients:
|
|
91
|
+
self._ble.on_fragments_available()
|
|
92
|
+
if self._peripheral is not None:
|
|
93
|
+
self._peripheral.on_fragments_available()
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
class _WifiDirectTransportCallbackImpl(WifiDirectTransportCallback):
|
|
97
|
+
"""Forwards the peer-stream slot's wake to :class:`PeerStreamManager`.
|
|
98
|
+
|
|
99
|
+
The core fires it only for a body queued toward an address a stream has
|
|
100
|
+
proved, so nothing is scheduled for a manager that holds no stream.
|
|
101
|
+
"""
|
|
102
|
+
|
|
103
|
+
def __init__(self, manager: PeerStreamManager | None) -> None:
|
|
104
|
+
self._manager = manager
|
|
105
|
+
|
|
106
|
+
def on_messages_available(self) -> None:
|
|
107
|
+
if self._manager is not None:
|
|
108
|
+
self._manager.on_messages_available()
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
class _NostrTransportCallbackImpl(NostrTransportCallback):
|
|
112
|
+
"""Stub — no desktop Nostr manager; apps driving Nostr manually must
|
|
113
|
+
call ``protocol.set_nostr_transport_callback()`` with their own impl."""
|
|
114
|
+
|
|
115
|
+
def on_messages_available(self) -> None:
|
|
116
|
+
pass
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
class _ReticulumTransportCallbackImpl(ReticulumTransportCallback):
|
|
120
|
+
"""Forwards the ``reticulum`` slot's wake to :class:`GatewayManager`.
|
|
121
|
+
|
|
122
|
+
The core fires it when a frame is queued for this carrier; the manager
|
|
123
|
+
drains only once the gateway has bound the session, so a wake for an
|
|
124
|
+
unattached manager is one drain that returns at once. An application
|
|
125
|
+
that drives the slot itself replaces this through
|
|
126
|
+
``protocol.set_reticulum_transport_callback``.
|
|
127
|
+
"""
|
|
128
|
+
|
|
129
|
+
def __init__(self, manager: GatewayManager | None) -> None:
|
|
130
|
+
self._manager = manager
|
|
131
|
+
|
|
132
|
+
def on_messages_available(self) -> None:
|
|
133
|
+
if self._manager is not None:
|
|
134
|
+
self._manager.on_messages_available()
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
#: Where :class:`ProtocolManager` finds the sealed MLS store's root when
|
|
138
|
+
#: ``mls_root`` is not given.
|
|
139
|
+
_MLS_ROOT_ENV = "OFFLINE_PROTOCOL_MLS_ROOT"
|
|
140
|
+
#: Length of a store key.
|
|
141
|
+
_STORE_KEY_BYTES = 32
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def _decode_store_key_text(variable: str, text: str) -> bytes:
|
|
145
|
+
"""A store key from its text form: 64 hex digits, or standard base64.
|
|
146
|
+
|
|
147
|
+
The same forms the Rust ``EnvStoreKey`` accepts, so one secret works
|
|
148
|
+
whichever side reads it. Base64 must be canonical (it re-encodes to the
|
|
149
|
+
same text), as the Rust decoder requires.
|
|
150
|
+
"""
|
|
151
|
+
text = text.strip()
|
|
152
|
+
if len(text) == 2 * _STORE_KEY_BYTES and all(c in "0123456789abcdefABCDEF" for c in text):
|
|
153
|
+
return bytes.fromhex(text)
|
|
154
|
+
unpadded = text.rstrip("=")
|
|
155
|
+
try:
|
|
156
|
+
raw = base64.b64decode(unpadded + "=" * (-len(unpadded) % 4), validate=True)
|
|
157
|
+
except (binascii.Error, ValueError):
|
|
158
|
+
raw = b""
|
|
159
|
+
canonical = base64.b64encode(raw).decode("ascii")
|
|
160
|
+
if len(raw) == _STORE_KEY_BYTES and text in (canonical, canonical.rstrip("=")):
|
|
161
|
+
return raw
|
|
162
|
+
raise ValueError(
|
|
163
|
+
f"{variable} must hold a {_STORE_KEY_BYTES}-byte store key as 64 hex "
|
|
164
|
+
"digits or as base64"
|
|
165
|
+
)
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def _run_here(call: Callable[[], Any]) -> asyncio.Future[Any]:
|
|
169
|
+
"""Runs ``call`` on this thread and returns a future that is already
|
|
170
|
+
done, carrying its result or its error."""
|
|
171
|
+
done: asyncio.Future[Any] = asyncio.get_running_loop().create_future()
|
|
172
|
+
try:
|
|
173
|
+
done.set_result(call())
|
|
174
|
+
except Exception as err:
|
|
175
|
+
done.set_exception(err)
|
|
176
|
+
return done
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
def _forget_frames(err: BaseException) -> None:
|
|
180
|
+
"""Drops the traceback of an exception a teardown caught and logged.
|
|
181
|
+
|
|
182
|
+
The traceback holds the teardown's frames, and through them the
|
|
183
|
+
manager. The executor future that carried the exception keeps it, in a
|
|
184
|
+
reference cycle that Python 3.10 frees only when the collector runs, so
|
|
185
|
+
a stopped or closed manager outlived ``del`` there (3.11 and later free
|
|
186
|
+
it at once). Nothing reads the traceback once it is logged.
|
|
187
|
+
"""
|
|
188
|
+
err.__traceback__ = None
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
def _hand_off(call: Callable[[], Any]) -> asyncio.Future[Any]:
|
|
192
|
+
"""Starts a blocking core call off the loop and returns its future.
|
|
193
|
+
|
|
194
|
+
A teardown must be able to finish on any loop it is asked to finish on.
|
|
195
|
+
A loop whose default executor has been shut down refuses the hand-off
|
|
196
|
+
before anything is submitted, so the call runs here instead: blocking
|
|
197
|
+
the loop for one teardown step is better than a manager that can never
|
|
198
|
+
release what it holds.
|
|
199
|
+
"""
|
|
200
|
+
try:
|
|
201
|
+
return asyncio.get_running_loop().run_in_executor(None, call)
|
|
202
|
+
except RuntimeError:
|
|
203
|
+
return _run_here(call)
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
def _require_root(value: str | Path | None, variable: str, what: str) -> str:
|
|
207
|
+
if value is not None and str(value).strip():
|
|
208
|
+
return str(value)
|
|
209
|
+
configured = os.environ.get(variable)
|
|
210
|
+
if configured and configured.strip():
|
|
211
|
+
# A service manager's environment file can carry stray whitespace;
|
|
212
|
+
# the key text is trimmed for the same reason. An argument is taken
|
|
213
|
+
# as given, since a path may legitimately end in a space.
|
|
214
|
+
return configured.strip()
|
|
215
|
+
raise ValueError(f"the file stores need {what}; pass it or set {variable}")
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
class _FileStores:
|
|
219
|
+
"""The built-in file stores: where they live and where the key comes from.
|
|
220
|
+
|
|
221
|
+
The roots are resolved at construction so a missing one fails there.
|
|
222
|
+
The key is read when :meth:`initialize` runs and handed to the core; a
|
|
223
|
+
key passed as bytes is dropped once the core has taken it, and one read
|
|
224
|
+
from the environment is never kept.
|
|
225
|
+
"""
|
|
226
|
+
|
|
227
|
+
def __init__(
|
|
228
|
+
self,
|
|
229
|
+
*,
|
|
230
|
+
mls_root: str | Path | None,
|
|
231
|
+
state_root: str | Path | None,
|
|
232
|
+
store_key: bytes | bytearray | None,
|
|
233
|
+
store_key_env: str | None,
|
|
234
|
+
) -> None:
|
|
235
|
+
if store_key is not None and store_key_env is not None:
|
|
236
|
+
raise ValueError("pass store_key or store_key_env, not both")
|
|
237
|
+
if store_key is not None:
|
|
238
|
+
if not isinstance(store_key, (bytes, bytearray)):
|
|
239
|
+
raise TypeError("store_key must be bytes")
|
|
240
|
+
if len(store_key) != _STORE_KEY_BYTES:
|
|
241
|
+
raise ValueError(
|
|
242
|
+
f"store_key must be {_STORE_KEY_BYTES} bytes, got {len(store_key)}"
|
|
243
|
+
)
|
|
244
|
+
if not any(store_key):
|
|
245
|
+
raise ValueError(
|
|
246
|
+
"store_key is all zero: an unset buffer, not a key"
|
|
247
|
+
)
|
|
248
|
+
if store_key_env is not None and not store_key_env.strip():
|
|
249
|
+
raise ValueError("store_key_env must name an environment variable")
|
|
250
|
+
self._mls_root = _require_root(mls_root, _MLS_ROOT_ENV, "mls_root")
|
|
251
|
+
self._state_root = _require_root(state_root, _STATE_ROOT_ENV, "state_root")
|
|
252
|
+
# A snapshot, not the caller's buffer: a bytearray the caller reuses
|
|
253
|
+
# before `start()` would otherwise create a new store sealed under
|
|
254
|
+
# whatever the buffer holds by then, and the real key would be
|
|
255
|
+
# refused on every later run.
|
|
256
|
+
self._store_key: bytes | None = (
|
|
257
|
+
bytes(store_key) if store_key is not None else None
|
|
258
|
+
)
|
|
259
|
+
self._store_key_env = store_key_env
|
|
260
|
+
|
|
261
|
+
def _key(self) -> bytes:
|
|
262
|
+
if self._store_key is not None:
|
|
263
|
+
return self._store_key
|
|
264
|
+
variable = self._store_key_env or ""
|
|
265
|
+
text = os.environ.get(variable)
|
|
266
|
+
if text is None:
|
|
267
|
+
raise ValueError(f"the environment variable {variable} is not set")
|
|
268
|
+
return _decode_store_key_text(variable, text)
|
|
269
|
+
|
|
270
|
+
def forget_key(self) -> None:
|
|
271
|
+
"""Drops a key the core will never take: the manager was closed."""
|
|
272
|
+
self._store_key = None
|
|
273
|
+
|
|
274
|
+
def initialize(self, protocol: OfflineProtocol) -> None:
|
|
275
|
+
# A restart of the same manager: the stores are already open, and
|
|
276
|
+
# the key was dropped when the core took it.
|
|
277
|
+
if protocol.is_mls_initialized():
|
|
278
|
+
return
|
|
279
|
+
protocol.initialize_mls_with_file_stores(
|
|
280
|
+
self._mls_root, self._state_root, self._key()
|
|
281
|
+
)
|
|
282
|
+
# Kept until the core accepted it, so a refused start can be retried.
|
|
283
|
+
self._store_key = None
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
class ProtocolManager:
|
|
287
|
+
"""Manages the full protocol lifecycle for desktop platforms.
|
|
288
|
+
|
|
289
|
+
Typical usage::
|
|
290
|
+
|
|
291
|
+
async with ProtocolManager(config, state_root="/app/install/state") as pm:
|
|
292
|
+
pm.on_event(lambda e: print(e))
|
|
293
|
+
pm.internet.configure(server_url="ws://relay.example.com")
|
|
294
|
+
await pm.internet.start()
|
|
295
|
+
pm.send_message("peer-id", "hello")
|
|
296
|
+
|
|
297
|
+
Or without ``async with``::
|
|
298
|
+
|
|
299
|
+
pm = ProtocolManager(config, state_root="/app/install/state")
|
|
300
|
+
await pm.start()
|
|
301
|
+
...
|
|
302
|
+
await pm.stop()
|
|
303
|
+
|
|
304
|
+
:meth:`stop` leaves the manager ready for another :meth:`start`.
|
|
305
|
+
:meth:`close` is final: it stops, and with the file stores it releases
|
|
306
|
+
their directories at once, so a new manager can open them while this one
|
|
307
|
+
still exists. Leaving ``async with`` closes a manager that uses the file
|
|
308
|
+
stores and stops any other.
|
|
309
|
+
|
|
310
|
+
Parameters
|
|
311
|
+
----------
|
|
312
|
+
config:
|
|
313
|
+
``ProtocolConfig`` dict/object (UniFFI-generated).
|
|
314
|
+
event_handler:
|
|
315
|
+
Optional callback invoked for every protocol event (parsed JSON dict).
|
|
316
|
+
storage:
|
|
317
|
+
Optional ``MlsStorageProvider`` for MLS key material. Defaults to
|
|
318
|
+
:class:`SecureStorage` backed by the platform keyring.
|
|
319
|
+
state_storage:
|
|
320
|
+
Optional ``ProtocolStateStorageProvider`` for restartable delivery
|
|
321
|
+
state. When omitted, ``state_root`` or ``OFFLINE_PROTOCOL_STATE_ROOT``
|
|
322
|
+
must select an application-owned directory that the installer removes
|
|
323
|
+
with the application.
|
|
324
|
+
state_root:
|
|
325
|
+
Root directory for protocol state: the built-in
|
|
326
|
+
:class:`AppStateStorage`, or the file stores' protocol-state half.
|
|
327
|
+
Ignored when ``state_storage`` is supplied.
|
|
328
|
+
store_key:
|
|
329
|
+
Selects the SDK's built-in file stores instead of ``SecureStorage``
|
|
330
|
+
and ``AppStateStorage``: 32 bytes that seal every MLS record (the
|
|
331
|
+
identity, group state, and the key that seals protocol state). For a
|
|
332
|
+
host with a filesystem and no platform keyring, such as a headless
|
|
333
|
+
Linux service. Exclusive with ``store_key_env``, ``storage`` and
|
|
334
|
+
``state_storage``.
|
|
335
|
+
store_key_env:
|
|
336
|
+
Selects the file stores like ``store_key``, reading the key when
|
|
337
|
+
:meth:`start` runs from this environment variable, as 64 hex digits
|
|
338
|
+
or as base64 (conventionally ``OFFLINE_PROTOCOL_STORE_KEY``). This is
|
|
339
|
+
how a service manager usually hands a process a secret; unset the
|
|
340
|
+
variable after :meth:`start` if nothing else needs it.
|
|
341
|
+
mls_root:
|
|
342
|
+
Root directory of the sealed MLS store in file-store mode, or
|
|
343
|
+
``OFFLINE_PROTOCOL_MLS_ROOT``. It holds this device's identity, so it
|
|
344
|
+
must survive an upgrade, and it should not be ``state_root``.
|
|
345
|
+
|
|
346
|
+
With the file stores, :meth:`start` raises when MLS cannot be
|
|
347
|
+
initialised (a wrong key, a directory another process holds) instead of
|
|
348
|
+
starting without encryption: an operator who supplied a key asked for
|
|
349
|
+
the sealed store, and a service that runs without it has lost its
|
|
350
|
+
identity without saying so.
|
|
351
|
+
"""
|
|
352
|
+
|
|
353
|
+
def __init__(
|
|
354
|
+
self,
|
|
355
|
+
config: ProtocolConfig,
|
|
356
|
+
event_handler: Callable[[dict[str, Any]], None] | None = None,
|
|
357
|
+
storage: Any | None = None,
|
|
358
|
+
state_storage: Any | None = None,
|
|
359
|
+
*,
|
|
360
|
+
state_root: str | Path | None = None,
|
|
361
|
+
store_key: bytes | bytearray | None = None,
|
|
362
|
+
store_key_env: str | None = None,
|
|
363
|
+
mls_root: str | Path | None = None,
|
|
364
|
+
) -> None:
|
|
365
|
+
self._config = config
|
|
366
|
+
self._event_handler = event_handler
|
|
367
|
+
|
|
368
|
+
profile = config.profile # type: ignore[union-attr]
|
|
369
|
+
app_id = config.app_id # type: ignore[union-attr]
|
|
370
|
+
|
|
371
|
+
# The built-in file stores, when a store key was given. Opened by
|
|
372
|
+
# the core in `start()`; nothing on this side holds them.
|
|
373
|
+
self._file_stores: _FileStores | None = None
|
|
374
|
+
if store_key is not None or store_key_env is not None:
|
|
375
|
+
if storage is not None or state_storage is not None:
|
|
376
|
+
raise ValueError(
|
|
377
|
+
"store_key/store_key_env select the built-in file stores; "
|
|
378
|
+
"they cannot be combined with storage= or state_storage="
|
|
379
|
+
)
|
|
380
|
+
self._file_stores = _FileStores(
|
|
381
|
+
mls_root=mls_root,
|
|
382
|
+
state_root=state_root,
|
|
383
|
+
store_key=store_key,
|
|
384
|
+
store_key_env=store_key_env,
|
|
385
|
+
)
|
|
386
|
+
self._storage: Any | None = None
|
|
387
|
+
self._state_storage: Any | None = None
|
|
388
|
+
else:
|
|
389
|
+
storage_namespace = account_storage_namespace(app_id, profile)
|
|
390
|
+
self._storage = (
|
|
391
|
+
storage
|
|
392
|
+
if storage is not None
|
|
393
|
+
else SecureStorage(namespace=storage_namespace)
|
|
394
|
+
)
|
|
395
|
+
self._state_storage = (
|
|
396
|
+
state_storage
|
|
397
|
+
if state_storage is not None
|
|
398
|
+
else AppStateStorage(root=state_root, namespace=storage_namespace)
|
|
399
|
+
)
|
|
400
|
+
|
|
401
|
+
# Create the core protocol instance
|
|
402
|
+
self._protocol = OfflineProtocol(config)
|
|
403
|
+
|
|
404
|
+
# Transport managers still carry the profile rather than this device's
|
|
405
|
+
# address: the address is derived when `start()` initialises MLS, which
|
|
406
|
+
# is after this point. Moving the transport surfaces onto the address
|
|
407
|
+
# is done as one piece with the rest of the transport identity work.
|
|
408
|
+
device_id = profile
|
|
409
|
+
|
|
410
|
+
# Transport managers
|
|
411
|
+
self.ble: BleManager | None = None
|
|
412
|
+
if getattr(config, "ble_enabled", False):
|
|
413
|
+
self.ble = BleManager(self._protocol, device_id)
|
|
414
|
+
|
|
415
|
+
self.internet: InternetManager | None = None
|
|
416
|
+
if getattr(config, "internet_enabled", False):
|
|
417
|
+
self.internet = InternetManager(self._protocol, device_id, app_id=app_id)
|
|
418
|
+
|
|
419
|
+
self.ble_peripheral: BlePeripheral | None = None
|
|
420
|
+
if getattr(config, "ble_enabled", False):
|
|
421
|
+
self.ble_peripheral = BlePeripheral(self._protocol, device_id)
|
|
422
|
+
|
|
423
|
+
# The peer-stream transport behind the `wifi_direct` slot: TCP
|
|
424
|
+
# streams to configured or discovered hosts, each proved by the
|
|
425
|
+
# preamble exchange. Started by the caller after `start()`, once
|
|
426
|
+
# this device has an address to prove; stopped here.
|
|
427
|
+
self.peer_stream: PeerStreamManager | None = None
|
|
428
|
+
if getattr(config, "wifi_direct_enabled", False):
|
|
429
|
+
self.peer_stream = PeerStreamManager(self._protocol)
|
|
430
|
+
|
|
431
|
+
# The gateway-daemon client behind the `reticulum` slot: TCP to a
|
|
432
|
+
# daemon built to the gateway contract, attached with a signed
|
|
433
|
+
# address declaration, each send settled on the gateway's verdict.
|
|
434
|
+
# Configured and started by the caller after `start()`, once this
|
|
435
|
+
# device has an address to declare; stopped here.
|
|
436
|
+
self.gateway: GatewayManager | None = None
|
|
437
|
+
if getattr(config, "reticulum_enabled", False):
|
|
438
|
+
self.gateway = GatewayManager(self._protocol, device_id)
|
|
439
|
+
|
|
440
|
+
# Processing loop task
|
|
441
|
+
self._process_task: asyncio.Task[None] | None = None
|
|
442
|
+
self._running = False
|
|
443
|
+
# Set while a teardown has begun and not run to its end: a `stop()`
|
|
444
|
+
# cancelled part-way, or one whose engine stop raised. `_running` is
|
|
445
|
+
# already False then, so without this a retry would return at once
|
|
446
|
+
# and leave the callbacks, and with them the store locks, held.
|
|
447
|
+
self._teardown_pending = False
|
|
448
|
+
# One teardown at a time. A second stop() (a signal handler racing an
|
|
449
|
+
# `async with` exit) would otherwise stop the engine and release the
|
|
450
|
+
# callbacks while the first is still inside a transport, and two
|
|
451
|
+
# transport stops would interleave over the same sockets.
|
|
452
|
+
self._stop_lock = asyncio.Lock()
|
|
453
|
+
# Set by `close()`. The core has given up its stores by then, so a
|
|
454
|
+
# later `start()` would run an engine that cannot write.
|
|
455
|
+
self._closed = False
|
|
456
|
+
|
|
457
|
+
# Registry of objects whose pointers are held by the Rust/UniFFI side.
|
|
458
|
+
# Prevents garbage collection while the protocol is alive.
|
|
459
|
+
self._prevent_gc: list[Any] = []
|
|
460
|
+
|
|
461
|
+
@property
|
|
462
|
+
def protocol(self) -> OfflineProtocol:
|
|
463
|
+
"""Direct access to the underlying UniFFI ``OfflineProtocol``."""
|
|
464
|
+
return self._protocol
|
|
465
|
+
|
|
466
|
+
# -- lifecycle ------------------------------------------------------------
|
|
467
|
+
|
|
468
|
+
@property
|
|
469
|
+
def local_address(self) -> str | None:
|
|
470
|
+
"""This device's derived ``off1…`` address, or ``None`` before start.
|
|
471
|
+
|
|
472
|
+
Derived from the identity key in this profile's storage rather than
|
|
473
|
+
chosen by the caller, and stable across restarts of the same profile.
|
|
474
|
+
"""
|
|
475
|
+
return self._protocol.local_address()
|
|
476
|
+
|
|
477
|
+
async def start(self) -> None:
|
|
478
|
+
"""Wire callbacks, initialise MLS, and start the processing loop."""
|
|
479
|
+
if self._closed:
|
|
480
|
+
raise RuntimeError(
|
|
481
|
+
"this ProtocolManager is closed: close() released its stores "
|
|
482
|
+
"for good, create a new manager"
|
|
483
|
+
)
|
|
484
|
+
if self._running:
|
|
485
|
+
return
|
|
486
|
+
|
|
487
|
+
# Set event callback
|
|
488
|
+
self._event_cb = _EventCallbackImpl(self._event_handler)
|
|
489
|
+
self._protocol.set_event_callback(self._event_cb)
|
|
490
|
+
|
|
491
|
+
# Set transport callbacks
|
|
492
|
+
self._ble_cb = _BleTransportCallbackImpl(self.ble, self.ble_peripheral)
|
|
493
|
+
self._protocol.set_ble_transport_callback(self._ble_cb)
|
|
494
|
+
|
|
495
|
+
# Mirror the RN iOS/Android modules: only wire the peer-stream,
|
|
496
|
+
# nostr and reticulum callbacks when the transport is enabled in
|
|
497
|
+
# config. Installing a stub unconditionally would silently swallow
|
|
498
|
+
# `on_messages_available` on desktop apps that enable the transport
|
|
499
|
+
# but drive it themselves.
|
|
500
|
+
self._wifi_cb: _WifiDirectTransportCallbackImpl | None = None
|
|
501
|
+
if self.peer_stream is not None:
|
|
502
|
+
self._wifi_cb = _WifiDirectTransportCallbackImpl(self.peer_stream)
|
|
503
|
+
self._protocol.set_wifi_direct_transport_callback(self._wifi_cb)
|
|
504
|
+
|
|
505
|
+
self._nostr_cb: _NostrTransportCallbackImpl | None = None
|
|
506
|
+
if getattr(self._config, "nostr_enabled", False):
|
|
507
|
+
self._nostr_cb = _NostrTransportCallbackImpl()
|
|
508
|
+
self._protocol.set_nostr_transport_callback(self._nostr_cb)
|
|
509
|
+
|
|
510
|
+
self._reticulum_cb: _ReticulumTransportCallbackImpl | None = None
|
|
511
|
+
if getattr(self._config, "reticulum_enabled", False):
|
|
512
|
+
self._reticulum_cb = _ReticulumTransportCallbackImpl(self.gateway)
|
|
513
|
+
self._protocol.set_reticulum_transport_callback(self._reticulum_cb)
|
|
514
|
+
|
|
515
|
+
# Keep strong references to all objects passed to the Rust/UniFFI
|
|
516
|
+
# side so that Python's GC cannot collect them while Rust holds
|
|
517
|
+
# raw callback pointers.
|
|
518
|
+
self._prevent_gc = [self._event_cb, self._ble_cb]
|
|
519
|
+
if self._storage is not None:
|
|
520
|
+
self._prevent_gc.append(self._storage)
|
|
521
|
+
if self._state_storage is not None:
|
|
522
|
+
self._prevent_gc.append(self._state_storage)
|
|
523
|
+
if self._wifi_cb is not None:
|
|
524
|
+
self._prevent_gc.append(self._wifi_cb)
|
|
525
|
+
if self._nostr_cb is not None:
|
|
526
|
+
self._prevent_gc.append(self._nostr_cb)
|
|
527
|
+
if self._reticulum_cb is not None:
|
|
528
|
+
self._prevent_gc.append(self._reticulum_cb)
|
|
529
|
+
|
|
530
|
+
# Initialise MLS encryption
|
|
531
|
+
if self._file_stores is not None:
|
|
532
|
+
# Fails closed: a refused key or a held directory raises here,
|
|
533
|
+
# before the engine starts, rather than running without the
|
|
534
|
+
# identity the operator's key protects. The callbacks above are
|
|
535
|
+
# already registered and `stop()` does nothing for a manager
|
|
536
|
+
# that never ran, so release them here or the core (and, through
|
|
537
|
+
# a handler that reaches it, the manager) outlives every refusal.
|
|
538
|
+
try:
|
|
539
|
+
self._file_stores.initialize(self._protocol)
|
|
540
|
+
except BaseException:
|
|
541
|
+
self._release_callbacks()
|
|
542
|
+
raise
|
|
543
|
+
else:
|
|
544
|
+
try:
|
|
545
|
+
self._protocol.initialize_mls(self._storage, self._state_storage)
|
|
546
|
+
except Exception as exc:
|
|
547
|
+
logger.warning("MLS initialisation failed (non-fatal): %s", exc)
|
|
548
|
+
|
|
549
|
+
# Start the protocol engine. A refusal here comes after the stores
|
|
550
|
+
# opened, and `stop()` does nothing for a manager that never ran, so
|
|
551
|
+
# release the callbacks now or the stores stay held for good.
|
|
552
|
+
try:
|
|
553
|
+
self._protocol.start()
|
|
554
|
+
except BaseException:
|
|
555
|
+
self._release_callbacks()
|
|
556
|
+
raise
|
|
557
|
+
self._running = True
|
|
558
|
+
|
|
559
|
+
# Start the 100 ms processing loop
|
|
560
|
+
self._process_task = asyncio.ensure_future(self._process_loop())
|
|
561
|
+
|
|
562
|
+
logger.info("ProtocolManager started (address=%s)", self.local_address)
|
|
563
|
+
|
|
564
|
+
async def stop(self) -> None:
|
|
565
|
+
"""Stop all transports and the processing loop.
|
|
566
|
+
|
|
567
|
+
The manager can be started again. With the file stores, the
|
|
568
|
+
directories stay open for that restart: use :meth:`close` to give
|
|
569
|
+
them up.
|
|
570
|
+
"""
|
|
571
|
+
async with self._stop_lock:
|
|
572
|
+
await self._stop_locked()
|
|
573
|
+
|
|
574
|
+
async def close(self) -> None:
|
|
575
|
+
"""Stop, and release what this manager holds, for good.
|
|
576
|
+
|
|
577
|
+
With the file stores, both directories are released before this
|
|
578
|
+
returns, whatever still refers to the manager or to ``protocol``: a
|
|
579
|
+
name the application kept, an event handler, an exception. A new
|
|
580
|
+
manager can open them at once. Without an explicit release the
|
|
581
|
+
directories stay locked until the core object is freed, and when
|
|
582
|
+
that happens is the interpreter's decision, not the caller's.
|
|
583
|
+
|
|
584
|
+
The manager cannot be started again; create a new one. Safe to call
|
|
585
|
+
twice, and on a manager that never started. Raises
|
|
586
|
+
``ProtocolError.InvalidState`` when the engine could not be stopped:
|
|
587
|
+
nothing was released, the manager is not closed, and the call can be
|
|
588
|
+
repeated. A call cancelled while the core is releasing the stores
|
|
589
|
+
still releases them, and the manager is closed once it has.
|
|
590
|
+
"""
|
|
591
|
+
await self.stop()
|
|
592
|
+
if self._file_stores is None:
|
|
593
|
+
# Nothing of this manager's outlives a stopped engine, and the
|
|
594
|
+
# core has no stores to ask, so an engine that would not stop is
|
|
595
|
+
# reported here.
|
|
596
|
+
if self._teardown_pending:
|
|
597
|
+
raise ProtocolError.InvalidState(
|
|
598
|
+
"close() could not stop the engine, so the manager is "
|
|
599
|
+
"not closed; call close() again"
|
|
600
|
+
)
|
|
601
|
+
self._closed = True
|
|
602
|
+
return
|
|
603
|
+
# Off the loop: when `stop()` could not disable telemetry, the core
|
|
604
|
+
# does it here, and the uploader's final flush can block for up to
|
|
605
|
+
# three seconds. Shielded, and marked from the hand-off itself: a
|
|
606
|
+
# caller's cancel does not stop the core, so the manager has to end
|
|
607
|
+
# up closed whether or not anyone is still waiting for it.
|
|
608
|
+
release = _hand_off(self._protocol.close_file_stores)
|
|
609
|
+
if release.done():
|
|
610
|
+
# Already over (the call ran here, or its worker was quick). A
|
|
611
|
+
# callback added now would run on a later loop turn, after this
|
|
612
|
+
# method had returned a manager not yet marked closed.
|
|
613
|
+
self._closed_by(release)
|
|
614
|
+
release.result()
|
|
615
|
+
return
|
|
616
|
+
release.add_done_callback(self._closed_by)
|
|
617
|
+
await asyncio.shield(release)
|
|
618
|
+
|
|
619
|
+
def _closed_by(self, release: asyncio.Future[Any]) -> None:
|
|
620
|
+
"""Marks the manager closed once the core released the stores."""
|
|
621
|
+
if release.cancelled() or release.exception() is not None:
|
|
622
|
+
return
|
|
623
|
+
self._closed = True
|
|
624
|
+
if self._file_stores is not None:
|
|
625
|
+
self._file_stores.forget_key()
|
|
626
|
+
if self._teardown_pending:
|
|
627
|
+
# `stop()` could not finish (telemetry would not disable, or the
|
|
628
|
+
# engine lock was poisoned), and the core released the stores
|
|
629
|
+
# anyway, which it does only for an engine that runs no more.
|
|
630
|
+
# What `stop()` held back for a running engine can go.
|
|
631
|
+
self._release_callbacks()
|
|
632
|
+
self._prevent_gc.clear()
|
|
633
|
+
self._teardown_pending = False
|
|
634
|
+
|
|
635
|
+
async def _stop_locked(self) -> None:
|
|
636
|
+
if not self._running and not self._teardown_pending:
|
|
637
|
+
return
|
|
638
|
+
|
|
639
|
+
self._running = False
|
|
640
|
+
self._teardown_pending = True
|
|
641
|
+
|
|
642
|
+
# Cancel processing loop
|
|
643
|
+
if self._process_task is not None and not self._process_task.done():
|
|
644
|
+
self._process_task.cancel()
|
|
645
|
+
# Waited on, never awaited. A CancelledError raised here is then
|
|
646
|
+
# always the caller's (a shutdown deadline), never the process
|
|
647
|
+
# task's own: awaiting the task would raise for both, and a
|
|
648
|
+
# handler that swallowed the task's would swallow the caller's
|
|
649
|
+
# cancel with it and run the teardown to its end regardless.
|
|
650
|
+
await asyncio.wait({self._process_task})
|
|
651
|
+
self._process_task = None
|
|
652
|
+
|
|
653
|
+
# One loop turn, always. A caller that retries after a cancelled
|
|
654
|
+
# stop() is still inside the task step that threw the CancelledError,
|
|
655
|
+
# and that step holds the exception (and through its traceback the
|
|
656
|
+
# first stop()'s frames, so this manager) until the task next
|
|
657
|
+
# suspends. Nothing below is certain to suspend: on Python 3.13+ an
|
|
658
|
+
# executor hand-off whose worker already finished completes in
|
|
659
|
+
# place. Without this turn the manager outlived `del` about one time
|
|
660
|
+
# in fifty, and the next manager was refused its directories. Taken
|
|
661
|
+
# here, after the process loop was cancelled, and not on entry: a
|
|
662
|
+
# turn before the cancel lets that loop run one more tick, and
|
|
663
|
+
# deliver one more message, after `stop()` was called.
|
|
664
|
+
await asyncio.sleep(0)
|
|
665
|
+
|
|
666
|
+
# Stop transports
|
|
667
|
+
if self.ble is not None:
|
|
668
|
+
await self.ble.stop()
|
|
669
|
+
if self.ble_peripheral is not None:
|
|
670
|
+
await self.ble_peripheral.stop()
|
|
671
|
+
if self.internet is not None:
|
|
672
|
+
await self.internet.stop()
|
|
673
|
+
if self.peer_stream is not None:
|
|
674
|
+
await self.peer_stream.stop()
|
|
675
|
+
if self.gateway is not None:
|
|
676
|
+
await self.gateway.stop()
|
|
677
|
+
|
|
678
|
+
# Give the telemetry pipe its final flush while the process is still
|
|
679
|
+
# ours to block: the pipe would also stop when the protocol is
|
|
680
|
+
# dropped, but an explicit disable is what puts the last batch on the
|
|
681
|
+
# wire rather than in the durable queue. Idempotent on the Rust side.
|
|
682
|
+
teardown_clean = True
|
|
683
|
+
try:
|
|
684
|
+
# Off the loop: the final flush blocks for up to three seconds,
|
|
685
|
+
# and every other awaitable in this teardown would wait behind it.
|
|
686
|
+
await _hand_off(self.disable_telemetry)
|
|
687
|
+
except Exception as err:
|
|
688
|
+
teardown_clean = False
|
|
689
|
+
logger.debug(
|
|
690
|
+
"disable_telemetry raised during stop (non-fatal)",
|
|
691
|
+
exc_info=True,
|
|
692
|
+
)
|
|
693
|
+
_forget_frames(err)
|
|
694
|
+
|
|
695
|
+
# Stop protocol engine
|
|
696
|
+
try:
|
|
697
|
+
self._protocol.stop()
|
|
698
|
+
except Exception as err:
|
|
699
|
+
teardown_clean = False
|
|
700
|
+
logger.debug("protocol.stop() raised (non-fatal)", exc_info=True)
|
|
701
|
+
_forget_frames(err)
|
|
702
|
+
|
|
703
|
+
if teardown_clean:
|
|
704
|
+
self._release_callbacks()
|
|
705
|
+
|
|
706
|
+
# Only release GC pins once Rust has confirmed it no longer holds
|
|
707
|
+
# callback handles. If either teardown step raised, Rust may still
|
|
708
|
+
# hold pointers to the pinned objects — dropping the last strong
|
|
709
|
+
# reference here would create a use-after-free risk on any future
|
|
710
|
+
# callback fire.
|
|
711
|
+
if teardown_clean:
|
|
712
|
+
self._prevent_gc.clear()
|
|
713
|
+
self._teardown_pending = False
|
|
714
|
+
elif self._prevent_gc:
|
|
715
|
+
logger.warning(
|
|
716
|
+
"ProtocolManager stop() encountered errors; retaining %d GC "
|
|
717
|
+
"pins so Rust callbacks cannot dangle.",
|
|
718
|
+
len(self._prevent_gc),
|
|
719
|
+
)
|
|
720
|
+
|
|
721
|
+
logger.info("ProtocolManager stopped")
|
|
722
|
+
|
|
723
|
+
def _release_callbacks(self) -> None:
|
|
724
|
+
"""Replaces the callbacks that can reach this manager with inert ones.
|
|
725
|
+
|
|
726
|
+
The core holds every registered callback. The BLE, peer-stream and
|
|
727
|
+
gateway callbacks hold their managers, the event callback holds the
|
|
728
|
+
application's handler (often a bound method of the object that owns
|
|
729
|
+
this manager, or a closure over it), and an application that drives
|
|
730
|
+
Nostr or the gateway slot itself registers its own callback, which
|
|
731
|
+
needs the core to drain it. Each of those reaches
|
|
732
|
+
the core again, and the cycle runs through Rust, so Python's
|
|
733
|
+
collector cannot see it, let alone break it: without this a stopped
|
|
734
|
+
manager is never freed. With the file stores that is not a leak but
|
|
735
|
+
an outage, because the core holds each store's directory lock and
|
|
736
|
+
every later manager over the same directories is refused.
|
|
737
|
+
:meth:`start` registers the real callbacks again.
|
|
738
|
+
"""
|
|
739
|
+
# Every slot, whether or not this manager registered it: the app
|
|
740
|
+
# may have. Each in its own `try`, so one refusal cannot leave the
|
|
741
|
+
# rest held. Every setter accepts a callback for a disabled transport.
|
|
742
|
+
core = self._protocol
|
|
743
|
+
for register, inert in (
|
|
744
|
+
(core.set_event_callback, _EventCallbackImpl(None)),
|
|
745
|
+
(core.set_ble_transport_callback, _BleTransportCallbackImpl(None, None)),
|
|
746
|
+
(
|
|
747
|
+
core.set_wifi_direct_transport_callback,
|
|
748
|
+
_WifiDirectTransportCallbackImpl(None),
|
|
749
|
+
),
|
|
750
|
+
(core.set_nostr_transport_callback, _NostrTransportCallbackImpl()),
|
|
751
|
+
(core.set_reticulum_transport_callback, _ReticulumTransportCallbackImpl(None)),
|
|
752
|
+
):
|
|
753
|
+
try:
|
|
754
|
+
register(inert)
|
|
755
|
+
except Exception:
|
|
756
|
+
logger.debug("releasing a callback raised (non-fatal)", exc_info=True)
|
|
757
|
+
|
|
758
|
+
def __del__(self) -> None:
|
|
759
|
+
# A constructor that raised (a refused argument) leaves no `_running`.
|
|
760
|
+
if getattr(self, "_running", False):
|
|
761
|
+
logger.error(
|
|
762
|
+
"ProtocolManager garbage-collected while still running! "
|
|
763
|
+
"Call await stop() before discarding the manager to avoid "
|
|
764
|
+
"dangling callback pointers on the Rust side."
|
|
765
|
+
)
|
|
766
|
+
|
|
767
|
+
async def __aenter__(self) -> ProtocolManager:
|
|
768
|
+
try:
|
|
769
|
+
await self.start()
|
|
770
|
+
except BaseException:
|
|
771
|
+
# `__aexit__` does not run for an entry that failed, and
|
|
772
|
+
# `async with ProtocolManager(...)` leaves the caller no name to
|
|
773
|
+
# close. A start that fails after the stores opened would hold
|
|
774
|
+
# the directories for as long as the exception lives.
|
|
775
|
+
if self._file_stores is not None:
|
|
776
|
+
try:
|
|
777
|
+
await self.close()
|
|
778
|
+
except Exception:
|
|
779
|
+
logger.debug(
|
|
780
|
+
"close() after a failed start raised (non-fatal)",
|
|
781
|
+
exc_info=True,
|
|
782
|
+
)
|
|
783
|
+
raise
|
|
784
|
+
return self
|
|
785
|
+
|
|
786
|
+
async def __aexit__(self, *exc: Any) -> None:
|
|
787
|
+
# The file stores hold their directories until they are closed, and
|
|
788
|
+
# the name bound by `async with ... as pm` outlives the block, so a
|
|
789
|
+
# stop alone would refuse the next block over the same directories.
|
|
790
|
+
# Any other manager keeps the exit it always had, and can be entered
|
|
791
|
+
# again.
|
|
792
|
+
if self._file_stores is not None:
|
|
793
|
+
await self.close()
|
|
794
|
+
else:
|
|
795
|
+
await self.stop()
|
|
796
|
+
|
|
797
|
+
# -- event handling -------------------------------------------------------
|
|
798
|
+
|
|
799
|
+
def on_event(self, handler: Callable[[dict[str, Any]], None]) -> None:
|
|
800
|
+
"""Register an event handler (replaces the current one)."""
|
|
801
|
+
self._event_handler = handler
|
|
802
|
+
# Update the live callback
|
|
803
|
+
if hasattr(self, "_event_cb"):
|
|
804
|
+
self._event_cb._handler = handler
|
|
805
|
+
|
|
806
|
+
# -- convenience wrappers -------------------------------------------------
|
|
807
|
+
|
|
808
|
+
def send_message(
|
|
809
|
+
self,
|
|
810
|
+
recipient: str,
|
|
811
|
+
content: str,
|
|
812
|
+
*,
|
|
813
|
+
priority: MessagePriority = MessagePriority.MEDIUM,
|
|
814
|
+
reply_to: str | None = None,
|
|
815
|
+
) -> str:
|
|
816
|
+
"""Send a text message and return its message ID.
|
|
817
|
+
|
|
818
|
+
``recipient == "*"`` is a **BLE-only convenience** in this
|
|
819
|
+
wrapper: the message is fanned out one-per-peer to every known
|
|
820
|
+
BLE peer (``get_known_ble_peers``). The Rust core's
|
|
821
|
+
``BleTransport::send()`` treats ``"*"`` as a literal peer-ID
|
|
822
|
+
lookup which always fails, so the fan-out is required for BLE.
|
|
823
|
+
|
|
824
|
+
This wrapper does **not** attempt cross-transport broadcast:
|
|
825
|
+
other transports (Internet, Nostr, Reticulum, Wi-Fi Direct)
|
|
826
|
+
accept ``"*"`` into their send queue but their broadcast
|
|
827
|
+
semantics are platform-layer concerns and are not routed
|
|
828
|
+
automatically by ``send_message``. If you need Nostr or
|
|
829
|
+
Internet broadcast, drive those transports directly.
|
|
830
|
+
|
|
831
|
+
Raises
|
|
832
|
+
------
|
|
833
|
+
ValueError
|
|
834
|
+
If ``recipient == "*"`` and no BLE peers are currently known.
|
|
835
|
+
To tolerate an empty BLE peer set, query
|
|
836
|
+
``get_known_ble_peers`` first or catch this exception.
|
|
837
|
+
"""
|
|
838
|
+
if recipient == "*":
|
|
839
|
+
peers = self.get_known_ble_peers()
|
|
840
|
+
if not peers:
|
|
841
|
+
raise ValueError(
|
|
842
|
+
"ProtocolManager's '*' broadcast fans out over BLE "
|
|
843
|
+
"peers only; no BLE peers are currently known. "
|
|
844
|
+
"Use get_known_ble_peers() to check before sending, "
|
|
845
|
+
"or address a specific peer directly."
|
|
846
|
+
)
|
|
847
|
+
last_id = ""
|
|
848
|
+
for peer_id in peers:
|
|
849
|
+
last_id = self._protocol.send_message(
|
|
850
|
+
recipient=peer_id,
|
|
851
|
+
content=content,
|
|
852
|
+
priority=priority,
|
|
853
|
+
reply_to_msg=reply_to,
|
|
854
|
+
)
|
|
855
|
+
return last_id
|
|
856
|
+
|
|
857
|
+
return self._protocol.send_message(
|
|
858
|
+
recipient=recipient,
|
|
859
|
+
content=content,
|
|
860
|
+
priority=priority,
|
|
861
|
+
reply_to_msg=reply_to,
|
|
862
|
+
)
|
|
863
|
+
|
|
864
|
+
def get_known_ble_peers(self) -> list[str]:
|
|
865
|
+
"""Return user_ids of all BLE-discovered peers (deduplicated).
|
|
866
|
+
|
|
867
|
+
Public because ``send_message("*")`` documents it as the
|
|
868
|
+
escape hatch for callers that want to check before a broadcast.
|
|
869
|
+
Union of central-mode (``self.ble``) and peripheral-mode
|
|
870
|
+
(``self.ble_peripheral``) peer maps.
|
|
871
|
+
"""
|
|
872
|
+
peers: list[str] = []
|
|
873
|
+
if self.ble is not None:
|
|
874
|
+
try:
|
|
875
|
+
with self.ble._lock:
|
|
876
|
+
peers.extend(self.ble._peer_device_ids.values())
|
|
877
|
+
except Exception:
|
|
878
|
+
logger.debug("ble peer lookup failed", exc_info=True)
|
|
879
|
+
if self.ble_peripheral is not None:
|
|
880
|
+
try:
|
|
881
|
+
with self.ble_peripheral._lock:
|
|
882
|
+
peers.extend(self.ble_peripheral._central_to_user_id.values())
|
|
883
|
+
except Exception:
|
|
884
|
+
logger.debug("ble_peripheral peer lookup failed", exc_info=True)
|
|
885
|
+
return list(set(peers))
|
|
886
|
+
|
|
887
|
+
def get_state(self) -> Any:
|
|
888
|
+
"""Return the current protocol state."""
|
|
889
|
+
return self._protocol.get_state()
|
|
890
|
+
|
|
891
|
+
# -- telemetry ------------------------------------------------------------
|
|
892
|
+
|
|
893
|
+
def enable_telemetry(
|
|
894
|
+
self,
|
|
895
|
+
api_key: str,
|
|
896
|
+
app_id: str,
|
|
897
|
+
app_version: str | None = None,
|
|
898
|
+
*,
|
|
899
|
+
debug: bool | None = None,
|
|
900
|
+
flush_interval_ms: int | None = None,
|
|
901
|
+
max_batch_bytes: int | None = None,
|
|
902
|
+
max_buffered_records: int | None = None,
|
|
903
|
+
include_device_id: bool | None = None,
|
|
904
|
+
scrub_ids: bool | None = None,
|
|
905
|
+
mls_verbosity: MlsVerbosity | None = None,
|
|
906
|
+
metrics_cadence_ms: int | None = None,
|
|
907
|
+
routing_diagnostic: bool | None = None,
|
|
908
|
+
mls_sampling_bypass: bool | None = None,
|
|
909
|
+
app_state: AppState = AppState.ACTIVE,
|
|
910
|
+
) -> None:
|
|
911
|
+
"""Enable telemetry: the SDK collects, batches and uploads accepted
|
|
912
|
+
events to the Offline Protocol ingest itself, on a background thread
|
|
913
|
+
inside the native library.
|
|
914
|
+
|
|
915
|
+
``api_key`` and ``app_id`` come from the developer portal. The host
|
|
916
|
+
platform is filled in from :mod:`platform`, never by the caller.
|
|
917
|
+
Every keyword argument left ``None`` keeps the Rust default. The
|
|
918
|
+
batch queue is durable from the first batch, because
|
|
919
|
+
:meth:`start` attaches the protocol-state store before anything is
|
|
920
|
+
emitted.
|
|
921
|
+
|
|
922
|
+
Raises ``ProtocolError.TelemetryConfigInvalid`` naming the refused
|
|
923
|
+
field. Calling it again replaces the running pipe after its final
|
|
924
|
+
flush. See ``docs/telemetry.md`` for what leaves the device.
|
|
925
|
+
"""
|
|
926
|
+
os_kind, os_major = _host_platform()
|
|
927
|
+
config = TelemetryConfig(
|
|
928
|
+
api_key=api_key,
|
|
929
|
+
app_id=app_id,
|
|
930
|
+
os=os_kind,
|
|
931
|
+
os_major=os_major,
|
|
932
|
+
app_version=app_version,
|
|
933
|
+
debug=debug,
|
|
934
|
+
flush_interval_ms=flush_interval_ms,
|
|
935
|
+
max_batch_bytes=max_batch_bytes,
|
|
936
|
+
max_buffered_records=max_buffered_records,
|
|
937
|
+
include_device_id=include_device_id,
|
|
938
|
+
scrub_ids=scrub_ids,
|
|
939
|
+
mls_verbosity=mls_verbosity,
|
|
940
|
+
metrics_cadence_ms=metrics_cadence_ms,
|
|
941
|
+
routing_diagnostic=routing_diagnostic,
|
|
942
|
+
mls_sampling_bypass=mls_sampling_bypass,
|
|
943
|
+
)
|
|
944
|
+
self._protocol.enable_telemetry(config, app_state)
|
|
945
|
+
|
|
946
|
+
def disable_telemetry(self) -> None:
|
|
947
|
+
"""Disable telemetry after one final flush of up to three seconds.
|
|
948
|
+
Idempotent.
|
|
949
|
+
|
|
950
|
+
**Blocks the calling thread** for the length of that flush. This
|
|
951
|
+
manager is otherwise asyncio-based, so from a coroutine call it as
|
|
952
|
+
``await asyncio.to_thread(manager.disable_telemetry)`` rather than
|
|
953
|
+
directly, the way :meth:`stop` already hands its blocking work off.
|
|
954
|
+
"""
|
|
955
|
+
self._protocol.disable_telemetry()
|
|
956
|
+
|
|
957
|
+
def flush_telemetry(self) -> None:
|
|
958
|
+
"""Ask the uploader to send what is queued now. Returns at once."""
|
|
959
|
+
self._protocol.flush_telemetry()
|
|
960
|
+
|
|
961
|
+
def telemetry_stats(self) -> TelemetryStats | None:
|
|
962
|
+
"""The pipe's counters, or ``None`` while telemetry is not enabled.
|
|
963
|
+
|
|
964
|
+
``accepted_events`` is what the ingest reported accepting, which is
|
|
965
|
+
what an invoice is reconciled against; ``dropped`` counts events
|
|
966
|
+
lost to the ring buffer, the queue caps, the six-day expiry, a
|
|
967
|
+
permanent rejection, or everything queued or collected after the
|
|
968
|
+
ingest reported the application's telemetry toggle off;
|
|
969
|
+
``last_error`` is the most recent send failure.
|
|
970
|
+
"""
|
|
971
|
+
return self._protocol.telemetry_stats()
|
|
972
|
+
|
|
973
|
+
def end_telemetry_session(self) -> None:
|
|
974
|
+
"""Close the current telemetry session: a summary, a flush of up to
|
|
975
|
+
three seconds, then a fresh session id.
|
|
976
|
+
|
|
977
|
+
**Blocks the calling thread** for the length of that flush; see
|
|
978
|
+
:meth:`disable_telemetry`. :meth:`flush_telemetry` is the
|
|
979
|
+
non-blocking call.
|
|
980
|
+
"""
|
|
981
|
+
self._protocol.end_telemetry_session()
|
|
982
|
+
|
|
983
|
+
def notify_app_state(self, state: AppState) -> None:
|
|
984
|
+
"""Report an application lifecycle transition. ``BACKGROUND`` closes
|
|
985
|
+
the session and requests a flush; the first ``ACTIVE`` after it
|
|
986
|
+
opens the next one. A desktop host that has no such lifecycle never
|
|
987
|
+
needs to call this."""
|
|
988
|
+
self._protocol.notify_app_state(state)
|
|
989
|
+
|
|
990
|
+
def set_telemetry_enabled(self, enabled: bool) -> None:
|
|
991
|
+
"""Stop or resume collection without tearing the pipe down. Off,
|
|
992
|
+
every emit costs one atomic load and nothing is buffered; what is
|
|
993
|
+
already queued still drains."""
|
|
994
|
+
self._protocol.set_telemetry_enabled(enabled)
|
|
995
|
+
|
|
996
|
+
def telemetry_install_id(self) -> str | None:
|
|
997
|
+
"""Stable, opaque per-install telemetry identifier (32 hex chars),
|
|
998
|
+
derived from the SDK-managed persistent scrub secret. The secret
|
|
999
|
+
itself never crosses the FFI and cannot be recovered from the id.
|
|
1000
|
+
|
|
1001
|
+
Returns ``None`` until the persistent secret is available, which is
|
|
1002
|
+
after :meth:`start` has wired secure storage. Stamped on telemetry
|
|
1003
|
+
batches only when ``include_device_id`` was set; that setting is a
|
|
1004
|
+
disclosure decision, see ``docs/privacy.md``.
|
|
1005
|
+
"""
|
|
1006
|
+
return self._protocol.telemetry_install_id()
|
|
1007
|
+
|
|
1008
|
+
# -- processing loop ------------------------------------------------------
|
|
1009
|
+
|
|
1010
|
+
async def _process_loop(self) -> None:
|
|
1011
|
+
"""Call ``protocol.process()`` every 100 ms (matches iOS/Android)."""
|
|
1012
|
+
try:
|
|
1013
|
+
while self._running:
|
|
1014
|
+
try:
|
|
1015
|
+
self._protocol.process()
|
|
1016
|
+
self._drain_incoming_messages()
|
|
1017
|
+
except Exception as exc:
|
|
1018
|
+
logger.error("Process error: %s", exc)
|
|
1019
|
+
await asyncio.sleep(_PROCESS_INTERVAL)
|
|
1020
|
+
except asyncio.CancelledError:
|
|
1021
|
+
return
|
|
1022
|
+
|
|
1023
|
+
def _drain_incoming_messages(self) -> None:
|
|
1024
|
+
"""Drain up to 100 messages per tick and dispatch to the event handler.
|
|
1025
|
+
|
|
1026
|
+
``receive_message()`` returns JSON strings. Each message is parsed
|
|
1027
|
+
and forwarded as a ``message_received`` event so that users only need
|
|
1028
|
+
to subscribe to the event handler (matching the iOS/Android pattern).
|
|
1029
|
+
|
|
1030
|
+
Note: because the processing loop consumes this queue, calling
|
|
1031
|
+
``protocol.receive_message()`` directly while ProtocolManager is
|
|
1032
|
+
running will always return ``None``.
|
|
1033
|
+
"""
|
|
1034
|
+
handler = self._event_handler
|
|
1035
|
+
drained = 0
|
|
1036
|
+
while drained < _MAX_MESSAGES_PER_TICK:
|
|
1037
|
+
raw = self._protocol.receive_message()
|
|
1038
|
+
if raw is None:
|
|
1039
|
+
break
|
|
1040
|
+
drained += 1
|
|
1041
|
+
|
|
1042
|
+
try:
|
|
1043
|
+
event = json.loads(raw)
|
|
1044
|
+
if isinstance(event, dict):
|
|
1045
|
+
event.setdefault("type", "message_received")
|
|
1046
|
+
else:
|
|
1047
|
+
event = {"type": "message_received", "raw": raw}
|
|
1048
|
+
except json.JSONDecodeError:
|
|
1049
|
+
event = {"type": "message_received", "raw": raw}
|
|
1050
|
+
|
|
1051
|
+
# Resolve BLE peripheral peer identity from the sender field.
|
|
1052
|
+
# The BLE central path reads the DEVICE_ID characteristic to
|
|
1053
|
+
# learn the peer's user_id; the peripheral has no equivalent
|
|
1054
|
+
# mechanism, so we extract it from the first received message.
|
|
1055
|
+
if (
|
|
1056
|
+
self.ble_peripheral is not None
|
|
1057
|
+
and isinstance(event, dict)
|
|
1058
|
+
and event.get("type") == "message_received"
|
|
1059
|
+
):
|
|
1060
|
+
sender = event.get("sender") or event.get("sender_id")
|
|
1061
|
+
if sender:
|
|
1062
|
+
self.ble_peripheral.resolve_sender_identity(sender)
|
|
1063
|
+
|
|
1064
|
+
if handler is not None:
|
|
1065
|
+
try:
|
|
1066
|
+
handler(event)
|
|
1067
|
+
except Exception:
|
|
1068
|
+
logger.debug("Event handler error for message", exc_info=True)
|
|
1069
|
+
if drained == _MAX_MESSAGES_PER_TICK:
|
|
1070
|
+
logger.warning(
|
|
1071
|
+
"Capped receiveMessage drain at %d for this tick",
|
|
1072
|
+
_MAX_MESSAGES_PER_TICK,
|
|
1073
|
+
)
|
|
1074
|
+
|
|
1075
|
+
|
|
1076
|
+
def _host_platform() -> tuple[TelemetryOs, int]:
|
|
1077
|
+
"""The host as the telemetry ingest names it, and its major version.
|
|
1078
|
+
|
|
1079
|
+
Filled here rather than by the caller: the ingest keys its per-platform
|
|
1080
|
+
aggregates on these, and a value the application cannot set is a value
|
|
1081
|
+
it cannot set wrong.
|
|
1082
|
+
"""
|
|
1083
|
+
system = platform.system()
|
|
1084
|
+
if system == "Darwin":
|
|
1085
|
+
release = platform.mac_ver()[0] or "0"
|
|
1086
|
+
return TelemetryOs.MACOS, _major(release)
|
|
1087
|
+
if system == "Linux":
|
|
1088
|
+
return TelemetryOs.LINUX, _major(platform.release())
|
|
1089
|
+
if system == "Windows":
|
|
1090
|
+
# `platform.release()` answers "10" on Windows 11, so on its own it
|
|
1091
|
+
# would fold two releases into one bucket for the whole life of the
|
|
1092
|
+
# aggregate. The build number is what separates them: 22000 is the
|
|
1093
|
+
# first Windows 11 build, and Microsoft never moved it.
|
|
1094
|
+
try:
|
|
1095
|
+
build = sys.getwindowsversion().build # type: ignore[attr-defined]
|
|
1096
|
+
except (AttributeError, OSError):
|
|
1097
|
+
build = 0
|
|
1098
|
+
return TelemetryOs.WINDOWS, 11 if build >= 22000 else _major(platform.release())
|
|
1099
|
+
return TelemetryOs.OTHER, 0
|
|
1100
|
+
|
|
1101
|
+
|
|
1102
|
+
def _major(version: str) -> int:
|
|
1103
|
+
head = version.split(".", 1)[0]
|
|
1104
|
+
digits = "".join(ch for ch in head if ch.isdigit())
|
|
1105
|
+
try:
|
|
1106
|
+
return max(0, min(int(digits), 65535)) if digits else 0
|
|
1107
|
+
except ValueError:
|
|
1108
|
+
return 0
|