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,1303 @@
1
+ """Peer-stream transport manager: TCP streams behind the ``wifi_direct`` slot.
2
+
3
+ A peer stream is a byte stream established to exactly one other device. On a
4
+ phone that is a Wi-Fi Direct group socket or a TCP stream over AWDL; on a host
5
+ it is a TCP connection over a LAN or a routed mesh. To the engine they are one
6
+ transport, registered in the slot the FFI names ``wifi_direct`` for
7
+ historical reasons, and this manager is the host's implementation of the
8
+ contract that makes them one: ``docs/spec/stream-framing.md``.
9
+
10
+ The two things a stream does not get from its socket for free are where a
11
+ message ends and who the peer is, and both are settled here:
12
+
13
+ * **Every frame is a ``u32`` big-endian length, then that many bytes.** A
14
+ length of zero, or above the 1 MiB message ceiling, closes the stream
15
+ before a byte of the body is read, so a hostile prefix costs four bytes and
16
+ never an allocation. The ceiling is inclusive.
17
+ * **The first frame in each direction is the identity assertion.** This
18
+ side sends its own as soon as the stream opens, without waiting for the
19
+ peer's, and verifies the peer's through ``verify_identity_assertion``, the
20
+ one verifier of that layout. A peer is announced to the core only under
21
+ the address that verification derived, never under a socket address, a
22
+ hostname, or an address merely read from a discovery record. A stream
23
+ whose preamble does not verify carries nothing and is closed, and a stream
24
+ that never proved a peer is never reported lost.
25
+ * **A stream carries one peer, and this host holds one announced stream per
26
+ address.** When a second stream proves an address already announced, one
27
+ of the two is kept and the other closed without a report, so the core sees
28
+ one announcement and, later, one loss for that address; without that rule,
29
+ a copied preamble on a second socket would let its close read as the real
30
+ peer's loss. Which one is kept is decided the same way on both ends: the
31
+ stream opened by the lower address wins. Two hosts that each list the
32
+ other open toward each other at once, and without a shared rule each would
33
+ keep the stream the other discards, close the other's, and reconnect
34
+ forever. Between two streams of the winning kind (the lower address
35
+ reconnecting while its old stream is still half-open here) the newer one
36
+ supersedes the older; the cost, that a copied preamble can force the real
37
+ peer to reconnect, is bounded by the same rule to exactly that, and the
38
+ threat model records it as R16. The higher address gets no such help: its
39
+ reconnect is the losing kind for as long as the lower side holds a stream
40
+ it believes live. So every stream carries TCP keepalive, which ends an
41
+ idle dead peer's stream within a bound, and every attempt that ends
42
+ unannounced climbs the reconnect ladder rather than retrying at a fixed
43
+ pace.
44
+ * **One peer's receive window never holds another peer's traffic.** The
45
+ core hands every outbound body through one queue, and each is moved at
46
+ once onto its stream's own queue, written by that stream's own writer.
47
+ A peer that stops reading, or reads slowly, stalls only itself. The queue
48
+ is bounded (4 MiB) only while its writer is paused on the peer, so a
49
+ burst handed over while the writer is idle is never dropped; one that
50
+ arrives while a frame is still in flight can be, and the retry path
51
+ re-offers it. The stream is aborted and reported lost once the buffers
52
+ between the two hosts are full and the peer then takes nothing for the
53
+ write deadline, so a slow link that is moving is never cut. Below that
54
+ point this layer cannot tell a stopped peer from a buffering one: both
55
+ kernels absorb on the order of a megabyte on a default host, so a peer
56
+ that is alive but not reading, under light traffic, stays announced, and
57
+ the reliability layer's acknowledgements are the only signal. Keepalive
58
+ does not cover the case either: a stream with data in flight is not idle,
59
+ and outside Linux nothing bounds its retransmissions.
60
+
61
+ The Rust reference for the same rules is ``stream_framing.rs`` in the
62
+ transport crate, and its conformance vectors are the ones this manager's
63
+ tests replay. The bounds are asserted as literals in ``test_peer_stream_manager.py``
64
+ rather than read from the core, for the reason the bridge rules give: a test
65
+ that read them would agree with any edit.
66
+
67
+ Peers come from two sources. A static peer list (``host:port`` entries, or
68
+ ``off1…@host:port`` when the address is known, which turns on the chapter's
69
+ fourth verification step: the derived address must equal the claim exactly)
70
+ serves routed meshes and tests. DNS-SD serves a LAN, through the optional
71
+ ``zeroconf`` dependency (``pip install 'offline-protocol-sdk[lan]'``): this
72
+ host advertises ``_offlineprotocol._tcp`` with ``txtvers=1`` and
73
+ ``addr=<off1…>`` and browses for the same, and the ``addr`` in a record is a
74
+ hint the preamble proves, never a name to announce.
75
+
76
+ The link is not encrypted by this manager. The chapter is explicit that link
77
+ encryption forms no part of the trust argument: every message inside a frame
78
+ authenticates itself at the layer that owns it, and a host that wants the
79
+ hop's bytes private on a shared LAN puts the stream inside whatever it
80
+ trusts for that (a mesh VPN, an SSH tunnel) and configures the peer list
81
+ accordingly.
82
+ """
83
+
84
+ from __future__ import annotations
85
+
86
+ import asyncio
87
+ import hashlib
88
+ import ipaddress
89
+ import logging
90
+ import socket
91
+ from dataclasses import dataclass
92
+ from typing import Any
93
+
94
+ from .offline_protocol import verify_identity_assertion
95
+ from .transport_manager import TransportError, TransportManager, TransportState
96
+
97
+ logger = logging.getLogger(__name__)
98
+
99
+ # -- Framing constants (docs/spec/stream-framing.md) --------------------------
100
+ # Mirrors of the Rust constants; pinned as literals by the tests.
101
+
102
+ #: The prefix on every frame: a ``u32``, big-endian.
103
+ LENGTH_PREFIX_LEN = 4
104
+ #: Ceiling on a frame body, inclusive: the transport message ceiling.
105
+ MAX_FRAME_BYTES = 1024 * 1024
106
+ #: Floor on a preamble body: the identity assertion's own floor.
107
+ PREAMBLE_FLOOR = 96
108
+
109
+ # -- DNS-SD (RFC 6763) ---------------------------------------------------------
110
+
111
+ #: The service type the chapter fixes. Fifteen characters, the label maximum.
112
+ SERVICE_TYPE = "_offlineprotocol._tcp.local."
113
+ #: The first TXT entry, as RFC 6763 section 6.7 recommends.
114
+ TXT_VERSION = "1"
115
+
116
+ # -- Policy (local, not wire format) ------------------------------------------
117
+
118
+ #: Seconds a freshly opened stream has to deliver its whole preamble frame,
119
+ #: prefix and body together. A deadline on the prefix alone would let four
120
+ #: bytes and then silence hold a slot forever.
121
+ PREAMBLE_TIMEOUT = 10.0
122
+ #: Seconds an outbound connect may take before it counts as a failed attempt.
123
+ CONNECT_TIMEOUT = 10.0
124
+ #: Streams this host holds open at once, announced or not.
125
+ MAX_STREAMS = 64
126
+ #: Inbound streams one remote host may hold at once, announced or not. A host
127
+ #: needs one, two while it reconnects past its own stale stream; without a
128
+ #: per-host bound one machine on the LAN fills ``MAX_STREAMS`` alone, with
129
+ #: silent sockets or with as many self-made identities.
130
+ MAX_STREAMS_PER_HOST = 8
131
+ #: Outbound reconnect ladder for a configured peer. Doubled after every
132
+ #: attempt that ends without an announced stream (connect failure, a silent
133
+ #: or closing endpoint, a tie-break loss), reset once a stream is announced.
134
+ RECONNECT_INITIAL_DELAY = 1.0
135
+ RECONNECT_MAX_DELAY = 30.0
136
+ #: Ceiling on the cooldown after repeated preamble refusals from one endpoint,
137
+ #: doubled per refusal from ``RECONNECT_INITIAL_DELAY``. A peer that cannot
138
+ #: prove its address fails the same way every time.
139
+ REFUSAL_BACKOFF_MAX = 600.0
140
+ #: TCP keepalive on every stream: idle seconds, probe interval, probe count.
141
+ #: An idle stream to a host that lost power or left the network is otherwise
142
+ #: never noticed, and the tie-break keeps an announced stream over a new one
143
+ #: of the losing kind, so an unnoticed dead stream would lock the peer out.
144
+ KEEPALIVE_IDLE = 15
145
+ KEEPALIVE_INTERVAL = 5
146
+ KEEPALIVE_COUNT = 3
147
+ #: Seconds the write buffer may sit with no byte leaving it, once the peer's
148
+ #: receive window and our send buffer are both full, before the stream is
149
+ #: aborted. Until those fill (on the order of a megabyte on a default host)
150
+ #: the kernel takes every write and this deadline cannot start, and bytes
151
+ #: moving into the kernel count as progress, so detection can take two of
152
+ #: these. Keepalive ends an *idle* dead stream; a stream with
153
+ #: unacknowledged data is not idle, and on macOS and Windows nothing else
154
+ #: bounds it, so without this a peer that stops reading holds its stream,
155
+ #: and everything queued to it, for as long as TCP keeps retransmitting.
156
+ #: Measured on progress, not per frame: a per-frame deadline is a throughput
157
+ #: floor (1 MiB in thirty seconds), and a slow link below it would be
158
+ #: aborted, reconnected, offered the same frame and aborted again, forever.
159
+ WRITE_TIMEOUT = 30.0
160
+ #: Bytes queued toward one stream and not yet written, while its writer is
161
+ #: blocked on the peer. A body that would go over is dropped (the
162
+ #: reliability layer retries it) rather than buffered without bound behind a
163
+ #: peer that is not taking any. One frame is always accepted onto an empty
164
+ #: queue, so the largest legal frame is never refused by this bound.
165
+ MAX_QUEUED_BYTES = 4 * 1024 * 1024
166
+
167
+
168
+ @dataclass(frozen=True)
169
+ class PeerEntry:
170
+ """A configured peer: where to connect, and optionally who to expect.
171
+
172
+ ``expected_address`` is a claim about the peer, and turns on the
173
+ chapter's fourth verification step: the address the preamble derives
174
+ must equal it exactly, or the stream is closed. It is never what gets
175
+ announced; the derived address is.
176
+ """
177
+
178
+ host: str
179
+ port: int
180
+ expected_address: str | None = None
181
+
182
+ @classmethod
183
+ def parse(cls, entry: str) -> "PeerEntry":
184
+ """Parse ``host:port`` or ``off1…@host:port``.
185
+
186
+ An IPv6 literal is written in brackets, ``[::1]:7878``.
187
+ """
188
+ expected: str | None = None
189
+ rest = entry.strip()
190
+ if "@" in rest:
191
+ expected, rest = rest.rsplit("@", 1)
192
+ expected = expected.strip()
193
+ if not expected:
194
+ raise ValueError(f"empty address before '@' in peer entry {entry!r}")
195
+ if rest.startswith("["):
196
+ close = rest.find("]")
197
+ if close < 0 or not rest[close + 1 :].startswith(":"):
198
+ raise ValueError(f"malformed IPv6 peer entry {entry!r}")
199
+ host, port_text = rest[1:close], rest[close + 2 :]
200
+ else:
201
+ if ":" not in rest:
202
+ raise ValueError(f"peer entry {entry!r} has no port")
203
+ host, port_text = rest.rsplit(":", 1)
204
+ if not host:
205
+ raise ValueError(f"peer entry {entry!r} has no host")
206
+ try:
207
+ port = int(port_text)
208
+ except ValueError as exc:
209
+ raise ValueError(f"peer entry {entry!r} has a non-numeric port") from exc
210
+ if not 1 <= port <= 65535:
211
+ raise ValueError(f"peer entry {entry!r} port out of range")
212
+ return cls(host=host, port=port, expected_address=expected)
213
+
214
+ @property
215
+ def endpoint(self) -> str:
216
+ return f"{self.host}:{self.port}"
217
+
218
+
219
+ class _Stream:
220
+ """One stream, both directions, and what it has proved."""
221
+
222
+ __slots__ = (
223
+ "reader",
224
+ "writer",
225
+ "endpoint",
226
+ "remote_host",
227
+ "expected",
228
+ "outbound",
229
+ "peer",
230
+ "learned",
231
+ "was_announced",
232
+ "superseded",
233
+ "outbound_queue",
234
+ "queued_bytes",
235
+ "writer_task",
236
+ "write_blocked",
237
+ )
238
+
239
+ def __init__(
240
+ self,
241
+ reader: asyncio.StreamReader,
242
+ writer: asyncio.StreamWriter,
243
+ endpoint: str,
244
+ expected: str | None,
245
+ outbound: bool,
246
+ remote_host: str | None = None,
247
+ ) -> None:
248
+ self.reader = reader
249
+ self.writer = writer
250
+ self.endpoint = endpoint
251
+ #: The remote IP, for the per-host bound on inbound streams.
252
+ self.remote_host = remote_host
253
+ self.expected = expected
254
+ #: Whether this host opened the stream. Decides the tie-break.
255
+ self.outbound = outbound
256
+ #: The address this stream is announced under, while it is.
257
+ self.peer: str | None = None
258
+ #: The address the preamble derived, kept even when the stream was
259
+ #: not the one announced, so a connector knows whom it reached.
260
+ self.learned: str | None = None
261
+ #: Whether this stream was ever the announced one, so a connector
262
+ #: can tell a lost link (reconnect now) from an attempt that went
263
+ #: nowhere (climb the ladder).
264
+ self.was_announced = False
265
+ #: Set when a newer stream took the announcement over. The stream
266
+ #: may still have a body in its buffer, and none may reach the core:
267
+ #: its frames belong to no announced peer any more.
268
+ self.superseded = False
269
+ #: Framed bodies waiting for this stream's writer, and their total
270
+ #: size. Per stream, so a peer that stops reading holds only its own.
271
+ self.outbound_queue: asyncio.Queue[bytes] = asyncio.Queue()
272
+ self.queued_bytes = 0
273
+ #: The task writing ``outbound_queue``, once the preamble is out.
274
+ self.writer_task: asyncio.Task[None] | None = None
275
+ #: Whether the writer is waiting on the peer's receive window right
276
+ #: now. The queue bound applies only then: a burst the core hands
277
+ #: over in one tick arrives before the writer has run at all, says
278
+ #: nothing about the peer, and its bytes were already held by the
279
+ #: core's queue.
280
+ self.write_blocked = False
281
+
282
+
283
+ def frame(body: bytes) -> bytes:
284
+ """Wrap one body as one frame, refusing what a receiver would refuse."""
285
+ if not body:
286
+ raise ValueError("a frame body is at least one byte")
287
+ if len(body) > MAX_FRAME_BYTES:
288
+ raise ValueError(
289
+ f"frame body of {len(body)} bytes is above the {MAX_FRAME_BYTES}-byte ceiling"
290
+ )
291
+ return len(body).to_bytes(LENGTH_PREFIX_LEN, "big") + body
292
+
293
+
294
+ def _digest(address: str) -> str:
295
+ return hashlib.sha256(address.encode("utf-8")).hexdigest()[:16]
296
+
297
+
298
+ def service_instance_name(address: str) -> str:
299
+ """The DNS-SD instance name for an address: a short digest, not the
300
+ address itself, which the TXT record already carries."""
301
+ return f"op-{_digest(address)}.{SERVICE_TYPE}"
302
+
303
+
304
+ def service_host_name(address: str) -> str:
305
+ """The host name the SRV record targets and the A/AAAA records name.
306
+
307
+ Its own name rather than the machine's: the operating system's responder
308
+ may already publish ``<hostname>.local.``, and two responders answering
309
+ for one name is a conflict. Without a host name and addresses at all the
310
+ record is unresolvable: a browser sees the service appear and can never
311
+ learn where it is.
312
+ """
313
+ return f"op-{_digest(address)}.local."
314
+
315
+
316
+ def _set_keepalive(writer: asyncio.StreamWriter) -> None:
317
+ """Turn TCP keepalive on for a stream, with the tightest timers the
318
+ platform exposes. Best effort: a socket that refuses an option keeps the
319
+ rest."""
320
+ sock = writer.get_extra_info("socket")
321
+ if sock is None:
322
+ return
323
+ try:
324
+ sock.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
325
+ except OSError:
326
+ return
327
+ # TCP_KEEPIDLE on Linux and Windows, TCP_KEEPALIVE (the idle time) on macOS.
328
+ idle_option = getattr(socket, "TCP_KEEPIDLE", None) or getattr(socket, "TCP_KEEPALIVE", None)
329
+ options = [
330
+ (idle_option, KEEPALIVE_IDLE),
331
+ (getattr(socket, "TCP_KEEPINTVL", None), KEEPALIVE_INTERVAL),
332
+ (getattr(socket, "TCP_KEEPCNT", None), KEEPALIVE_COUNT),
333
+ # Linux: bound how long unacknowledged data may sit, which keepalive
334
+ # does not cover once a write is in flight.
335
+ (
336
+ getattr(socket, "TCP_USER_TIMEOUT", None),
337
+ (KEEPALIVE_IDLE + KEEPALIVE_INTERVAL * KEEPALIVE_COUNT) * 1000,
338
+ ),
339
+ ]
340
+ for option, value in options:
341
+ if option is None:
342
+ continue
343
+ try:
344
+ sock.setsockopt(socket.IPPROTO_TCP, option, value)
345
+ except OSError:
346
+ pass
347
+
348
+
349
+ def _write_paused(writer: asyncio.StreamWriter) -> bool:
350
+ """Whether ``drain()`` will wait: the transport's buffer is over its
351
+ high-water mark, which is when asyncio pauses the writer. Assumed paused
352
+ when the transport cannot say."""
353
+ try:
354
+ transport = writer.transport
355
+ return transport.get_write_buffer_size() > transport.get_write_buffer_limits()[1]
356
+ except Exception:
357
+ return True
358
+
359
+
360
+ def _discard_socket(writer: asyncio.StreamWriter) -> None:
361
+ """Close a stream's socket now, whatever is still buffered.
362
+
363
+ ``writer.close()`` waits for the write buffer to flush before the socket
364
+ goes, and toward a peer that stopped reading it never flushes: the
365
+ socket, and a writer awaiting ``drain()`` on it, would outlive the close.
366
+ Abort discards the buffer, which is correct for a stream being
367
+ discarded; a stream with nothing buffered closes gracefully.
368
+ """
369
+ try:
370
+ transport = writer.transport
371
+ if transport.get_write_buffer_size() > 0:
372
+ transport.abort()
373
+ return
374
+ except Exception:
375
+ pass
376
+ try:
377
+ writer.close()
378
+ except Exception:
379
+ pass
380
+
381
+
382
+ class PeerStreamManager(TransportManager):
383
+ """The host's peer-stream transport: a TCP listener, outbound connections
384
+ to configured and discovered peers, the preamble exchange, and the drain
385
+ of the core's outbound queue onto the stream that proved each recipient.
386
+
387
+ Parameters
388
+ ----------
389
+ protocol:
390
+ The ``OfflineProtocol`` UniFFI instance. Its MLS must be initialised
391
+ before :meth:`start`, because a stream layer that cannot prove its
392
+ own address is refused by every conforming peer.
393
+ listen_host, listen_port:
394
+ Where to accept streams. The default ``0.0.0.0`` accepts on every
395
+ interface; pass ``127.0.0.1`` or one interface's address to narrow
396
+ it. Port ``0`` binds an ephemeral port, readable afterwards as
397
+ :attr:`listen_port`; ``listen_port=None`` accepts nothing and only
398
+ connects out.
399
+ peers:
400
+ Static peer entries, as :class:`PeerEntry` values or strings
401
+ :meth:`PeerEntry.parse` accepts. Each is connected with a reconnect
402
+ ladder for as long as the manager runs.
403
+ advertise, discover:
404
+ Publish this host over DNS-SD, and connect to hosts found there.
405
+ Either requires the optional ``zeroconf`` dependency.
406
+ write_timeout:
407
+ Seconds the write buffer may make no progress, once the kernel
408
+ buffers toward the peer are full, before its stream is aborted and
409
+ reported lost.
410
+ """
411
+
412
+ transport_id = "wifi_direct"
413
+ transport_name = "Peer stream (TCP)"
414
+
415
+ def __init__(
416
+ self,
417
+ protocol: Any,
418
+ *,
419
+ listen_host: str = "0.0.0.0",
420
+ listen_port: int | None = 0,
421
+ peers: Any = (),
422
+ advertise: bool = False,
423
+ discover: bool = False,
424
+ preamble_timeout: float = PREAMBLE_TIMEOUT,
425
+ max_streams: int = MAX_STREAMS,
426
+ max_streams_per_host: int = MAX_STREAMS_PER_HOST,
427
+ write_timeout: float = WRITE_TIMEOUT,
428
+ ) -> None:
429
+ super().__init__()
430
+ self._protocol = protocol
431
+ self.listen_host = listen_host
432
+ self._listen_port_requested = listen_port
433
+ #: The bound port once started, ``None`` before or when not listening.
434
+ self.listen_port: int | None = None
435
+ self._peers: list[PeerEntry] = [
436
+ p if isinstance(p, PeerEntry) else PeerEntry.parse(p) for p in peers
437
+ ]
438
+ self.advertise = advertise
439
+ self.discover = discover
440
+ self._preamble_timeout = preamble_timeout
441
+ self._max_streams = max_streams
442
+ self._max_streams_per_host = max_streams_per_host
443
+ self._write_timeout = write_timeout
444
+
445
+ self._loop: asyncio.AbstractEventLoop | None = None
446
+ self._server: asyncio.base_events.Server | None = None
447
+ #: Every open stream, announced or not.
448
+ self._streams: set[_Stream] = set()
449
+ #: The one announced stream per proved address.
450
+ self._by_peer: dict[str, _Stream] = {}
451
+ #: connector key -> the task keeping a stream open toward it.
452
+ self._connector_tasks: dict[str, asyncio.Task[None]] = {}
453
+ #: connector key -> the entries it tries, in order, on each attempt.
454
+ #: A discovered host's addresses can change while its connector runs.
455
+ self._connector_entries: dict[str, list[PeerEntry]] = {}
456
+ #: Connector keys whose source is gone (a DNS-SD record removed). The
457
+ #: connector finishes its current stream and does not open another.
458
+ self._retired: set[str] = set()
459
+ #: Set on every reported loss, so a connector idling on an announced
460
+ #: peer wakes when that peer is lost rather than on a poll.
461
+ self._loss = asyncio.Event()
462
+ #: endpoint -> consecutive preamble refusals, for the backoff. Only
463
+ #: outbound endpoints: an inbound one is a fresh ephemeral port every
464
+ #: time, and remembering it would only grow the map.
465
+ self._refusals: dict[str, int] = {}
466
+ self._discovery: _LanDiscovery | None = None
467
+
468
+ # Metrics
469
+ self._bytes_sent = 0
470
+ self._bytes_received = 0
471
+ self._frames_sent = 0
472
+ self._frames_received = 0
473
+ self._streams_refused = 0
474
+ self._streams_superseded = 0
475
+ self._frames_dropped = 0
476
+
477
+ # -- TransportManager interface -------------------------------------------
478
+
479
+ def is_available(self) -> bool:
480
+ return True
481
+
482
+ def configure(
483
+ self,
484
+ *,
485
+ listen_host: str | None = None,
486
+ listen_port: int | None | object = ...,
487
+ peers: Any | None = None,
488
+ advertise: bool | None = None,
489
+ discover: bool | None = None,
490
+ ) -> None:
491
+ """Change the settings before :meth:`start`."""
492
+ if self._state != TransportState.STOPPED:
493
+ raise TransportError("configure the peer-stream transport before starting it")
494
+ if listen_host is not None:
495
+ self.listen_host = listen_host
496
+ if listen_port is not ...:
497
+ self._listen_port_requested = listen_port # type: ignore[assignment]
498
+ if peers is not None:
499
+ self._peers = [p if isinstance(p, PeerEntry) else PeerEntry.parse(p) for p in peers]
500
+ if advertise is not None:
501
+ self.advertise = advertise
502
+ if discover is not None:
503
+ self.discover = discover
504
+
505
+ @property
506
+ def peers(self) -> list[PeerEntry]:
507
+ return list(self._peers)
508
+
509
+ @property
510
+ def local_address(self) -> str | None:
511
+ return self._protocol.local_address()
512
+
513
+ def connected_peers(self) -> list[str]:
514
+ """The addresses with an announced stream right now."""
515
+ return list(self._by_peer)
516
+
517
+ async def start(self) -> None:
518
+ if self._state == TransportState.RUNNING:
519
+ raise TransportError("peer-stream transport is already running")
520
+ self._loop = asyncio.get_running_loop()
521
+ self._update_state(TransportState.STARTING)
522
+
523
+ # Refuse to open a single stream this host cannot prove itself on:
524
+ # every conforming peer would close it at the first frame, and a
525
+ # listener that answers each connect with an unverifiable preamble
526
+ # only costs the LAN a connect-refuse cycle per peer.
527
+ try:
528
+ self._protocol.identity_assertion(signed_data=[])
529
+ except Exception as exc:
530
+ self._update_state(TransportState.STOPPED)
531
+ raise TransportError(
532
+ "peer-stream transport needs an identity to prove: initialise MLS "
533
+ f"before starting it ({exc})"
534
+ ) from exc
535
+
536
+ if self._listen_port_requested is not None:
537
+ try:
538
+ self._server = await asyncio.start_server(
539
+ self._on_inbound, self.listen_host, self._listen_port_requested
540
+ )
541
+ except OSError as exc:
542
+ self._update_state(TransportState.STOPPED)
543
+ raise TransportError(f"peer-stream listen failed: {exc}") from exc
544
+ sockets = self._server.sockets or ()
545
+ self.listen_port = sockets[0].getsockname()[1] if sockets else None
546
+
547
+ if self.advertise or self.discover:
548
+ try:
549
+ self._discovery = _LanDiscovery(self)
550
+ await self._discovery.start()
551
+ except Exception as exc:
552
+ await self._close_everything()
553
+ self._update_state(TransportState.STOPPED)
554
+ raise TransportError(f"peer-stream DNS-SD failed to start: {exc}") from exc
555
+
556
+ try:
557
+ self._protocol.wifi_direct_status_changed(is_connected=True)
558
+ except Exception:
559
+ logger.debug("wifi_direct_status_changed(True) failed", exc_info=True)
560
+
561
+ self._update_state(TransportState.RUNNING)
562
+ for entry in self._peers:
563
+ self._ensure_connector(entry.endpoint, [entry])
564
+ self._emit_diagnostic(
565
+ "info",
566
+ "Peer-stream transport started",
567
+ {"listen_port": self.listen_port, "static_peers": len(self._peers)},
568
+ )
569
+
570
+ async def stop(self) -> None:
571
+ # STOPPING too: a stop() cancelled part-way (a shutdown deadline)
572
+ # leaves the transport there, and a retry that returned at once would
573
+ # leave it half torn down for good. Every step below is idempotent.
574
+ if self._state not in (
575
+ TransportState.RUNNING,
576
+ TransportState.STARTING,
577
+ TransportState.STOPPING,
578
+ ):
579
+ return
580
+ self._update_state(TransportState.STOPPING)
581
+ await self._close_everything()
582
+ try:
583
+ self._protocol.wifi_direct_status_changed(is_connected=False)
584
+ except Exception:
585
+ logger.debug("wifi_direct_status_changed(False) failed", exc_info=True)
586
+ self._update_state(TransportState.STOPPED)
587
+ self._emit_diagnostic("info", "Peer-stream transport stopped")
588
+
589
+ async def _close_everything(self) -> None:
590
+ tasks = list(self._connector_tasks.values())
591
+ for task in tasks:
592
+ task.cancel()
593
+ # Awaited, so no connector outlives the manager: one that never
594
+ # yields again would otherwise be destroyed pending with the loop.
595
+ await asyncio.gather(*tasks, return_exceptions=True)
596
+ self._connector_tasks.clear()
597
+ self._connector_entries.clear()
598
+ self._retired.clear()
599
+ if self._discovery is not None:
600
+ try:
601
+ await self._discovery.stop()
602
+ except Exception:
603
+ logger.debug("DNS-SD stop failed", exc_info=True)
604
+ self._discovery = None
605
+ if self._server is not None:
606
+ self._server.close()
607
+ # Streams before the server's wait: since Python 3.12 `wait_closed`
608
+ # waits for every connection handler to finish, and a handler
609
+ # finishes only once its stream is closed.
610
+ writers = [s.writer_task for s in self._streams if s.writer_task is not None]
611
+ for stream in list(self._streams):
612
+ await self._close_stream(stream, "transport stopping")
613
+ await asyncio.gather(*writers, return_exceptions=True)
614
+ self._streams.clear()
615
+ self._by_peer.clear()
616
+ self._refusals.clear()
617
+ if self._server is not None:
618
+ try:
619
+ await asyncio.wait_for(self._server.wait_closed(), 2.0)
620
+ except Exception:
621
+ pass
622
+ self._server = None
623
+ self.listen_port = None
624
+
625
+ def get_metrics(self) -> dict[str, Any]:
626
+ return {
627
+ "bytes_sent": self._bytes_sent,
628
+ "bytes_received": self._bytes_received,
629
+ "frames_sent": self._frames_sent,
630
+ "frames_received": self._frames_received,
631
+ "streams_refused": self._streams_refused,
632
+ "streams_superseded": self._streams_superseded,
633
+ "frames_dropped": self._frames_dropped,
634
+ "connected_peers": len(self._by_peer),
635
+ "open_streams": len(self._streams),
636
+ "listen_port": self.listen_port,
637
+ }
638
+
639
+ # -- inbound and outbound streams -----------------------------------------
640
+
641
+ async def _on_inbound(
642
+ self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
643
+ ) -> None:
644
+ peername = writer.get_extra_info("peername")
645
+ endpoint = f"{peername[0]}:{peername[1]}" if peername else "?"
646
+ remote_host = peername[0] if peername else None
647
+ refusal = None
648
+ if self._state not in (TransportState.RUNNING, TransportState.STARTING):
649
+ # Accepted before the listener closed and scheduled after the
650
+ # stop swept the streams: serving it would announce a peer to a
651
+ # core already told the layer is down.
652
+ refusal = "Stream refused: transport stopping"
653
+ elif len(self._streams) >= self._max_streams:
654
+ refusal = "Stream refused: at capacity"
655
+ elif (
656
+ remote_host is not None
657
+ and self._inbound_from(remote_host) >= self._max_streams_per_host
658
+ ):
659
+ refusal = "Stream refused: per-host limit"
660
+ if refusal is not None:
661
+ self._streams_refused += 1
662
+ self._emit_diagnostic("warning", refusal, {"endpoint": endpoint})
663
+ writer.close()
664
+ return
665
+ _set_keepalive(writer)
666
+ # An inbound connection carries no claim: the derived address is the
667
+ # peer's id, and there is nothing to compare.
668
+ await self._run_stream(
669
+ _Stream(reader, writer, endpoint, expected=None, outbound=False, remote_host=remote_host)
670
+ )
671
+
672
+ def _inbound_from(self, remote_host: str) -> int:
673
+ return sum(1 for s in self._streams if not s.outbound and s.remote_host == remote_host)
674
+
675
+ def _ensure_connector(self, key: str, entries: list[PeerEntry]) -> None:
676
+ """Keep a connector running toward ``key``, trying ``entries`` in
677
+ order. A running connector picks up new entries on its next attempt."""
678
+ self._connector_entries[key] = list(entries)
679
+ self._retired.discard(key)
680
+ existing = self._connector_tasks.get(key)
681
+ if existing is not None and not existing.done():
682
+ return
683
+ self._connector_tasks[key] = asyncio.ensure_future(self._connector(key))
684
+
685
+ def _retire_connector(self, key: str) -> None:
686
+ """The source of ``key`` is gone. Its connector keeps a live stream
687
+ until that stream ends, then stops instead of reconnecting."""
688
+ if key in self._connector_tasks:
689
+ self._retired.add(key)
690
+
691
+ async def _wait_while_announced(self, address: str) -> None:
692
+ """Idle while ``address`` is announced over another stream, waking on
693
+ each reported loss (and at the ladder's ceiling, as a safety net)."""
694
+ while address in self._by_peer and self._state == TransportState.RUNNING:
695
+ self._loss.clear()
696
+ try:
697
+ await asyncio.wait_for(self._loss.wait(), timeout=RECONNECT_MAX_DELAY)
698
+ except asyncio.TimeoutError:
699
+ pass
700
+
701
+ async def _connector(self, key: str) -> None:
702
+ """Keep one stream open toward a configured or discovered peer."""
703
+ delay = RECONNECT_INITIAL_DELAY
704
+ # The address this peer turned out to hold, once a preamble said.
705
+ entries = self._connector_entries.get(key) or []
706
+ reached: str | None = entries[0].expected_address if entries else None
707
+ try:
708
+ while self._state in (TransportState.RUNNING, TransportState.STARTING):
709
+ if key in self._retired:
710
+ return
711
+ if reached is not None and reached in self._by_peer:
712
+ # The peer is announced over another stream (it reached us
713
+ # first, or its stream won the tie-break). Nothing to open
714
+ # until that one ends.
715
+ await self._wait_while_announced(reached)
716
+ continue
717
+ stream = await self._open(key)
718
+ if stream is None:
719
+ await asyncio.sleep(delay)
720
+ delay = min(delay * 2, RECONNECT_MAX_DELAY)
721
+ continue
722
+ await self._run_stream(stream)
723
+ if stream.learned is not None:
724
+ reached = stream.learned
725
+ if stream.was_announced:
726
+ # A link that worked and was lost: try again promptly.
727
+ delay = RECONNECT_INITIAL_DELAY
728
+ wait = self._cooldown(stream.endpoint)
729
+ else:
730
+ # An attempt that went nowhere (silent or closing endpoint,
731
+ # refused preamble, tie-break loss): climb the ladder, and
732
+ # longer still if the endpoint keeps failing verification.
733
+ wait = max(delay, self._cooldown(stream.endpoint))
734
+ delay = min(delay * 2, RECONNECT_MAX_DELAY)
735
+ await asyncio.sleep(wait)
736
+ except asyncio.CancelledError:
737
+ return
738
+ finally:
739
+ if self._connector_tasks.get(key) is asyncio.current_task():
740
+ self._connector_tasks.pop(key, None)
741
+ self._connector_entries.pop(key, None)
742
+ self._retired.discard(key)
743
+
744
+ async def _open(self, key: str) -> _Stream | None:
745
+ """One connect attempt toward ``key``: each of its entries in turn,
746
+ the first that connects wins. ``None`` when none did."""
747
+ for entry in list(self._connector_entries.get(key) or []):
748
+ try:
749
+ reader, writer = await asyncio.wait_for(
750
+ asyncio.open_connection(entry.host, entry.port),
751
+ timeout=CONNECT_TIMEOUT,
752
+ )
753
+ except asyncio.CancelledError:
754
+ raise
755
+ except Exception as exc:
756
+ # Not only OSError: a malformed host raises ValueError or
757
+ # UnicodeError, and a connector that died on one would never
758
+ # retry the peer, silently.
759
+ self._emit_diagnostic(
760
+ "debug", "Peer connect failed", {"endpoint": entry.endpoint, "error": str(exc)}
761
+ )
762
+ continue
763
+ _set_keepalive(writer)
764
+ return _Stream(
765
+ reader, writer, entry.endpoint, expected=entry.expected_address, outbound=True
766
+ )
767
+ return None
768
+
769
+ def _cooldown(self, endpoint: str) -> float:
770
+ refusals = self._refusals.get(endpoint, 0)
771
+ if refusals == 0:
772
+ return RECONNECT_INITIAL_DELAY
773
+ return min(RECONNECT_INITIAL_DELAY * (2 ** min(refusals, 16)), REFUSAL_BACKOFF_MAX)
774
+
775
+ async def _read_frame_prefix(self, stream: _Stream, deadline: float | None) -> bytes:
776
+ read = stream.reader.readexactly(LENGTH_PREFIX_LEN)
777
+ if deadline is None:
778
+ return await read
779
+ return await asyncio.wait_for(read, timeout=self._remaining(deadline))
780
+
781
+ async def _read_frame_body(self, stream: _Stream, length: int, deadline: float | None) -> bytes:
782
+ read = stream.reader.readexactly(length)
783
+ if deadline is None:
784
+ return await read
785
+ return await asyncio.wait_for(read, timeout=self._remaining(deadline))
786
+
787
+ def _remaining(self, deadline: float) -> float:
788
+ assert self._loop is not None
789
+ return max(0.0, deadline - self._loop.time())
790
+
791
+ async def _run_stream(self, stream: _Stream) -> None:
792
+ """Send our preamble, then read frames until the stream ends.
793
+
794
+ Owns the stream from open to close: whatever ends it, the peer is
795
+ reported lost if and only if it was announced, and the socket is
796
+ closed exactly once.
797
+ """
798
+ self._streams.add(stream)
799
+ reason = "peer closed the stream"
800
+ loop = asyncio.get_running_loop()
801
+ try:
802
+ # Ours first, without waiting for theirs: a peer that never speaks
803
+ # cannot hold the stream half-open on purpose.
804
+ assertion = bytes(self._protocol.identity_assertion(signed_data=[]))
805
+ # One deadline for the whole preamble exchange, our write and
806
+ # their frame, prefix and body: a deadline on the prefix alone
807
+ # lets four bytes hold the slot.
808
+ deadline: float | None = loop.time() + self._preamble_timeout
809
+ stream.writer.write(frame(assertion))
810
+ try:
811
+ await asyncio.wait_for(stream.writer.drain(), timeout=self._remaining(deadline))
812
+ except asyncio.TimeoutError:
813
+ reason = "preamble write stalled"
814
+ return
815
+ # Every later frame goes through this stream's own writer, so
816
+ # the preamble is first on the wire by construction.
817
+ stream.writer_task = asyncio.ensure_future(self._write_loop(stream))
818
+ first = True
819
+ while True:
820
+ if stream.superseded:
821
+ reason = "superseded"
822
+ break
823
+ try:
824
+ prefix = await self._read_frame_prefix(stream, deadline)
825
+ except asyncio.TimeoutError:
826
+ reason = "no preamble within the deadline"
827
+ break
828
+ except (asyncio.IncompleteReadError, ConnectionError, OSError):
829
+ break
830
+ length = int.from_bytes(prefix, "big")
831
+
832
+ # Bounds on the prefix, before a byte of the body.
833
+ if length == 0 or length > MAX_FRAME_BYTES:
834
+ reason = f"refused frame length {length}"
835
+ break
836
+ if first and length < PREAMBLE_FLOOR:
837
+ reason = f"refused preamble length {length}"
838
+ self._record_refusal(stream)
839
+ break
840
+
841
+ try:
842
+ body = await self._read_frame_body(stream, length, deadline)
843
+ except asyncio.TimeoutError:
844
+ reason = "no preamble within the deadline"
845
+ break
846
+ except (asyncio.IncompleteReadError, ConnectionError, OSError):
847
+ break
848
+ self._bytes_received += LENGTH_PREFIX_LEN + length
849
+
850
+ if first:
851
+ if not self._accept_preamble(stream, bytes(body)):
852
+ reason = "preamble refused"
853
+ break
854
+ first = False
855
+ deadline = None
856
+ continue
857
+
858
+ # Checked after the read as well as before it: a newer stream
859
+ # may have taken the announcement over while this one waited.
860
+ if stream.superseded or stream.peer is None:
861
+ reason = "superseded"
862
+ break
863
+ self._frames_received += 1
864
+ try:
865
+ self._protocol.wifi_direct_message_received(
866
+ sender_id=stream.peer, data=list(body)
867
+ )
868
+ except Exception as exc:
869
+ self._emit_diagnostic(
870
+ "error",
871
+ "Error handing a frame to the core",
872
+ {"peer": stream.peer, "error": str(exc)},
873
+ )
874
+ except asyncio.CancelledError:
875
+ reason = "transport stopping"
876
+ raise
877
+ except Exception as exc:
878
+ reason = f"stream error: {exc}"
879
+ finally:
880
+ await self._close_stream(stream, reason)
881
+
882
+ def _accept_preamble(self, stream: _Stream, body: bytes) -> bool:
883
+ """Steps one to four of the chapter's verification, then the
884
+ one-announced-stream-per-address rule, then the announcement."""
885
+ try:
886
+ derived = verify_identity_assertion(list(body))
887
+ except Exception as exc:
888
+ self._record_refusal(stream)
889
+ self._emit_diagnostic(
890
+ "warning",
891
+ "Peer preamble did not verify",
892
+ {"endpoint": stream.endpoint, "error": str(exc)},
893
+ )
894
+ return False
895
+ stream.learned = derived
896
+ if stream.expected is not None and derived != stream.expected:
897
+ # Exact, never normalised, and the claim is never announced.
898
+ self._record_refusal(stream)
899
+ self._emit_diagnostic(
900
+ "warning",
901
+ "Peer preamble names another address",
902
+ {"endpoint": stream.endpoint, "expected": stream.expected, "derived": derived},
903
+ )
904
+ return False
905
+ if derived == self.local_address:
906
+ # Counted, so a peer entry that points at this host climbs to the
907
+ # refusal ceiling instead of reconnecting at the ladder's pace
908
+ # forever.
909
+ self._record_refusal(stream)
910
+ self._emit_diagnostic(
911
+ "debug", "Refusing a stream to ourselves", {"endpoint": stream.endpoint}
912
+ )
913
+ return False
914
+ self._refusals.pop(stream.endpoint, None)
915
+
916
+ older = self._by_peer.get(derived)
917
+ if older is not None:
918
+ # One announced stream per address, and both ends must keep the
919
+ # same one: the stream the lower address opened wins, and among
920
+ # two of that kind the newer one. If that is this stream, it
921
+ # takes the announcement over and the older one closes silently;
922
+ # if not, this one closes silently. The core sees neither.
923
+ if not self._new_stream_wins(stream, derived):
924
+ self._streams_refused += 1
925
+ self._emit_diagnostic(
926
+ "info", "Refusing a second stream for an announced address", {"peer": derived}
927
+ )
928
+ return False
929
+ self._streams_superseded += 1
930
+ older.peer = None
931
+ older.superseded = True
932
+ stream.peer = derived
933
+ stream.was_announced = True
934
+ self._by_peer[derived] = stream
935
+ self._emit_diagnostic(
936
+ "info", "A newer stream supersedes the announced one", {"peer": derived}
937
+ )
938
+ asyncio.ensure_future(self._close_stream(older, "superseded"))
939
+ return True
940
+
941
+ stream.peer = derived
942
+ stream.was_announced = True
943
+ self._by_peer[derived] = stream
944
+ try:
945
+ self._protocol.wifi_direct_peer_connected(peer_id=derived)
946
+ except Exception as exc:
947
+ self._emit_diagnostic(
948
+ "error", "wifi_direct_peer_connected failed", {"peer": derived, "error": str(exc)}
949
+ )
950
+ self._emit_diagnostic("info", "Peer announced", {"peer": derived, "endpoint": stream.endpoint})
951
+ # Something may already be queued for this address.
952
+ self._schedule_drain()
953
+ return True
954
+
955
+ def _new_stream_wins(self, new: _Stream, peer: str) -> bool:
956
+ """The tie-break both ends compute alike: the stream opened by the
957
+ lower of the two addresses is the one to keep.
958
+
959
+ This helps only the lower address past its own stale stream. The
960
+ higher address's reconnect is the losing kind while the lower side
961
+ still holds a stream it believes live, which is why every stream
962
+ carries TCP keepalive: a dead peer's stream ends within a bound, and
963
+ the reconnect wins from then on.
964
+ """
965
+ local = self.local_address
966
+ if local is None:
967
+ # No address of our own to order by; keep what is announced.
968
+ return False
969
+ we_open = local < peer
970
+ return new.outbound == we_open
971
+
972
+ def _record_refusal(self, stream: _Stream) -> None:
973
+ # Only an outbound endpoint is ever connected to again; an inbound
974
+ # one is a new ephemeral port each time.
975
+ if stream.outbound:
976
+ self._refusals[stream.endpoint] = self._refusals.get(stream.endpoint, 0) + 1
977
+
978
+ async def _close_stream(self, stream: _Stream, reason: str) -> None:
979
+ if stream not in self._streams:
980
+ return
981
+ self._streams.discard(stream)
982
+ announced = stream.peer is not None and self._by_peer.get(stream.peer) is stream
983
+ if announced:
984
+ self._by_peer.pop(stream.peer, None)
985
+ task = stream.writer_task
986
+ if task is not None and task is not asyncio.current_task():
987
+ task.cancel()
988
+ _discard_socket(stream.writer)
989
+ # A stream that never proved a peer was never announced, and there
990
+ # is nothing to report.
991
+ if announced:
992
+ try:
993
+ self._protocol.wifi_direct_peer_disconnected(peer_id=stream.peer)
994
+ except Exception:
995
+ logger.debug("wifi_direct_peer_disconnected failed for %s", stream.peer)
996
+ self._emit_diagnostic("info", "Peer lost", {"peer": stream.peer, "reason": reason})
997
+ self._loss.set()
998
+ else:
999
+ self._emit_diagnostic(
1000
+ "debug", "Unannounced stream closed", {"endpoint": stream.endpoint, "reason": reason}
1001
+ )
1002
+
1003
+ async def _write_loop(self, stream: _Stream) -> None:
1004
+ """Write ``stream``'s queued frames, one at a time. A peer that takes
1005
+ nothing for the write deadline aborts the stream: the peer is
1006
+ reported lost, and nothing else waited on it."""
1007
+ reason = "write failed"
1008
+ try:
1009
+ while True:
1010
+ data = await stream.outbound_queue.get()
1011
+ stream.queued_bytes -= len(data)
1012
+ stream.writer.write(data)
1013
+ # Marked only when drain() will actually wait. Before 3.12,
1014
+ # wait_for wraps even an immediate drain() in a task, so a
1015
+ # flag set unconditionally reads as blocked for a loop
1016
+ # iteration or two after every write.
1017
+ stream.write_blocked = _write_paused(stream.writer)
1018
+ try:
1019
+ await self._drain_while_moving(stream)
1020
+ finally:
1021
+ stream.write_blocked = False
1022
+ self._bytes_sent += len(data)
1023
+ self._frames_sent += 1
1024
+ except asyncio.CancelledError:
1025
+ return
1026
+ except asyncio.TimeoutError:
1027
+ reason = "write stalled past the deadline"
1028
+ except Exception as exc:
1029
+ reason = f"write failed: {exc}"
1030
+ self._emit_diagnostic(
1031
+ "warning", "Peer stream write failed", {"peer": stream.peer, "reason": reason}
1032
+ )
1033
+ await self._close_stream(stream, reason)
1034
+
1035
+ async def _drain_while_moving(self, stream: _Stream) -> None:
1036
+ """Wait for ``stream``'s write buffer to flush, for as long as the
1037
+ peer keeps taking bytes. Raises :class:`asyncio.TimeoutError` once a
1038
+ whole ``write_timeout`` passes with the buffer no smaller: the
1039
+ deadline is on progress, so a slow link is never mistaken for a
1040
+ dead one."""
1041
+ transport = stream.writer.transport
1042
+ last = transport.get_write_buffer_size()
1043
+ while True:
1044
+ try:
1045
+ await asyncio.wait_for(stream.writer.drain(), timeout=self._write_timeout)
1046
+ return
1047
+ except asyncio.TimeoutError:
1048
+ size = transport.get_write_buffer_size()
1049
+ if size >= last:
1050
+ raise
1051
+ last = size
1052
+
1053
+ # -- outbound drain ---------------------------------------------------------
1054
+
1055
+ def on_messages_available(self) -> None:
1056
+ """``WifiDirectTransportCallback.on_messages_available``: the core
1057
+ queued a body toward an announced peer.
1058
+
1059
+ Invoked from a Rust callback thread, so the drain is scheduled onto
1060
+ the event loop rather than run here.
1061
+ """
1062
+ self._schedule_drain()
1063
+
1064
+ def _schedule_drain(self) -> None:
1065
+ loop = self._loop
1066
+ if loop is not None and not loop.is_closed() and loop.is_running():
1067
+ loop.call_soon_threadsafe(self._drain)
1068
+
1069
+ def _drain(self) -> None:
1070
+ """Move every body the core holds onto its stream's own queue.
1071
+
1072
+ Never awaits: the core's queue is one FIFO for every peer, and a
1073
+ drain that waited on one peer's socket would hold every other
1074
+ peer's traffic behind it. Each stream's writer does the waiting.
1075
+ """
1076
+ while True:
1077
+ try:
1078
+ message = self._protocol.wifi_direct_get_next_message()
1079
+ except Exception as exc:
1080
+ logger.warning("wifi_direct_get_next_message failed: %s", exc)
1081
+ return
1082
+ if message is None:
1083
+ return
1084
+ stream = self._by_peer.get(message.recipient_id)
1085
+ if stream is None or stream.writer_task is None:
1086
+ # The stream closed between the queue and the drain; the
1087
+ # core's retry path re-offers the message.
1088
+ self._emit_diagnostic(
1089
+ "debug", "No announced stream for a queued body", {"peer": message.recipient_id}
1090
+ )
1091
+ continue
1092
+ try:
1093
+ data = frame(bytes(message.data))
1094
+ except ValueError as exc:
1095
+ # A body no receiver would accept. Refused here, and the
1096
+ # stream, which did nothing wrong, stays up.
1097
+ self._frames_dropped += 1
1098
+ self._emit_diagnostic(
1099
+ "error", "Refusing to frame a body", {"peer": message.recipient_id, "error": str(exc)}
1100
+ )
1101
+ continue
1102
+ if (
1103
+ stream.write_blocked
1104
+ and stream.queued_bytes
1105
+ and stream.queued_bytes + len(data) > MAX_QUEUED_BYTES
1106
+ ):
1107
+ # The peer is not taking what it already has. Buffering
1108
+ # without bound would only move the stall into memory; the
1109
+ # write deadline ends a peer that has stopped, and the retry
1110
+ # path re-offers this. Only while blocked: a burst handed
1111
+ # over before the writer ran says nothing about the peer.
1112
+ self._frames_dropped += 1
1113
+ self._emit_diagnostic(
1114
+ "warning", "Peer stream queue full, dropping a body", {"peer": message.recipient_id}
1115
+ )
1116
+ continue
1117
+ stream.queued_bytes += len(data)
1118
+ stream.outbound_queue.put_nowait(data)
1119
+
1120
+ # -- discovery hooks --------------------------------------------------------
1121
+
1122
+ def _on_record_resolved(self, name: str, entries: list[PeerEntry]) -> None:
1123
+ """A DNS-SD record named a host, under ``name``. Its ``addr`` is a
1124
+ hint the preamble proves; nothing is announced from the record. One
1125
+ connector per record, trying the record's addresses in turn."""
1126
+ if not entries:
1127
+ return
1128
+ claimed = entries[0].expected_address
1129
+ if claimed is not None and claimed == self.local_address:
1130
+ return
1131
+ self._ensure_connector(f"dns-sd:{name}", entries)
1132
+
1133
+ def _on_record_removed(self, name: str) -> None:
1134
+ """A DNS-SD record went away: stop reconnecting toward it once its
1135
+ current stream, if any, ends. A live stream is not cut, because a
1136
+ record expiring says nothing about the stream."""
1137
+ self._retire_connector(f"dns-sd:{name}")
1138
+
1139
+
1140
+ def advertised_addresses(listen_host: str) -> list[str]:
1141
+ """The addresses a DNS-SD record should carry for a listener on
1142
+ ``listen_host``: that address when it names one, otherwise every
1143
+ non-loopback address of every interface (``ifaddr`` comes with the
1144
+ ``lan`` extra)."""
1145
+ try:
1146
+ bound = ipaddress.ip_address(listen_host)
1147
+ except ValueError:
1148
+ bound = None
1149
+ if bound is not None and not bound.is_unspecified:
1150
+ return [str(bound)]
1151
+
1152
+ import ifaddr
1153
+
1154
+ want_v4 = bound is None or bound.version == 4 or listen_host == "::"
1155
+ want_v6 = bound is None or bound.version == 6
1156
+ found: list[str] = []
1157
+ for adapter in ifaddr.get_adapters():
1158
+ for ip in adapter.ips:
1159
+ if isinstance(ip.ip, tuple):
1160
+ if not want_v6:
1161
+ continue
1162
+ address = ipaddress.ip_address(ip.ip[0])
1163
+ else:
1164
+ if not want_v4:
1165
+ continue
1166
+ address = ipaddress.ip_address(ip.ip)
1167
+ if address.is_loopback:
1168
+ continue
1169
+ text = str(address)
1170
+ if text not in found:
1171
+ found.append(text)
1172
+ return found
1173
+
1174
+
1175
+ class _LanDiscovery:
1176
+ """DNS-SD advertiser and browser over the optional ``zeroconf`` package.
1177
+
1178
+ Imported lazily so the base install carries no LGPL dependency; a manager
1179
+ that asks for discovery without it fails at :meth:`start` with the
1180
+ install hint.
1181
+ """
1182
+
1183
+ def __init__(self, manager: PeerStreamManager) -> None:
1184
+ self._manager = manager
1185
+ self._zc: Any = None
1186
+ self._info: Any = None
1187
+ self._browser: Any = None
1188
+ self._pending: set[asyncio.Task[None]] = set()
1189
+
1190
+ async def start(self) -> None:
1191
+ try:
1192
+ from zeroconf import IPVersion, ServiceInfo, ServiceStateChange
1193
+ from zeroconf.asyncio import AsyncServiceBrowser, AsyncServiceInfo, AsyncZeroconf
1194
+ except ImportError as exc:
1195
+ raise TransportError(
1196
+ "LAN discovery needs the optional dependency: pip install 'offline-protocol-sdk[lan]'"
1197
+ ) from exc
1198
+
1199
+ self._zc = AsyncZeroconf(ip_version=IPVersion.All)
1200
+ manager = self._manager
1201
+
1202
+ if manager.advertise:
1203
+ address = manager.local_address
1204
+ port = manager.listen_port
1205
+ if address is None or port is None:
1206
+ raise TransportError("advertising needs an address and a listening port")
1207
+ addresses = advertised_addresses(manager.listen_host)
1208
+ if not addresses:
1209
+ raise TransportError("advertising found no interface address to publish")
1210
+ self._info = ServiceInfo(
1211
+ SERVICE_TYPE,
1212
+ service_instance_name(address),
1213
+ port=port,
1214
+ properties=txt_record(address),
1215
+ server=service_host_name(address),
1216
+ parsed_addresses=addresses,
1217
+ )
1218
+ await self._zc.async_register_service(self._info)
1219
+
1220
+ if manager.discover:
1221
+ zc = self._zc.zeroconf
1222
+
1223
+ def on_change(zeroconf: Any, service_type: str, name: str, state_change: Any) -> None:
1224
+ if state_change is ServiceStateChange.Removed:
1225
+ manager._on_record_removed(name)
1226
+ return
1227
+ info = AsyncServiceInfo(service_type, name)
1228
+
1229
+ async def resolve() -> None:
1230
+ if await info.async_request(zeroconf, 3000):
1231
+ manager._on_record_resolved(name, peers_from_record(info))
1232
+
1233
+ task = asyncio.ensure_future(resolve())
1234
+ self._pending.add(task)
1235
+ task.add_done_callback(self._pending.discard)
1236
+
1237
+ self._browser = AsyncServiceBrowser(zc, SERVICE_TYPE, handlers=[on_change])
1238
+
1239
+ async def stop(self) -> None:
1240
+ for task in list(self._pending):
1241
+ task.cancel()
1242
+ if self._browser is not None:
1243
+ await self._browser.async_cancel()
1244
+ self._browser = None
1245
+ if self._zc is not None:
1246
+ if self._info is not None:
1247
+ await self._zc.async_unregister_service(self._info)
1248
+ self._info = None
1249
+ await self._zc.async_close()
1250
+ self._zc = None
1251
+
1252
+
1253
+ def txt_record(address: str) -> dict[str, str]:
1254
+ """The TXT record the chapter fixes: ``txtvers`` first, then ``addr``."""
1255
+ return {"txtvers": TXT_VERSION, "addr": address}
1256
+
1257
+
1258
+ def peers_from_record(info: Any) -> list[PeerEntry]:
1259
+ """Turn a resolved DNS-SD record into peer entries, one per address the
1260
+ host published, each carrying the record's ``addr`` as the claim to
1261
+ verify against. A record without a well-formed ``addr`` yields nothing:
1262
+ the chapter makes the entry mandatory, and a host that omits it is not
1263
+ advertising this service.
1264
+
1265
+ Link-local IPv6 addresses come with their scope (``fe80::1%en0``); an
1266
+ unscoped one cannot be connected to.
1267
+ """
1268
+ properties = getattr(info, "properties", None) or {}
1269
+ # A record carrying `sid` is a service instance under the DNS-SD mapping
1270
+ # chapter, published under a subtype of this type. It names the same
1271
+ # host and address as the peer record and would become a second
1272
+ # connector to it per service; the chapter's invariant 5 has a peer
1273
+ # browser ignore it.
1274
+ if b"sid" in properties:
1275
+ return []
1276
+ raw = properties.get(b"addr")
1277
+ if raw is None:
1278
+ return []
1279
+ try:
1280
+ claimed = raw.decode("utf-8") if isinstance(raw, (bytes, bytearray)) else str(raw)
1281
+ except UnicodeDecodeError:
1282
+ return []
1283
+ if not claimed.startswith("off1"):
1284
+ return []
1285
+ port = getattr(info, "port", None)
1286
+ if not port:
1287
+ return []
1288
+ hosts: list[str] = []
1289
+ for accessor in ("parsed_scoped_addresses", "parsed_addresses"):
1290
+ parsed = getattr(info, accessor, None)
1291
+ if not callable(parsed):
1292
+ continue
1293
+ try:
1294
+ hosts = [str(h) for h in parsed()]
1295
+ except Exception:
1296
+ hosts = []
1297
+ if hosts:
1298
+ break
1299
+ if not hosts:
1300
+ server = getattr(info, "server", None)
1301
+ if server:
1302
+ hosts = [str(server).rstrip(".")]
1303
+ return [PeerEntry(host=h, port=int(port), expected_address=claimed) for h in hosts]