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,537 @@
1
+ """The method table: which declarations are on the wire, and the call path
2
+ from a JSON-RPC request to the generated binding and back.
3
+
4
+ ``EXPOSED`` and ``PLATFORM`` classify every declaration in ``table.py`` by
5
+ its wire name. The two sets are the chapter's method table and platform
6
+ table, and a Rust guard in the FFI crate holds all three to each other: a
7
+ declaration in neither set fails that guard and the test in
8
+ ``tests/local_api``, so an unclassified method is a failing test rather than
9
+ a method every local application can reach by default.
10
+
11
+ A call is decoded by the declared parameter types, checked against the
12
+ server-side rules, executed against the binding, and encoded by the declared
13
+ result type. Two methods are stamped: ``send_message`` and ``send_media``
14
+ are executed through their rich twins with the connection's application id
15
+ set, and the rich twins refuse an ``app_id`` the client sent.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import asyncio
21
+ from typing import Any, Callable
22
+
23
+ from .. import offline_protocol as generated
24
+ from . import codec
25
+ from .authz import Policy, ServiceOwnership
26
+ from .codec import RpcError, error_from_protocol, taxonomy_error
27
+ from .mux import EventRouter
28
+ from .session import Session
29
+ from .table import TABLE
30
+
31
+ #: The interface definition's declarations a client may call, by wire name.
32
+ EXPOSED: frozenset[str] = frozenset(
33
+ {
34
+ # identity and state
35
+ "get_state",
36
+ "local_address",
37
+ "get_identity_public_key",
38
+ "derive_user_id_from_public_key",
39
+ "sign_data",
40
+ "verify_signature",
41
+ "create_invite",
42
+ "resolve_username",
43
+ # messaging
44
+ "send_message",
45
+ "send_message_rich",
46
+ "forward_message",
47
+ "send_presence_update",
48
+ "send_typing_indicator",
49
+ "send_read_receipt",
50
+ # connection requests
51
+ "send_connection_request",
52
+ "accept_connection_request",
53
+ "reject_connection_request",
54
+ "cancel_connection_request",
55
+ # media and files
56
+ "send_media",
57
+ "send_media_rich",
58
+ "send_file",
59
+ "get_file_progress",
60
+ "cancel_file_transfer",
61
+ # secure sessions
62
+ "is_mls_initialized",
63
+ "has_pending_key_package",
64
+ "get_establishment_state",
65
+ "establish_secure_session",
66
+ "rekey_session",
67
+ "mls_has_session",
68
+ "mls_list_sessions",
69
+ "mls_delete_session",
70
+ # manual MLS
71
+ "mls_generate_key_package",
72
+ "mls_get_or_create_key_package",
73
+ "mls_import_key_package",
74
+ "mls_get_pending_key_packages",
75
+ "mls_mark_key_package_synced",
76
+ "mls_create_session",
77
+ "mls_join_session",
78
+ "mls_encrypt_for_user",
79
+ "mls_decrypt_from_user",
80
+ "mls_get_pending_welcome",
81
+ "mls_clear_pending_welcome",
82
+ "mls_decrypt",
83
+ "mls_process_welcome",
84
+ # groups
85
+ "create_group",
86
+ "send_group_message",
87
+ "forward_message_to_group",
88
+ "invite_to_group",
89
+ "remove_from_group",
90
+ "leave_group",
91
+ "list_groups",
92
+ "get_group_info",
93
+ "group_rich_readiness",
94
+ "group_relay_sync_state",
95
+ "request_group_relay_registration",
96
+ "set_member_role",
97
+ "get_member_role",
98
+ "get_group_roles",
99
+ "rename_group",
100
+ # blocking
101
+ "block_user",
102
+ "unblock_user",
103
+ "get_blocked_users",
104
+ "is_user_blocked",
105
+ # transports and metrics
106
+ "get_active_transports",
107
+ "get_transport_metrics",
108
+ "should_escalate_to_wifi",
109
+ "get_topology",
110
+ "get_message_stats",
111
+ "get_delivery_success_rate",
112
+ "get_median_latency",
113
+ "get_median_hops",
114
+ "get_battery_level",
115
+ "get_is_charging",
116
+ "is_relay",
117
+ "get_relay_priority",
118
+ "get_relay_config",
119
+ "get_dors_config",
120
+ "get_dedup_stats",
121
+ "get_pending_ack_count",
122
+ "get_retry_queue_size",
123
+ "get_mesh_relay_stats",
124
+ "get_mesh_relay_tunables",
125
+ "get_custody_stats",
126
+ # instance-wide tuning
127
+ "set_relay_priority",
128
+ "update_relay_config",
129
+ "force_transport",
130
+ "release_transport_lock",
131
+ "update_dors_config",
132
+ "update_ack_config",
133
+ "update_retry_config",
134
+ "update_dedup_config",
135
+ # services
136
+ "services.register_service",
137
+ "services.unregister_service",
138
+ "services.discover_services",
139
+ "services.send_service_request",
140
+ "services.respond_to_service_request",
141
+ # documents
142
+ "data.create_doc",
143
+ "data.delete_doc",
144
+ "data.remove_doc",
145
+ "data.remove_space",
146
+ "data.set_interest",
147
+ "data.list_docs",
148
+ "data.list_spaces",
149
+ "data.map_set",
150
+ "data.map_delete",
151
+ "data.map_get_json",
152
+ "data.list_push",
153
+ "data.list_delete",
154
+ "data.list_len",
155
+ "data.text_insert",
156
+ "data.text_delete",
157
+ "data.text_value",
158
+ "data.counter_increment",
159
+ "data.counter_value",
160
+ "data.doc_json",
161
+ "data.export_raw",
162
+ "data.flush",
163
+ "data.flush_all",
164
+ "data.doc_size",
165
+ "data.attachment_hash",
166
+ "data.fetch_attachment",
167
+ "data.provide_attachment",
168
+ "data.decline_attachment",
169
+ "data.fetch_attachment_from",
170
+ # instance-less
171
+ "derive_address",
172
+ "parse_invite",
173
+ "verify_identity_assertion",
174
+ }
175
+ )
176
+
177
+ #: The declarations the server owns and never puts on the wire (the
178
+ #: chapter's fifth invariant). A request naming one is answered with
179
+ #: method-not-found, the same answer an unknown name gets.
180
+ PLATFORM: frozenset[str] = frozenset(
181
+ {
182
+ # lifecycle, run loop, drain
183
+ "constructor",
184
+ "start",
185
+ "stop",
186
+ "pause",
187
+ "resume",
188
+ "process",
189
+ "receive_message",
190
+ "set_event_callback",
191
+ "poll_event",
192
+ "emit_test_event",
193
+ # storage attach
194
+ "initialize_mls",
195
+ "initialize_mls_with_file_stores",
196
+ "close_file_stores",
197
+ # telemetry (C12)
198
+ "enable_telemetry",
199
+ "disable_telemetry",
200
+ "set_telemetry_enabled",
201
+ "flush_telemetry",
202
+ "flush_telemetry_blocking",
203
+ "telemetry_stats",
204
+ "end_telemetry_session",
205
+ "notify_app_state",
206
+ "telemetry_install_id",
207
+ # callback installers
208
+ "set_ble_transport_callback",
209
+ "set_wifi_direct_transport_callback",
210
+ "set_reticulum_transport_callback",
211
+ "set_nostr_transport_callback",
212
+ # Bluetooth LE driver
213
+ "ble_peer_discovered",
214
+ "ble_peer_lost",
215
+ "ble_status_changed",
216
+ "ble_fragment_received",
217
+ "ble_get_next_fragment",
218
+ "ble_return_fragment",
219
+ "ble_get_peer_count",
220
+ "ble_set_peer_mtu",
221
+ "ble_clear_peer_mtu",
222
+ "ble_undersized_mtu_reports",
223
+ "ble_fragment_fallback_count",
224
+ "ble_recipient_not_among_peers_count",
225
+ "protocol_lock_diagnostics",
226
+ # relay client
227
+ "internet_status_changed",
228
+ "internet_message_received",
229
+ "internet_get_next_message",
230
+ "internet_confirm_sent",
231
+ "internet_send_failed",
232
+ "internet_send_failed_with_reason",
233
+ "internet_peer_presence",
234
+ "internet_presence_watchlist",
235
+ "internet_relay_capabilities",
236
+ "internet_group_report_received",
237
+ "internet_address_declared",
238
+ "internet_address_declaration_refused",
239
+ # peer-stream driver
240
+ "wifi_direct_status_changed",
241
+ "wifi_direct_message_received",
242
+ "wifi_direct_get_next_message",
243
+ "wifi_direct_peer_connected",
244
+ "wifi_direct_peer_disconnected",
245
+ # gateway client
246
+ "reticulum_status_changed",
247
+ "reticulum_message_received",
248
+ "reticulum_get_next_message",
249
+ "reticulum_confirm_sent",
250
+ "reticulum_send_failed",
251
+ "reticulum_send_failed_with_reason",
252
+ "reticulum_address_declared",
253
+ "reticulum_address_declaration_refused",
254
+ "reticulum_gateway_capabilities",
255
+ "reticulum_peer_presence",
256
+ "reticulum_presence_watchlist",
257
+ # Nostr client
258
+ "nostr_status_changed",
259
+ "nostr_message_received",
260
+ "nostr_message_received_at",
261
+ "nostr_get_next_message",
262
+ "nostr_confirm_sent",
263
+ "nostr_send_failed",
264
+ "nostr_send_failed_with_reason",
265
+ "nostr_get_public_key",
266
+ "nostr_get_subscription_filter",
267
+ "nostr_get_next_query",
268
+ "nostr_query_event_received",
269
+ "nostr_query_completed",
270
+ # host facts
271
+ "update_transport_metrics",
272
+ "remove_transport",
273
+ "set_battery_level",
274
+ "set_battery_state",
275
+ # carrier proofs
276
+ "identity_assertion",
277
+ "gateway_address_declaration",
278
+ # inbound chunk driver
279
+ "process_file_chunk",
280
+ "finalize_file",
281
+ # the two objects' construction
282
+ "services.constructor",
283
+ "data.constructor",
284
+ "data.with_storage",
285
+ # the operator's logout
286
+ "data.wipe_all",
287
+ # erases what every client's traffic deposited
288
+ "erase_custody",
289
+ # takes a callback interface
290
+ "run_storage_conformance",
291
+ }
292
+ )
293
+
294
+ #: The server's own methods. Not in the definition; the only such methods.
295
+ SESSION_METHODS: frozenset[str] = frozenset({"hello", "subscribe", "unsubscribe"})
296
+
297
+ #: The one group a client may call before ``hello``: nothing to stamp,
298
+ #: nothing to route.
299
+ BEFORE_HELLO: frozenset[str] = frozenset(
300
+ {"derive_address", "parse_invite", "verify_identity_assertion"}
301
+ )
302
+
303
+ #: Methods whose result is an identifier (or a list of them) that later
304
+ #: events name; the router records it as the caller's.
305
+ ID_RESULTS: frozenset[str] = frozenset(
306
+ {
307
+ "send_message",
308
+ "send_message_rich",
309
+ "forward_message",
310
+ "send_presence_update",
311
+ "send_typing_indicator",
312
+ "send_read_receipt",
313
+ "send_connection_request",
314
+ "accept_connection_request",
315
+ "reject_connection_request",
316
+ "cancel_connection_request",
317
+ "send_media",
318
+ "send_media_rich",
319
+ "send_file",
320
+ "send_group_message",
321
+ "forward_message_to_group",
322
+ "services.discover_services",
323
+ "services.send_service_request",
324
+ "services.respond_to_service_request",
325
+ }
326
+ )
327
+
328
+
329
+ def resolve(method: str) -> tuple[str, str]:
330
+ """``(object, declaration)`` for a wire name."""
331
+ if method.startswith("services."):
332
+ return "MeshServices", method[len("services.") :]
333
+ if method.startswith("data."):
334
+ return "DataStore", method[len("data.") :]
335
+ if method in TABLE["methods"]["namespace"]:
336
+ return "namespace", method
337
+ return "OfflineProtocol", method
338
+
339
+
340
+ def all_wire_names() -> frozenset[str]:
341
+ """Every declaration in the table by its wire name."""
342
+ prefixes = {"OfflineProtocol": "", "MeshServices": "services.", "DataStore": "data.", "namespace": ""}
343
+ return frozenset(
344
+ prefix + name for obj, prefix in prefixes.items() for name in TABLE["methods"][obj]
345
+ )
346
+
347
+
348
+ class Dispatcher:
349
+ """Executes exposed methods against the binding for one server."""
350
+
351
+ def __init__(
352
+ self,
353
+ engine: Any,
354
+ services: Any,
355
+ data: Any,
356
+ router: EventRouter,
357
+ policy: Policy,
358
+ ownership: ServiceOwnership,
359
+ lock: asyncio.Lock,
360
+ ) -> None:
361
+ #: One lock for the whole server: engine calls run one at a time, on
362
+ #: the default executor, so a slow one (a media send marshals its
363
+ #: bytes per element in pure Python, about 1.5 s per MiB) neither
364
+ #: stalls the event loop nor interleaves with another client's call,
365
+ #: which is what keeps the caller rule's attribution exact.
366
+ self._lock = lock
367
+ self._engine = engine
368
+ self._services = services
369
+ #: The ``DataStore``, or the exception its construction raised, so
370
+ #: every ``data.*`` call answers with the engine's own refusal.
371
+ self._data = data
372
+ self._router = router
373
+ self._policy = policy
374
+ self._ownership = ownership
375
+
376
+ # -- entry ----------------------------------------------------------------
377
+
378
+ async def call(self, session: Session, method: str, params: Any) -> Any:
379
+ if method not in EXPOSED:
380
+ raise RpcError(codec.METHOD_NOT_FOUND, f"unknown method {method}")
381
+ if session.app_id is None:
382
+ if method not in BEFORE_HELLO:
383
+ raise taxonomy_error("InvalidState", "hello has not been sent on this connection")
384
+ else:
385
+ self._policy.check_method(session.app_id, method)
386
+ obj, declaration = resolve(method)
387
+ spec_params, result_type = TABLE["methods"][obj][declaration]
388
+ args = self._decode_params(method, spec_params, params)
389
+ target, declaration, args, result_type = self._prepare(
390
+ session, method, obj, declaration, args, result_type
391
+ )
392
+ fn: Callable[..., Any] = getattr(target, declaration)
393
+ loop = asyncio.get_running_loop()
394
+ failure: RpcError | None = None
395
+ result: Any = None
396
+ try:
397
+ async with self._lock:
398
+ # Set while the lock is held: an event the engine emits on
399
+ # the executor thread during this call reaches the loop
400
+ # through `call_soon_threadsafe` ahead of the call's own
401
+ # completion, so it is routed while this is still the caller.
402
+ # An event the run loop emits meanwhile that names an
403
+ # identifier nobody owns yet is parked by the router.
404
+ self._router.current_caller = session
405
+ try:
406
+ result = await loop.run_in_executor(None, lambda: fn(**args))
407
+ except generated.ProtocolError as exc:
408
+ self._after_failure(method, args)
409
+ failure = error_from_protocol(exc)
410
+ except RpcError as exc:
411
+ failure = exc
412
+ except Exception as exc: # the binding itself failed
413
+ self._after_failure(method, args)
414
+ failure = RpcError(codec.INTERNAL_ERROR, f"{method}: {exc}")
415
+ finally:
416
+ self._router.current_caller = None
417
+ if failure is None:
418
+ result = self._after_success(session, method, args, result)
419
+ finally:
420
+ # Nothing has yielded since the caller was cleared, so the parked
421
+ # events are routed with this call's identifiers recorded (or,
422
+ # after a failure, with none issued), and before any other call
423
+ # takes the lock.
424
+ self._router.flush_parked()
425
+ if failure is not None:
426
+ raise failure
427
+ return codec.encode(result_type, result)
428
+
429
+ # -- parameters -----------------------------------------------------------
430
+
431
+ @staticmethod
432
+ def _decode_params(
433
+ method: str, spec: tuple[tuple[str, str], ...], params: Any
434
+ ) -> dict[str, Any]:
435
+ if params is None:
436
+ params = {}
437
+ if not isinstance(params, dict):
438
+ raise codec.invalid_params(f"{method}: params must be an object of named parameters")
439
+ known = {name for name, _ in spec}
440
+ unknown = sorted(set(params) - known)
441
+ if unknown:
442
+ raise codec.invalid_params(f"{method} has no parameter {unknown[0]!r}")
443
+ args: dict[str, Any] = {}
444
+ for name, type_name in spec:
445
+ if name in params:
446
+ args[name] = codec.decode(type_name, params[name], f"{method}.{name}")
447
+ elif type_name.endswith("?"):
448
+ args[name] = None
449
+ else:
450
+ raise codec.invalid_params(f"{method} requires {name}")
451
+ return args
452
+
453
+ # -- the rules and the stamping, before the call -------------------------
454
+
455
+ def _prepare(
456
+ self,
457
+ session: Session,
458
+ method: str,
459
+ obj: str,
460
+ declaration: str,
461
+ args: dict[str, Any],
462
+ result_type: str,
463
+ ) -> tuple[Any, str, dict[str, Any], str]:
464
+ app_id = session.app_id
465
+ if obj == "namespace":
466
+ return generated, declaration, args, result_type
467
+ if obj == "MeshServices":
468
+ assert app_id is not None
469
+ service_id = args.get("service_id")
470
+ if declaration == "register_service":
471
+ self._ownership.claim(service_id, app_id)
472
+ elif declaration in ("unregister_service", "respond_to_service_request"):
473
+ self._ownership.check(service_id, app_id)
474
+ return self._services, declaration, args, result_type
475
+ if obj == "DataStore":
476
+ assert app_id is not None
477
+ if isinstance(self._data, BaseException):
478
+ raise error_from_protocol(self._data)
479
+ space_id = args.get("space_id")
480
+ if isinstance(space_id, str):
481
+ self._policy.check_space(app_id, space_id)
482
+ return self._data, declaration, args, result_type
483
+ # OfflineProtocol: the two stamped methods and their rich twins.
484
+ assert app_id is not None
485
+ if method == "send_message":
486
+ options = generated.SendMessageOptions(
487
+ priority=args["priority"], reply_to_msg=args["reply_to_msg"], app_id=app_id
488
+ )
489
+ return (
490
+ self._engine,
491
+ "send_message_rich",
492
+ {"recipient": args["recipient"], "content": args["content"], "options": options},
493
+ "string",
494
+ )
495
+ if method == "send_media":
496
+ options = generated.MediaSendOptions(
497
+ media_metadata=args["media_metadata"], app_id=app_id
498
+ )
499
+ return (
500
+ self._engine,
501
+ "send_media_rich",
502
+ {
503
+ "recipient": args["recipient"],
504
+ "file_data": args["file_data"],
505
+ "file_name": args["file_name"],
506
+ "content_type": args["content_type"],
507
+ "options": options,
508
+ },
509
+ "string",
510
+ )
511
+ if method in ("send_message_rich", "send_media_rich"):
512
+ options = args["options"]
513
+ if options.app_id is not None:
514
+ raise taxonomy_error(
515
+ "InvalidArgument",
516
+ "options.app_id is set by the server from the connection's hello",
517
+ )
518
+ options.app_id = app_id
519
+ return self._engine, declaration, args, result_type
520
+
521
+ # -- after the call -------------------------------------------------------
522
+
523
+ def _after_failure(self, method: str, args: dict[str, Any]) -> None:
524
+ if method == "services.register_service":
525
+ # The engine refused the registration; a claim nothing backs
526
+ # would block the next attempt by another application forever.
527
+ self._ownership.release(args["service_id"])
528
+
529
+ def _after_success(self, session: Session, method: str, args: dict[str, Any], result: Any) -> Any:
530
+ app_id = session.app_id
531
+ if method == "services.unregister_service" and result:
532
+ self._ownership.release(args["service_id"])
533
+ if method == "data.list_spaces" and app_id is not None:
534
+ result = [space for space in result if self._policy.allows_space(app_id, space)]
535
+ if method in ID_RESULTS and app_id is not None:
536
+ self._router.note_ids(app_id, result if isinstance(result, list) else [result])
537
+ return result