Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/object_events.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
object_events.py · 24.8 KB · 749 lines
1"""Daemon-compatible event and subscription state.
2
3The old private prototype stored event trigger state in the `events` object
4state file. Keep that shape here so the public HTTP server, Scroll, and the
5daemon do not grow separate event systems.
6"""
7
8from __future__ import annotations
9
10import json
11import re
12import time
13from collections.abc import Mapping
14from datetime import datetime, timezone
15from pathlib import Path
16from typing import Any
17from urllib.parse import urlparse
18
19import object_ids
20import object_state
21from object_versions import DEFAULT_DATA_DIR
22
23EVENTS_OBJECT_ID = "events"
24DEFAULT_EVENT_LIMIT = 100
25MAX_EVENT_LIMIT = 1000
26DEFAULT_EVENT_KEEP_COUNT = 1000
27DEFAULT_EVENT_KEEP_SECONDS = 7 * 24 * 60 * 60
28MAX_EVENT_KEEP_COUNT = 1_000_000
29VALID_CALLBACK_SCHEMES = {"http", "https"}
30VALID_DELIVERY_STATUSES = {"idle", "ok", "failed"}
31
32_EVENT_TYPE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$")
33_SUBSCRIBER_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$")
34
35
36class InvalidEventTypeError(ValueError):
37 """Raised when an event type is not safe for state keys or routing."""
38
39
40class InvalidSubscriberIdError(ValueError):
41 """Raised when a subscriber id is not safe for state keys or routing."""
42
43
44class SubscriptionNotFoundError(LookupError):
45 """Raised when an event subscription cannot be found."""
46
47
48def validate_event_type(event_type: str) -> bool:
49 """Return True when an event type is route and state-key safe."""
50 if not isinstance(event_type, str):
51 return False
52 return bool(_EVENT_TYPE_RE.fullmatch(event_type))
53
54
55def validate_subscriber_id(subscriber_id: str) -> bool:
56 """Return True when a subscriber id is route and state-key safe."""
57 if not isinstance(subscriber_id, str):
58 return False
59 return bool(_SUBSCRIBER_ID_RE.fullmatch(subscriber_id))
60
61
62def publish_event(
63 event_type: str,
64 *,
65 payload: Any | None = None,
66 source: str = "api",
67 actor: str = "api",
68 base_dir: Path | str = DEFAULT_DATA_DIR,
69 keep_count: int | None = None,
70 keep_seconds: int | None = None,
71) -> dict[str, Any]:
72 """Publish one event into daemon-compatible trigger state."""
73 clean_event_type = _clean_event_type(event_type)
74 clean_keep_count = _clean_keep_count(keep_count)
75 clean_keep_seconds = _clean_keep_seconds(keep_seconds)
76 timestamp = int(time.time())
77 event = {
78 "id": object_ids.new_uuid4(),
79 "event_type": clean_event_type,
80 "payload": _json_safe_value({} if payload is None else payload),
81 "source": _clean_text(source, default="api"),
82 "actor": _clean_text(actor, default="api"),
83 "timestamp": timestamp,
84 "created_at": _utc_timestamp(),
85 }
86
87 manager = _state_manager(base_dir)
88 manager.set(_event_state_key(event), _json_dumps(event))
89 if _should_prune_after_publish(
90 manager.get_all(),
91 keep_count=clean_keep_count,
92 keep_seconds=clean_keep_seconds,
93 now=timestamp,
94 ):
95 prune_events(
96 base_dir=base_dir,
97 keep_count=clean_keep_count,
98 keep_seconds=clean_keep_seconds,
99 now=timestamp,
100 )
101 return event
102
103
104def list_events(
105 *,
106 event_type: str | None = None,
107 since: int | None = None,
108 base_dir: Path | str = DEFAULT_DATA_DIR,
109 limit: int = DEFAULT_EVENT_LIMIT,
110 offset: int = 0,
111) -> dict[str, Any]:
112 """Return newest-first events from daemon-compatible trigger state."""
113 if event_type is not None:
114 event_type = _clean_event_type(event_type)
115 if since is not None and since < 0:
116 raise ValueError("since must be at least 0")
117 _validate_page(limit=limit, offset=offset)
118
119 events = []
120 for key, value in _state_manager(base_dir).get_all().items():
121 if not key.startswith("event_"):
122 continue
123 event = _load_json_object(value)
124 if event is None:
125 continue
126 if event_type is not None and event.get("event_type") != event_type:
127 continue
128 if since is not None and _coerce_int(event.get("timestamp")) < since:
129 continue
130 events.append(event)
131
132 events.sort(
133 key=lambda item: (_coerce_int(item.get("timestamp")), str(item.get("id", ""))),
134 reverse=True,
135 )
136 total = len(events)
137 window = events[offset:offset + limit]
138 payload: dict[str, Any] = {
139 "events": window,
140 "count": len(window),
141 "total": total,
142 "limit": limit,
143 "offset": offset,
144 "has_more": offset + len(window) < total,
145 }
146 if event_type is not None:
147 payload["event_type"] = event_type
148 if since is not None:
149 payload["since"] = since
150 return payload
151
152
153def prune_events(
154 *,
155 base_dir: Path | str = DEFAULT_DATA_DIR,
156 keep_count: int | None = DEFAULT_EVENT_KEEP_COUNT,
157 keep_seconds: int | None = DEFAULT_EVENT_KEEP_SECONDS,
158 now: int | None = None,
159) -> dict[str, Any]:
160 """Prune old event queue rows while preserving subscriptions.
161
162 Events are a delivery queue. Durable audit history lives in record change
163 logs, source versions, and object logs, so this helper removes old event
164 rows before the shared events state file grows without bound.
165 """
166 clean_keep_count = _clean_keep_count(keep_count)
167 clean_keep_seconds = _clean_keep_seconds(keep_seconds)
168 current_time = int(time.time() if now is None else now)
169
170 manager = _state_manager(base_dir)
171 state = manager.get_all()
172 protected_ids = _subscription_last_event_ids(state)
173 events: list[tuple[str, dict[str, Any], int, bool]] = []
174 event_keys: set[str] = set()
175 keys_to_delete: set[str] = set()
176 corrupt_deleted = 0
177
178 for key, value in state.items():
179 if not key.startswith("event_"):
180 continue
181 event_keys.add(key)
182 event = _load_json_object(value)
183 if event is None:
184 keys_to_delete.add(key)
185 corrupt_deleted += 1
186 continue
187
188 event_id = str(event.get("id", ""))
189 events.append(
190 (
191 key,
192 event,
193 _coerce_int(event.get("timestamp")),
194 event_id in protected_ids,
195 )
196 )
197
198 if clean_keep_seconds is not None:
199 cutoff = current_time - clean_keep_seconds
200 for key, _event, timestamp, protected in events:
201 if not protected and timestamp < cutoff:
202 keys_to_delete.add(key)
203
204 remaining = [row for row in events if row[0] not in keys_to_delete]
205 if clean_keep_count is not None:
206 unprotected = [row for row in remaining if not row[3]]
207 unprotected.sort(
208 key=lambda row: (_coerce_int(row[1].get("timestamp")), str(row[1].get("id", ""))),
209 reverse=True,
210 )
211 for key, _event, _timestamp, _protected in unprotected[clean_keep_count:]:
212 keys_to_delete.add(key)
213
214 deleted = manager.delete_many(sorted(keys_to_delete)) if keys_to_delete else 0
215 valid_deleted = len(keys_to_delete.intersection(event_keys)) - corrupt_deleted
216
217 return {
218 "deleted": deleted,
219 "kept": len(events) - valid_deleted,
220 "scanned": len(event_keys),
221 "protected": sum(1 for _key, _event, _timestamp, protected in events if protected),
222 "corrupt_deleted": corrupt_deleted,
223 "keep_count": clean_keep_count,
224 "keep_seconds": clean_keep_seconds,
225 }
226
227
228def subscribe_event(
229 event_type: str,
230 *,
231 subscriber_id: str | None = None,
232 callback_url: str = "",
233 actor: str = "api",
234 base_dir: Path | str = DEFAULT_DATA_DIR,
235) -> dict[str, Any]:
236 """Create or replace one daemon-compatible event subscription."""
237 clean_event_type = _clean_event_type(event_type)
238 clean_subscriber_id = _clean_subscriber_id(subscriber_id or object_ids.new_uuid4())
239 clean_callback_url = _clean_callback_url(callback_url)
240 timestamp = int(time.time())
241 subscription = {
242 "id": clean_subscriber_id,
243 "event_type": clean_event_type,
244 "callback_url": clean_callback_url,
245 "created_at": timestamp,
246 "created_at_iso": _utc_timestamp(),
247 "created_by": _clean_text(actor, default="api"),
248 "last_event_id": None,
249 "delivery": _delivery_defaults(),
250 }
251
252 manager = _state_manager(base_dir)
253 manager.set(_subscription_state_key(clean_event_type, clean_subscriber_id), _json_dumps(subscription))
254 return subscription
255
256
257def list_subscriptions(
258 *,
259 event_type: str | None = None,
260 base_dir: Path | str = DEFAULT_DATA_DIR,
261 limit: int = DEFAULT_EVENT_LIMIT,
262 offset: int = 0,
263) -> dict[str, Any]:
264 """Return newest-first event subscriptions."""
265 if event_type is not None:
266 event_type = _clean_event_type(event_type)
267 _validate_page(limit=limit, offset=offset)
268
269 subscriptions = []
270 for key, value in _state_manager(base_dir).get_all().items():
271 if not key.startswith("sub_"):
272 continue
273 subscription = _load_json_object(value)
274 if subscription is None:
275 continue
276 if event_type is not None and subscription.get("event_type") != event_type:
277 continue
278 subscriptions.append(_subscription_with_defaults(subscription))
279
280 subscriptions.sort(
281 key=lambda item: (_coerce_int(item.get("created_at")), str(item.get("id", ""))),
282 reverse=True,
283 )
284 total = len(subscriptions)
285 window = subscriptions[offset:offset + limit]
286 payload: dict[str, Any] = {
287 "subscriptions": window,
288 "count": len(window),
289 "total": total,
290 "limit": limit,
291 "offset": offset,
292 "has_more": offset + len(window) < total,
293 }
294 if event_type is not None:
295 payload["event_type"] = event_type
296 return payload
297
298
299def list_event_deliveries(
300 *,
301 event_type: str | None = None,
302 delivery_status: str | None = None,
303 pending: bool | None = None,
304 include_callback_url: bool = False,
305 include_events: bool = False,
306 event_limit: int = 10,
307 base_dir: Path | str = DEFAULT_DATA_DIR,
308 limit: int = DEFAULT_EVENT_LIMIT,
309 offset: int = 0,
310) -> dict[str, Any]:
311 """Return per-subscription delivery state for operator dashboards."""
312 if event_type is not None:
313 event_type = _clean_event_type(event_type)
314 if delivery_status is not None:
315 delivery_status = _clean_delivery_status(delivery_status)
316 _validate_page(limit=limit, offset=offset)
317 clean_event_limit = _clean_event_limit(event_limit)
318
319 state = _state_manager(base_dir).get_all()
320 events = _event_rows(state)
321 subscriptions = _subscription_rows(state)
322 deliveries = []
323
324 for subscription in subscriptions:
325 if event_type is not None and subscription.get("event_type") != event_type:
326 continue
327
328 delivery = _delivery_with_defaults(subscription.get("delivery"))
329 if delivery_status is not None and delivery.get("status") != delivery_status:
330 continue
331
332 matching_events = _matching_events_after_cursor(subscription, events)
333 is_pending = bool(matching_events)
334 if pending is not None and is_pending != pending:
335 continue
336
337 row: dict[str, Any] = {
338 "id": subscription.get("id"),
339 "subscriber_id": subscription.get("id"),
340 "event_type": subscription.get("event_type"),
341 "created_at": subscription.get("created_at"),
342 "created_at_iso": subscription.get("created_at_iso"),
343 "created_by": subscription.get("created_by"),
344 "last_event_id": subscription.get("last_event_id"),
345 "callback_url_present": bool(subscription.get("callback_url")),
346 "pending": is_pending,
347 "pending_count": len(matching_events),
348 "next_pending_event": _event_summary(matching_events[0]) if matching_events else None,
349 "latest_pending_event": _event_summary(matching_events[-1]) if matching_events else None,
350 "delivery": delivery,
351 }
352 if include_callback_url:
353 row["callback_url"] = subscription.get("callback_url", "")
354 if include_events:
355 row["pending_events"] = [
356 _event_summary(event) for event in matching_events[:clean_event_limit]
357 ]
358 row["pending_event_limit"] = clean_event_limit
359 deliveries.append(row)
360
361 deliveries.sort(key=_delivery_sort_key, reverse=True)
362 total = len(deliveries)
363 window = deliveries[offset:offset + limit]
364 payload: dict[str, Any] = {
365 "deliveries": window,
366 "count": len(window),
367 "total": total,
368 "limit": limit,
369 "offset": offset,
370 "has_more": offset + len(window) < total,
371 }
372 if event_type is not None:
373 payload["event_type"] = event_type
374 if delivery_status is not None:
375 payload["delivery_status"] = delivery_status
376 if pending is not None:
377 payload["pending"] = pending
378 return payload
379
380
381def delete_subscription(
382 event_type: str,
383 subscriber_id: str,
384 *,
385 base_dir: Path | str = DEFAULT_DATA_DIR,
386) -> dict[str, Any]:
387 """Delete one event subscription and return the removed subscription."""
388 clean_event_type = _clean_event_type(event_type)
389 clean_subscriber_id = _clean_subscriber_id(subscriber_id)
390 key = _subscription_state_key(clean_event_type, clean_subscriber_id)
391 manager = _state_manager(base_dir)
392 current = _load_json_object(manager.get(key))
393 if current is None:
394 raise SubscriptionNotFoundError(
395 f"Subscription not found: {clean_event_type}/{clean_subscriber_id}"
396 )
397
398 manager.delete(key)
399 return _subscription_with_defaults(current)
400
401
402def record_subscription_delivery(
403 subscription: Mapping[str, Any],
404 event: Mapping[str, Any],
405 *,
406 success: bool,
407 status_code: int | None = None,
408 error: str | None = None,
409 now: int | None = None,
410) -> dict[str, Any]:
411 """Return subscription state updated with one callback delivery attempt."""
412 timestamp = int(time.time() if now is None else now)
413 event_id = str(event.get("id", "") or "")
414 updated = _subscription_with_defaults(subscription)
415 delivery = _delivery_with_defaults(updated.get("delivery"))
416 delivery["attempts"] = _coerce_int(delivery.get("attempts")) + 1
417 delivery["last_attempted_event_id"] = event_id or None
418 delivery["last_attempt_at"] = timestamp
419 delivery["last_attempt_at_iso"] = _utc_timestamp_from(timestamp)
420 delivery["last_status_code"] = status_code
421
422 if success:
423 delivery["status"] = "ok"
424 delivery["successes"] = _coerce_int(delivery.get("successes")) + 1
425 delivery["last_success_event_id"] = event_id or None
426 delivery["last_success_at"] = timestamp
427 delivery["last_success_at_iso"] = _utc_timestamp_from(timestamp)
428 delivery["last_error"] = None
429 updated["last_event_id"] = event_id or updated.get("last_event_id")
430 else:
431 delivery["status"] = "failed"
432 delivery["failures"] = _coerce_int(delivery.get("failures")) + 1
433 delivery["last_failure_event_id"] = event_id or None
434 delivery["last_failure_at"] = timestamp
435 delivery["last_failure_at_iso"] = _utc_timestamp_from(timestamp)
436 delivery["last_error"] = _clean_error(error)
437
438 updated["delivery"] = delivery
439 return updated
440
441
442def _state_manager(base_dir: Path | str) -> object_state.ObjectStateManager:
443 return object_state.ObjectStateManager(EVENTS_OBJECT_ID, base_dir=base_dir)
444
445
446def _event_state_key(event: dict[str, Any]) -> str:
447 return f"event_{event['timestamp']}_{event['id']}"
448
449
450def _subscription_state_key(event_type: str, subscriber_id: str) -> str:
451 return f"sub_{event_type}_{subscriber_id}"
452
453
454def _subscription_with_defaults(subscription: Mapping[str, Any]) -> dict[str, Any]:
455 updated = dict(subscription)
456 updated.setdefault("last_event_id", None)
457 updated["delivery"] = _delivery_with_defaults(updated.get("delivery"))
458 return updated
459
460
461def _event_rows(state: Mapping[str, Any]) -> list[dict[str, Any]]:
462 events = []
463 for key, value in state.items():
464 if not str(key).startswith("event_"):
465 continue
466 event = _load_json_object(value)
467 if event is not None:
468 events.append(event)
469 return events
470
471
472def _subscription_rows(state: Mapping[str, Any]) -> list[dict[str, Any]]:
473 subscriptions = []
474 for key, value in state.items():
475 if not str(key).startswith("sub_"):
476 continue
477 subscription = _load_json_object(value)
478 if subscription is not None:
479 subscriptions.append(_subscription_with_defaults(subscription))
480 return subscriptions
481
482
483def _matching_events_after_cursor(
484 subscription: Mapping[str, Any],
485 events: list[dict[str, Any]],
486) -> list[dict[str, Any]]:
487 event_type = subscription.get("event_type")
488 matching = [event for event in events if event.get("event_type") == event_type]
489 matching.sort(
490 key=lambda item: (_coerce_int(item.get("timestamp")), str(item.get("id", "")))
491 )
492 if not matching:
493 return []
494
495 last_event_id = subscription.get("last_event_id")
496 if not last_event_id:
497 return matching
498
499 for index, event in enumerate(matching):
500 if event.get("id") == last_event_id:
501 return matching[index + 1:]
502 return matching
503
504
505def _event_summary(event: Mapping[str, Any]) -> dict[str, Any]:
506 return {
507 "id": event.get("id"),
508 "event_type": event.get("event_type"),
509 "source": event.get("source"),
510 "actor": event.get("actor"),
511 "timestamp": _coerce_int(event.get("timestamp")),
512 "created_at": event.get("created_at"),
513 }
514
515
516def _delivery_sort_key(row: Mapping[str, Any]) -> tuple[int, int, int, int, str]:
517 delivery = row.get("delivery")
518 status = "unknown"
519 last_attempt = 0
520 if isinstance(delivery, Mapping):
521 status = str(delivery.get("status") or "unknown")
522 last_attempt = _coerce_int(delivery.get("last_attempt_at"))
523 status_rank = {"failed": 3, "idle": 2, "ok": 1}.get(status, 0)
524 return (
525 status_rank,
526 _coerce_int(row.get("pending_count")),
527 last_attempt,
528 _coerce_int(row.get("created_at")),
529 str(row.get("id") or ""),
530 )
531
532
533def _delivery_defaults() -> dict[str, Any]:
534 return {
535 "status": "idle",
536 "attempts": 0,
537 "successes": 0,
538 "failures": 0,
539 "last_attempted_event_id": None,
540 "last_attempt_at": None,
541 "last_attempt_at_iso": None,
542 "last_success_event_id": None,
543 "last_success_at": None,
544 "last_success_at_iso": None,
545 "last_failure_event_id": None,
546 "last_failure_at": None,
547 "last_failure_at_iso": None,
548 "last_status_code": None,
549 "last_error": None,
550 }
551
552
553def _delivery_with_defaults(value: Any) -> dict[str, Any]:
554 delivery = _delivery_defaults()
555 if isinstance(value, Mapping):
556 delivery.update(dict(value))
557 return delivery
558
559
560def _clean_event_type(event_type: str) -> str:
561 if not isinstance(event_type, str):
562 raise InvalidEventTypeError(f"Invalid event type: {event_type}")
563 clean = event_type.strip()
564 if not validate_event_type(clean):
565 raise InvalidEventTypeError(f"Invalid event type: {event_type}")
566 return clean
567
568
569def _clean_subscriber_id(subscriber_id: str) -> str:
570 if not isinstance(subscriber_id, str):
571 raise InvalidSubscriberIdError(f"Invalid subscriber id: {subscriber_id}")
572 clean = subscriber_id.strip()
573 if not validate_subscriber_id(clean):
574 raise InvalidSubscriberIdError(f"Invalid subscriber id: {subscriber_id}")
575 return clean
576
577
578def _clean_callback_url(callback_url: str) -> str:
579 clean = str(callback_url or "").strip()
580 if not clean:
581 return ""
582
583 parsed = urlparse(clean)
584 if parsed.scheme not in VALID_CALLBACK_SCHEMES or not parsed.netloc:
585 raise ValueError("callback_url must be an absolute http or https URL")
586 return clean
587
588
589def _clean_delivery_status(delivery_status: str) -> str:
590 clean = str(delivery_status or "").strip().lower()
591 if clean not in VALID_DELIVERY_STATUSES:
592 allowed = ", ".join(sorted(VALID_DELIVERY_STATUSES))
593 raise ValueError(f"delivery_status must be one of: {allowed}")
594 return clean
595
596
597def _validate_page(*, limit: int, offset: int) -> None:
598 if limit < 1:
599 raise ValueError("limit must be at least 1")
600 if limit > MAX_EVENT_LIMIT:
601 raise ValueError(f"limit must be at most {MAX_EVENT_LIMIT}")
602 if offset < 0:
603 raise ValueError("offset must be at least 0")
604
605
606def _clean_keep_count(value: int | None) -> int | None:
607 if value is None:
608 return None
609 if isinstance(value, bool):
610 raise ValueError("keep_count must be an integer")
611 try:
612 count = int(value)
613 except (TypeError, ValueError) as exc:
614 raise ValueError("keep_count must be an integer") from exc
615 if count < 0:
616 raise ValueError("keep_count must be at least 0")
617 if count > MAX_EVENT_KEEP_COUNT:
618 raise ValueError(f"keep_count must be at most {MAX_EVENT_KEEP_COUNT}")
619 return count or None
620
621
622def _clean_keep_seconds(value: int | None) -> int | None:
623 if value is None:
624 return None
625 if isinstance(value, bool):
626 raise ValueError("keep_seconds must be an integer")
627 try:
628 seconds = int(value)
629 except (TypeError, ValueError) as exc:
630 raise ValueError("keep_seconds must be an integer") from exc
631 if seconds < 0:
632 raise ValueError("keep_seconds must be at least 0")
633 return seconds or None
634
635
636def _clean_event_limit(value: int) -> int:
637 if isinstance(value, bool):
638 raise ValueError("event_limit must be an integer")
639 try:
640 limit = int(value)
641 except (TypeError, ValueError) as exc:
642 raise ValueError("event_limit must be an integer") from exc
643 if limit < 0:
644 raise ValueError("event_limit must be at least 0")
645 if limit > MAX_EVENT_LIMIT:
646 raise ValueError(f"event_limit must be at most {MAX_EVENT_LIMIT}")
647 return limit
648
649
650def _subscription_last_event_ids(state: dict[str, Any]) -> set[str]:
651 protected: set[str] = set()
652 for key, value in state.items():
653 if not key.startswith("sub_"):
654 continue
655 subscription = _load_json_object(value)
656 if subscription is None:
657 continue
658 last_event_id = subscription.get("last_event_id")
659 if isinstance(last_event_id, str) and last_event_id:
660 protected.add(last_event_id)
661 delivery = subscription.get("delivery")
662 if isinstance(delivery, Mapping) and delivery.get("status") == "failed":
663 for field in ("last_attempted_event_id", "last_failure_event_id"):
664 event_id = delivery.get(field)
665 if isinstance(event_id, str) and event_id:
666 protected.add(event_id)
667 return protected
668
669
670def _should_prune_after_publish(
671 state: dict[str, Any],
672 *,
673 keep_count: int | None,
674 keep_seconds: int | None,
675 now: int,
676) -> bool:
677 if keep_count is None and keep_seconds is None:
678 return False
679
680 protected_ids = _subscription_last_event_ids(state)
681 cutoff = None if keep_seconds is None else now - keep_seconds
682 unprotected_count = 0
683 for key, value in state.items():
684 if not key.startswith("event_"):
685 continue
686 event = _load_json_object(value)
687 if event is None:
688 return True
689 event_id = str(event.get("id", ""))
690 if event_id in protected_ids:
691 continue
692 unprotected_count += 1
693 if cutoff is not None and _coerce_int(event.get("timestamp")) < cutoff:
694 return True
695
696 return keep_count is not None and unprotected_count > keep_count
697
698
699def _json_safe_value(value: Any) -> Any:
700 if value is None or isinstance(value, str | int | float | bool):
701 return value
702 if isinstance(value, list):
703 return [_json_safe_value(item) for item in value]
704 if isinstance(value, dict):
705 return {str(key): _json_safe_value(item) for key, item in value.items()}
706 return str(value)
707
708
709def _load_json_object(value: Any) -> dict[str, Any] | None:
710 if not isinstance(value, str):
711 return None
712 try:
713 payload = json.loads(value)
714 except json.JSONDecodeError:
715 return None
716 if not isinstance(payload, dict):
717 return None
718 return payload
719
720
721def _json_dumps(value: dict[str, Any]) -> str:
722 return json.dumps(value, sort_keys=True, separators=(",", ":"))
723
724
725def _clean_text(value: str, *, default: str) -> str:
726 text = str(value or "").strip()
727 return text or default
728
729
730def _clean_error(value: str | None) -> str | None:
731 text = str(value or "").strip()
732 if not text:
733 return None
734 return text[:500]
735
736
737def _coerce_int(value: Any, *, default: int = 0) -> int:
738 try:
739 return int(value)
740 except (TypeError, ValueError):
741 return default
742
743
744def _utc_timestamp() -> str:
745 return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
746
747
748def _utc_timestamp_from(timestamp: int) -> str:
749 return datetime.fromtimestamp(timestamp, timezone.utc).isoformat().replace("+00:00", "Z")