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_file_changes.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_file_changes.py · 7.1 KB · 229 lines
1"""Append-only change logs for object-owned files.
2
3Object logs are useful while debugging one object. File changes are the durable
4operator facts behind upload, overwrite, delete, audit, and Scroll history
5screens.
6"""
7
8from __future__ import annotations
9
10import json
11import threading
12from datetime import datetime, timezone
13from pathlib import Path
14from typing import Any, Mapping
15
16import object_ids
17from object_namespace import validate_object_id
18from object_versions import DEFAULT_DATA_DIR, InvalidObjectIdError
19
20FILE_CHANGES_DIR = "file_changes"
21CHANGES_FILE = "changes.jsonl"
22DEFAULT_CHANGE_LIMIT = 100
23MAX_CHANGE_LIMIT = 1000
24VALID_ACTIONS = {"file_create", "file_update", "file_delete"}
25
26_LOCKS: dict[str, threading.Lock] = {}
27_LOCKS_GUARD = threading.Lock()
28
29
30class InvalidFileChangeError(ValueError):
31 """Raised when a file change entry is not safe to write or read."""
32
33
34def 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
76def 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
106def 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
126def _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
149def _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
157def _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
167def _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
176def _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
186def _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
198def _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
205def _clean_text(value: str, *, default: str) -> str:
206 text = str(value).strip()
207 return text or default
208
209
210def _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
218def _utc_timestamp() -> str:
219 return datetime.now(timezone.utc).isoformat()
220
221
222def _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