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_namespace.py · 9.8 KB · 304 lines
| 1 | """Object source discovery and object ID resolution. |
| 2 | |
| 3 | This module is intentionally small and standalone while the public package |
| 4 | layout is being decided. It is the shared namespace contract for the daemon, |
| 5 | future HTTP server, tests, and companion tools. |
| 6 | """ |
| 7 | from __future__ import annotations |
| 8 | |
| 9 | import os |
| 10 | import re |
| 11 | from dataclasses import dataclass |
| 12 | from pathlib import Path |
| 13 | from typing import Iterable, Literal |
| 14 | |
| 15 | |
| 16 | DEFAULT_OBJECTS_DIR = "objects" |
| 17 | OBJECTS_DIR_ENV = "DBBASIC_OBJECTS_DIR" |
| 18 | OVERRIDES_DIR_ENV = "DBBASIC_OVERRIDES_DIR" |
| 19 | |
| 20 | _OBJECT_ID_RE = re.compile(r"^[A-Za-z0-9_]{1,64}$") |
| 21 | _USER_OBJECT_RE = re.compile(r"^u_(\d+)_([A-Za-z][A-Za-z0-9_]{0,49})$") |
| 22 | |
| 23 | |
| 24 | @dataclass(frozen=True) |
| 25 | class ObjectSource: |
| 26 | """A discovered object source file.""" |
| 27 | |
| 28 | object_id: str |
| 29 | path: Path |
| 30 | relative_path: Path |
| 31 | kind: Literal["system", "user", "override"] |
| 32 | |
| 33 | |
| 34 | def get_base_object_roots() -> list[Path]: |
| 35 | """Return the package/system object roots (never the override root). |
| 36 | |
| 37 | This is the root packages install into and reconcile against. It is |
| 38 | identical to the pre-override-support get_object_roots() body, so |
| 39 | install/baseline/reconcile logic always operates on the pristine, |
| 40 | upgradeable copy regardless of whether overrides are enabled. |
| 41 | """ |
| 42 | configured = os.environ.get(OBJECTS_DIR_ENV) |
| 43 | if configured: |
| 44 | return [Path(configured)] |
| 45 | return [Path(DEFAULT_OBJECTS_DIR)] |
| 46 | |
| 47 | |
| 48 | def get_override_root() -> Path | None: |
| 49 | """Return the override root when DBBASIC_OVERRIDES_DIR is set, else None. |
| 50 | |
| 51 | Overrides are strictly opt-in: when the env var is unset or empty, this |
| 52 | returns None and every override-aware code path behaves exactly as it |
| 53 | did before overrides existed. |
| 54 | """ |
| 55 | configured = os.environ.get(OVERRIDES_DIR_ENV) |
| 56 | if configured: |
| 57 | return Path(configured) |
| 58 | return None |
| 59 | |
| 60 | |
| 61 | def get_object_roots() -> list[Path]: |
| 62 | """Return object source roots in lookup order (override first, then base). |
| 63 | |
| 64 | When DBBASIC_OVERRIDES_DIR is unset this returns exactly |
| 65 | get_base_object_roots() — a single-element list identical to the |
| 66 | pre-override behavior of this function. |
| 67 | """ |
| 68 | override = get_override_root() |
| 69 | return ([override] if override is not None else []) + get_base_object_roots() |
| 70 | |
| 71 | |
| 72 | def validate_object_id(object_id: str) -> bool: |
| 73 | """Return True when an object ID is safe to resolve.""" |
| 74 | if not isinstance(object_id, str): |
| 75 | return False |
| 76 | return bool(_OBJECT_ID_RE.fullmatch(object_id)) |
| 77 | |
| 78 | |
| 79 | def parse_user_object_id(object_id: str) -> tuple[int, str] | None: |
| 80 | """Parse `u_{user_id}_{name}` object IDs.""" |
| 81 | if not validate_object_id(object_id): |
| 82 | return None |
| 83 | |
| 84 | match = _USER_OBJECT_RE.fullmatch(object_id) |
| 85 | if not match: |
| 86 | return None |
| 87 | return int(match.group(1)), match.group(2) |
| 88 | |
| 89 | |
| 90 | def is_user_object_id(object_id: str) -> bool: |
| 91 | """Return True when an object ID belongs to a user namespace.""" |
| 92 | return parse_user_object_id(object_id) is not None |
| 93 | |
| 94 | |
| 95 | def override_relative_path(object_id: str) -> Path | None: |
| 96 | """Return the canonical override-root-relative path for an object ID. |
| 97 | |
| 98 | Mirrors the first candidate form used by _candidate_system_paths. |
| 99 | Overrides only exist for system/package objects; user object IDs (and |
| 100 | any other invalid ID) are not supported and return None. |
| 101 | """ |
| 102 | if not validate_object_id(object_id) or is_user_object_id(object_id): |
| 103 | return None |
| 104 | if "_" in object_id: |
| 105 | category, name = object_id.split("_", 1) |
| 106 | return Path(category) / f"{name}.py" |
| 107 | return Path(f"{object_id}.py") |
| 108 | |
| 109 | |
| 110 | def override_path(object_id: str) -> Path | None: |
| 111 | """Return the absolute override path for an object ID, or None. |
| 112 | |
| 113 | None is returned when overrides are not enabled (no override root |
| 114 | configured) or when the object ID is not a valid override target. |
| 115 | """ |
| 116 | root = get_override_root() |
| 117 | if root is None: |
| 118 | return None |
| 119 | relative = override_relative_path(object_id) |
| 120 | if relative is None: |
| 121 | return None |
| 122 | return root / relative |
| 123 | |
| 124 | |
| 125 | def has_override(object_id: str) -> bool: |
| 126 | """Return True when an override file exists for this object ID.""" |
| 127 | path = override_path(object_id) |
| 128 | return path is not None and path.is_file() |
| 129 | |
| 130 | |
| 131 | def resolve_object_id(object_id: str, roots: Iterable[Path] | None = None) -> Path | None: |
| 132 | """Resolve an object ID to an existing source file.""" |
| 133 | if not validate_object_id(object_id): |
| 134 | return None |
| 135 | |
| 136 | search_roots = list(roots) if roots is not None else get_object_roots() |
| 137 | |
| 138 | parsed_user = parse_user_object_id(object_id) |
| 139 | if parsed_user: |
| 140 | user_id, name = parsed_user |
| 141 | for root in search_roots: |
| 142 | candidate = root / "users" / str(user_id) / f"{name}.py" |
| 143 | if _is_allowed_source_file(candidate, root): |
| 144 | return candidate |
| 145 | return None |
| 146 | |
| 147 | for candidate in _candidate_system_paths(object_id, search_roots): |
| 148 | root = _candidate_root(candidate, search_roots) |
| 149 | if root is not None and _is_allowed_source_file(candidate, root): |
| 150 | return candidate |
| 151 | |
| 152 | for source in iter_object_sources(search_roots): |
| 153 | if source.object_id == object_id: |
| 154 | return source.path |
| 155 | |
| 156 | return None |
| 157 | |
| 158 | |
| 159 | def find_trigger_file(trigger_name: str, roots: Iterable[Path] | None = None) -> Path | None: |
| 160 | """Find a known trigger object file under `objects/triggers/`.""" |
| 161 | if not _is_safe_source_stem(trigger_name): |
| 162 | return None |
| 163 | |
| 164 | search_roots = list(roots) if roots is not None else get_object_roots() |
| 165 | for root in search_roots: |
| 166 | candidate = root / "triggers" / f"{trigger_name}.py" |
| 167 | if _is_allowed_source_file(candidate, root): |
| 168 | return candidate |
| 169 | return None |
| 170 | |
| 171 | |
| 172 | def object_id_from_path(path: Path | str, root: Path | str) -> str: |
| 173 | """Return the object ID represented by a source path under a root.""" |
| 174 | source_path = Path(path) |
| 175 | source_root = Path(root) |
| 176 | rel = _relative_to_root(source_path, source_root) |
| 177 | |
| 178 | if not _is_public_source_relative_path(rel): |
| 179 | raise ValueError(f"Not a public object source: {source_path}") |
| 180 | |
| 181 | parts = rel.parts |
| 182 | if parts[0] == "users": |
| 183 | if len(parts) != 3: |
| 184 | raise ValueError(f"Invalid user object source path: {source_path}") |
| 185 | user_id = parts[1] |
| 186 | name = Path(parts[2]).stem |
| 187 | object_id = f"u_{user_id}_{name}" |
| 188 | else: |
| 189 | path_without_suffix = rel.with_suffix("") |
| 190 | object_id = "_".join(path_without_suffix.parts) |
| 191 | |
| 192 | if not validate_object_id(object_id): |
| 193 | raise ValueError(f"Invalid object ID derived from path: {object_id}") |
| 194 | return object_id |
| 195 | |
| 196 | |
| 197 | def iter_object_sources(roots: Iterable[Path] | None = None) -> list[ObjectSource]: |
| 198 | """List object source files from configured roots in deterministic order.""" |
| 199 | search_roots = list(roots) if roots is not None else get_object_roots() |
| 200 | override_root = get_override_root() |
| 201 | sources: list[ObjectSource] = [] |
| 202 | |
| 203 | for root in search_roots: |
| 204 | if not root.exists() or not root.is_dir(): |
| 205 | continue |
| 206 | |
| 207 | is_override_root = override_root is not None and _same_root(root, override_root) |
| 208 | |
| 209 | for path in sorted(root.rglob("*.py"), key=lambda p: p.relative_to(root).as_posix()): |
| 210 | try: |
| 211 | rel = _relative_to_root(path, root) |
| 212 | object_id = object_id_from_path(path, root) |
| 213 | except ValueError: |
| 214 | continue |
| 215 | |
| 216 | kind: Literal["system", "user", "override"] |
| 217 | if rel.parts[0] == "users": |
| 218 | kind = "user" |
| 219 | elif is_override_root: |
| 220 | kind = "override" |
| 221 | else: |
| 222 | kind = "system" |
| 223 | sources.append( |
| 224 | ObjectSource( |
| 225 | object_id=object_id, |
| 226 | path=path, |
| 227 | relative_path=rel, |
| 228 | kind=kind, |
| 229 | ) |
| 230 | ) |
| 231 | |
| 232 | return sources |
| 233 | |
| 234 | |
| 235 | def _same_root(a: Path, b: Path) -> bool: |
| 236 | return a.resolve(strict=False) == b.resolve(strict=False) |
| 237 | |
| 238 | |
| 239 | def _candidate_system_paths(object_id: str, roots: Iterable[Path]) -> list[Path]: |
| 240 | candidates: list[Path] = [] |
| 241 | for root in roots: |
| 242 | if "_" in object_id: |
| 243 | category, name = object_id.split("_", 1) |
| 244 | candidates.append(root / category / f"{name}.py") |
| 245 | candidates.append(root / f"{object_id}.py") |
| 246 | return candidates |
| 247 | |
| 248 | |
| 249 | def _candidate_root(candidate: Path, roots: Iterable[Path]) -> Path | None: |
| 250 | for root in roots: |
| 251 | try: |
| 252 | _relative_to_root(candidate, root) |
| 253 | return root |
| 254 | except ValueError: |
| 255 | continue |
| 256 | return None |
| 257 | |
| 258 | |
| 259 | def _relative_to_root(path: Path, root: Path) -> Path: |
| 260 | resolved_path = path.resolve(strict=False) |
| 261 | resolved_root = root.resolve(strict=False) |
| 262 | |
| 263 | try: |
| 264 | return resolved_path.relative_to(resolved_root) |
| 265 | except ValueError as exc: |
| 266 | raise ValueError(f"Path escapes object root: {path}") from exc |
| 267 | |
| 268 | |
| 269 | def _is_allowed_source_file(path: Path, root: Path) -> bool: |
| 270 | if not path.exists() or not path.is_file(): |
| 271 | return False |
| 272 | try: |
| 273 | rel = _relative_to_root(path, root) |
| 274 | except ValueError: |
| 275 | return False |
| 276 | return _is_public_source_relative_path(rel) |
| 277 | |
| 278 | |
| 279 | def _is_public_source_relative_path(rel: Path) -> bool: |
| 280 | parts = rel.parts |
| 281 | if not parts: |
| 282 | return False |
| 283 | if rel.suffix != ".py": |
| 284 | return False |
| 285 | if rel.name == "__init__.py": |
| 286 | return False |
| 287 | if "__pycache__" in parts: |
| 288 | return False |
| 289 | if any(part.startswith(".") or part.startswith("_") for part in parts): |
| 290 | return False |
| 291 | if any(part in {"", ".", ".."} for part in parts): |
| 292 | return False |
| 293 | |
| 294 | if parts[0] == "users": |
| 295 | if len(parts) != 3: |
| 296 | return False |
| 297 | return parts[1].isdigit() and _is_safe_source_stem(Path(parts[2]).stem) |
| 298 | |
| 299 | return all(_is_safe_source_stem(part if i < len(parts) - 1 else Path(part).stem) |
| 300 | for i, part in enumerate(parts)) |
| 301 | |
| 302 | |
| 303 | def _is_safe_source_stem(stem: str) -> bool: |
| 304 | return bool(re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_]{0,49}", stem)) |