agentdevlabs 0.1.0__py3-none-any.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.
agentdevlabs/replay.py ADDED
@@ -0,0 +1,184 @@
1
+ import itertools
2
+ import threading
3
+ from collections.abc import Callable
4
+ from concurrent.futures import Future
5
+ from dataclasses import dataclass
6
+
7
+ from .cache import ObjectCache
8
+ from .decrypt import decrypt_object
9
+ from .server import CaptureRef, Decision, Pin, Variation, download_object
10
+ from .trace import Trace
11
+
12
+ Say = Callable[[str], None]
13
+
14
+ DOWNLOADS_AT_ONCE = 4
15
+
16
+
17
+ @dataclass(frozen=True)
18
+ class Question:
19
+ step: int
20
+ cache_key: str
21
+ provider: str
22
+ model: str
23
+ is_stream: bool
24
+
25
+
26
+ @dataclass(frozen=True)
27
+ class Choice:
28
+ """What answers a call: `replay` a stored capture (with a drift note when its key differs;
29
+ `pinned` when the pinned trace answered by position), `none` (nothing stored for this call)
30
+ or `past-the-end` (the recording has no such step)."""
31
+
32
+ kind: str
33
+ capture: CaptureRef | None = None
34
+ variation: int = 0
35
+ trace_id: str = ""
36
+ drift: str | None = None
37
+ reason: str = ""
38
+ pinned: bool = False
39
+
40
+
41
+ def _step_of(variation: Variation | None, step: int) -> CaptureRef | None:
42
+ if variation is None:
43
+ return None
44
+ return next((capture for capture in variation.captures if capture.step == step), None)
45
+
46
+
47
+ def choose_step(
48
+ variations: list[Variation], current: int, question: Question, strict: bool
49
+ ) -> Choice:
50
+ """S7, S8, M10, C13: call n is answered by step n of the variation being followed, else of
51
+ the newest one that has it. An exact cache-key match always replays (the key holds the
52
+ provider); the kind of call matters only for drift."""
53
+
54
+ def replay_of(capture: CaptureRef, index: int, drift: str | None = None) -> Choice:
55
+ return Choice("replay", capture, index, variations[index].trace_id, drift)
56
+
57
+ here = _step_of(variations[current] if current < len(variations) else None, question.step)
58
+ if here is not None and here.cache_key == question.cache_key:
59
+ return replay_of(here, current)
60
+ for index, variation in enumerate(variations):
61
+ there = _step_of(variation, question.step)
62
+ if there is not None and there.cache_key == question.cache_key:
63
+ return replay_of(there, index)
64
+ if here is None:
65
+ return Choice("past-the-end")
66
+ same_call = here.provider == question.provider and here.is_stream == question.is_stream
67
+ if strict or not same_call:
68
+ return Choice("none", reason=f"no capture for cache key {question.cache_key}")
69
+ drift = (
70
+ f"drift at step {question.step}: the call has cache key {question.cache_key}, "
71
+ f"the recording has {here.cache_key}"
72
+ )
73
+ return replay_of(here, current, drift)
74
+
75
+
76
+ def choose_by_position(pin: Pin, question: Question) -> Choice:
77
+ """Call n is answered by step n of the pinned trace, whatever the request says; only a step
78
+ recorded for another provider or model cannot answer."""
79
+ capture = next((c for c in pin.captures if c.step == question.step), None)
80
+ if capture is None:
81
+ return Choice("past-the-end")
82
+ if capture.provider != question.provider:
83
+ return Choice(
84
+ "none",
85
+ reason=(
86
+ f"pinned trace {pin.trace_id} step {question.step} was recorded for "
87
+ f"{capture.provider}, the call is for {question.provider}"
88
+ ),
89
+ )
90
+ if capture.model != question.model:
91
+ return Choice(
92
+ "none",
93
+ reason=(
94
+ f"pinned trace {pin.trace_id} step {question.step} was recorded for model "
95
+ f"{capture.model}, the call is for model {question.model}"
96
+ ),
97
+ )
98
+ return Choice("replay", capture, 0, pin.trace_id, pinned=True)
99
+
100
+
101
+ @dataclass(frozen=True)
102
+ class Load:
103
+ """A capture to fetch and the cache folder it lives in: the pinned trace's folder or the
104
+ trace's own."""
105
+
106
+ capture: CaptureRef
107
+ folder: str
108
+
109
+
110
+ def loads_of(trace: Trace, decision: Decision) -> list[Load]:
111
+ """The pinned captures first, then the variations', each capture once."""
112
+ loads = []
113
+ if decision.pin:
114
+ loads = [Load(c, decision.pin.first_cache_key) for c in decision.pin.captures]
115
+ loads += [
116
+ Load(capture, trace.first_cache_key)
117
+ for variation in decision.variations
118
+ for capture in variation.captures
119
+ ]
120
+ unique: dict[str, Load] = {}
121
+ for load in loads:
122
+ unique.setdefault(load.capture.capture_id, load)
123
+ return list(unique.values())
124
+
125
+
126
+ def _document_of(trace: Trace, load: Load, cache: ObjectCache, say: Say) -> str | None:
127
+ """Reads the object from the local cache or the store, opens it, and keeps only ciphertext on
128
+ disk (L2, L3)."""
129
+ capture, first_key = load.capture, load.folder
130
+ key = trace.keys.get(capture.capture_id)
131
+ if key is None or trace.ended:
132
+ return None
133
+ stored = cache.read(first_key, capture.capture_id)
134
+ if stored is not None:
135
+ try:
136
+ return decrypt_object(stored, key, capture.capture_id)
137
+ except Exception:
138
+ cache.remove(first_key, capture.capture_id)
139
+ say("a cached capture failed its integrity check and was deleted")
140
+ return None
141
+ if not capture.download_url:
142
+ return None
143
+ sealed = download_object(capture.download_url)
144
+ document = decrypt_object(sealed, key, capture.capture_id)
145
+ try:
146
+ cache.write(first_key, capture.capture_id, sealed)
147
+ except OSError:
148
+ say("a capture could not be written to the local cache")
149
+ return document
150
+
151
+
152
+ def _load_one(trace: Trace, load: Load, cache: ObjectCache, say: Say) -> str | None:
153
+ try:
154
+ return _document_of(trace, load, cache, say)
155
+ except Exception:
156
+ say("a stored capture could not be loaded")
157
+ return None
158
+
159
+
160
+ def start_loads(trace: Trace, decision: Decision, cache: ObjectCache, say: Say) -> None:
161
+ """Starts once per trace, right after trace start: every variation's objects load in the
162
+ background, four at a time on daemon threads of their own, so a later call replays from
163
+ memory and no upload or event job holds a download back. The keys move from the decision into
164
+ the trace, which drops them at its end (S8)."""
165
+ if trace.ended or trace.loads:
166
+ return
167
+ trace.keys.update(decision.keys)
168
+ decision.keys.clear()
169
+ queue = loads_of(trace, decision)
170
+ futures: dict[str, Future] = {load.capture.capture_id: Future() for load in queue}
171
+ trace.loads.update(futures)
172
+ pending = iter(queue)
173
+ take = threading.Lock()
174
+
175
+ def work() -> None:
176
+ while True:
177
+ with take:
178
+ load = next(pending, None)
179
+ if load is None:
180
+ return
181
+ futures[load.capture.capture_id].set_result(_load_one(trace, load, cache, say))
182
+
183
+ for _ in itertools.islice(range(DOWNLOADS_AT_ONCE), len(queue)):
184
+ threading.Thread(target=work, name="agentdevlabs-download", daemon=True).start()
agentdevlabs/rules.py ADDED
@@ -0,0 +1,55 @@
1
+ """The project's rules for the process (S6): `ignore` and `mask` change the cache key, the two
2
+ redact lists only the upload copy. One fetch is shared by concurrent calls; a failed fetch is not
3
+ kept, so the next trace asks again. A different version seen at trace start means the next trace
4
+ fetches again."""
5
+
6
+ import threading
7
+ from collections.abc import Callable
8
+ from concurrent.futures import Future
9
+ from typing import Any
10
+
11
+ from . import background
12
+
13
+ Rules = dict[str, Any]
14
+
15
+
16
+ class RulesHolder:
17
+ def __init__(self, load: Callable[[], Rules | str | None]):
18
+ self._load = load
19
+ self._lock = threading.Lock()
20
+ self._future: Future[Rules | str | None] | None = None
21
+ self._stale = False
22
+
23
+ def get(self, starts_trace: bool) -> Future[Rules | str | None]:
24
+ """`starts_trace` is whether this call opens a trace: rules never change in the middle of
25
+ one."""
26
+ with self._lock:
27
+ if self._stale and starts_trace:
28
+ self._future = None
29
+ self._stale = False
30
+ if self._future is None:
31
+ self._future = background.run_apart(self._fetch)
32
+ return self._future
33
+
34
+ def note_version(self, version: int | float | None) -> None:
35
+ with self._lock:
36
+ held = self._held()
37
+ if held is not None and version is not None and version != held["rules_version"]:
38
+ self._stale = True
39
+
40
+ def _held(self) -> Rules | None:
41
+ future = self._future
42
+ if future is None or not future.done() or future.exception() is not None:
43
+ return None
44
+ rules = future.result()
45
+ return rules if isinstance(rules, dict) else None
46
+
47
+ def _fetch(self) -> Rules | str | None:
48
+ rules = None
49
+ try:
50
+ rules = self._load()
51
+ finally:
52
+ if not isinstance(rules, dict):
53
+ with self._lock:
54
+ self._future = None
55
+ return rules
agentdevlabs/server.py ADDED
@@ -0,0 +1,446 @@
1
+ import re
2
+ import threading
3
+ import time
4
+ from collections.abc import Callable
5
+ from dataclasses import dataclass, field
6
+ from datetime import UTC, datetime
7
+ from importlib.metadata import PackageNotFoundError, version
8
+ from typing import Any, Literal
9
+
10
+ import httpx2
11
+
12
+ from . import background
13
+ from .config import MODES, Config
14
+ from .log import warn, warn_once
15
+
16
+ START_TIMEOUT_S = 2.0
17
+ UPLOAD_TIMEOUT_S = 30.0
18
+ DOWNLOAD_TIMEOUT_S = 30.0
19
+ MAX_PENDING_BYTES = 64 * 1024 * 1024
20
+ EVENTS_RETRY_DELAY_S = 0.25
21
+
22
+ # Ids go into a path of the local cache, so anything but a UUID is refused (never `../..`).
23
+ UUID = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE)
24
+
25
+
26
+ @dataclass(frozen=True)
27
+ class CaptureRef:
28
+ capture_id: str
29
+ step: int
30
+ cache_key: str
31
+ provider: str
32
+ model: str
33
+ is_stream: bool
34
+ download_url: str | None
35
+
36
+
37
+ @dataclass(frozen=True)
38
+ class Variation:
39
+ """Variations come newest first, as trace start lists them."""
40
+
41
+ trace_id: str
42
+ captures: list[CaptureRef]
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class Pin:
47
+ """The trace this developer pinned in this environment; its steps answer every call by
48
+ position."""
49
+
50
+ trace_id: str
51
+ first_cache_key: str
52
+ set_at: datetime
53
+ captures: list[CaptureRef]
54
+
55
+
56
+ @dataclass(frozen=True)
57
+ class Decision:
58
+ reachable: bool
59
+ # The server refused the token (401), which is not the same as being unreachable.
60
+ rejected: bool = False
61
+ mode: str | None = None
62
+ off_reason: str | None = None
63
+ variations: list[Variation] = field(default_factory=list)
64
+ # Base64url capture keys by capture id; the trace drops them when it ends (S8).
65
+ keys: dict[str, str] = field(default_factory=dict)
66
+ # Whether the requested group exists; None when no group was asked for.
67
+ group_exists: bool | None = None
68
+ # The version of the project's rules the server holds; None when it did not say.
69
+ rules_version: int | float | None = None
70
+ pin: Pin | None = None
71
+
72
+
73
+ UNREACHABLE = Decision(reachable=False)
74
+ REJECTED = Decision(reachable=False, rejected=True)
75
+ REJECTED_RULES = "rejected"
76
+ # An answer we cannot use (a 5xx, not JSON, or rules `parse_rules` refuses): the server is there,
77
+ # so its mode is still worth asking (S6, S10).
78
+ UNUSABLE_RULES = "unusable"
79
+
80
+ _expiry_warned = warn_once()
81
+
82
+
83
+ def _warn_before_expiry(response: httpx2.Response) -> None:
84
+ """The header crosses a trust boundary: only a value that parses as a date warns, once per
85
+ date per process."""
86
+ expires = _parse_time(response.headers.get("agent-dev-labs-token-expires-at"))
87
+ if expires is None:
88
+ return
89
+ day = expires.astimezone(UTC).strftime("%Y-%m-%d")
90
+ _expiry_warned(
91
+ f"the token expires on {day} UTC. Make a new one on the console's Access tokens page "
92
+ "before then."
93
+ )
94
+
95
+
96
+ def _is_text(value: Any) -> bool:
97
+ return isinstance(value, str)
98
+
99
+
100
+ def _is_number(value: Any) -> bool:
101
+ return isinstance(value, int | float) and not isinstance(value, bool)
102
+
103
+
104
+ def _parse_capture(raw: Any) -> CaptureRef | None:
105
+ if not isinstance(raw, dict):
106
+ return None
107
+ capture_id = raw.get("capture_id")
108
+ download_url = raw.get("download_url")
109
+ valid = (
110
+ _is_text(capture_id)
111
+ and UUID.match(capture_id)
112
+ and _is_number(raw.get("step"))
113
+ and _is_text(raw.get("cache_key"))
114
+ and _is_text(raw.get("provider"))
115
+ and _is_text(raw.get("model"))
116
+ and isinstance(raw.get("is_stream"), bool)
117
+ and _is_text(raw.get("key"))
118
+ and (_is_text(download_url) or download_url is None)
119
+ )
120
+ if not valid:
121
+ return None
122
+ return CaptureRef(
123
+ capture_id=capture_id,
124
+ step=int(raw["step"]),
125
+ cache_key=raw["cache_key"],
126
+ provider=raw["provider"],
127
+ model=raw["model"],
128
+ is_stream=raw["is_stream"],
129
+ download_url=download_url,
130
+ )
131
+
132
+
133
+ def _parse_captures(raw_captures: Any, keys: dict[str, str]) -> list[CaptureRef] | None:
134
+ """The captures of one trace, with their keys added to `keys`; None on the wrong shape."""
135
+ if not isinstance(raw_captures, list):
136
+ return None
137
+ captures = []
138
+ for raw in raw_captures:
139
+ capture = _parse_capture(raw)
140
+ if capture is None:
141
+ return None
142
+ captures.append(capture)
143
+ keys[capture.capture_id] = raw["key"]
144
+ return captures
145
+
146
+
147
+ def _parse_time(value: Any) -> datetime | None:
148
+ if not _is_text(value):
149
+ return None
150
+ try:
151
+ return datetime.fromisoformat(value.replace("Z", "+00:00"))
152
+ except ValueError:
153
+ return None
154
+
155
+
156
+ def parse_pin(raw: Any, keys: dict[str, str]) -> Pin | None:
157
+ if not isinstance(raw, dict) or not _is_text(raw.get("trace_id")):
158
+ return None
159
+ set_at = _parse_time(raw.get("set_at"))
160
+ captures = _parse_captures(raw.get("captures"), keys)
161
+ if not UUID.match(raw["trace_id"]) or not _is_text(raw.get("first_cache_key")):
162
+ return None
163
+ if set_at is None or captures is None:
164
+ return None
165
+ return Pin(raw["trace_id"], raw["first_cache_key"], set_at, captures)
166
+
167
+
168
+ def parse_decision(body: Any) -> Decision:
169
+ """The response comes from our server across a trust boundary: anything of the wrong shape
170
+ counts as unreachable."""
171
+ if not isinstance(body, dict) or body.get("mode") not in MODES:
172
+ return UNREACHABLE
173
+ traces = body.get("traces")
174
+ if not isinstance(traces, list):
175
+ return UNREACHABLE
176
+ variations: list[Variation] = []
177
+ keys: dict[str, str] = {}
178
+ for trace in traces:
179
+ if not isinstance(trace, dict) or not _is_text(trace.get("trace_id")):
180
+ return UNREACHABLE
181
+ captures = _parse_captures(trace.get("captures"), keys)
182
+ if not UUID.match(trace["trace_id"]) or captures is None:
183
+ return UNREACHABLE
184
+ variations.append(Variation(trace_id=trace["trace_id"], captures=captures))
185
+ pin = None
186
+ if body.get("pin") is not None:
187
+ pin = parse_pin(body["pin"], keys)
188
+ if pin is None:
189
+ return UNREACHABLE
190
+ off_reason = body.get("off_reason")
191
+ group_exists = body.get("group_exists")
192
+ rules_version = body.get("rules_version")
193
+ return Decision(
194
+ reachable=True,
195
+ mode=body["mode"],
196
+ off_reason=off_reason if _is_text(off_reason) else None,
197
+ variations=variations,
198
+ keys=keys,
199
+ group_exists=group_exists if isinstance(group_exists, bool) else None,
200
+ rules_version=rules_version if _is_number(rules_version) else None,
201
+ pin=pin,
202
+ )
203
+
204
+
205
+ def _all_text(value: Any) -> bool:
206
+ return isinstance(value, list) and all(_is_text(item) for item in value)
207
+
208
+
209
+ def _compiles(pattern: str) -> bool:
210
+ try:
211
+ re.compile(pattern)
212
+ except (re.error, OverflowError):
213
+ return False
214
+ return True
215
+
216
+
217
+ def parse_rules(body: Any) -> dict[str, Any] | None:
218
+ """The four lists and their version, or None when the answer is of the wrong shape or a
219
+ pattern does not compile: two machines must never hash with different rule sets."""
220
+ if not isinstance(body, dict) or not _is_number(body.get("rules_version")):
221
+ return None
222
+ lists = ("ignore", "mask", "redact_fields", "redact_patterns")
223
+ if not all(_all_text(body.get(name)) for name in lists):
224
+ return None
225
+ if not all(_compiles(pattern) for pattern in [*body["mask"], *body["redact_patterns"]]):
226
+ return None
227
+ return {**{name: body[name] for name in lists}, "rules_version": body["rules_version"]}
228
+
229
+
230
+ def sdk_header() -> str:
231
+ try:
232
+ return f"python/{version('agentdevlabs')}"
233
+ except PackageNotFoundError:
234
+ # Run from a source tree that was never installed; the SDK must still send (S10).
235
+ return "python/unknown"
236
+
237
+
238
+ SDK_HEADER = sdk_header()
239
+
240
+
241
+ def _auth_headers(config: Config) -> dict[str, str]:
242
+ """Sent on every request to our API and nowhere else: the token, and which SDK and version
243
+ sent it, as a User-Agent does. Nothing about the app or its user."""
244
+ return {"authorization": f"Bearer {config.token}", "agent-dev-labs-sdk": SDK_HEADER}
245
+
246
+
247
+ def _headers(config: Config, content_type: str) -> dict[str, str]:
248
+ return {**_auth_headers(config), "content-type": content_type}
249
+
250
+
251
+ # Our own clients, never the wrapped ones, so our own calls are never recorded.
252
+ _client = httpx2.Client()
253
+
254
+
255
+ def start_trace(config: Config, first_cache_key: str, cached: list[str]) -> Decision:
256
+ try:
257
+ response = _client.post(
258
+ f"{config.api_url}/v1/traces/start",
259
+ headers=_headers(config, "application/json"),
260
+ json={
261
+ "first_cache_key": first_cache_key,
262
+ "cached": cached,
263
+ **({"group": config.group} if config.group else {}),
264
+ },
265
+ timeout=START_TIMEOUT_S,
266
+ )
267
+ _warn_before_expiry(response)
268
+ if response.status_code == 401:
269
+ return REJECTED
270
+ if not response.is_success:
271
+ return UNREACHABLE
272
+ return parse_decision(response.json())
273
+ except (httpx2.HTTPError, ValueError):
274
+ return UNREACHABLE
275
+
276
+
277
+ def fetch_rules(config: Config) -> dict[str, Any] | str | None:
278
+ """Same budget and same fallback as trace start: None means treat the server as
279
+ unreachable, `REJECTED_RULES` that it refused the token and `UNUSABLE_RULES` that it answered
280
+ with an error or rules we cannot use."""
281
+ try:
282
+ response = _client.get(
283
+ f"{config.api_url}/v1/project-rules",
284
+ headers=_auth_headers(config),
285
+ timeout=START_TIMEOUT_S,
286
+ )
287
+ except httpx2.HTTPError:
288
+ return None
289
+ _warn_before_expiry(response)
290
+ if response.status_code == 401:
291
+ return REJECTED_RULES
292
+ if response.status_code >= 500:
293
+ return UNUSABLE_RULES
294
+ if not response.is_success:
295
+ return None
296
+ try:
297
+ return parse_rules(response.json()) or UNUSABLE_RULES
298
+ except ValueError:
299
+ return UNUSABLE_RULES
300
+
301
+
302
+ def fetch_mode(config: Config, started_at: float) -> Decision | None:
303
+ """The server's mode as trace start would resolve it, read alone because the rules failed and
304
+ trace start needs the cache key they shape. It gets only what is left of the rules fetch's
305
+ budget (`started_at` is when that fetch began, on the monotonic clock); None means the read
306
+ failed, which is an unreachable server (S10)."""
307
+ left = START_TIMEOUT_S - (time.monotonic() - started_at)
308
+ if left <= 0:
309
+ return None
310
+ try:
311
+ response = _client.get(
312
+ f"{config.api_url}/v1/mode", headers=_auth_headers(config), timeout=left
313
+ )
314
+ _warn_before_expiry(response)
315
+ body = response.json() if response.is_success else None
316
+ except (httpx2.HTTPError, ValueError):
317
+ return None
318
+ if not isinstance(body, dict) or body.get("mode") not in MODES:
319
+ return None
320
+ off_reason = body.get("off_reason")
321
+ return Decision(
322
+ reachable=True,
323
+ mode=body["mode"],
324
+ off_reason=off_reason if isinstance(off_reason, str) else None,
325
+ )
326
+
327
+
328
+ def download_object(url: str) -> bytes:
329
+ response = _client.get(url, timeout=DOWNLOAD_TIMEOUT_S)
330
+ response.raise_for_status()
331
+ return response.content
332
+
333
+
334
+ _pending_bytes = 0
335
+ _pending_lock = threading.Lock()
336
+
337
+ Outcome = Literal["stored", "retry", "dropped"]
338
+
339
+
340
+ def _error_detail(response: httpx2.Response) -> object:
341
+ """The `detail` of an error answer; None when the body is not JSON or has none."""
342
+ try:
343
+ answer = response.json()
344
+ except ValueError:
345
+ return None
346
+ return answer.get("detail") if isinstance(answer, dict) else None
347
+
348
+
349
+ _scope_warned = warn_once()
350
+ _REPLAY_ONLY_WARNING = (
351
+ "a capture was not stored: this token can only replay. "
352
+ "Unset AGENT_DEV_LABS_MODE, or use a token that can capture."
353
+ )
354
+
355
+
356
+ def _attempt_upload(config: Config, document: str) -> tuple[Outcome, str | None]:
357
+ try:
358
+ response = _client.post(
359
+ f"{config.api_url}/v1/captures",
360
+ headers=_headers(config, "application/x-ndjson"),
361
+ content=document.encode("utf-8"),
362
+ timeout=UPLOAD_TIMEOUT_S,
363
+ )
364
+ except httpx2.HTTPError:
365
+ return "retry", None
366
+ if response.is_success:
367
+ return "stored", _answered_capture_id(response)
368
+ detail = _error_detail(response) if response.status_code >= 400 else None
369
+ # A 409 `capture-exists` means the server holds this capture; any other 409 (`trace-conflict`)
370
+ # does not.
371
+ if response.status_code == 409 and detail == "capture-exists":
372
+ return "stored", None
373
+ if response.status_code >= 500:
374
+ return "retry", None
375
+ if response.status_code == 403 and detail == "token-scope-insufficient":
376
+ _scope_warned(_REPLAY_ONLY_WARNING)
377
+ else:
378
+ warn(f"a capture was not stored (the server answered {response.status_code})")
379
+ return "dropped", None
380
+
381
+
382
+ def _answered_capture_id(response: httpx2.Response) -> str | None:
383
+ try:
384
+ answer = response.json()
385
+ except ValueError:
386
+ return None
387
+ capture_id = answer.get("capture_id") if isinstance(answer, dict) else None
388
+ return capture_id if isinstance(capture_id, str) else None
389
+
390
+
391
+ def queue_upload(config: Config, document: str, on_done: Callable[[str | None], None]) -> None:
392
+ """Queues the upload on the worker, then calls `on_done` there with the id the server gave
393
+ the stored capture, or None when it gave none or stored nothing. The 64 MiB cap counts
394
+ captures from the moment they wait, since the worker sends them one at a time. The app never
395
+ waits on this (C9, F5)."""
396
+ global _pending_bytes
397
+ size = len(document.encode("utf-8"))
398
+ with _pending_lock:
399
+ if _pending_bytes + size > MAX_PENDING_BYTES:
400
+ warn("a capture was dropped: too many uploads are waiting")
401
+ on_done(None)
402
+ return
403
+ _pending_bytes += size
404
+ background.run(lambda: on_done(_upload_and_release(config, document, size)))
405
+
406
+
407
+ def _upload_and_release(config: Config, document: str, size: int) -> str | None:
408
+ global _pending_bytes
409
+ try:
410
+ return _upload(config, document)
411
+ finally:
412
+ with _pending_lock:
413
+ _pending_bytes -= size
414
+
415
+
416
+ def _upload(config: Config, document: str) -> str | None:
417
+ """One retry covers a blip; a second failure drops the capture."""
418
+ outcome, capture_id = _attempt_upload(config, document)
419
+ if outcome == "retry":
420
+ outcome, capture_id = _attempt_upload(config, document)
421
+ if outcome == "retry":
422
+ warn("a capture was dropped: the server could not be reached or kept failing")
423
+ return capture_id
424
+
425
+
426
+ def _attempt_events(config: Config, events: list[dict[str, Any]]) -> bool:
427
+ try:
428
+ response = _client.post(
429
+ f"{config.api_url}/v1/events",
430
+ headers=_headers(config, "application/json"),
431
+ json={"events": events},
432
+ timeout=UPLOAD_TIMEOUT_S,
433
+ )
434
+ except httpx2.HTTPError:
435
+ return False
436
+ return response.status_code < 500
437
+
438
+
439
+ def send_events(config: Config, events: list[dict[str, Any]]) -> None:
440
+ """One retry covers a blip; after that the batch is dropped. Events are never worth slowing
441
+ the app (OP3)."""
442
+ if _attempt_events(config, events):
443
+ return
444
+ time.sleep(EVENTS_RETRY_DELAY_S)
445
+ if not _attempt_events(config, events):
446
+ warn("call events were dropped: the server kept failing")