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_schema_versions.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_schema_versions.py · 6.6 KB · 203 lines
1"""Schema metadata version storage.
2
3Schema changes need the same operational trail as object source changes:
4
5- data/schema_versions/{collection}/metadata.tsv
6- data/schema_versions/{collection}/v1.json
7- data/schema_versions/{collection}/v2.json
8
9Rollback is non-destructive. It creates a new version containing the older
10schema JSON, preserving who changed what and when.
11"""
12
13from __future__ import annotations
14
15import csv
16import hashlib
17import json
18from datetime import datetime
19from pathlib import Path
20from typing import Any
21
22import object_schemas
23from object_versions import DEFAULT_DATA_DIR
24
25SCHEMA_VERSIONS_DIR = "schema_versions"
26METADATA_FILE = "metadata.tsv"
27METADATA_FIELDS = ["version_id", "timestamp", "author", "message", "hash"]
28
29
30class SchemaVersionError(Exception):
31 """Base exception for schema version errors."""
32
33
34class InvalidSchemaNameError(SchemaVersionError):
35 """Raised when a schema name is not safe for version storage."""
36
37
38class SchemaVersionNotFoundError(SchemaVersionError):
39 """Raised when a requested schema version does not exist."""
40
41
42class SchemaVersionManager:
43 """Manage per-schema JSON versions stored as TSV metadata and files."""
44
45 def __init__(self, base_dir: Path | str = DEFAULT_DATA_DIR):
46 self.base_dir = Path(base_dir)
47 self.versions_dir = self.base_dir / SCHEMA_VERSIONS_DIR
48 self.versions_dir.mkdir(parents=True, exist_ok=True)
49
50 def save_version(
51 self,
52 schema: str,
53 content: str,
54 author: str,
55 message: str,
56 ) -> int:
57 """Save a new schema version and return its integer version ID."""
58 schema_dir = self._schema_dir(schema, create=True)
59 version_id = self._get_next_version_id(schema)
60 content_hash = self._compute_hash(content)
61 timestamp = datetime.now().isoformat()
62
63 content_file = schema_dir / f"v{version_id}.json"
64 content_file.write_text(content)
65
66 metadata_file = schema_dir / METADATA_FILE
67 is_new_file = not metadata_file.exists()
68 with metadata_file.open("a", newline="") as f:
69 writer = csv.DictWriter(f, fieldnames=METADATA_FIELDS, delimiter="\t")
70 if is_new_file:
71 writer.writeheader()
72 writer.writerow(
73 {
74 "version_id": version_id,
75 "timestamp": timestamp,
76 "author": author,
77 "message": message,
78 "hash": content_hash,
79 }
80 )
81
82 return version_id
83
84 def get_version(self, schema: str, version_id: int | None = None) -> dict[str, Any] | None:
85 """Get one schema version with content. `version_id=None` returns latest."""
86 versions = self._read_metadata(schema)
87 if not versions:
88 return None
89
90 if version_id is None:
91 target_version = versions[-1]
92 else:
93 target_version = next((v for v in versions if v["version_id"] == version_id), None)
94 if target_version is None:
95 return None
96
97 content_file = self._schema_dir(schema) / f"v{target_version['version_id']}.json"
98 if not content_file.exists() or not content_file.is_file():
99 return None
100
101 return {
102 **target_version,
103 "content": content_file.read_text(),
104 }
105
106 def get_history(
107 self,
108 schema: str,
109 limit: int | None = None,
110 offset: int = 0,
111 ) -> list[dict[str, Any]]:
112 """Return schema metadata history, newest first, without content."""
113 versions = list(reversed(self._read_metadata(schema)))
114
115 if offset > 0:
116 versions = versions[offset:]
117
118 if limit is not None:
119 versions = versions[:limit]
120
121 return versions
122
123 def rollback(
124 self,
125 schema: str,
126 to_version: int,
127 author: str,
128 message: str,
129 ) -> int:
130 """Create a new version containing schema JSON from an older version."""
131 old_version = self.get_version(schema, to_version)
132 if old_version is None:
133 raise SchemaVersionNotFoundError(f"Version {to_version} not found for schema {schema}")
134
135 return self.save_version(
136 schema=schema,
137 content=old_version["content"],
138 author=author,
139 message=message,
140 )
141
142 def _schema_dir(self, schema: str, *, create: bool = False) -> Path:
143 if not object_schemas.validate_schema_name(schema):
144 raise InvalidSchemaNameError(f"Invalid schema name: {schema}")
145
146 schema_dir = self.versions_dir / schema
147 versions_root = self.versions_dir.resolve(strict=False)
148 resolved_schema_dir = schema_dir.resolve(strict=False)
149
150 try:
151 resolved_schema_dir.relative_to(versions_root)
152 except ValueError as exc:
153 raise InvalidSchemaNameError(f"Schema name escapes versions directory: {schema}") from exc
154
155 if create:
156 schema_dir.mkdir(parents=True, exist_ok=True)
157 return schema_dir
158
159 def _read_metadata(self, schema: str) -> list[dict[str, Any]]:
160 metadata_file = self._schema_dir(schema) / METADATA_FILE
161 if not metadata_file.exists() or not metadata_file.is_file():
162 return []
163
164 versions: list[dict[str, Any]] = []
165 with metadata_file.open("r", newline="") as f:
166 reader = csv.DictReader(f, delimiter="\t")
167 for row in reader:
168 normalized = self._normalize_metadata_row(row)
169 if normalized is not None:
170 versions.append(normalized)
171
172 return versions
173
174 def _normalize_metadata_row(self, row: dict[str, str | None]) -> dict[str, Any] | None:
175 if any(row.get(field) is None for field in METADATA_FIELDS):
176 return None
177
178 try:
179 version_id = int(row["version_id"] or "")
180 except ValueError:
181 return None
182
183 return {
184 "version_id": version_id,
185 "timestamp": row["timestamp"] or "",
186 "author": row["author"] or "",
187 "message": row["message"] or "",
188 "hash": row["hash"] or "",
189 }
190
191 def _get_next_version_id(self, schema: str) -> int:
192 versions = self._read_metadata(schema)
193 if not versions:
194 return 1
195 return max(version["version_id"] for version in versions) + 1
196
197 def _compute_hash(self, content: str) -> str:
198 return hashlib.sha256(content.encode()).hexdigest()
199
200
201def schema_version_content(schema: dict[str, Any]) -> str:
202 """Return canonical JSON text for schema version files."""
203 return json.dumps(schema, indent=2, sort_keys=True) + "\n"