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
test_package_nav.py · 15.1 KB · 366 lines
| 1 | """Navigation ships with the app that owns the door. |
| 2 | |
| 3 | Before this, the same list of apps was maintained by hand in three |
| 4 | places -- the app switcher's JS array, the home page's tile grid, and a |
| 5 | search-hit URL map -- and they had already drifted: 25 entries against |
| 6 | 21, and between them no mention of the eight newest apps. Nothing failed |
| 7 | when they drifted; the front door simply advertised a server that no |
| 8 | longer existed, which is why nobody noticed. |
| 9 | |
| 10 | So the properties worth holding are about SURVIVING an install rather |
| 11 | than performing one: an operator's `hidden` outlives an upgrade, a plan |
| 12 | that says "unchanged" writes nothing, a second package cannot quietly |
| 13 | take over somebody's door, and a package still installs when the nav app |
| 14 | is absent entirely. The last test in this file is the one that stops the |
| 15 | drift coming back. |
| 16 | """ |
| 17 | |
| 18 | import json |
| 19 | import pathlib |
| 20 | |
| 21 | import pytest |
| 22 | |
| 23 | import object_packages |
| 24 | import object_records |
| 25 | |
| 26 | REPO_ROOT = pathlib.Path(__file__).resolve().parents[1] |
| 27 | PACKAGES = REPO_ROOT / "packages" |
| 28 | NAV_SCHEMA = json.loads((PACKAGES / "app-nav" / "schemas" / "nav_entries.json").read_text()) |
| 29 | |
| 30 | MANIFEST = { |
| 31 | "id": "app-demo", |
| 32 | "name": "Demo", |
| 33 | "version": "1.0.0", |
| 34 | "objects": [{"id": "site_demo", "path": "objects/site/demo.py"}], |
| 35 | "schemas": [{"collection": "nav_entries", "path": "schemas/nav_entries.json"}], |
| 36 | "nav": [{"id": "demo", "label": "Demo", "path": "/demo", |
| 37 | "blurb": "A door.", "group": "Work", "order": 10}], |
| 38 | } |
| 39 | |
| 40 | SOURCE = "def GET(request):\n return {'ok': True}\n" |
| 41 | |
| 42 | |
| 43 | @pytest.fixture |
| 44 | def package(tmp_path): |
| 45 | """A one-page, one-door package that also ships the nav_entries |
| 46 | schema, so the registry exists for it to register into.""" |
| 47 | root = tmp_path / "packages" |
| 48 | pkg = root / "app-demo" |
| 49 | (pkg / "objects" / "site").mkdir(parents=True) |
| 50 | (pkg / "objects" / "site" / "demo.py").write_text(SOURCE) |
| 51 | (pkg / "schemas").mkdir() |
| 52 | (pkg / "schemas" / "nav_entries.json").write_text(json.dumps(NAV_SCHEMA)) |
| 53 | (pkg / "dbbasic-package.json").write_text(json.dumps(MANIFEST)) |
| 54 | objects = tmp_path / "objects" |
| 55 | objects.mkdir() |
| 56 | data = tmp_path / "data" |
| 57 | data.mkdir() |
| 58 | return {"root": root, "dir": pkg, "objects": objects, "data": data} |
| 59 | |
| 60 | |
| 61 | def write_manifest(package, **overrides): |
| 62 | manifest = {**MANIFEST, **overrides} |
| 63 | (package["dir"] / "dbbasic-package.json").write_text(json.dumps(manifest)) |
| 64 | |
| 65 | |
| 66 | def install(package, **kwargs): |
| 67 | return object_packages.install_package( |
| 68 | "app-demo", root=package["root"], base_dir=package["data"], |
| 69 | object_roots=[package["objects"]], **kwargs) |
| 70 | |
| 71 | |
| 72 | def plan(package): |
| 73 | return object_packages.dry_run_package( |
| 74 | "app-demo", root=package["root"], base_dir=package["data"], |
| 75 | object_roots=[package["objects"]]) |
| 76 | |
| 77 | |
| 78 | def entries(package): |
| 79 | try: |
| 80 | rows = object_records.read_collection_records("nav_entries", base_dir=package["data"]) |
| 81 | except Exception: |
| 82 | return {} |
| 83 | return {row["id"]: row for row in rows} |
| 84 | |
| 85 | |
| 86 | def set_entry(fixture, nav_id, **changes): |
| 87 | """An operator editing a row by hand -- `fixture` rather than |
| 88 | `package` because `package` is itself one of the row's columns.""" |
| 89 | object_records.update_collection_record( |
| 90 | "nav_entries", nav_id, changes, base_dir=fixture["data"], actor="operator") |
| 91 | |
| 92 | |
| 93 | # --- registering ------------------------------------------------------------- |
| 94 | |
| 95 | def test_installing_a_package_registers_its_door(package): |
| 96 | result = install(package) |
| 97 | assert [entry["status"] for entry in result["nav"]] == ["written"] |
| 98 | |
| 99 | row = entries(package)["demo"] |
| 100 | assert row["label"] == "Demo" |
| 101 | assert row["path"] == "/demo" |
| 102 | assert row["blurb"] == "A door." |
| 103 | assert row["group"] == "Work" |
| 104 | assert row["surface"] == "member" # the default tier |
| 105 | assert row["order"] == "10" |
| 106 | assert row["package"] == "app-demo" # provenance, stamped by install |
| 107 | assert row["operator_hidden"] == "false" |
| 108 | |
| 109 | |
| 110 | def test_the_plan_says_what_it_would_register_before_it_does(package): |
| 111 | assert plan(package)["nav"] == [{"id": "demo", "label": "Demo", "path": "/demo", |
| 112 | "group": "Work", "surface": "member", |
| 113 | "exists": False, "action": "create"}] |
| 114 | assert plan(package)["package"]["nav_count"] == 1 |
| 115 | assert entries(package) == {} # a dry run writes nothing |
| 116 | |
| 117 | |
| 118 | def test_a_package_with_no_nav_touches_no_records(package): |
| 119 | write_manifest(package, nav=[]) |
| 120 | result = install(package) |
| 121 | assert result["nav"] == [] |
| 122 | assert entries(package) == {} |
| 123 | |
| 124 | |
| 125 | # --- surviving an upgrade ------------------------------------------------------ |
| 126 | |
| 127 | def test_reinstalling_preserves_the_operators_hidden(package): |
| 128 | """The package declares what the app IS; the operator decides what |
| 129 | they want to SEE. An upgrade that silently puts back a door somebody |
| 130 | deliberately removed is the same incident as one that restarts a |
| 131 | paused nightly pass.""" |
| 132 | install(package) |
| 133 | set_entry(package, "demo", operator_hidden="true") |
| 134 | |
| 135 | write_manifest(package, version="1.1.0", |
| 136 | nav=[{**MANIFEST["nav"][0], "label": "Demo App"}]) |
| 137 | install(package, allow_replace=True) |
| 138 | |
| 139 | row = entries(package)["demo"] |
| 140 | assert row["operator_hidden"] == "true" # untouched |
| 141 | assert row["label"] == "Demo App" # but the package's word is restated |
| 142 | |
| 143 | |
| 144 | def test_reinstalling_updates_a_changed_label(package): |
| 145 | install(package) |
| 146 | write_manifest(package, version="1.1.0", |
| 147 | nav=[{**MANIFEST["nav"][0], "label": "Renamed", "path": "/renamed", |
| 148 | "group": "System", "surface": "operator", "order": 5}]) |
| 149 | result = install(package, allow_replace=True) |
| 150 | |
| 151 | assert result["nav"][0]["action"] == "update" |
| 152 | assert result["nav"][0]["status"] == "updated" |
| 153 | row = entries(package)["demo"] |
| 154 | assert (row["label"], row["path"], row["group"], row["surface"], row["order"]) == ( |
| 155 | "Renamed", "/renamed", "System", "operator", "5") |
| 156 | |
| 157 | |
| 158 | def test_an_unchanged_entry_reports_unchanged(package): |
| 159 | install(package) |
| 160 | result = install(package, allow_replace=True) |
| 161 | assert result["nav"][0]["status"] == "unchanged" |
| 162 | assert result["nav"][0]["action"] == "unchanged" |
| 163 | |
| 164 | |
| 165 | def test_a_plan_that_says_unchanged_writes_nothing_at_all(package): |
| 166 | """Every package-owned field is compared, blurb and order included: |
| 167 | a dry run that under-reports is worse than no dry run.""" |
| 168 | install(package) |
| 169 | write_manifest(package, nav=[{**MANIFEST["nav"][0], "blurb": "Reworded."}]) |
| 170 | assert plan(package)["nav"][0]["action"] == "update" |
| 171 | |
| 172 | result = install(package, allow_replace=True) |
| 173 | assert result["nav"][0]["status"] == "updated" |
| 174 | assert entries(package)["demo"]["blurb"] == "Reworded." |
| 175 | |
| 176 | |
| 177 | def test_an_unchanged_reinstall_does_not_rewrite_the_row(package): |
| 178 | install(package) |
| 179 | before = entries(package)["demo"] |
| 180 | install(package, allow_replace=True) |
| 181 | assert entries(package)["demo"] == before # byte-for-byte, created_at included |
| 182 | |
| 183 | |
| 184 | def test_a_hand_made_entry_is_adopted_not_duplicated(package): |
| 185 | """Somebody adding a door by hand before its package declared one |
| 186 | must be taken over, not shadowed by a second row for the same id.""" |
| 187 | install(package) |
| 188 | set_entry(package, "demo", package="", label="Typed By Hand") |
| 189 | install(package, allow_replace=True) |
| 190 | |
| 191 | assert len(entries(package)) == 1 |
| 192 | assert entries(package)["demo"]["package"] == "app-demo" |
| 193 | |
| 194 | |
| 195 | # --- refusing what could not work ---------------------------------------------- |
| 196 | |
| 197 | def test_two_packages_cannot_fight_over_one_door(package): |
| 198 | """Whichever installed last would silently win, and the loser's menu |
| 199 | entry would point somewhere its own package never chose.""" |
| 200 | install(package) |
| 201 | set_entry(package, "demo", package="app-other") |
| 202 | with pytest.raises(object_packages.PackageInstallError) as exc: |
| 203 | install(package, allow_replace=True) |
| 204 | assert "app-other" in str(exc.value) |
| 205 | |
| 206 | |
| 207 | def test_a_path_another_package_already_claims_blocks_the_install(package): |
| 208 | install(package) |
| 209 | object_records.create_collection_record( |
| 210 | "nav_entries", |
| 211 | {"id": "rival", "package": "app-other", "label": "Rival", "path": "/second", |
| 212 | "group": "Work", "surface": "member", "order": "10"}, |
| 213 | base_dir=package["data"], actor="test") |
| 214 | write_manifest(package, nav=[{**MANIFEST["nav"][0], "path": "/second"}]) |
| 215 | |
| 216 | with pytest.raises(object_packages.PackageInstallError) as exc: |
| 217 | install(package, allow_replace=True) |
| 218 | assert "/second" in str(exc.value) |
| 219 | |
| 220 | |
| 221 | @pytest.mark.parametrize("bad, reason", [ |
| 222 | ({"id": "two words", "label": "X", "path": "/x"}, "nav id"), |
| 223 | ({"id": "demo", "label": "X", "path": "demo"}, "start with"), |
| 224 | ({"id": "demo", "label": "X", "path": "/two words"}, "whitespace"), |
| 225 | ({"id": "demo", "label": "X", "path": "/x\nmore"}, "whitespace"), |
| 226 | ({"id": "demo", "label": "X", "path": "/x", "surface": "everyone"}, |
| 227 | "public|member|operator|hidden"), |
| 228 | ({"id": "demo", "label": "X", "path": "/x", "order": "first"}, "integer"), |
| 229 | ({"id": "demo", "path": "/x"}, "requires 'label'"), |
| 230 | ({"id": "demo", "label": "X"}, "requires 'path'"), |
| 231 | ]) |
| 232 | def test_a_door_that_could_not_work_is_refused_at_install(package, bad, reason): |
| 233 | write_manifest(package, nav=[bad]) |
| 234 | with pytest.raises(object_packages.InvalidPackageManifestError) as exc: |
| 235 | install(package) |
| 236 | assert reason in str(exc.value) |
| 237 | assert entries(package) == {} |
| 238 | |
| 239 | |
| 240 | def test_two_nav_entries_cannot_share_an_id(package): |
| 241 | write_manifest(package, nav=[MANIFEST["nav"][0], |
| 242 | {**MANIFEST["nav"][0], "path": "/other"}]) |
| 243 | with pytest.raises(object_packages.InvalidPackageManifestError): |
| 244 | install(package) |
| 245 | |
| 246 | |
| 247 | # --- when the nav app is not installed ------------------------------------------- |
| 248 | |
| 249 | def test_a_missing_registry_skips_gracefully_instead_of_failing(package): |
| 250 | """A package must never fail to install because the navigation app is |
| 251 | absent. It says so in the result rather than pretending it wrote.""" |
| 252 | write_manifest(package, schemas=[]) |
| 253 | result = install(package) |
| 254 | |
| 255 | assert [entry["status"] for entry in result["nav"]] == ["skipped"] |
| 256 | assert "nav_entries" in result["nav"][0]["reason"] |
| 257 | assert not (package["data"] / "collections" / "nav_entries").exists() |
| 258 | |
| 259 | |
| 260 | def test_a_missing_registry_still_plans_the_entry(package): |
| 261 | write_manifest(package, schemas=[]) |
| 262 | assert plan(package)["nav"][0]["action"] == "create" |
| 263 | assert plan(package)["safe_to_install"] is True |
| 264 | |
| 265 | |
| 266 | # --- the real packages ------------------------------------------------------------ |
| 267 | |
| 268 | def _manifests(): |
| 269 | return {path.parent.name: json.loads(path.read_text()) |
| 270 | for path in sorted(PACKAGES.glob("*/dbbasic-package.json"))} |
| 271 | |
| 272 | |
| 273 | def test_every_package_that_ships_a_page_declares_a_door(): |
| 274 | """The test that stops the drift coming back. |
| 275 | |
| 276 | A package that serves a URL and registers nothing is exactly how the |
| 277 | hand-maintained lists fell four apps behind without anybody noticing. |
| 278 | A package whose site_* object is a widget or a per-record document |
| 279 | rather than a front page says so with `nav_optional`, which makes |
| 280 | "this app has no front door" a reviewable claim instead of an |
| 281 | omission. |
| 282 | """ |
| 283 | missing = [] |
| 284 | for package_id, manifest in _manifests().items(): |
| 285 | ships_page = any(entry["id"].startswith("site_") |
| 286 | for entry in manifest.get("objects", [])) |
| 287 | ships_routes = any(entry["collection"] == "site_routes" |
| 288 | for entry in manifest.get("seed", [])) |
| 289 | if not (ships_page or ships_routes): |
| 290 | continue |
| 291 | if manifest.get("nav") or manifest.get("nav_optional"): |
| 292 | continue |
| 293 | missing.append(package_id) |
| 294 | assert not missing, ( |
| 295 | f"these packages serve a URL and register no nav entry: {missing}. " |
| 296 | "Declare `nav`, or `nav_optional: true` if the page is not a door.") |
| 297 | |
| 298 | |
| 299 | def test_shipped_nav_entries_do_not_collide_on_an_id_or_a_path(): |
| 300 | """Two packages writing the same nav_entries row would silently |
| 301 | overwrite each other; two claiming one path is two doors on one room.""" |
| 302 | seen_ids: dict[str, str] = {} |
| 303 | seen_paths: dict[str, str] = {} |
| 304 | for package_id, manifest in _manifests().items(): |
| 305 | for entry in manifest.get("nav") or []: |
| 306 | assert entry["id"] not in seen_ids, ( |
| 307 | f"{entry['id']} declared by both {seen_ids.get(entry['id'])} " |
| 308 | f"and {package_id}") |
| 309 | seen_ids[entry["id"]] = package_id |
| 310 | assert entry["path"] not in seen_paths, ( |
| 311 | f"{entry['path']} claimed by both {seen_paths[entry['path']]} " |
| 312 | f"and {package_id}") |
| 313 | seen_paths[entry["path"]] = package_id |
| 314 | assert len(seen_ids) >= 30, "the box's doors should all be declared" |
| 315 | |
| 316 | |
| 317 | def test_shipped_nav_entries_normalize_and_use_the_house_groups(): |
| 318 | """Six groups, decided once. A seventh would not break anything -- |
| 319 | `group` is free text on purpose -- but it would mean somebody invented |
| 320 | a heading rather than filing under one that exists.""" |
| 321 | groups = {"Work", "Publishing", "Money", "Commerce", "Warehouse", "System"} |
| 322 | for package_id in _manifests(): |
| 323 | package = object_packages.get_package(package_id, root=PACKAGES) |
| 324 | for entry in package["nav"]: |
| 325 | assert entry["group"] in groups, f"{package_id}: {entry['group']}" |
| 326 | assert entry["blurb"], f"{package_id}: {entry['id']} has no blurb" |
| 327 | assert entry["path"].startswith("/") |
| 328 | |
| 329 | |
| 330 | def test_the_public_tier_is_only_the_pages_a_visitor_should_meet(): |
| 331 | """A `public` surface is a menu decision, not a grant -- but a door |
| 332 | offered to somebody who will be bounced by permissions is still a |
| 333 | broken promise, so the list is small and deliberate. |
| 334 | |
| 335 | `privacy` earns its place the same way the other two do: app-privacy |
| 336 | grants `public` execute on site_privacy, and a privacy policy behind |
| 337 | a sign-in is not a privacy policy. |
| 338 | |
| 339 | `notary` earns it by the same argument turned up one notch. An |
| 340 | attestation that only its submitter can look up is not an attestation, |
| 341 | it is a favour -- the whole value of lodging a digest with an |
| 342 | independent party is that a THIRD person can check it without an |
| 343 | account here or a relationship with the operator, and a door they |
| 344 | cannot find is a door they do not have. app-notary grants `public` |
| 345 | execute on site_notary to match. Note that the OPERATOR-facing |
| 346 | `notarizations` list in the same manifest is deliberately not on this |
| 347 | tier: reading the whole log is a different question from checking one |
| 348 | digest you were already given. |
| 349 | |
| 350 | `docs` is the plainest case of all: developer documentation behind a |
| 351 | sign-in is not documentation. app-docs grants `public` execute on all |
| 352 | three of its page objects and `public` read on doc_pages to match. |
| 353 | """ |
| 354 | public = {entry["id"] |
| 355 | for manifest in _manifests().values() |
| 356 | for entry in manifest.get("nav") or [] |
| 357 | if entry.get("surface") == "public"} |
| 358 | assert public == {"home", "shop", "privacy", "notary", "docs"} |
| 359 | |
| 360 | |
| 361 | def test_app_nav_declares_its_own_front_door(): |
| 362 | manifest = _manifests()["app-nav"] |
| 363 | assert manifest["nav"] == [{ |
| 364 | "id": "home", "label": "Home", "path": "/", |
| 365 | "blurb": "The switchboard: every app this server installs", |
| 366 | "surface": "public", "group": "Work", "order": 0}] |