askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
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 | |
| 3 | The working prototype stores object-owned files under: |
| 4 | |
| 5 | data/files/{object_id}/ |
| 6 | |
| 7 | The HTTP surface gates writes separately from reads. These helpers keep path |
| 8 | handling local and conservative so higher layers can apply auth, quotas, and |
| 9 | permission policy. |
| 10 | """ |
| 11 | |
| 12 | from __future__ import annotations |
| 13 | |
| 14 | import tempfile |
| 15 | from dataclasses import asdict, dataclass |
| 16 | from pathlib import Path |
| 17 | from typing import Any |
| 18 | |
| 19 | from object_namespace import validate_object_id |
| 20 | from object_versions import DEFAULT_DATA_DIR, InvalidObjectIdError |
| 21 | |
| 22 | |
| 23 | class InvalidObjectFilenameError(ValueError): |
| 24 | """Raised when an object file name is unsafe.""" |
| 25 | |
| 26 | |
| 27 | class ObjectFileNotFoundError(FileNotFoundError): |
| 28 | """Raised when an object-owned file is missing.""" |
| 29 | |
| 30 | |
| 31 | class ObjectFileExistsError(FileExistsError): |
| 32 | """Raised when an object-owned file already exists.""" |
| 33 | |
| 34 | |
| 35 | class ObjectFileTooLargeError(ValueError): |
| 36 | """Raised when an object-owned file exceeds the configured size limit.""" |
| 37 | |
| 38 | |
| 39 | @dataclass(frozen=True) |
| 40 | class 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 | |
| 49 | def 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 | |
| 57 | def 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 | |
| 86 | def 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 | |
| 117 | def 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 | |
| 131 | def 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 | |
| 174 | def 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 | |
| 191 | def _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 | |
| 205 | def _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 | |
| 232 | def _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 | |
| 243 | def _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) |