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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. offline_protocol_sdk/__init__.py +22 -0
  2. offline_protocol_sdk/_callback_reentrancy.py +64 -0
  3. offline_protocol_sdk/address_declaration.py +207 -0
  4. offline_protocol_sdk/ble_manager.py +595 -0
  5. offline_protocol_sdk/ble_peripheral.py +673 -0
  6. offline_protocol_sdk/dnssd_bridge.py +614 -0
  7. offline_protocol_sdk/gateway_attach_policy.py +437 -0
  8. offline_protocol_sdk/gateway_manager.py +1217 -0
  9. offline_protocol_sdk/gateway_verdict_tracker.py +97 -0
  10. offline_protocol_sdk/internet_manager.py +1444 -0
  11. offline_protocol_sdk/legacy_store_adoption.py +184 -0
  12. offline_protocol_sdk/local_api/__init__.py +34 -0
  13. offline_protocol_sdk/local_api/authz.py +180 -0
  14. offline_protocol_sdk/local_api/cli.py +171 -0
  15. offline_protocol_sdk/local_api/codec.py +210 -0
  16. offline_protocol_sdk/local_api/dispatch.py +537 -0
  17. offline_protocol_sdk/local_api/mux.py +239 -0
  18. offline_protocol_sdk/local_api/server.py +546 -0
  19. offline_protocol_sdk/local_api/session.py +86 -0
  20. offline_protocol_sdk/local_api/table.py +849 -0
  21. offline_protocol_sdk/offline_protocol.py +13508 -0
  22. offline_protocol_sdk/peer_stream_manager.py +1303 -0
  23. offline_protocol_sdk/presence_watch_policy.py +102 -0
  24. offline_protocol_sdk/protocol_manager.py +1108 -0
  25. offline_protocol_sdk/relay_answer_prefixes.py +61 -0
  26. offline_protocol_sdk/secure_storage.py +551 -0
  27. offline_protocol_sdk/services.py +195 -0
  28. offline_protocol_sdk/state_storage.py +452 -0
  29. offline_protocol_sdk/storage_namespace.py +33 -0
  30. offline_protocol_sdk/transport_manager.py +138 -0
  31. offline_protocol_sdk/uniffi.dll +0 -0
  32. offline_protocol_sdk-0.28.0.dist-info/METADATA +519 -0
  33. offline_protocol_sdk-0.28.0.dist-info/RECORD +40 -0
  34. offline_protocol_sdk-0.28.0.dist-info/WHEEL +5 -0
  35. offline_protocol_sdk-0.28.0.dist-info/entry_points.txt +2 -0
  36. offline_protocol_sdk-0.28.0.dist-info/licenses/EXPORT.md +68 -0
  37. offline_protocol_sdk-0.28.0.dist-info/licenses/LICENSE +661 -0
  38. offline_protocol_sdk-0.28.0.dist-info/licenses/LICENSE-COMMERCIAL.md +89 -0
  39. offline_protocol_sdk-0.28.0.dist-info/licenses/THIRD-PARTY-NOTICES.md +6645 -0
  40. offline_protocol_sdk-0.28.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,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