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_source_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_source_changes.py · 6.5 KB · 218 lines
1"""Append-only change logs for DBBASIC object source updates.
2
3Source versions store recoverable source snapshots. Source changes are the
4operator-facing activity facts behind edit, rollback, 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
20SOURCE_CHANGES_DIR = "source_changes"
21CHANGES_FILE = "changes.jsonl"
22DEFAULT_CHANGE_LIMIT = 100
23MAX_CHANGE_LIMIT = 1000
24VALID_ACTIONS = {"source_create", "source_update", "source_rollback"}
25
26_LOCKS: dict[str, threading.Lock] = {}
27_LOCKS_GUARD = threading.Lock()
28
29
30class InvalidSourceChangeError(ValueError):
31 """Raised when a source change entry is not safe to write or read."""
32
33
34def 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
81def 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
106def 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
126def _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
146def _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
154def _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
164def _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
173def _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
183def _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
190def _clean_text(value: str, *, default: str) -> str:
191 text = str(value).strip()
192 return text or default
193
194
195def _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
203def _change_id(timestamp: str, object_id: str, action: str) -> str:
204 return object_ids.new_uuid4()
205
206
207def _utc_timestamp() -> str:
208 return datetime.now(timezone.utc).isoformat()
209
210
211def _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