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/tests/test_http_api_contract.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
test_http_api_contract.py · 18.7 KB · 525 lines
1from pathlib import Path
2
3import pytest
4
5import http_api_contract
6
7
8def test_contract_keeps_objects_paths_as_public_surface():
9 assert http_api_contract.OBJECTS_PATH == "/objects"
10 assert http_api_contract.OBJECT_PATH == "/objects/{object_id}"
11 assert http_api_contract.OBJECT_STATION_PATH == "/objects/{object_id}@{station_id}"
12 assert http_api_contract.ADMIN_OBJECTS_PATH == "/admin/objects"
13 assert http_api_contract.ADMIN_OBJECT_PATH == "/admin/objects/{object_id}"
14 assert http_api_contract.ADMIN_FILES_PATH == "/admin/files"
15 assert http_api_contract.ADMIN_OBJECT_FILES_PATH == "/admin/files/{object_id}"
16 assert http_api_contract.ADMIN_COLLECTIONS_PATH == "/admin/collections"
17 assert http_api_contract.ADMIN_COLLECTION_PATH == "/admin/collections/{collection}"
18 assert (
19 http_api_contract.ADMIN_COLLECTION_RECORDS_PATH
20 == "/admin/collections/{collection}/records"
21 )
22 assert (
23 http_api_contract.ADMIN_COLLECTION_RECORD_PATH
24 == "/admin/collections/{collection}/records/{record_id}"
25 )
26 assert (
27 http_api_contract.ADMIN_COLLECTION_CHANGES_PATH
28 == "/admin/collections/{collection}/changes"
29 )
30 assert (
31 http_api_contract.ADMIN_COLLECTION_RECORD_CHANGES_PATH
32 == "/admin/collections/{collection}/records/{record_id}/changes"
33 )
34 assert http_api_contract.ADMIN_SCHEMAS_PATH == "/admin/schemas"
35 assert http_api_contract.ADMIN_SCHEMA_PATH == "/admin/schemas/{collection}"
36 assert http_api_contract.ADMIN_IDENTITY_ACCOUNTS_PATH == "/admin/identity/accounts"
37 assert (
38 http_api_contract.ADMIN_IDENTITY_ACCOUNT_PATH
39 == "/admin/identity/accounts/{account_id}"
40 )
41 assert http_api_contract.ADMIN_IDENTITY_USERS_PATH == "/admin/identity/users"
42 assert http_api_contract.ADMIN_IDENTITY_USER_PATH == "/admin/identity/users/{user_id}"
43 assert http_api_contract.ADMIN_IDENTITY_SESSIONS_PATH == "/admin/identity/sessions"
44 assert (
45 http_api_contract.ADMIN_IDENTITY_SESSION_PATH
46 == "/admin/identity/sessions/{session_id}"
47 )
48 assert http_api_contract.COLLECTIONS_PATH == "/collections"
49 assert http_api_contract.COLLECTION_PATH == "/collections/{collection}"
50 assert http_api_contract.COLLECTION_RECORDS_PATH == "/collections/{collection}/records"
51 assert http_api_contract.COLLECTION_RECORD_PATH == "/collections/{collection}/records/{record_id}"
52 assert http_api_contract.COLLECTION_CHANGES_PATH == "/collections/{collection}/changes"
53 assert (
54 http_api_contract.COLLECTION_RECORD_CHANGES_PATH
55 == "/collections/{collection}/records/{record_id}/changes"
56 )
57 assert http_api_contract.SCHEMAS_PATH == "/schemas"
58 assert http_api_contract.SCHEMA_PATH == "/schemas/{collection}"
59 assert http_api_contract.EVENTS_PATH == "/events"
60 assert http_api_contract.EVENT_DELIVERIES_PATH == "/events/deliveries"
61 assert http_api_contract.EVENT_SUBSCRIPTIONS_PATH == "/events/subscriptions"
62 assert http_api_contract.PACKAGES_PATH == "/packages"
63 assert http_api_contract.PACKAGE_PATH == "/packages/{package_id}"
64 assert http_api_contract.PACKAGE_INSTALL_PATH == "/packages/{package_id}/install"
65 assert http_api_contract.PACKAGE_RESTORE_PATH == "/packages/{package_id}/restore"
66 assert http_api_contract.PACKAGE_CHANGES_PATH == "/packages/{package_id}/changes"
67 assert http_api_contract.ADMIN_STATUS_PATH == "/admin/status"
68 assert http_api_contract.ADMIN_CHANGES_PATH == "/admin/changes"
69 assert http_api_contract.DAEMON_STATUS_PATH == "/daemon/status"
70 assert http_api_contract.DAEMON_SCHEDULER_TASKS_PATH == "/daemon/scheduler/tasks"
71 assert http_api_contract.DAEMON_SCHEDULER_TASK_PATH == "/daemon/scheduler/tasks/{task_id}"
72 assert http_api_contract.DAEMON_QUEUE_MESSAGES_PATH == "/daemon/queue/messages"
73 assert http_api_contract.DAEMON_QUEUE_MESSAGE_PATH == "/daemon/queue/messages/{message_id}"
74 assert http_api_contract.IDENTITY_PATH == "/identity"
75 assert http_api_contract.IDENTITY_ACCOUNTS_PATH == "/identity/accounts"
76 assert http_api_contract.IDENTITY_ACCOUNT_PATH == "/identity/accounts/{account_id}"
77 assert http_api_contract.IDENTITY_USERS_PATH == "/identity/users"
78 assert http_api_contract.IDENTITY_USER_PATH == "/identity/users/{user_id}"
79 assert http_api_contract.IDENTITY_SESSIONS_PATH == "/identity/sessions"
80 assert http_api_contract.IDENTITY_SESSION_PATH == "/identity/sessions/{session_id}"
81 assert http_api_contract.IDENTITY_CURRENT_SESSION_PATH == "/identity/session"
82 assert http_api_contract.PERMISSIONS_POLICY_PATH == "/permissions/policy"
83 assert http_api_contract.PERMISSIONS_STATUS_PATH == "/permissions/status"
84 assert http_api_contract.PERMISSIONS_CHECK_PATH == "/permissions/check"
85 assert http_api_contract.PERMISSIONS_AUDIT_PATH == "/permissions/audit"
86
87
88def test_contract_keeps_existing_introspection_query_flags():
89 assert http_api_contract.SOURCE_QUERY == {"source": "true", "format": "json"}
90 assert http_api_contract.STATE_QUERY == {"state": "true"}
91 assert http_api_contract.METADATA_QUERY == {"metadata": "true"}
92 assert http_api_contract.FILES_QUERY == {"files": "true"}
93 assert http_api_contract.FILE_QUERY == {"file": "name"}
94 assert http_api_contract.LOGS_QUERY == {
95 "logs": "true",
96 "format": "json",
97 "limit": "100",
98 }
99 assert http_api_contract.SOURCE_CHANGES_QUERY == {
100 "source_changes": "true",
101 "limit": "100",
102 }
103 assert http_api_contract.CHANGES_QUERY == {"changes": "true", "limit": "100"}
104 assert http_api_contract.VERSIONS_QUERY == {"versions": "true", "limit": "10"}
105
106
107@pytest.mark.parametrize(
108 ("response_name", "payload"),
109 [
110 (
111 "object_list",
112 {"status": "ok", "objects": [], "count": 0},
113 ),
114 (
115 "collection_list",
116 {"status": "ok", "collections": [], "count": 0},
117 ),
118 (
119 "collection",
120 {"status": "ok", "collection": {"name": "site", "object_count": 1}},
121 ),
122 (
123 "record_list",
124 {
125 "status": "ok",
126 "collection": "contacts",
127 "records": [],
128 "count": 0,
129 "total": 0,
130 },
131 ),
132 (
133 "record",
134 {"status": "ok", "collection": "contacts", "record": {"id": "c1"}},
135 ),
136 (
137 "record_changes",
138 {"status": "ok", "collection": "contacts", "changes": [], "count": 0, "total": 0},
139 ),
140 (
141 "schema_list",
142 {"status": "ok", "schemas": [], "count": 0},
143 ),
144 (
145 "schema",
146 {"status": "ok", "schema": {"name": "invoices", "fields": []}},
147 ),
148 (
149 "event_list",
150 {"status": "ok", "events": [], "count": 0, "total": 0},
151 ),
152 (
153 "event",
154 {"status": "ok", "event": {"id": "evt_1", "event_type": "invoice.created"}},
155 ),
156 (
157 "event_retention",
158 {"status": "ok", "retention": {"deleted": 0, "kept": 0}},
159 ),
160 (
161 "event_delivery_list",
162 {"status": "ok", "deliveries": [], "count": 0, "total": 0},
163 ),
164 (
165 "event_subscription_list",
166 {"status": "ok", "subscriptions": [], "count": 0, "total": 0},
167 ),
168 (
169 "event_subscription",
170 {"status": "ok", "subscription": {"id": "scroll"}},
171 ),
172 (
173 "package_list",
174 {"status": "ok", "packages": [], "count": 0},
175 ),
176 (
177 "package",
178 {"status": "ok", "package": {"id": "hello-world"}},
179 ),
180 (
181 "package_dry_run",
182 {
183 "status": "ok",
184 "dry_run": {"package": {"id": "hello-world"}},
185 "change": {"change_id": "chg_1"},
186 },
187 ),
188 (
189 "package_install",
190 {
191 "status": "ok",
192 "install": {"package": {"id": "hello-world"}},
193 "changes": {"requested": {"change_id": "chg_1"}},
194 "restore_point": {"path": "data/backups/restore.tar.gz"},
195 },
196 ),
197 (
198 "package_restore",
199 {
200 "status": "ok",
201 "restore": {"backup_path": "data/backups/restore.tar.gz"},
202 "changes": {"rolled_back": {"change_id": "chg_2"}},
203 "restore_point": {"path": "data/backups/restore.tar.gz"},
204 "from_change": {"change_id": "chg_1"},
205 },
206 ),
207 (
208 "package_changes",
209 {
210 "status": "ok",
211 "package_id": "hello-world",
212 "changes": [],
213 "count": 0,
214 "total": 0,
215 },
216 ),
217 (
218 "admin_changes",
219 {"status": "ok", "changes": [], "count": 0, "total": 0},
220 ),
221 (
222 "file_list",
223 {"status": "ok", "files": [], "count": 0, "total": 0},
224 ),
225 (
226 "admin_status",
227 {
228 "status": "ok",
229 "timestamp": "2026-01-01T00:00:00+00:00",
230 "version": "0.0.1",
231 "health": {"status": "ok"},
232 "inventory": {"objects": 0},
233 "capabilities": {"source_writes": {"enabled": False}},
234 "packages": [],
235 },
236 ),
237 (
238 "daemon_status",
239 {
240 "status": "ok",
241 "timestamp": "2026-01-01T00:00:00+00:00",
242 "daemon": {"mode": "polling"},
243 "scheduler": {"tasks": {"active": 0}},
244 "queue": {"messages": {"pending_visible": 0}},
245 "events": {"events": {"total": 0}},
246 "cleanup": {"event_retention": {}},
247 },
248 ),
249 (
250 "daemon_scheduler_task_list",
251 {"status": "ok", "tasks": [], "count": 0, "total": 0},
252 ),
253 (
254 "daemon_scheduler_task",
255 {"status": "ok", "task": {"id": "task_1"}},
256 ),
257 (
258 "daemon_queue_message_list",
259 {"status": "ok", "messages": [], "count": 0, "total": 0},
260 ),
261 (
262 "daemon_queue_message",
263 {"status": "ok", "message": {"id": "msg_1"}},
264 ),
265 (
266 "identity",
267 {
268 "status": "ok",
269 "subject": {"authenticated": False},
270 "auth": {"method": "anonymous"},
271 "permissions": {"enforcement_enabled": False},
272 },
273 ),
274 (
275 "identity_account_list",
276 {"status": "ok", "accounts": [], "count": 0},
277 ),
278 (
279 "identity_account",
280 {"status": "ok", "account": {"account_id": "acme"}},
281 ),
282 (
283 "identity_user_list",
284 {"status": "ok", "users": [], "count": 0},
285 ),
286 (
287 "identity_user",
288 {"status": "ok", "user": {"user_id": "u_7"}},
289 ),
290 (
291 "identity_session_list",
292 {"status": "ok", "sessions": [], "count": 0},
293 ),
294 (
295 "identity_session_create",
296 {"status": "ok", "session": {"session_id": "sess_123"}, "token": "once"},
297 ),
298 (
299 "identity_session",
300 {"status": "ok", "session": {"session_id": "sess_123"}},
301 ),
302 (
303 "identity_current_session",
304 {"status": "ok", "session": {"session_id": "sess_123"}},
305 ),
306 (
307 "create_object",
308 {"status": "ok", "object_id": "u_42_deals", "message": "created"},
309 ),
310 (
311 "error",
312 {"status": "error", "error": "Execution failed: boom"},
313 ),
314 (
315 "source",
316 {"status": "ok", "object_id": "basics_counter", "source": "def GET(request): ..."},
317 ),
318 (
319 "update_source",
320 {
321 "status": "ok",
322 "message": "Code updated to version 2",
323 "version_id": 2,
324 "object_id": "u_42_deals",
325 },
326 ),
327 (
328 "state",
329 {"status": "ok", "object_id": "basics_counter", "state": {"count": "3"}},
330 ),
331 (
332 "metadata",
333 {
334 "status": "ok",
335 "object_id": "basics_counter",
336 "metadata": {"version_count": 2},
337 },
338 ),
339 (
340 "files",
341 {"status": "ok", "object_id": "basics_counter", "files": [], "count": 0},
342 ),
343 (
344 "logs",
345 {"status": "ok", "object_id": "basics_counter", "logs": [], "count": 0},
346 ),
347 (
348 "source_changes",
349 {
350 "status": "ok",
351 "object_id": "basics_counter",
352 "changes": [],
353 "count": 0,
354 "total": 0,
355 },
356 ),
357 (
358 "object_changes",
359 {
360 "status": "ok",
361 "object_id": "basics_counter",
362 "changes": [],
363 "count": 0,
364 "total": 0,
365 },
366 ),
367 (
368 "versions",
369 {"status": "ok", "object_id": "basics_counter", "versions": [], "count": 0},
370 ),
371 (
372 "version",
373 {"status": "ok", "object_id": "basics_counter", "version": {"version_id": 2}},
374 ),
375 (
376 "rollback",
377 {
378 "status": "ok",
379 "message": "Rolled back to version 1",
380 "version_id": 1,
381 "object_id": "u_42_deals",
382 },
383 ),
384 (
385 "destroy_object",
386 {"status": "ok", "message": "Object destroyed: u_42_deals", "object_id": "u_42_deals"},
387 ),
388 (
389 "permissions_policy",
390 {"status": "ok", "policy": {"access_mode": "role_based"}},
391 ),
392 (
393 "permissions_status",
394 {
395 "status": "ok",
396 "permissions": {"enforcement_enabled": False},
397 "identity": {"users": {"count": 0}},
398 "policy": {"valid": True},
399 "coverage": {"policy_checked": []},
400 "readiness": {"can_enable_enforcement": False, "blockers": []},
401 "warnings": [],
402 },
403 ),
404 (
405 "permissions_check",
406 {"status": "ok", "decision": {"allowed": True}},
407 ),
408 (
409 "permissions_audit",
410 {"status": "ok", "entries": [], "count": 0},
411 ),
412 ],
413)
414def test_existing_client_response_shapes_have_required_fields(response_name, payload):
415 assert http_api_contract.missing_response_fields(response_name, payload) == set()
416
417
418def test_missing_response_fields_reports_contract_breaks():
419 payload = {"status": "ok", "object_id": "basics_counter"}
420
421 assert http_api_contract.missing_response_fields("source", payload) == {"source"}
422
423
424def test_unknown_response_shape_is_rejected():
425 with pytest.raises(ValueError, match="Unknown HTTP API response shape"):
426 http_api_contract.required_response_fields("new_parallel_api")
427
428
429def test_rollback_keeps_legacy_version_id_even_if_new_version_id_is_added():
430 payload = {
431 "status": "ok",
432 "message": "Rolled back to version 1",
433 "version_id": 1,
434 "new_version_id": 3,
435 "object_id": "u_42_deals",
436 }
437
438 assert http_api_contract.missing_response_fields("rollback", payload) == set()
439
440
441def test_http_contract_doc_mentions_required_compatibility_surface():
442 doc = Path("docs/http-api-contract.md").read_text()
443
444 required_fragments = [
445 "GET /objects?format=json",
446 "GET /collections",
447 "GET /collections/{collection}",
448 "GET /collections/{collection}/records",
449 "POST /collections/{collection}/records",
450 "GET /collections/{collection}/records/{record_id}",
451 "PUT /collections/{collection}/records/{record_id}",
452 "DELETE /collections/{collection}/records/{record_id}",
453 "GET /collections/{collection}/changes",
454 "GET /collections/{collection}/records/{record_id}/changes",
455 "GET /schemas",
456 "GET /schemas/{collection}",
457 "GET /schemas/{collection}?versions=true&limit=10",
458 "GET /schemas/{collection}?version=1",
459 "PUT /schemas/{collection}",
460 "POST /schemas/{collection}",
461 "GET /events",
462 "POST /events",
463 "DELETE /events",
464 "GET /events/deliveries",
465 "GET /events/subscriptions",
466 "POST /events/subscriptions",
467 "DELETE /events/subscriptions",
468 "GET /daemon/status",
469 "GET /daemon/scheduler/tasks",
470 "POST /daemon/scheduler/tasks",
471 "PATCH /daemon/scheduler/tasks/{task_id}",
472 "DELETE /daemon/scheduler/tasks/{task_id}",
473 "GET /daemon/queue/messages",
474 "POST /daemon/queue/messages",
475 "PATCH /daemon/queue/messages/{message_id}",
476 "DELETE /daemon/queue/messages/{message_id}",
477 "GET /packages",
478 "GET /packages/{package_id}",
479 "GET /packages/{package_id}?dry_run=true",
480 "POST /packages/{package_id}/install",
481 "GET /packages/{package_id}/changes",
482 "GET /admin/objects",
483 "GET /admin/objects/{object_id}",
484 "GET /admin/files",
485 "GET /admin/files/{object_id}",
486 "GET /admin/collections",
487 "GET /admin/collections/{collection}",
488 "GET /admin/collections/{collection}/records",
489 "GET /admin/collections/{collection}/records/{record_id}",
490 "GET /admin/collections/{collection}/changes",
491 "GET /admin/collections/{collection}/records/{record_id}/changes",
492 "GET /admin/schemas",
493 "GET /admin/schemas/{collection}",
494 "GET /admin/schemas/{collection}?versions=true&limit=10",
495 "GET /admin/schemas/{collection}?version=1",
496 "GET /admin/identity/accounts",
497 "GET /admin/identity/accounts/{account_id}",
498 "GET /admin/identity/users",
499 "GET /admin/identity/users/{user_id}",
500 "GET /admin/identity/sessions",
501 "GET /admin/identity/sessions/{session_id}",
502 "POST /objects",
503 "GET /objects/{object_id}",
504 "PUT /objects/{object_id}?source=true",
505 "POST /objects/{object_id}",
506 "DELETE /objects/{object_id}?destroy=true",
507 "GET /permissions/policy",
508 "PUT /permissions/policy",
509 "GET /permissions/status",
510 "POST /permissions/check",
511 "GET /permissions/audit",
512 "source=true",
513 "state=true",
514 "metadata=true",
515 "files=true",
516 "file=report.txt",
517 "versions=true",
518 "action=rollback",
519 "version_id",
520 "new_version_id",
521 "/api/v1",
522 ]
523
524 for fragment in required_fragments:
525 assert fragment in doc