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,546 @@
1
+ """The reference server: one engine, any number of local clients, JSON-RPC
2
+ 2.0 over a WebSocket on a Unix domain socket or a loopback TCP port.
3
+
4
+ The server owns the :class:`~offline_protocol_sdk.ProtocolManager` (its run
5
+ loop and its drain), the ``MeshServices`` and ``DataStore`` handles, and the
6
+ routing tables. A connection runs one request at a time; every engine call
7
+ runs on the event loop's thread, so an event the engine emits inside a call
8
+ is attributed to that call's connection without any locking.
9
+
10
+ There is no HTTP request path. The pinned WebSocket library's handshake
11
+ parser accepts only ``GET`` and drops any other method before the request
12
+ hook runs (verified against ``websockets`` 16.1), so a ``POST`` would fail
13
+ with zero bytes back rather than with a JSON-RPC error. The request hook
14
+ serves one thing: ``GET /health``.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import asyncio
20
+ import hmac
21
+ import http
22
+ import json
23
+ import logging
24
+ import os
25
+ import secrets
26
+ import stat
27
+ from pathlib import Path
28
+ from typing import Any
29
+
30
+ from websockets.asyncio.server import Server, ServerConnection, serve, unix_serve
31
+ from websockets.exceptions import ConnectionClosed
32
+ from websockets.http11 import Request, Response
33
+
34
+ from .. import offline_protocol as generated
35
+ from ..protocol_manager import ProtocolManager
36
+ from . import codec
37
+ from .authz import Policy, ServiceOwnership
38
+ from .codec import RpcError, taxonomy_error
39
+ from .dispatch import SESSION_METHODS, Dispatcher
40
+ from .mux import EventRouter
41
+ from .session import Session
42
+
43
+ logger = logging.getLogger(__name__)
44
+
45
+ API_VERSION = 1
46
+ SERVER_NAME = "offline-protocol-service"
47
+
48
+ #: The engine's file size limit (``file_transfer.rs``, ``max_file_size``),
49
+ #: which is not configurable through the interface.
50
+ FILE_SIZE_LIMIT = 100 * 1024 * 1024
51
+ #: The inbound frame limit: the file limit as base64, plus room for the
52
+ #: request around it. Below this a media send fails as a closed connection
53
+ #: instead of as the engine's own refusal.
54
+ MAX_MESSAGE_SIZE = FILE_SIZE_LIMIT * 4 // 3 + 1024 * 1024
55
+ TOKEN_BYTES = 32
56
+ #: WebSocket close code for a connection refused by policy.
57
+ POLICY_VIOLATION = 1008
58
+ #: The engine's own rule for an application id (``ProtocolConfig`` validation).
59
+ APP_ID_MAX_BYTES = 256
60
+ LOOPBACK_HOSTS = frozenset({"127.0.0.1", "::1"})
61
+
62
+
63
+ def _package_version() -> str:
64
+ try:
65
+ from importlib.metadata import version
66
+
67
+ return version("offline-protocol-sdk")
68
+ except Exception: # not installed as a distribution
69
+ return "0"
70
+
71
+
72
+ def validate_app_id(value: Any) -> str:
73
+ """The engine's rule for an application id, applied to ``hello``."""
74
+ if not isinstance(value, str):
75
+ raise taxonomy_error("InvalidArgument", "app_id must be a string")
76
+ if not value or value in (".", ".."):
77
+ raise taxonomy_error("InvalidArgument", "app_id must not be empty, '.' or '..'")
78
+ try:
79
+ encoded = value.encode("utf-8")
80
+ except UnicodeEncodeError:
81
+ # A lone surrogate is valid JSON text and not valid UTF-8.
82
+ raise taxonomy_error("InvalidArgument", "app_id is not valid UTF-8") from None
83
+ if len(encoded) > APP_ID_MAX_BYTES:
84
+ raise taxonomy_error("InvalidArgument", f"app_id is over {APP_ID_MAX_BYTES} bytes")
85
+ if any(ord(ch) < 0x20 or ch == "\x7f" for ch in value):
86
+ raise taxonomy_error("InvalidArgument", "app_id contains a control character")
87
+ if any(ch in value for ch in "/\\:"):
88
+ raise taxonomy_error("InvalidArgument", "app_id must not contain '/', '\\' or ':'")
89
+ return value
90
+
91
+
92
+ class _CloseAfter(RpcError):
93
+ """An error after which the connection is closed with a policy code."""
94
+
95
+
96
+ class LocalApiServer:
97
+ """Fronts one :class:`ProtocolManager` for local clients.
98
+
99
+ Parameters
100
+ ----------
101
+ manager:
102
+ A manager that has not been started. The server registers itself as
103
+ its event handler, starts it, and starts its peer-stream transport
104
+ when the configuration enables one.
105
+ policy:
106
+ The space allow-lists and method denials; empty by default.
107
+ socket_path:
108
+ The Unix domain socket to serve on (the default carrier). Created
109
+ ``0600``. A directory the server creates for it is made ``0700``; a
110
+ directory that already exists must be this user's with no group or
111
+ other permissions, and is refused otherwise rather than narrowed. A
112
+ stale socket file at the path is removed first; anything else at
113
+ the path is refused.
114
+
115
+ Every engine call a client makes runs on the event loop's default
116
+ executor behind one server-wide lock: calls are serialised, so the
117
+ caller rule's attribution stays exact, and the loop keeps ticking
118
+ (``process()``, the drain, other connections' framing, ``GET /health``)
119
+ while one runs. A media send marshals its bytes per element in pure
120
+ Python, about 1.5 s per MiB, which is the cost that rule pays for.
121
+ ``hello``, ``subscribe`` and ``unsubscribe`` run on the loop; the two
122
+ engine reads in ``hello`` hold the engine's lock for microseconds.
123
+ tcp_port, tcp_host, token_path:
124
+ The loopback TCP alternative: ``tcp_port`` (``0`` picks a free port,
125
+ readable as :attr:`port`), a loopback ``tcp_host``, and the file the
126
+ per-launch token is written to, ``0600``. A client presents the
127
+ token in ``hello``.
128
+ health:
129
+ Serve ``GET /health`` through the request hook.
130
+ max_size:
131
+ The inbound frame limit.
132
+ """
133
+
134
+ def __init__(
135
+ self,
136
+ manager: ProtocolManager,
137
+ *,
138
+ policy: Policy | None = None,
139
+ socket_path: str | Path | None = None,
140
+ tcp_port: int | None = None,
141
+ tcp_host: str = "127.0.0.1",
142
+ token_path: str | Path | None = None,
143
+ health: bool = True,
144
+ max_size: int = MAX_MESSAGE_SIZE,
145
+ ) -> None:
146
+ if (socket_path is None) == (tcp_port is None):
147
+ raise ValueError("pass exactly one of socket_path or tcp_port")
148
+ if tcp_port is not None:
149
+ if token_path is None:
150
+ raise ValueError("tcp_port requires token_path: TCP is served only with the token")
151
+ if tcp_host not in LOOPBACK_HOSTS:
152
+ raise ValueError(f"tcp_host must be loopback ({sorted(LOOPBACK_HOSTS)}), not {tcp_host!r}")
153
+ self._manager = manager
154
+ self._policy = policy or Policy()
155
+ self._ownership = ServiceOwnership()
156
+ self._router = EventRouter(self._policy, self._ownership)
157
+ self.socket_path = Path(socket_path) if socket_path is not None else None
158
+ self._tcp_port = tcp_port
159
+ self._tcp_host = tcp_host
160
+ self.token_path = Path(token_path) if token_path is not None else None
161
+ self._health = health
162
+ self._max_size = max_size
163
+ self._loop: asyncio.AbstractEventLoop | None = None
164
+ self._server: Server | None = None
165
+ self._dispatcher: Dispatcher | None = None
166
+ self._sessions: set[Session] = set()
167
+ self.token: str | None = None
168
+ self.port: int | None = None
169
+ self.version = _package_version()
170
+
171
+ # -- lifecycle ------------------------------------------------------------
172
+
173
+ @property
174
+ def carrier(self) -> str:
175
+ return "unix" if self.socket_path is not None else "tcp"
176
+
177
+ @property
178
+ def manager(self) -> ProtocolManager:
179
+ return self._manager
180
+
181
+ @property
182
+ def router(self) -> EventRouter:
183
+ return self._router
184
+
185
+ async def start(self) -> None:
186
+ self._loop = asyncio.get_running_loop()
187
+ if self.socket_path is not None:
188
+ # Refused before the engine starts: a directory or a path the
189
+ # server may not use is the operator's to fix, and no reason to
190
+ # have opened the stores.
191
+ _prepare_socket_directory(self.socket_path.parent)
192
+ _remove_stale_socket(self.socket_path)
193
+ self._manager.on_event(self._on_engine_event)
194
+ await self._manager.start()
195
+ try:
196
+ if self._manager.peer_stream is not None:
197
+ await self._manager.peer_stream.start()
198
+ # Only once configured: an unconfigured gateway client has no
199
+ # daemon to dial, and starting it would refuse the whole server.
200
+ gateway = self._manager.gateway
201
+ if gateway is not None and gateway.is_available():
202
+ await gateway.start()
203
+ engine = self._manager.protocol
204
+ services = generated.MeshServices(engine)
205
+ data: Any
206
+ try:
207
+ data = generated.DataStore(engine)
208
+ except generated.ProtocolError as exc:
209
+ # The data layer is off or has no storage; every `data.*`
210
+ # call answers with this same refusal.
211
+ data = exc
212
+ self._call_lock = asyncio.Lock()
213
+ self._dispatcher = Dispatcher(
214
+ engine, services, data, self._router, self._policy, self._ownership, self._call_lock
215
+ )
216
+ if self.socket_path is not None:
217
+ self._server = await self._serve_unix(self.socket_path)
218
+ else:
219
+ self._server = await self._serve_tcp()
220
+ except BaseException:
221
+ # The two handles hold the engine, and the engine holds the
222
+ # storage callbacks; freed here, before the interpreter is on
223
+ # its way out, rather than from a finaliser at exit.
224
+ self._dispatcher = None
225
+ await self._stop_manager()
226
+ raise
227
+ logger.info("local API serving on %s", self.socket_path or f"{self._tcp_host}:{self.port}")
228
+
229
+ async def _serve_unix(self, path: Path) -> Server:
230
+ # The directory and the path were checked in `start()`, before the
231
+ # engine came up.
232
+ server = await unix_serve(
233
+ self._handle,
234
+ path=str(path),
235
+ process_request=self._process_request,
236
+ max_size=self._max_size,
237
+ )
238
+ # The credential on this carrier is the file's mode: whoever can
239
+ # open the socket is one of the operator's applications. The peer's
240
+ # credentials (its uid, as the kernel could report them) are not
241
+ # read, and nothing here tells one local process from another.
242
+ os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
243
+ return server
244
+
245
+ async def _serve_tcp(self) -> Server:
246
+ assert self.token_path is not None and self._tcp_port is not None
247
+ self.token = secrets.token_hex(TOKEN_BYTES)
248
+ self.token_path.parent.mkdir(parents=True, exist_ok=True)
249
+ # Created with its mode in one step, never created and then
250
+ # narrowed: a file that exists world-readable for even a moment has
251
+ # already published the token. A stale file from an earlier launch
252
+ # is removed first; its token died with that process.
253
+ try:
254
+ self.token_path.unlink()
255
+ except FileNotFoundError:
256
+ pass
257
+ fd = os.open(
258
+ self.token_path,
259
+ os.O_WRONLY | os.O_CREAT | os.O_EXCL,
260
+ stat.S_IRUSR | stat.S_IWUSR,
261
+ )
262
+ with os.fdopen(fd, "w", encoding="ascii") as handle:
263
+ handle.write(self.token + "\n")
264
+ server = await serve(
265
+ self._handle,
266
+ self._tcp_host,
267
+ self._tcp_port,
268
+ process_request=self._process_request,
269
+ max_size=self._max_size,
270
+ )
271
+ self.port = server.sockets[0].getsockname()[1]
272
+ return server
273
+
274
+ async def stop(self) -> None:
275
+ """Closes every connection, then the engine and its transports."""
276
+ server, self._server = self._server, None
277
+ if server is not None:
278
+ server.close()
279
+ await server.wait_closed()
280
+ for session in list(self._sessions):
281
+ self._router.detach(session)
282
+ self._sessions.clear()
283
+ self._dispatcher = None
284
+ await self._stop_manager()
285
+ if self.socket_path is not None:
286
+ try:
287
+ _remove_stale_socket(self.socket_path)
288
+ except ValueError:
289
+ logger.warning("%s is no longer this server's socket; left in place", self.socket_path)
290
+ if self.token_path is not None:
291
+ try:
292
+ self.token_path.unlink()
293
+ except FileNotFoundError:
294
+ pass
295
+ self.token = None
296
+
297
+ async def _stop_manager(self) -> None:
298
+ if self._manager._file_stores is not None:
299
+ await self._manager.close()
300
+ else:
301
+ await self._manager.stop()
302
+
303
+ # -- events ---------------------------------------------------------------
304
+
305
+ def _on_engine_event(self, event: dict[str, Any]) -> None:
306
+ """The manager's one event handler, on whatever thread emits."""
307
+ loop = self._loop
308
+ if loop is None or loop.is_closed():
309
+ return
310
+ try:
311
+ on_loop = asyncio.get_running_loop() is loop
312
+ except RuntimeError:
313
+ on_loop = False
314
+ if on_loop:
315
+ # The run loop or the drain, on this thread: never a client's
316
+ # call, whatever call is in flight on the executor right now.
317
+ self._route(event)
318
+ else:
319
+ # The executor thread executing one client's call. Queued behind
320
+ # whatever is already on the loop and ahead of the call's own
321
+ # completion, so it is routed while that client is the caller.
322
+ loop.call_soon_threadsafe(self._route, event, True)
323
+
324
+ def _route(self, event: dict[str, Any], in_call: bool = False) -> None:
325
+ if not isinstance(event, dict):
326
+ return
327
+ if event.get("type") == "message_received" and "message_id" not in event:
328
+ # The manager's drain wraps the pull-style `receive_message()`
329
+ # JSON as a second `message_received` (keyed `id`). The engine
330
+ # emitted the real event inside that same `receive_message()`
331
+ # call, so this copy is dropped rather than delivered twice.
332
+ return
333
+ self._router.route(event, in_call=in_call)
334
+
335
+ # -- the request hook -----------------------------------------------------
336
+
337
+ def _process_request(self, connection: ServerConnection, request: Request) -> Response | None:
338
+ if not self._health or request.path != "/health":
339
+ return None
340
+ if "upgrade" in request.headers.get("Connection", "").lower():
341
+ return None
342
+ body = json.dumps(
343
+ {
344
+ "server": {"name": SERVER_NAME, "version": self.version},
345
+ "api_version": API_VERSION,
346
+ "carrier": self.carrier,
347
+ }
348
+ )
349
+ response = connection.respond(http.HTTPStatus.OK, body + "\n")
350
+ response.headers["Content-Type"] = "application/json"
351
+ return response
352
+
353
+ # -- connections ----------------------------------------------------------
354
+
355
+ async def _handle(self, websocket: ServerConnection) -> None:
356
+ session = Session(self.carrier)
357
+ self._sessions.add(session)
358
+ sender = asyncio.ensure_future(session.sender(websocket))
359
+ try:
360
+ async for raw in websocket:
361
+ # One request at a time per connection, in arrival order;
362
+ # the call itself runs on the executor behind the server's
363
+ # one lock, so the loop keeps ticking while it runs.
364
+ await self._handle_frame(session, raw)
365
+ except ConnectionClosed:
366
+ pass
367
+ finally:
368
+ self._router.detach(session)
369
+ self._sessions.discard(session)
370
+ session.closed = True
371
+ sender.cancel()
372
+ await asyncio.gather(sender, return_exceptions=True)
373
+
374
+ async def _handle_frame(self, session: Session, raw: str | bytes) -> None:
375
+ if isinstance(raw, bytes):
376
+ session.push(self._error(None, RpcError(codec.INVALID_REQUEST, "text frames only")))
377
+ return
378
+ try:
379
+ request = json.loads(raw)
380
+ except ValueError:
381
+ session.push(self._error(None, RpcError(codec.PARSE_ERROR, "parse error")))
382
+ return
383
+ if isinstance(request, list):
384
+ session.push(
385
+ self._error(None, RpcError(codec.INVALID_REQUEST, "batches are not supported"))
386
+ )
387
+ return
388
+ if not isinstance(request, dict) or request.get("jsonrpc") != "2.0":
389
+ session.push(self._error(None, RpcError(codec.INVALID_REQUEST, "not a JSON-RPC 2.0 request")))
390
+ return
391
+ if "id" not in request:
392
+ # A notification: a client never sends one, and it gets no answer.
393
+ return
394
+ request_id = request["id"]
395
+ # A string or a number (JSON-RPC 2.0 allows a fractional one); `true`
396
+ # is an int to Python and not a number to the framing.
397
+ if not (request_id is None or isinstance(request_id, (str, int, float))) or isinstance(request_id, bool):
398
+ session.push(self._error(None, RpcError(codec.INVALID_REQUEST, "id must be a string or a number")))
399
+ return
400
+ method = request.get("method")
401
+ if not isinstance(method, str):
402
+ session.push(self._error(request_id, RpcError(codec.INVALID_REQUEST, "method must be a string")))
403
+ return
404
+ params = request.get("params")
405
+ if params is not None and not isinstance(params, dict):
406
+ session.push(
407
+ self._error(request_id, RpcError(codec.INVALID_PARAMS, "params must be an object of named parameters"))
408
+ )
409
+ return
410
+ try:
411
+ if method == "hello":
412
+ result = self._hello(session, params or {})
413
+ session.push({"jsonrpc": "2.0", "id": request_id, "result": result})
414
+ # Registered only now: the hello result is queued ahead of
415
+ # the held events, and the held events ahead of anything the
416
+ # router delivers from here on.
417
+ for event in self._router.attach(session):
418
+ session.push_event(event)
419
+ return
420
+ if method in SESSION_METHODS:
421
+ result = self._subscription(session, method, params or {})
422
+ else:
423
+ assert self._dispatcher is not None
424
+ result = await self._dispatcher.call(session, method, params)
425
+ except _CloseAfter as exc:
426
+ session.push(self._error(request_id, exc))
427
+ session.push_close(POLICY_VIOLATION, "policy violation")
428
+ return
429
+ except RpcError as exc:
430
+ session.push(self._error(request_id, exc))
431
+ return
432
+ except Exception:
433
+ # A value the decoders did not foresee, or a failure of the
434
+ # server's own: the server's log gets the traceback, the client
435
+ # gets an error object, and the connection stays open. Without
436
+ # this the library closes the socket with 1011 and the client
437
+ # learns nothing.
438
+ logger.exception("internal error handling %s", method)
439
+ session.push(
440
+ self._error(request_id, RpcError(codec.INTERNAL_ERROR, f"{method}: internal error"))
441
+ )
442
+ return
443
+ session.push({"jsonrpc": "2.0", "id": request_id, "result": result})
444
+
445
+ @staticmethod
446
+ def _error(request_id: Any, error: RpcError) -> dict[str, Any]:
447
+ return {"jsonrpc": "2.0", "id": request_id, "error": error.to_json()}
448
+
449
+ # -- the session methods --------------------------------------------------
450
+
451
+ def _hello(self, session: Session, params: dict[str, Any]) -> dict[str, Any]:
452
+ if session.app_id is not None:
453
+ raise taxonomy_error("InvalidState", "hello was already sent on this connection")
454
+ unknown = sorted(set(params) - {"app_id", "client", "token"})
455
+ if unknown:
456
+ raise codec.invalid_params(f"hello has no parameter {unknown[0]!r}")
457
+ if "app_id" not in params:
458
+ raise codec.invalid_params("hello requires app_id")
459
+ app_id = validate_app_id(params["app_id"])
460
+ client = params.get("client")
461
+ if client is not None and not isinstance(client, str):
462
+ raise codec.invalid_params("hello.client must be a string")
463
+ if self.carrier == "tcp":
464
+ token = params.get("token")
465
+ # `compare_digest` takes ASCII strings only and raises on
466
+ # anything else; a token that is not ASCII is simply wrong.
467
+ if (
468
+ not isinstance(token, str)
469
+ or not token.isascii()
470
+ or self.token is None
471
+ or not hmac.compare_digest(token, self.token)
472
+ ):
473
+ raise _CloseAfter(*_permission_denied("hello.token is missing or wrong"))
474
+ # Once any rule is configured, an id no rule names is refused, so a
475
+ # rule cannot be stepped around by reconnecting under another name.
476
+ self._policy.check_admission(app_id)
477
+ session.app_id = app_id
478
+ session.client = client
479
+ engine = self._manager.protocol
480
+ return {
481
+ "api_version": API_VERSION,
482
+ "server": {"name": SERVER_NAME, "version": self.version},
483
+ "state": codec.encode("ProtocolState", engine.get_state()),
484
+ "local_address": engine.local_address(),
485
+ }
486
+
487
+ @staticmethod
488
+ def _subscription(session: Session, method: str, params: dict[str, Any]) -> bool:
489
+ if session.app_id is None:
490
+ raise taxonomy_error("InvalidState", "hello has not been sent on this connection")
491
+ unknown = sorted(set(params) - {"types"})
492
+ if unknown:
493
+ raise codec.invalid_params(f"{method} has no parameter {unknown[0]!r}")
494
+ types = params.get("types")
495
+ if types != "all":
496
+ if not isinstance(types, list) or not all(isinstance(t, str) for t in types):
497
+ raise codec.invalid_params(f"{method}.types is a list of tags or \"all\"")
498
+ if method == "subscribe":
499
+ session.subscribe(types)
500
+ else:
501
+ session.unsubscribe(types)
502
+ return True
503
+
504
+
505
+ def _permission_denied(message: str) -> tuple[int, str, dict[str, Any]]:
506
+ error = taxonomy_error("PermissionDenied", message)
507
+ return error.code, error.message, error.data or {}
508
+
509
+
510
+ def _prepare_socket_directory(directory: Path) -> None:
511
+ """The socket's directory, owner-only, without touching what the server
512
+ did not create.
513
+
514
+ A directory the server creates is made ``0700``. One that already exists
515
+ is required to be this user's with no group or other bits, and is
516
+ otherwise refused by name: narrowing an operator's ``0755`` directory
517
+ (or ``/tmp``) to ``0700`` is not the server's to do, and a socket inside
518
+ a directory others can enter is not the credential the chapter says it
519
+ is.
520
+ """
521
+ try:
522
+ found = directory.stat()
523
+ except FileNotFoundError:
524
+ directory.mkdir(parents=True)
525
+ os.chmod(directory, stat.S_IRWXU)
526
+ return
527
+ if not stat.S_ISDIR(found.st_mode):
528
+ raise ValueError(f"{directory} exists and is not a directory")
529
+ mode = stat.S_IMODE(found.st_mode)
530
+ if found.st_uid != os.getuid() or mode & 0o077:
531
+ raise ValueError(
532
+ f"{directory} must be owned by this user with no group or other "
533
+ f"permissions (found mode {mode:04o}); the server does not narrow a "
534
+ "directory it did not create"
535
+ )
536
+
537
+
538
+ def _remove_stale_socket(path: Path) -> None:
539
+ """Removes a socket file left by an earlier launch, and nothing else."""
540
+ try:
541
+ found = os.lstat(path)
542
+ except FileNotFoundError:
543
+ return
544
+ if not stat.S_ISSOCK(found.st_mode):
545
+ raise ValueError(f"{path} exists and is not a socket; refusing to remove it")
546
+ path.unlink()
@@ -0,0 +1,86 @@
1
+ """One connection's state: the application id it declared, its event
2
+ filter, and the outbound queue everything it receives goes through.
3
+
4
+ Every response and every notification a connection receives is pushed onto
5
+ one queue and written by one task, in push order. That is what makes the
6
+ chapter's ordering rules cheap to keep: the ``hello`` result is pushed, then
7
+ the held events, then whatever the router delivers later, and nothing can
8
+ overtake anything.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import asyncio
14
+ import itertools
15
+ import json
16
+ from typing import Any
17
+
18
+ _ids = itertools.count(1)
19
+
20
+
21
+ class _Close:
22
+ """A close request queued behind everything pushed before it."""
23
+
24
+ def __init__(self, code: int, reason: str) -> None:
25
+ self.code = code
26
+ self.reason = reason
27
+
28
+
29
+ class Session:
30
+ """Per-connection state. ``app_id`` is ``None`` until ``hello``."""
31
+
32
+ def __init__(self, carrier: str) -> None:
33
+ self.id: int = next(_ids)
34
+ self.carrier = carrier
35
+ self.app_id: str | None = None
36
+ self.client: str | None = None
37
+ #: ``None`` delivers every event the routing rules select; a set
38
+ #: narrows delivery to those tags.
39
+ self.subscriptions: set[str] | None = None
40
+ self._queue: asyncio.Queue[str | _Close] = asyncio.Queue()
41
+ self.closed = False
42
+
43
+ # -- the filter ---------------------------------------------------------
44
+
45
+ def wants(self, tag: str | None) -> bool:
46
+ if self.subscriptions is None:
47
+ return True
48
+ return tag is not None and tag in self.subscriptions
49
+
50
+ def subscribe(self, types: Any) -> None:
51
+ if types == "all":
52
+ self.subscriptions = None
53
+ return
54
+ if self.subscriptions is None:
55
+ self.subscriptions = set()
56
+ self.subscriptions.update(types)
57
+
58
+ def unsubscribe(self, types: Any) -> None:
59
+ if types == "all":
60
+ self.subscriptions = set()
61
+ return
62
+ if self.subscriptions is not None:
63
+ self.subscriptions.difference_update(types)
64
+
65
+ # -- the outbound queue -------------------------------------------------
66
+
67
+ def push(self, payload: dict[str, Any]) -> None:
68
+ if not self.closed:
69
+ self._queue.put_nowait(json.dumps(payload, separators=(",", ":")))
70
+
71
+ def push_event(self, event: dict[str, Any]) -> None:
72
+ self.push({"jsonrpc": "2.0", "method": "event", "params": event})
73
+
74
+ def push_close(self, code: int, reason: str) -> None:
75
+ self._queue.put_nowait(_Close(code, reason))
76
+
77
+ async def sender(self, websocket: Any) -> None:
78
+ """Writes the queue to the socket until a close is queued or the
79
+ socket goes away. Runs as one task per connection."""
80
+ while True:
81
+ item = await self._queue.get()
82
+ if isinstance(item, _Close):
83
+ self.closed = True
84
+ await websocket.close(item.code, item.reason)
85
+ return
86
+ await websocket.send(item)