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_object_concurrency.py · 12.6 KB · 310 lines
| 1 | """Tests for 63 -- optimistic concurrency (If-Match / expected_rev |
| 2 | compare-and-set on record update). See plan/vocabulary/63-concurrency-spec.md. |
| 3 | |
| 4 | Covers the primitive at the record layer (compute_record_rev's properties and |
| 5 | update_collection_record's expected_rev precondition, including the claim race |
| 6 | the spec's worked example describes) plus the MCP bridge that carries the |
| 7 | precondition as a reserved body key. |
| 8 | """ |
| 9 | |
| 10 | import json |
| 11 | from pathlib import Path |
| 12 | |
| 13 | import pytest |
| 14 | |
| 15 | import object_mcp |
| 16 | import object_records |
| 17 | |
| 18 | |
| 19 | def write_records(data_dir: Path, collection: str, content: str) -> Path: |
| 20 | path = data_dir / "collections" / collection / "records.tsv" |
| 21 | path.parent.mkdir(parents=True, exist_ok=True) |
| 22 | path.write_text(content) |
| 23 | return path |
| 24 | |
| 25 | |
| 26 | def write_schema(data_dir: Path, collection: str, fields: list[dict]) -> Path: |
| 27 | path = data_dir / "schemas" / f"{collection}.json" |
| 28 | path.parent.mkdir(parents=True, exist_ok=True) |
| 29 | path.write_text(json.dumps({"fields": fields})) |
| 30 | return path |
| 31 | |
| 32 | |
| 33 | # --------------------------------------------------------------------------- |
| 34 | # compute_record_rev -- the content fingerprint |
| 35 | # --------------------------------------------------------------------------- |
| 36 | |
| 37 | |
| 38 | def test_rev_is_deterministic_and_key_order_independent(): |
| 39 | a = {"id": "t1", "status": "open", "assigned_to": ""} |
| 40 | b = {"assigned_to": "", "id": "t1", "status": "open"} # same content, reordered |
| 41 | assert object_records.compute_record_rev(a) == object_records.compute_record_rev(b) |
| 42 | |
| 43 | |
| 44 | def test_rev_changes_when_any_field_changes(): |
| 45 | base = {"id": "t1", "status": "open", "assigned_to": ""} |
| 46 | changed = {"id": "t1", "status": "assigned", "assigned_to": "agent-A"} |
| 47 | assert object_records.compute_record_rev(base) != object_records.compute_record_rev(changed) |
| 48 | |
| 49 | |
| 50 | def test_rev_excludes_the_rev_field_itself(): |
| 51 | """A caller round-tripping a full record it read (which carries `_rev`) |
| 52 | must fingerprint to the same value as the stored row without it -- else |
| 53 | echoing a read's token back would never match.""" |
| 54 | stored = {"id": "t1", "status": "open"} |
| 55 | round_tripped = {"id": "t1", "status": "open", object_records.REV_FIELD: "whatever"} |
| 56 | assert object_records.compute_record_rev(stored) == object_records.compute_record_rev(round_tripped) |
| 57 | |
| 58 | |
| 59 | def test_rev_handles_mixed_type_extra_values(): |
| 60 | # Surfaced extra-blob values can be non-string (ints, lists); the hash |
| 61 | # must still be stable and not raise. |
| 62 | rec = {"id": "o1", "total_cents": 1299, "tags": ["a", "b"], "meta": {"k": 1}} |
| 63 | first = object_records.compute_record_rev(rec) |
| 64 | assert first == object_records.compute_record_rev(dict(rec)) |
| 65 | |
| 66 | |
| 67 | # --------------------------------------------------------------------------- |
| 68 | # update_collection_record -- the precondition |
| 69 | # --------------------------------------------------------------------------- |
| 70 | |
| 71 | |
| 72 | def _seed_task(data_dir: Path) -> str: |
| 73 | write_records( |
| 74 | data_dir, |
| 75 | "tasks", |
| 76 | "id\tstatus\tassigned_to\nt1\topen\t\n", |
| 77 | ) |
| 78 | rev = object_records.compute_record_rev( |
| 79 | object_records.get_collection_record("tasks", "t1", base_dir=data_dir, roots=[]) |
| 80 | ) |
| 81 | return rev |
| 82 | |
| 83 | |
| 84 | def test_matching_expected_rev_allows_the_write(tmp_path): |
| 85 | data_dir = tmp_path / "data" |
| 86 | rev = _seed_task(data_dir) |
| 87 | |
| 88 | updated = object_records.update_collection_record( |
| 89 | "tasks", |
| 90 | "t1", |
| 91 | {"status": "assigned", "assigned_to": "agent-A"}, |
| 92 | base_dir=data_dir, |
| 93 | roots=[], |
| 94 | expected_rev=rev, |
| 95 | ) |
| 96 | assert updated["assigned_to"] == "agent-A" |
| 97 | |
| 98 | |
| 99 | def test_mismatched_expected_rev_raises_and_writes_nothing(tmp_path): |
| 100 | data_dir = tmp_path / "data" |
| 101 | _seed_task(data_dir) |
| 102 | |
| 103 | with pytest.raises(object_records.VersionConflictError): |
| 104 | object_records.update_collection_record( |
| 105 | "tasks", |
| 106 | "t1", |
| 107 | {"status": "assigned", "assigned_to": "agent-B"}, |
| 108 | base_dir=data_dir, |
| 109 | roots=[], |
| 110 | expected_rev="stale-token-that-does-not-match", |
| 111 | ) |
| 112 | # No write happened: the row is untouched. |
| 113 | row = object_records.get_collection_record("tasks", "t1", base_dir=data_dir, roots=[]) |
| 114 | assert row == {"id": "t1", "status": "open", "assigned_to": ""} |
| 115 | |
| 116 | |
| 117 | def test_omitted_expected_rev_is_last_write_wins(tmp_path): |
| 118 | data_dir = tmp_path / "data" |
| 119 | _seed_task(data_dir) |
| 120 | # No precondition supplied -> behaves exactly as before, no conflict. |
| 121 | updated = object_records.update_collection_record( |
| 122 | "tasks", "t1", {"status": "assigned"}, base_dir=data_dir, roots=[] |
| 123 | ) |
| 124 | assert updated["status"] == "assigned" |
| 125 | |
| 126 | |
| 127 | def test_claim_race_second_writer_conflicts(tmp_path): |
| 128 | """The spec's worked example: two agents read the same open task at the |
| 129 | same `_rev`, both try to claim. First write wins; the second's precondition |
| 130 | now compares against the changed row and fails -- no silent clobber.""" |
| 131 | data_dir = tmp_path / "data" |
| 132 | rev = _seed_task(data_dir) # both A and B read this same token |
| 133 | |
| 134 | # A claims first, with the shared rev -> succeeds. |
| 135 | object_records.update_collection_record( |
| 136 | "tasks", "t1", {"status": "assigned", "assigned_to": "agent-A"}, |
| 137 | base_dir=data_dir, roots=[], expected_rev=rev, |
| 138 | ) |
| 139 | |
| 140 | # B claims with the SAME (now stale) rev -> conflict, no overwrite. |
| 141 | with pytest.raises(object_records.VersionConflictError): |
| 142 | object_records.update_collection_record( |
| 143 | "tasks", "t1", {"status": "assigned", "assigned_to": "agent-B"}, |
| 144 | base_dir=data_dir, roots=[], expected_rev=rev, |
| 145 | ) |
| 146 | |
| 147 | row = object_records.get_collection_record("tasks", "t1", base_dir=data_dir, roots=[]) |
| 148 | assert row["assigned_to"] == "agent-A" # A holds it; B never clobbered |
| 149 | |
| 150 | |
| 151 | def test_new_rev_after_write_is_usable_for_next_update(tmp_path): |
| 152 | """A read-modify-write loop can chain: the rev of the just-written row is |
| 153 | the precondition for the next write.""" |
| 154 | data_dir = tmp_path / "data" |
| 155 | rev1 = _seed_task(data_dir) |
| 156 | r1 = object_records.update_collection_record( |
| 157 | "tasks", "t1", {"status": "assigned"}, base_dir=data_dir, roots=[], expected_rev=rev1 |
| 158 | ) |
| 159 | rev2 = object_records.compute_record_rev(r1) |
| 160 | assert rev2 != rev1 |
| 161 | # The chained write succeeds against the fresh token. |
| 162 | object_records.update_collection_record( |
| 163 | "tasks", "t1", {"assigned_to": "agent-A"}, base_dir=data_dir, roots=[], expected_rev=rev2 |
| 164 | ) |
| 165 | # But the original token is now stale. |
| 166 | with pytest.raises(object_records.VersionConflictError): |
| 167 | object_records.update_collection_record( |
| 168 | "tasks", "t1", {"status": "done"}, base_dir=data_dir, roots=[], expected_rev=rev1 |
| 169 | ) |
| 170 | |
| 171 | |
| 172 | # --------------------------------------------------------------------------- |
| 173 | # MCP bridge -- precondition rides a reserved body key (no header channel) |
| 174 | # --------------------------------------------------------------------------- |
| 175 | |
| 176 | |
| 177 | def test_mcp_update_record_without_expected_rev_sends_plain_changes(): |
| 178 | method, path, query, body = object_mcp.tool_route( |
| 179 | "update_record", |
| 180 | {"collection": "tasks", "record_id": "t1", "changes": {"status": "assigned"}}, |
| 181 | ) |
| 182 | assert method == "PUT" |
| 183 | assert json.loads(body) == {"status": "assigned"} # no expected_rev key injected |
| 184 | |
| 185 | |
| 186 | def test_mcp_update_record_threads_expected_rev_into_body(): |
| 187 | method, path, query, body = object_mcp.tool_route( |
| 188 | "update_record", |
| 189 | { |
| 190 | "collection": "tasks", |
| 191 | "record_id": "t1", |
| 192 | "changes": {"status": "assigned"}, |
| 193 | "expected_rev": "abc123", |
| 194 | }, |
| 195 | ) |
| 196 | payload = json.loads(body) |
| 197 | assert payload["status"] == "assigned" |
| 198 | assert payload["expected_rev"] == "abc123" |
| 199 | |
| 200 | |
| 201 | def test_mcp_update_record_rejects_non_string_expected_rev(): |
| 202 | with pytest.raises(ValueError): |
| 203 | object_mcp.tool_route( |
| 204 | "update_record", |
| 205 | {"collection": "tasks", "record_id": "t1", "changes": {}, "expected_rev": 5}, |
| 206 | ) |
| 207 | |
| 208 | |
| 209 | # --------------------------------------------------------------------------- |
| 210 | # `revs` on the LIST read -- 63's missing half |
| 211 | # |
| 212 | # Single-record reads have always returned `_rev`. List reads did not, so a |
| 213 | # claiming agent had to GET each candidate individually just to obtain a rev |
| 214 | # before it could claim safely with If-Match: an extra round trip per attempt, |
| 215 | # on the exact path 63 exists for ("claim becomes race-safe"). A list that |
| 216 | # hands back rows you cannot act on without re-reading them made the caller |
| 217 | # do the work twice. |
| 218 | |
| 219 | import sys as _sys # noqa: E402 |
| 220 | _sys.path.insert(0, str(Path(__file__).resolve().parent)) |
| 221 | from test_object_server import ( # noqa: E402 |
| 222 | auth_headers, enable_admin_token, request, write_records, write_source, |
| 223 | ) |
| 224 | |
| 225 | |
| 226 | def _contacts_box(tmp_path, monkeypatch, rows="id\tname\nc1\tAda\nc2\tGrace\n"): |
| 227 | root, data_dir = tmp_path / "objects", tmp_path / "data" |
| 228 | write_source(root / "contacts" / "directory.py", "def GET(request):\n return {}\n") |
| 229 | write_records(data_dir, "contacts", rows) |
| 230 | monkeypatch.setenv("DBBASIC_OBJECTS_DIR", str(root)) |
| 231 | monkeypatch.setenv("DBBASIC_DATA_DIR", str(data_dir)) |
| 232 | enable_admin_token(monkeypatch) |
| 233 | return data_dir |
| 234 | |
| 235 | |
| 236 | def test_a_list_read_hands_back_a_rev_for_every_row(tmp_path, monkeypatch): |
| 237 | _contacts_box(tmp_path, monkeypatch) |
| 238 | status, _, payload = request("/admin/collections/contacts/records", |
| 239 | headers=auth_headers()) |
| 240 | assert status == 200 |
| 241 | assert set(payload["revs"]) == {"c1", "c2"} |
| 242 | assert all(len(rev) == 64 for rev in payload["revs"].values()) |
| 243 | |
| 244 | |
| 245 | def test_the_list_rev_is_the_same_token_the_single_read_gives(tmp_path, monkeypatch): |
| 246 | """If these two ever disagreed, an If-Match built from a list would 409 |
| 247 | forever while the identical one from a detail read succeeded -- the |
| 248 | worst kind of bug, because it looks like a race that is not there.""" |
| 249 | _contacts_box(tmp_path, monkeypatch) |
| 250 | _, _, listed = request("/admin/collections/contacts/records", |
| 251 | headers=auth_headers()) |
| 252 | _, _, single = request("/admin/collections/contacts/records/c1", |
| 253 | headers=auth_headers()) |
| 254 | assert listed["revs"]["c1"] == single["_rev"] |
| 255 | |
| 256 | |
| 257 | def test_a_rev_from_a_list_actually_claims(tmp_path, monkeypatch): |
| 258 | """The whole point, end to end: list, claim with the listed rev, and a |
| 259 | second claim holding the same now-stale rev loses.""" |
| 260 | _contacts_box(tmp_path, monkeypatch) |
| 261 | _, _, listed = request("/admin/collections/contacts/records", |
| 262 | headers=auth_headers()) |
| 263 | rev = listed["revs"]["c1"] |
| 264 | |
| 265 | first = request("/admin/collections/contacts/records/c1", method="PUT", |
| 266 | body=json.dumps({"name": "Ada L"}).encode(), |
| 267 | headers=auth_headers() + [("if-match", rev)]) |
| 268 | assert first[0] == 200 |
| 269 | |
| 270 | second = request("/admin/collections/contacts/records/c1", method="PUT", |
| 271 | body=json.dumps({"name": "Somebody Else"}).encode(), |
| 272 | headers=auth_headers() + [("if-match", rev)]) |
| 273 | assert second[0] == 409 |
| 274 | |
| 275 | |
| 276 | def test_only_the_returned_window_is_hashed(tmp_path, monkeypatch): |
| 277 | """One sha256 per RETURNED row, never per matching row, so a narrow |
| 278 | page over a large collection stays cheap.""" |
| 279 | rows = "id\tname\n" + "".join(f"c{n}\tName{n}\n" for n in range(1, 51)) |
| 280 | _contacts_box(tmp_path, monkeypatch, rows=rows) |
| 281 | _, _, payload = request("/admin/collections/contacts/records", |
| 282 | query_string="limit=5", headers=auth_headers()) |
| 283 | assert payload["count"] == 5 |
| 284 | assert payload["total"] == 50 |
| 285 | assert len(payload["revs"]) == 5 |
| 286 | assert set(payload["revs"]) == {row["id"] for row in payload["records"]} |
| 287 | |
| 288 | |
| 289 | def test_revs_are_a_sibling_map_never_merged_into_the_rows(tmp_path, monkeypatch): |
| 290 | """The record shape is a contract: the single-record read documents |
| 291 | `_rev` as sibling metadata that must never collide with a schema field |
| 292 | or appear on write-back. A list is the one place records are most |
| 293 | likely to be echoed straight into a write, so merging it there would |
| 294 | break the rule where it matters most.""" |
| 295 | _contacts_box(tmp_path, monkeypatch) |
| 296 | _, _, payload = request("/admin/collections/contacts/records", |
| 297 | headers=auth_headers()) |
| 298 | for row in payload["records"]: |
| 299 | assert "_rev" not in row |
| 300 | |
| 301 | |
| 302 | def test_the_flag_governs_the_list_too(tmp_path, monkeypatch): |
| 303 | """With the precondition ignored, shipping revs would hand callers a |
| 304 | token that buys them nothing -- and every If-Match built from it would |
| 305 | silently succeed against a changed row.""" |
| 306 | _contacts_box(tmp_path, monkeypatch) |
| 307 | monkeypatch.setenv("DBBASIC_ENABLE_CONCURRENCY", "false") |
| 308 | _, _, payload = request("/admin/collections/contacts/records", |
| 309 | headers=auth_headers()) |
| 310 | assert "revs" not in payload |