offline-protocol-sdk 0.28.0__py3-none-win_amd64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- offline_protocol_sdk/__init__.py +22 -0
- offline_protocol_sdk/_callback_reentrancy.py +64 -0
- offline_protocol_sdk/address_declaration.py +207 -0
- offline_protocol_sdk/ble_manager.py +595 -0
- offline_protocol_sdk/ble_peripheral.py +673 -0
- offline_protocol_sdk/dnssd_bridge.py +614 -0
- offline_protocol_sdk/gateway_attach_policy.py +437 -0
- offline_protocol_sdk/gateway_manager.py +1217 -0
- offline_protocol_sdk/gateway_verdict_tracker.py +97 -0
- offline_protocol_sdk/internet_manager.py +1444 -0
- offline_protocol_sdk/legacy_store_adoption.py +184 -0
- offline_protocol_sdk/local_api/__init__.py +34 -0
- offline_protocol_sdk/local_api/authz.py +180 -0
- offline_protocol_sdk/local_api/cli.py +171 -0
- offline_protocol_sdk/local_api/codec.py +210 -0
- offline_protocol_sdk/local_api/dispatch.py +537 -0
- offline_protocol_sdk/local_api/mux.py +239 -0
- offline_protocol_sdk/local_api/server.py +546 -0
- offline_protocol_sdk/local_api/session.py +86 -0
- offline_protocol_sdk/local_api/table.py +849 -0
- offline_protocol_sdk/offline_protocol.py +13508 -0
- offline_protocol_sdk/peer_stream_manager.py +1303 -0
- offline_protocol_sdk/presence_watch_policy.py +102 -0
- offline_protocol_sdk/protocol_manager.py +1108 -0
- offline_protocol_sdk/relay_answer_prefixes.py +61 -0
- offline_protocol_sdk/secure_storage.py +551 -0
- offline_protocol_sdk/services.py +195 -0
- offline_protocol_sdk/state_storage.py +452 -0
- offline_protocol_sdk/storage_namespace.py +33 -0
- offline_protocol_sdk/transport_manager.py +138 -0
- offline_protocol_sdk/uniffi.dll +0 -0
- offline_protocol_sdk-0.28.0.dist-info/METADATA +519 -0
- offline_protocol_sdk-0.28.0.dist-info/RECORD +40 -0
- offline_protocol_sdk-0.28.0.dist-info/WHEEL +5 -0
- offline_protocol_sdk-0.28.0.dist-info/entry_points.txt +2 -0
- offline_protocol_sdk-0.28.0.dist-info/licenses/EXPORT.md +68 -0
- offline_protocol_sdk-0.28.0.dist-info/licenses/LICENSE +661 -0
- offline_protocol_sdk-0.28.0.dist-info/licenses/LICENSE-COMMERCIAL.md +89 -0
- offline_protocol_sdk-0.28.0.dist-info/licenses/THIRD-PARTY-NOTICES.md +6645 -0
- offline_protocol_sdk-0.28.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,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)
|