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_files.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_files.py · 7.7 KB · 246 lines
1"""Object-owned file helpers.
2
3The working prototype stores object-owned files under:
4
5 data/files/{object_id}/
6
7The HTTP surface gates writes separately from reads. These helpers keep path
8handling local and conservative so higher layers can apply auth, quotas, and
9permission policy.
10"""
11
12from __future__ import annotations
13
14import tempfile
15from dataclasses import asdict, dataclass
16from pathlib import Path
17from typing import Any
18
19from object_namespace import validate_object_id
20from object_versions import DEFAULT_DATA_DIR, InvalidObjectIdError
21
22
23class InvalidObjectFilenameError(ValueError):
24 """Raised when an object file name is unsafe."""
25
26
27class ObjectFileNotFoundError(FileNotFoundError):
28 """Raised when an object-owned file is missing."""
29
30
31class ObjectFileExistsError(FileExistsError):
32 """Raised when an object-owned file already exists."""
33
34
35class ObjectFileTooLargeError(ValueError):
36 """Raised when an object-owned file exceeds the configured size limit."""
37
38
39@dataclass(frozen=True)
40class ObjectFileMetadata:
41 name: str
42 size: int
43 modified: float
44
45 def to_dict(self) -> dict[str, Any]:
46 return asdict(self)
47
48
49def object_files_dir(object_id: str, base_dir: Path | str = DEFAULT_DATA_DIR) -> Path:
50 """Return the object-owned files directory for a validated object id."""
51 if not validate_object_id(object_id):
52 raise InvalidObjectIdError(f"Invalid object ID: {object_id}")
53
54 return Path(base_dir) / "files" / object_id
55
56
57def list_object_files(
58 object_id: str,
59 base_dir: Path | str = DEFAULT_DATA_DIR,
60) -> list[dict[str, Any]]:
61 """List object-owned files as metadata dictionaries."""
62 files_dir = object_files_dir(object_id, base_dir)
63 if not files_dir.exists():
64 return []
65 if not files_dir.is_dir():
66 raise OSError(f"Object files path is not a directory: {files_dir}")
67
68 files = []
69 for path in sorted(files_dir.rglob("*")):
70 if not path.is_file():
71 continue
72 relative_name = path.relative_to(files_dir).as_posix()
73 try:
74 safe_path = _safe_file_path(files_dir, relative_name)
75 except InvalidObjectFilenameError:
76 continue
77 if path.resolve() != safe_path:
78 continue
79
80 metadata = _metadata(files_dir, path)
81 files.append(metadata.to_dict())
82
83 return files
84
85
86def list_all_object_files(
87 base_dir: Path | str = DEFAULT_DATA_DIR,
88 *,
89 object_id: str | None = None,
90) -> list[dict[str, Any]]:
91 """List object-owned files across the local file store."""
92 if object_id is not None:
93 return [
94 {"object_id": object_id, **metadata}
95 for metadata in list_object_files(object_id, base_dir=base_dir)
96 ]
97
98 files_root = Path(base_dir) / "files"
99 if not files_root.exists():
100 return []
101 if not files_root.is_dir():
102 raise OSError(f"Object files root is not a directory: {files_root}")
103
104 files = []
105 for object_dir in sorted(files_root.iterdir()):
106 if not object_dir.is_dir() or not validate_object_id(object_dir.name):
107 continue
108 files.extend(
109 {"object_id": object_dir.name, **metadata}
110 for metadata in list_object_files(object_dir.name, base_dir=base_dir)
111 )
112
113 files.sort(key=lambda item: (-float(item["modified"]), item["object_id"], item["name"]))
114 return files
115
116
117def read_object_file(
118 object_id: str,
119 filename: str,
120 base_dir: Path | str = DEFAULT_DATA_DIR,
121) -> tuple[bytes, dict[str, Any]]:
122 """Read one object-owned file and return bytes plus metadata."""
123 files_dir = object_files_dir(object_id, base_dir)
124 path = _safe_file_path(files_dir, filename)
125 if not path.exists() or not path.is_file():
126 raise ObjectFileNotFoundError(f"File not found: {filename}")
127
128 return path.read_bytes(), _metadata(files_dir, path).to_dict()
129
130
131def write_object_file(
132 object_id: str,
133 filename: str,
134 content: bytes,
135 base_dir: Path | str = DEFAULT_DATA_DIR,
136 *,
137 overwrite: bool = False,
138 max_bytes: int | None = None,
139) -> dict[str, Any]:
140 """Write one object-owned file and return metadata."""
141 if max_bytes is not None and len(content) > max_bytes:
142 raise ObjectFileTooLargeError(
143 f"Object file exceeds max size: {len(content)} bytes > {max_bytes} bytes"
144 )
145
146 files_dir = object_files_dir(object_id, base_dir)
147 path = _safe_write_file_path(files_dir, filename)
148 if path.exists():
149 if path.is_symlink() or not path.is_file():
150 raise InvalidObjectFilenameError(f"Invalid filename: {filename!r}")
151 if not overwrite:
152 raise ObjectFileExistsError(f"File already exists: {filename}")
153
154 path.parent.mkdir(parents=True, exist_ok=True)
155 temp_path: Path | None = None
156 try:
157 with tempfile.NamedTemporaryFile(
158 "wb",
159 delete=False,
160 dir=path.parent,
161 prefix=f".{path.name}.",
162 suffix=".tmp",
163 ) as temp_file:
164 temp_file.write(content)
165 temp_path = Path(temp_file.name)
166 temp_path.replace(path)
167 finally:
168 if temp_path is not None and temp_path.exists():
169 temp_path.unlink()
170
171 return _metadata(files_dir, path).to_dict()
172
173
174def delete_object_file(
175 object_id: str,
176 filename: str,
177 base_dir: Path | str = DEFAULT_DATA_DIR,
178) -> dict[str, Any]:
179 """Delete one object-owned file and return its previous metadata."""
180 files_dir = object_files_dir(object_id, base_dir)
181 path = _safe_write_file_path(files_dir, filename)
182 if not path.exists() or not path.is_file() or path.is_symlink():
183 raise ObjectFileNotFoundError(f"File not found: {filename}")
184
185 metadata = _metadata(files_dir, path).to_dict()
186 path.unlink()
187 _prune_empty_dirs(path.parent, files_dir)
188 return metadata
189
190
191def _safe_file_path(files_dir: Path, filename: str) -> Path:
192 if not filename or "\x00" in filename or filename.startswith("/") or ".." in filename:
193 raise InvalidObjectFilenameError(f"Invalid filename: {filename!r}")
194
195 root = files_dir.resolve()
196 resolved = (files_dir / filename).resolve()
197 try:
198 resolved.relative_to(root)
199 except ValueError as exc:
200 raise InvalidObjectFilenameError(f"Path traversal blocked: {filename!r}") from exc
201
202 return resolved
203
204
205def _safe_write_file_path(files_dir: Path, filename: str) -> Path:
206 if not filename or "\x00" in filename or filename.startswith("/") or ".." in filename:
207 raise InvalidObjectFilenameError(f"Invalid filename: {filename!r}")
208
209 relative = Path(filename)
210 if relative.is_absolute() or any(part in {"", ".", ".."} for part in relative.parts):
211 raise InvalidObjectFilenameError(f"Invalid filename: {filename!r}")
212
213 root = files_dir.resolve()
214 candidate = files_dir / relative
215 current = files_dir
216 for part in relative.parts[:-1]:
217 current = current / part
218 if current.exists() and current.is_symlink():
219 raise InvalidObjectFilenameError(f"Invalid filename: {filename!r}")
220
221 if candidate.exists() and candidate.is_symlink():
222 raise InvalidObjectFilenameError(f"Invalid filename: {filename!r}")
223
224 try:
225 candidate.parent.resolve().relative_to(root)
226 except ValueError as exc:
227 raise InvalidObjectFilenameError(f"Path traversal blocked: {filename!r}") from exc
228
229 return candidate
230
231
232def _prune_empty_dirs(start: Path, stop: Path) -> None:
233 stop = stop.resolve()
234 current = start
235 while current != stop:
236 try:
237 current.rmdir()
238 except OSError:
239 return
240 current = current.parent
241
242
243def _metadata(files_dir: Path, path: Path) -> ObjectFileMetadata:
244 stat = path.stat()
245 name = path.relative_to(files_dir).as_posix()
246 return ObjectFileMetadata(name=name, size=stat.st_size, modified=stat.st_mtime)