askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
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 | |
| 3 | The old private prototype stored event trigger state in the `events` object |
| 4 | state file. Keep that shape here so the public HTTP server, Scroll, and the |
| 5 | daemon do not grow separate event systems. |
| 6 | """ |
| 7 | |
| 8 | from __future__ import annotations |
| 9 | |
| 10 | import json |
| 11 | import re |
| 12 | import time |
| 13 | from collections.abc import Mapping |
| 14 | from datetime import datetime, timezone |
| 15 | from pathlib import Path |
| 16 | from typing import Any |
| 17 | from urllib.parse import urlparse |
| 18 | |
| 19 | import object_ids |
| 20 | import object_state |
| 21 | from object_versions import DEFAULT_DATA_DIR |
| 22 | |
| 23 | EVENTS_OBJECT_ID = "events" |
| 24 | DEFAULT_EVENT_LIMIT = 100 |
| 25 | MAX_EVENT_LIMIT = 1000 |
| 26 | DEFAULT_EVENT_KEEP_COUNT = 1000 |
| 27 | DEFAULT_EVENT_KEEP_SECONDS = 7 * 24 * 60 * 60 |
| 28 | MAX_EVENT_KEEP_COUNT = 1_000_000 |
| 29 | VALID_CALLBACK_SCHEMES = {"http", "https"} |
| 30 | VALID_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 | |
| 36 | class InvalidEventTypeError(ValueError): |
| 37 | """Raised when an event type is not safe for state keys or routing.""" |
| 38 | |
| 39 | |
| 40 | class InvalidSubscriberIdError(ValueError): |
| 41 | """Raised when a subscriber id is not safe for state keys or routing.""" |
| 42 | |
| 43 | |
| 44 | class SubscriptionNotFoundError(LookupError): |
| 45 | """Raised when an event subscription cannot be found.""" |
| 46 | |
| 47 | |
| 48 | def 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 | |
| 55 | def 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 | |
| 62 | def 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 | |
| 104 | def 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 | |
| 153 | def 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 | |
| 228 | def 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 | |
| 257 | def 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 | |
| 299 | def 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 | |
| 381 | def 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 | |
| 402 | def 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 | |
| 442 | def _state_manager(base_dir: Path | str) -> object_state.ObjectStateManager: |
| 443 | return object_state.ObjectStateManager(EVENTS_OBJECT_ID, base_dir=base_dir) |
| 444 | |
| 445 | |
| 446 | def _event_state_key(event: dict[str, Any]) -> str: |
| 447 | return f"event_{event['timestamp']}_{event['id']}" |
| 448 | |
| 449 | |
| 450 | def _subscription_state_key(event_type: str, subscriber_id: str) -> str: |
| 451 | return f"sub_{event_type}_{subscriber_id}" |
| 452 | |
| 453 | |
| 454 | def _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 | |
| 461 | def _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 | |
| 472 | def _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 | |
| 483 | def _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 | |
| 505 | def _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 | |
| 516 | def _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 | |
| 533 | def _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 | |
| 553 | def _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 | |
| 560 | def _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 | |
| 569 | def _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 | |
| 578 | def _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 | |
| 589 | def _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 | |
| 597 | def _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 | |
| 606 | def _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 | |
| 622 | def _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 | |
| 636 | def _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 | |
| 650 | def _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 | |
| 670 | def _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 | |
| 699 | def _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 | |
| 709 | def _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 | |
| 721 | def _json_dumps(value: dict[str, Any]) -> str: |
| 722 | return json.dumps(value, sort_keys=True, separators=(",", ":")) |
| 723 | |
| 724 | |
| 725 | def _clean_text(value: str, *, default: str) -> str: |
| 726 | text = str(value or "").strip() |
| 727 | return text or default |
| 728 | |
| 729 | |
| 730 | def _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 | |
| 737 | def _coerce_int(value: Any, *, default: int = 0) -> int: |
| 738 | try: |
| 739 | return int(value) |
| 740 | except (TypeError, ValueError): |
| 741 | return default |
| 742 | |
| 743 | |
| 744 | def _utc_timestamp() -> str: |
| 745 | return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z") |
| 746 | |
| 747 | |
| 748 | def _utc_timestamp_from(timestamp: int) -> str: |
| 749 | return datetime.fromtimestamp(timestamp, timezone.utc).isoformat().replace("+00:00", "Z") |