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_package_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_package_changes.py · 8.5 KB · 275 lines
1"""Append-only change logs for DBBASIC packages.
2
3Package changes are the durable package manager facts behind dry-run, install,
4failure, restore, and rollback screens. The public server records dry-run plans
5and gated package operations, including failed operations.
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
17import object_packages
18from object_versions import DEFAULT_DATA_DIR
19
20PACKAGE_CHANGES_DIR = "package_changes"
21CHANGES_FILE = "changes.jsonl"
22DEFAULT_CHANGE_LIMIT = 100
23MAX_CHANGE_LIMIT = 1000
24VALID_ACTIONS = {
25 "dry_run",
26 "install_requested",
27 "installed",
28 "restore_requested",
29 "failed",
30 "rolled_back",
31}
32
33_LOCKS: dict[str, threading.Lock] = {}
34_LOCKS_GUARD = threading.Lock()
35
36
37class InvalidPackageChangeError(ValueError):
38 """Raised when a package change entry is not safe to write or read."""
39
40
41def append_package_change(
42 *,
43 package_id: str,
44 action: str,
45 package_version: str | None = None,
46 actor: str = "api",
47 message: str = "",
48 details: Mapping[str, Any] | None = None,
49 base_dir: Path | str = DEFAULT_DATA_DIR,
50) -> dict[str, Any]:
51 """Append one package change and return the stored entry."""
52 path = package_changes_file(package_id, base_dir=base_dir)
53 if action not in VALID_ACTIONS:
54 raise InvalidPackageChangeError(f"Invalid package change action: {action}")
55
56 timestamp = _utc_timestamp()
57 entry = {
58 "change_id": _change_id(timestamp, package_id, action),
59 "timestamp": timestamp,
60 "package_id": package_id,
61 "package_version": _clean_optional_text(package_version),
62 "action": action,
63 "actor": _clean_text(actor, default="api"),
64 "message": _clean_text(message, default=_default_message(action)),
65 "details": _normalize_details(details),
66 }
67
68 with _file_lock(path):
69 path.parent.mkdir(parents=True, exist_ok=True)
70 with path.open("a", encoding="utf-8") as handle:
71 handle.write(json.dumps(entry, sort_keys=True, separators=(",", ":")))
72 handle.write("\n")
73
74 return entry
75
76
77def list_package_changes(
78 package_id: str,
79 *,
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 package changes."""
85 path = package_changes_file(package_id, base_dir=base_dir)
86 _validate_page(limit=limit, offset=offset)
87
88 changes = _read_changes(path)
89 total = len(changes)
90 window = changes[offset:offset + limit]
91 return {
92 "package_id": package_id,
93 "changes": window,
94 "count": len(window),
95 "total": total,
96 "limit": limit,
97 "offset": offset,
98 "has_more": offset + len(window) < total,
99 }
100
101
102def get_package_change(
103 package_id: str,
104 change_id: str,
105 *,
106 base_dir: Path | str = DEFAULT_DATA_DIR,
107) -> dict[str, Any] | None:
108 """Return one package change by id, or None when it is not in the log."""
109 clean_change_id = _clean_change_id(change_id)
110 path = package_changes_file(package_id, base_dir=base_dir)
111 for change in _read_changes(path):
112 if change.get("change_id") == clean_change_id:
113 return change
114 return None
115
116
117def package_changes_file(package_id: str, base_dir: Path | str = DEFAULT_DATA_DIR) -> Path:
118 """Return the validated JSONL package change-log path."""
119 if not object_packages.validate_package_id(package_id):
120 raise object_packages.InvalidPackageIdError(f"Invalid package id: {package_id}")
121
122 root = Path(base_dir) / PACKAGE_CHANGES_DIR
123 path = root / package_id / CHANGES_FILE
124 resolved_root = root.resolve(strict=False)
125 resolved_path = path.resolve(strict=False)
126
127 try:
128 resolved_path.relative_to(resolved_root)
129 except ValueError as exc:
130 raise object_packages.InvalidPackageIdError(
131 f"Package change path escapes change directory: {package_id}"
132 ) from exc
133
134 return path
135
136
137def dry_run_change_details(plan: Mapping[str, Any]) -> dict[str, Any]:
138 """Return compact dry-run details safe for package change history."""
139 package = plan.get("package")
140 summary = package if isinstance(package, Mapping) else {}
141 return {
142 "package": {
143 "id": summary.get("id"),
144 "name": summary.get("name"),
145 "version": summary.get("version"),
146 },
147 "safe_to_install": bool(plan.get("safe_to_install")),
148 "install_enabled": bool(plan.get("install_enabled")),
149 "objects": _action_counts(plan.get("objects")),
150 "schemas": _action_counts(plan.get("schemas")),
151 "permissions": _action_counts(plan.get("permissions")),
152 "seed": _action_counts(plan.get("seed")),
153 "migrations": _action_counts(plan.get("migrations")),
154 "schedules": _action_counts(plan.get("schedules")),
155 "nav": _action_counts(plan.get("nav")),
156 "attention": _action_counts(plan.get("attention")),
157 "warnings": _string_list(plan.get("warnings")),
158 }
159
160
161def _read_changes(path: Path) -> list[dict[str, Any]]:
162 if not path.exists():
163 return []
164
165 changes: list[dict[str, Any]] = []
166 with _file_lock(path):
167 for line in path.read_text(encoding="utf-8").splitlines():
168 if not line.strip():
169 continue
170 try:
171 entry = json.loads(line)
172 except json.JSONDecodeError:
173 continue
174 if isinstance(entry, dict):
175 changes.append(entry)
176
177 changes.reverse()
178 return changes
179
180
181def _action_counts(entries: Any) -> dict[str, int]:
182 counts: dict[str, int] = {}
183 if not isinstance(entries, list):
184 return counts
185 for entry in entries:
186 if not isinstance(entry, Mapping):
187 continue
188 action = entry.get("action")
189 if not isinstance(action, str) or not action:
190 continue
191 counts[action] = counts.get(action, 0) + 1
192 return counts
193
194
195def _normalize_details(details: Mapping[str, Any] | None) -> dict[str, Any]:
196 if details is None:
197 return {}
198 if not isinstance(details, Mapping):
199 raise InvalidPackageChangeError("Package change details must be an object")
200 return {str(key): _json_safe_value(value) for key, value in details.items()}
201
202
203def _json_safe_value(value: Any) -> Any:
204 if value is None or isinstance(value, str | int | float | bool):
205 return value
206 if isinstance(value, Mapping):
207 return {str(key): _json_safe_value(item) for key, item in value.items()}
208 if isinstance(value, list | tuple):
209 return [_json_safe_value(item) for item in value]
210 return str(value)
211
212
213def _string_list(value: Any) -> list[str]:
214 if not isinstance(value, list):
215 return []
216 return [str(item) for item in value]
217
218
219def _validate_page(*, limit: int, offset: int) -> None:
220 if limit < 1:
221 raise ValueError("limit must be at least 1")
222 if limit > MAX_CHANGE_LIMIT:
223 raise ValueError(f"limit must be at most {MAX_CHANGE_LIMIT}")
224 if offset < 0:
225 raise ValueError("offset must be at least 0")
226
227
228def _clean_optional_text(value: str | None) -> str | None:
229 if value is None:
230 return None
231 text = str(value).strip()
232 return text or None
233
234
235def _clean_text(value: str, *, default: str) -> str:
236 text = str(value).strip()
237 return text or default
238
239
240def _clean_change_id(value: str) -> str:
241 text = str(value).strip()
242 if not text:
243 raise InvalidPackageChangeError("Package change id must not be empty")
244 if len(text) > 256 or any(ord(character) < 32 for character in text):
245 raise InvalidPackageChangeError("Package change id is not safe")
246 return text
247
248
249def _default_message(action: str) -> str:
250 return {
251 "dry_run": "Dry run package install",
252 "install_requested": "Requested package install",
253 "installed": "Installed package",
254 "restore_requested": "Requested package restore",
255 "failed": "Package operation failed",
256 "rolled_back": "Rolled back package",
257 }[action]
258
259
260def _change_id(timestamp: str, package_id: str, action: str) -> str:
261 return object_ids.new_uuid4()
262
263
264def _utc_timestamp() -> str:
265 return datetime.now(timezone.utc).isoformat()
266
267
268def _file_lock(path: Path) -> threading.Lock:
269 key = str(path.resolve(strict=False))
270 with _LOCKS_GUARD:
271 lock = _LOCKS.get(key)
272 if lock is None:
273 lock = threading.Lock()
274 _LOCKS[key] = lock
275 return lock