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,239 @@
1
+ """Event routing and the per-application hold.
2
+
3
+ Implements the chapter's routing classes (stamped, then the caller of the
4
+ call an event was emitted inside, then correlated, then broadcast) and its
5
+ replay rule. The event object the engine serialised is pushed unchanged
6
+ (C3); this module reads only ``type``, ``app_id``, the correlation
7
+ identifiers and ``space_id``.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import logging
13
+ from collections import OrderedDict, deque
14
+ from typing import Any, Callable, Iterable
15
+
16
+ from .authz import Policy, ServiceOwnership
17
+ from .session import Session
18
+
19
+ logger = logging.getLogger(__name__)
20
+
21
+ #: The stamped inbound tags held for an application with no connected client
22
+ #: (chapter, "Replay"). The engine has already acknowledged and dedup-marked
23
+ #: the message by the time these fire, so nothing will restate them.
24
+ HELD_TAGS: frozenset[str] = frozenset({"message_received", "file_received", "media_resend_required"})
25
+
26
+ #: The hold's capacity per application id: the same real capacity the
27
+ #: mobile bridges keep for inbound tags before a subscriber exists (C10).
28
+ HOLD_CAPACITY = 256
29
+
30
+ #: Identifier fields the server correlates by, in the order they are read.
31
+ CORRELATION_KEYS: tuple[str, ...] = ("message_id", "file_id", "query_id", "request_id")
32
+
33
+ #: How many issued identifiers are remembered. An identifier is forgotten on
34
+ #: its terminal event; one whose terminal event never comes (a query, a
35
+ #: message the engine gave up on silently) is evicted oldest-first past
36
+ #: this, after which its events are broadcast, which is what the chapter
37
+ #: says happens to an identifier the server does not know.
38
+ ISSUED_CAPACITY = 65536
39
+
40
+ #: The last event that names an identifier, after which it is forgotten.
41
+ TERMINAL_TAGS: dict[str, str] = {
42
+ "message_delivered": "message_id",
43
+ "message_failed": "message_id",
44
+ "message_undeliverable": "message_id",
45
+ "connection_request_undeliverable": "message_id",
46
+ "media_sent": "file_id",
47
+ "media_send_failed": "file_id",
48
+ "service_response_received": "request_id",
49
+ }
50
+
51
+
52
+ class EventRouter:
53
+ """Selects the sessions an event reaches and pushes it to them."""
54
+
55
+ def __init__(
56
+ self,
57
+ policy: Policy,
58
+ ownership: ServiceOwnership,
59
+ *,
60
+ on_drop: Callable[[str, dict[str, Any]], None] | None = None,
61
+ ) -> None:
62
+ self._policy = policy
63
+ self._ownership = ownership
64
+ self._sessions: dict[str, list[Session]] = {}
65
+ self._issued: OrderedDict[str, str] = OrderedDict()
66
+ self._held: dict[str, deque[dict[str, Any]]] = {}
67
+ #: Events the run loop emitted while a call was in flight, naming an
68
+ #: identifier nobody owned yet. Routed once the call's result is
69
+ #: recorded (see `flush_parked`).
70
+ self._parked: list[dict[str, Any]] = []
71
+ self._on_drop = on_drop
72
+ #: The session whose call the server is executing right now, if any.
73
+ self.current_caller: Session | None = None
74
+ self.dropped = 0
75
+
76
+ # -- sessions -------------------------------------------------------------
77
+
78
+ def attach(self, session: Session) -> list[dict[str, Any]]:
79
+ """Registers a session under its application id and returns the
80
+ events held for that id, oldest first, emptying the hold."""
81
+ assert session.app_id is not None
82
+ self._sessions.setdefault(session.app_id, []).append(session)
83
+ held = self._held.pop(session.app_id, None)
84
+ return list(held) if held else []
85
+
86
+ def detach(self, session: Session) -> None:
87
+ if session.app_id is None:
88
+ return
89
+ sessions = self._sessions.get(session.app_id)
90
+ if sessions and session in sessions:
91
+ sessions.remove(session)
92
+ if not sessions:
93
+ del self._sessions[session.app_id]
94
+
95
+ def sessions_for(self, app_id: str) -> list[Session]:
96
+ return list(self._sessions.get(app_id, ()))
97
+
98
+ def all_sessions(self) -> list[Session]:
99
+ return [s for sessions in self._sessions.values() for s in sessions]
100
+
101
+ def held_count(self, app_id: str) -> int:
102
+ return len(self._held.get(app_id, ()))
103
+
104
+ # -- identifiers ----------------------------------------------------------
105
+
106
+ def issued_count(self) -> int:
107
+ return len(self._issued)
108
+
109
+ def knows(self, identifier: str) -> bool:
110
+ return identifier in self._issued
111
+
112
+ def note_ids(self, app_id: str, ids: Iterable[Any]) -> None:
113
+ """Records identifiers the server handed to ``app_id`` as results."""
114
+ for value in ids:
115
+ if isinstance(value, str) and value:
116
+ self._remember(value, app_id)
117
+
118
+ def _remember(self, identifier: str, app_id: str) -> None:
119
+ self._issued[identifier] = app_id
120
+ self._issued.move_to_end(identifier)
121
+ while len(self._issued) > ISSUED_CAPACITY:
122
+ self._issued.popitem(last=False)
123
+
124
+ def _record_from_event(self, app_id: str, event: dict[str, Any]) -> None:
125
+ for key in CORRELATION_KEYS:
126
+ value = event.get(key)
127
+ if isinstance(value, str) and value and value not in self._issued:
128
+ self._remember(value, app_id)
129
+
130
+ def _correlated_app(self, event: dict[str, Any]) -> str | None:
131
+ for key in CORRELATION_KEYS:
132
+ value = event.get(key)
133
+ if isinstance(value, str) and value in self._issued:
134
+ return self._issued[value]
135
+ service_id = event.get("service_id")
136
+ if isinstance(service_id, str):
137
+ return self._ownership.owner(service_id)
138
+ return None
139
+
140
+ def _forget_terminal(self, tag: Any, event: dict[str, Any]) -> None:
141
+ key = TERMINAL_TAGS.get(tag) if isinstance(tag, str) else None
142
+ if key is None:
143
+ return
144
+ value = event.get(key)
145
+ if isinstance(value, str):
146
+ self._issued.pop(value, None)
147
+
148
+ # -- routing --------------------------------------------------------------
149
+
150
+ def route(self, event: dict[str, Any], *, in_call: bool = False) -> None:
151
+ """Pushes ``event`` to the sessions the rules select.
152
+
153
+ ``in_call`` says the event was emitted on the thread executing a
154
+ client's call. Only then does the caller rule apply: an event the
155
+ run loop emits while a call is in flight on the executor is not the
156
+ caller's, and would be misattributed to it otherwise.
157
+ """
158
+ tag = event.get("type")
159
+ app_id = event.get("app_id")
160
+ if isinstance(app_id, str):
161
+ targets = self.sessions_for(app_id)
162
+ if not targets and tag in HELD_TAGS:
163
+ self._hold(app_id, event)
164
+ return
165
+ elif tag in HELD_TAGS:
166
+ # A stamped tag whose id is absent (a `file_received` assembled
167
+ # with no metadata entry, a `media_resend_required` without one)
168
+ # has nothing to route or hold by, so it is broadcast, and said.
169
+ logger.info("%s carries no app_id: broadcast, not held", tag)
170
+ targets = self.all_sessions()
171
+ elif in_call and self.current_caller is not None and self.current_caller.app_id is not None:
172
+ caller = self.current_caller
173
+ self._record_from_event(caller.app_id, event)
174
+ targets = self.sessions_for(caller.app_id)
175
+ else:
176
+ owner = self._correlated_app(event)
177
+ if owner is None and self.current_caller is not None and self._names_an_identifier(event):
178
+ # The run loop emitted this while a call was in flight, and
179
+ # nobody owns the identifier it names yet. Between the
180
+ # executor's completion and the wakeup that records the
181
+ # call's result, one or two loop iterations run; a `process()`
182
+ # tick landing there can emit `message_sent` for the very id
183
+ # the call is about to return, content and all. Broadcasting
184
+ # it would hand one application's message to every other, so
185
+ # it waits for the result to be recorded.
186
+ self._parked.append(event)
187
+ return
188
+ targets = self.sessions_for(owner) if owner is not None else self.all_sessions()
189
+ for session in targets:
190
+ self._deliver(session, tag, event)
191
+ self._forget_terminal(tag, event)
192
+
193
+ def flush_parked(self) -> None:
194
+ """Routes what was parked during a call, now that its identifiers are
195
+ recorded. Called with no caller set, after the call's result was
196
+ noted, or after its failure, when the events route by the ordinary
197
+ rules (an unknown identifier broadcasts) but never with the caller's
198
+ own identifiers still unknown."""
199
+ parked, self._parked = self._parked, []
200
+ for event in parked:
201
+ self.route(event)
202
+
203
+ def parked_count(self) -> int:
204
+ return len(self._parked)
205
+
206
+ @staticmethod
207
+ def _names_an_identifier(event: dict[str, Any]) -> bool:
208
+ return any(
209
+ isinstance(event.get(key), str) and event.get(key) for key in CORRELATION_KEYS
210
+ )
211
+
212
+ def _deliver(self, session: Session, tag: Any, event: dict[str, Any]) -> None:
213
+ if not session.wants(tag):
214
+ return
215
+ if isinstance(tag, str) and tag.startswith("data_"):
216
+ # The reference server filters document events by the space
217
+ # allow-list, which the chapter allows a server to add.
218
+ space_id = event.get("space_id")
219
+ if isinstance(space_id, str) and session.app_id is not None:
220
+ if not self._policy.allows_space(session.app_id, space_id):
221
+ return
222
+ session.push_event(event)
223
+
224
+ def _hold(self, app_id: str, event: dict[str, Any]) -> None:
225
+ held = self._held.get(app_id)
226
+ if held is None:
227
+ held = self._held[app_id] = deque()
228
+ if len(held) >= HOLD_CAPACITY:
229
+ dropped = held.popleft()
230
+ self.dropped += 1
231
+ logger.warning(
232
+ "hold for %r is full (%d): dropping the oldest %s",
233
+ app_id,
234
+ HOLD_CAPACITY,
235
+ dropped.get("type"),
236
+ )
237
+ if self._on_drop is not None:
238
+ self._on_drop(app_id, dropped)
239
+ held.append(event)