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_file_changes.py · 7.1 KB · 229 lines
| 1 | """Append-only change logs for object-owned files. |
| 2 | |
| 3 | Object logs are useful while debugging one object. File changes are the durable |
| 4 | operator facts behind upload, overwrite, delete, 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 | FILE_CHANGES_DIR = "file_changes" |
| 21 | CHANGES_FILE = "changes.jsonl" |
| 22 | DEFAULT_CHANGE_LIMIT = 100 |
| 23 | MAX_CHANGE_LIMIT = 1000 |
| 24 | VALID_ACTIONS = {"file_create", "file_update", "file_delete"} |
| 25 | |
| 26 | _LOCKS: dict[str, threading.Lock] = {} |
| 27 | _LOCKS_GUARD = threading.Lock() |
| 28 | |
| 29 | |
| 30 | class InvalidFileChangeError(ValueError): |
| 31 | """Raised when a file change entry is not safe to write or read.""" |
| 32 | |
| 33 | |
| 34 | def append_file_change( |
| 35 | *, |
| 36 | object_id: str, |
| 37 | action: str, |
| 38 | file_name: str, |
| 39 | file_size: 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 object-file change and return the stored entry.""" |
| 47 | path = file_changes_file(object_id, base_dir=base_dir) |
| 48 | if action not in VALID_ACTIONS: |
| 49 | raise InvalidFileChangeError(f"Invalid file change action: {action}") |
| 50 | |
| 51 | clean_file_name = _clean_filename(file_name) |
| 52 | clean_file_size = _optional_non_negative_int(file_size, field="file_size") |
| 53 | timestamp = _utc_timestamp() |
| 54 | entry = { |
| 55 | "change_id": object_ids.new_uuid4(), |
| 56 | "timestamp": timestamp, |
| 57 | "object_id": object_id, |
| 58 | "action": action, |
| 59 | "file_name": clean_file_name, |
| 60 | "file_size": clean_file_size, |
| 61 | "actor": _clean_text(actor, default="api"), |
| 62 | "message": _clean_text(message, default=_default_message(action)), |
| 63 | "correlation_id": _clean_optional_text(correlation_id), |
| 64 | "details": _normalize_details(details), |
| 65 | } |
| 66 | |
| 67 | with _file_lock(path): |
| 68 | path.parent.mkdir(parents=True, exist_ok=True) |
| 69 | with path.open("a", encoding="utf-8") as handle: |
| 70 | handle.write(json.dumps(entry, sort_keys=True, separators=(",", ":"))) |
| 71 | handle.write("\n") |
| 72 | |
| 73 | return entry |
| 74 | |
| 75 | |
| 76 | def list_file_changes( |
| 77 | object_id: str, |
| 78 | *, |
| 79 | file_name: str | None = None, |
| 80 | base_dir: Path | str = DEFAULT_DATA_DIR, |
| 81 | limit: int = DEFAULT_CHANGE_LIMIT, |
| 82 | offset: int = 0, |
| 83 | ) -> dict[str, Any]: |
| 84 | """Return newest-first file changes for one object or file.""" |
| 85 | path = file_changes_file(object_id, base_dir=base_dir) |
| 86 | clean_file_name = _clean_filename(file_name) if file_name is not None else None |
| 87 | _validate_page(limit=limit, offset=offset) |
| 88 | |
| 89 | changes = _read_changes(path, file_name=clean_file_name) |
| 90 | total = len(changes) |
| 91 | window = changes[offset:offset + limit] |
| 92 | payload: dict[str, Any] = { |
| 93 | "object_id": object_id, |
| 94 | "changes": window, |
| 95 | "count": len(window), |
| 96 | "total": total, |
| 97 | "limit": limit, |
| 98 | "offset": offset, |
| 99 | "has_more": offset + len(window) < total, |
| 100 | } |
| 101 | if clean_file_name is not None: |
| 102 | payload["file_name"] = clean_file_name |
| 103 | return payload |
| 104 | |
| 105 | |
| 106 | def file_changes_file(object_id: str, base_dir: Path | str = DEFAULT_DATA_DIR) -> Path: |
| 107 | """Return the validated JSONL file 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) / FILE_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"File change path escapes change directory: {object_id}" |
| 121 | ) from exc |
| 122 | |
| 123 | return path |
| 124 | |
| 125 | |
| 126 | def _read_changes(path: Path, *, file_name: str | None) -> 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 not isinstance(entry, dict): |
| 140 | continue |
| 141 | if file_name is not None and entry.get("file_name") != file_name: |
| 142 | continue |
| 143 | changes.append(entry) |
| 144 | |
| 145 | changes.reverse() |
| 146 | return changes |
| 147 | |
| 148 | |
| 149 | def _normalize_details(details: Mapping[str, Any] | None) -> dict[str, Any]: |
| 150 | if details is None: |
| 151 | return {} |
| 152 | if not isinstance(details, Mapping): |
| 153 | raise InvalidFileChangeError("File change details must be an object") |
| 154 | return {str(key): _json_safe_value(value) for key, value in details.items()} |
| 155 | |
| 156 | |
| 157 | def _json_safe_value(value: Any) -> Any: |
| 158 | if value is None or isinstance(value, str | int | float | bool): |
| 159 | return value |
| 160 | if isinstance(value, Mapping): |
| 161 | return {str(key): _json_safe_value(item) for key, item in value.items()} |
| 162 | if isinstance(value, list | tuple): |
| 163 | return [_json_safe_value(item) for item in value] |
| 164 | return str(value) |
| 165 | |
| 166 | |
| 167 | def _validate_page(*, limit: int, offset: int) -> None: |
| 168 | if limit < 1: |
| 169 | raise ValueError("limit must be at least 1") |
| 170 | if limit > MAX_CHANGE_LIMIT: |
| 171 | raise ValueError(f"limit must be at most {MAX_CHANGE_LIMIT}") |
| 172 | if offset < 0: |
| 173 | raise ValueError("offset must be at least 0") |
| 174 | |
| 175 | |
| 176 | def _clean_filename(value: str) -> str: |
| 177 | text = str(value).strip() |
| 178 | if not text or "\x00" in text or text.startswith("/") or ".." in text: |
| 179 | raise InvalidFileChangeError(f"Invalid file name: {value!r}") |
| 180 | path = Path(text) |
| 181 | if path.is_absolute() or any(part in {"", ".", ".."} for part in path.parts): |
| 182 | raise InvalidFileChangeError(f"Invalid file name: {value!r}") |
| 183 | return path.as_posix() |
| 184 | |
| 185 | |
| 186 | def _optional_non_negative_int(value: int | None, *, field: str) -> int | None: |
| 187 | if value is None: |
| 188 | return None |
| 189 | try: |
| 190 | parsed = int(value) |
| 191 | except (TypeError, ValueError) as exc: |
| 192 | raise InvalidFileChangeError(f"{field} must be an integer") from exc |
| 193 | if parsed < 0: |
| 194 | raise InvalidFileChangeError(f"{field} must be at least 0") |
| 195 | return parsed |
| 196 | |
| 197 | |
| 198 | def _clean_optional_text(value: str | None) -> str | None: |
| 199 | if value is None: |
| 200 | return None |
| 201 | text = str(value).strip() |
| 202 | return text or None |
| 203 | |
| 204 | |
| 205 | def _clean_text(value: str, *, default: str) -> str: |
| 206 | text = str(value).strip() |
| 207 | return text or default |
| 208 | |
| 209 | |
| 210 | def _default_message(action: str) -> str: |
| 211 | return { |
| 212 | "file_create": "Created object file", |
| 213 | "file_update": "Updated object file", |
| 214 | "file_delete": "Deleted object file", |
| 215 | }[action] |
| 216 | |
| 217 | |
| 218 | def _utc_timestamp() -> str: |
| 219 | return datetime.now(timezone.utc).isoformat() |
| 220 | |
| 221 | |
| 222 | def _file_lock(path: Path) -> threading.Lock: |
| 223 | key = str(path.resolve(strict=False)) |
| 224 | with _LOCKS_GUARD: |
| 225 | lock = _LOCKS.get(key) |
| 226 | if lock is None: |
| 227 | lock = threading.Lock() |
| 228 | _LOCKS[key] = lock |
| 229 | return lock |