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_source_changes.py · 6.5 KB · 218 lines
| 1 | """Append-only change logs for DBBASIC object source updates. |
| 2 | |
| 3 | Source versions store recoverable source snapshots. Source changes are the |
| 4 | operator-facing activity facts behind edit, rollback, audit, and Scroll history |
| 5 | screens. |
| 6 | """ |
| 7 | |
| 8 | from __future__ import annotations |
| 9 | |
| 10 | import json |
| 11 | import threading |
| 12 | from datetime import datetime, timezone |
| 13 | from pathlib import Path |
| 14 | from typing import Any, Mapping |
| 15 | |
| 16 | import object_ids |
| 17 | from object_namespace import validate_object_id |
| 18 | from object_versions import DEFAULT_DATA_DIR, InvalidObjectIdError |
| 19 | |
| 20 | SOURCE_CHANGES_DIR = "source_changes" |
| 21 | CHANGES_FILE = "changes.jsonl" |
| 22 | DEFAULT_CHANGE_LIMIT = 100 |
| 23 | MAX_CHANGE_LIMIT = 1000 |
| 24 | VALID_ACTIONS = {"source_create", "source_update", "source_rollback"} |
| 25 | |
| 26 | _LOCKS: dict[str, threading.Lock] = {} |
| 27 | _LOCKS_GUARD = threading.Lock() |
| 28 | |
| 29 | |
| 30 | class InvalidSourceChangeError(ValueError): |
| 31 | """Raised when a source change entry is not safe to write or read.""" |
| 32 | |
| 33 | |
| 34 | def append_source_change( |
| 35 | *, |
| 36 | object_id: str, |
| 37 | action: str, |
| 38 | version_id: int, |
| 39 | from_version_id: int | None = None, |
| 40 | actor: str = "api", |
| 41 | message: str = "", |
| 42 | correlation_id: str | None = None, |
| 43 | details: Mapping[str, Any] | None = None, |
| 44 | base_dir: Path | str = DEFAULT_DATA_DIR, |
| 45 | ) -> dict[str, Any]: |
| 46 | """Append one source change and return the stored entry.""" |
| 47 | path = source_changes_file(object_id, base_dir=base_dir) |
| 48 | if action not in VALID_ACTIONS: |
| 49 | raise InvalidSourceChangeError(f"Invalid source change action: {action}") |
| 50 | |
| 51 | clean_version_id = _positive_int(version_id, field="version_id") |
| 52 | clean_from_version_id = ( |
| 53 | _positive_int(from_version_id, field="from_version_id") |
| 54 | if from_version_id is not None |
| 55 | else None |
| 56 | ) |
| 57 | |
| 58 | timestamp = _utc_timestamp() |
| 59 | entry = { |
| 60 | "change_id": _change_id(timestamp, object_id, action), |
| 61 | "timestamp": timestamp, |
| 62 | "object_id": object_id, |
| 63 | "action": action, |
| 64 | "version_id": clean_version_id, |
| 65 | "from_version_id": clean_from_version_id, |
| 66 | "actor": _clean_text(actor, default="api"), |
| 67 | "message": _clean_text(message, default=_default_message(action)), |
| 68 | "correlation_id": _clean_optional_text(correlation_id), |
| 69 | "details": _normalize_details(details), |
| 70 | } |
| 71 | |
| 72 | with _file_lock(path): |
| 73 | path.parent.mkdir(parents=True, exist_ok=True) |
| 74 | with path.open("a", encoding="utf-8") as handle: |
| 75 | handle.write(json.dumps(entry, sort_keys=True, separators=(",", ":"))) |
| 76 | handle.write("\n") |
| 77 | |
| 78 | return entry |
| 79 | |
| 80 | |
| 81 | def list_source_changes( |
| 82 | object_id: str, |
| 83 | *, |
| 84 | base_dir: Path | str = DEFAULT_DATA_DIR, |
| 85 | limit: int = DEFAULT_CHANGE_LIMIT, |
| 86 | offset: int = 0, |
| 87 | ) -> dict[str, Any]: |
| 88 | """Return newest-first source changes for one object.""" |
| 89 | path = source_changes_file(object_id, base_dir=base_dir) |
| 90 | _validate_page(limit=limit, offset=offset) |
| 91 | |
| 92 | changes = _read_changes(path) |
| 93 | total = len(changes) |
| 94 | window = changes[offset:offset + limit] |
| 95 | return { |
| 96 | "object_id": object_id, |
| 97 | "changes": window, |
| 98 | "count": len(window), |
| 99 | "total": total, |
| 100 | "limit": limit, |
| 101 | "offset": offset, |
| 102 | "has_more": offset + len(window) < total, |
| 103 | } |
| 104 | |
| 105 | |
| 106 | def source_changes_file(object_id: str, base_dir: Path | str = DEFAULT_DATA_DIR) -> Path: |
| 107 | """Return the validated JSONL source change-log path.""" |
| 108 | if not validate_object_id(object_id): |
| 109 | raise InvalidObjectIdError(f"Invalid object ID: {object_id}") |
| 110 | |
| 111 | root = Path(base_dir) / SOURCE_CHANGES_DIR |
| 112 | path = root / object_id / CHANGES_FILE |
| 113 | resolved_root = root.resolve(strict=False) |
| 114 | resolved_path = path.resolve(strict=False) |
| 115 | |
| 116 | try: |
| 117 | resolved_path.relative_to(resolved_root) |
| 118 | except ValueError as exc: |
| 119 | raise InvalidObjectIdError( |
| 120 | f"Source change path escapes change directory: {object_id}" |
| 121 | ) from exc |
| 122 | |
| 123 | return path |
| 124 | |
| 125 | |
| 126 | def _read_changes(path: Path) -> list[dict[str, Any]]: |
| 127 | if not path.exists(): |
| 128 | return [] |
| 129 | |
| 130 | changes: list[dict[str, Any]] = [] |
| 131 | with _file_lock(path): |
| 132 | for line in path.read_text(encoding="utf-8").splitlines(): |
| 133 | if not line.strip(): |
| 134 | continue |
| 135 | try: |
| 136 | entry = json.loads(line) |
| 137 | except json.JSONDecodeError: |
| 138 | continue |
| 139 | if isinstance(entry, dict): |
| 140 | changes.append(entry) |
| 141 | |
| 142 | changes.reverse() |
| 143 | return changes |
| 144 | |
| 145 | |
| 146 | def _normalize_details(details: Mapping[str, Any] | None) -> dict[str, Any]: |
| 147 | if details is None: |
| 148 | return {} |
| 149 | if not isinstance(details, Mapping): |
| 150 | raise InvalidSourceChangeError("Source change details must be an object") |
| 151 | return {str(key): _json_safe_value(value) for key, value in details.items()} |
| 152 | |
| 153 | |
| 154 | def _json_safe_value(value: Any) -> Any: |
| 155 | if value is None or isinstance(value, str | int | float | bool): |
| 156 | return value |
| 157 | if isinstance(value, Mapping): |
| 158 | return {str(key): _json_safe_value(item) for key, item in value.items()} |
| 159 | if isinstance(value, list | tuple): |
| 160 | return [_json_safe_value(item) for item in value] |
| 161 | return str(value) |
| 162 | |
| 163 | |
| 164 | def _validate_page(*, limit: int, offset: int) -> None: |
| 165 | if limit < 1: |
| 166 | raise ValueError("limit must be at least 1") |
| 167 | if limit > MAX_CHANGE_LIMIT: |
| 168 | raise ValueError(f"limit must be at most {MAX_CHANGE_LIMIT}") |
| 169 | if offset < 0: |
| 170 | raise ValueError("offset must be at least 0") |
| 171 | |
| 172 | |
| 173 | def _positive_int(value: int, *, field: str) -> int: |
| 174 | try: |
| 175 | parsed = int(value) |
| 176 | except (TypeError, ValueError) as exc: |
| 177 | raise InvalidSourceChangeError(f"{field} must be an integer") from exc |
| 178 | if parsed < 1: |
| 179 | raise InvalidSourceChangeError(f"{field} must be at least 1") |
| 180 | return parsed |
| 181 | |
| 182 | |
| 183 | def _clean_optional_text(value: str | None) -> str | None: |
| 184 | if value is None: |
| 185 | return None |
| 186 | text = str(value).strip() |
| 187 | return text or None |
| 188 | |
| 189 | |
| 190 | def _clean_text(value: str, *, default: str) -> str: |
| 191 | text = str(value).strip() |
| 192 | return text or default |
| 193 | |
| 194 | |
| 195 | def _default_message(action: str) -> str: |
| 196 | return { |
| 197 | "source_create": "Created object source", |
| 198 | "source_update": "Updated object source", |
| 199 | "source_rollback": "Rolled back object source", |
| 200 | }[action] |
| 201 | |
| 202 | |
| 203 | def _change_id(timestamp: str, object_id: str, action: str) -> str: |
| 204 | return object_ids.new_uuid4() |
| 205 | |
| 206 | |
| 207 | def _utc_timestamp() -> str: |
| 208 | return datetime.now(timezone.utc).isoformat() |
| 209 | |
| 210 | |
| 211 | def _file_lock(path: Path) -> threading.Lock: |
| 212 | key = str(path.resolve(strict=False)) |
| 213 | with _LOCKS_GUARD: |
| 214 | lock = _LOCKS.get(key) |
| 215 | if lock is None: |
| 216 | lock = threading.Lock() |
| 217 | _LOCKS[key] = lock |
| 218 | return lock |