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
http_api_contract.py · 9.4 KB · 196 lines
| 1 | """Compatibility constants for the DBBASIC Object HTTP API. |
| 2 | |
| 3 | This is not a router. It records the response fields and paths existing clients |
| 4 | expect so future server code can be tested against the same contract. |
| 5 | """ |
| 6 | |
| 7 | from __future__ import annotations |
| 8 | |
| 9 | from collections.abc import Mapping |
| 10 | from typing import Any |
| 11 | |
| 12 | OBJECTS_PATH = "/objects" |
| 13 | OBJECT_PATH = "/objects/{object_id}" |
| 14 | OBJECT_STATION_PATH = "/objects/{object_id}@{station_id}" |
| 15 | ADMIN_OBJECTS_PATH = "/admin/objects" |
| 16 | ADMIN_OBJECT_PATH = "/admin/objects/{object_id}" |
| 17 | ADMIN_COLLECTIONS_PATH = "/admin/collections" |
| 18 | ADMIN_COLLECTION_PATH = "/admin/collections/{collection}" |
| 19 | ADMIN_COLLECTION_RECORDS_PATH = "/admin/collections/{collection}/records" |
| 20 | ADMIN_COLLECTION_RECORD_PATH = "/admin/collections/{collection}/records/{record_id}" |
| 21 | ADMIN_COLLECTION_CHANGES_PATH = "/admin/collections/{collection}/changes" |
| 22 | ADMIN_COLLECTION_RECORD_CHANGES_PATH = ( |
| 23 | "/admin/collections/{collection}/records/{record_id}/changes" |
| 24 | ) |
| 25 | ADMIN_SCHEMAS_PATH = "/admin/schemas" |
| 26 | ADMIN_SCHEMA_PATH = "/admin/schemas/{collection}" |
| 27 | ADMIN_IDENTITY_ACCOUNTS_PATH = "/admin/identity/accounts" |
| 28 | ADMIN_IDENTITY_ACCOUNT_PATH = "/admin/identity/accounts/{account_id}" |
| 29 | ADMIN_IDENTITY_USERS_PATH = "/admin/identity/users" |
| 30 | ADMIN_IDENTITY_USER_PATH = "/admin/identity/users/{user_id}" |
| 31 | ADMIN_IDENTITY_USER_PASSWORD_PATH = "/admin/identity/users/{user_id}/password" |
| 32 | ADMIN_IDENTITY_SESSIONS_PATH = "/admin/identity/sessions" |
| 33 | ADMIN_IDENTITY_SESSION_PATH = "/admin/identity/sessions/{session_id}" |
| 34 | COLLECTIONS_PATH = "/collections" |
| 35 | COLLECTION_PATH = "/collections/{collection}" |
| 36 | COLLECTION_RECORDS_PATH = "/collections/{collection}/records" |
| 37 | COLLECTION_RECORD_PATH = "/collections/{collection}/records/{record_id}" |
| 38 | COLLECTION_CHANGES_PATH = "/collections/{collection}/changes" |
| 39 | COLLECTION_RECORD_CHANGES_PATH = "/collections/{collection}/records/{record_id}/changes" |
| 40 | SCHEMAS_PATH = "/schemas" |
| 41 | SCHEMA_PATH = "/schemas/{collection}" |
| 42 | EVENTS_PATH = "/events" |
| 43 | EVENT_DELIVERIES_PATH = "/events/deliveries" |
| 44 | EVENT_SUBSCRIPTIONS_PATH = "/events/subscriptions" |
| 45 | PACKAGES_PATH = "/packages" |
| 46 | PACKAGE_PATH = "/packages/{package_id}" |
| 47 | PACKAGE_INSTALL_PATH = "/packages/{package_id}/install" |
| 48 | PACKAGE_RESTORE_PATH = "/packages/{package_id}/restore" |
| 49 | PACKAGE_CHANGES_PATH = "/packages/{package_id}/changes" |
| 50 | ADMIN_STATUS_PATH = "/admin/status" |
| 51 | ADMIN_STORAGE_PATH = "/admin/storage" |
| 52 | ADMIN_COLLECTION_COMPACT_PATH = "/admin/collections/{collection}/compact" |
| 53 | ADMIN_CHANGES_PATH = "/admin/changes" |
| 54 | ADMIN_OPS_PATH = "/admin/ops" |
| 55 | ADMIN_BACKUPS_PATH = "/admin/backups" |
| 56 | ADMIN_FILES_PATH = "/admin/files" |
| 57 | ADMIN_OBJECT_FILES_PATH = "/admin/files/{object_id}" |
| 58 | ADMIN_RECONCILES_PATH = "/admin/reconciles" |
| 59 | ADMIN_RECONCILE_PATH = "/admin/reconciles/{id}" |
| 60 | ADMIN_RECONCILE_RESOLVE_PATH = "/admin/reconciles/{id}/resolve" |
| 61 | WEBHOOKS_PATH = "/webhooks" |
| 62 | DAEMON_STATUS_PATH = "/daemon/status" |
| 63 | DAEMON_SCHEDULER_TASKS_PATH = "/daemon/scheduler/tasks" |
| 64 | DAEMON_SCHEDULER_TASK_PATH = "/daemon/scheduler/tasks/{task_id}" |
| 65 | DAEMON_QUEUE_MESSAGES_PATH = "/daemon/queue/messages" |
| 66 | DAEMON_QUEUE_MESSAGE_PATH = "/daemon/queue/messages/{message_id}" |
| 67 | IDENTITY_PATH = "/identity" |
| 68 | IDENTITY_ACCOUNTS_PATH = "/identity/accounts" |
| 69 | IDENTITY_ACCOUNT_PATH = "/identity/accounts/{account_id}" |
| 70 | IDENTITY_USERS_PATH = "/identity/users" |
| 71 | IDENTITY_USER_PATH = "/identity/users/{user_id}" |
| 72 | IDENTITY_USER_PASSWORD_PATH = "/identity/users/{user_id}/password" |
| 73 | IDENTITY_SESSIONS_PATH = "/identity/sessions" |
| 74 | IDENTITY_SESSION_PATH = "/identity/sessions/{session_id}" |
| 75 | IDENTITY_CURRENT_SESSION_PATH = "/identity/session" |
| 76 | LOGIN_PATH = "/login" |
| 77 | LOGOUT_PATH = "/logout" |
| 78 | SIGNUP_PATH = "/signup" |
| 79 | VERIFY_EMAIL_PATH = "/verify" |
| 80 | PASSWORD_RESET_PATH = "/reset" |
| 81 | PASSWORD_RESET_CONFIRM_PATH = "/reset/confirm" |
| 82 | MCP_PATH = "/api/mcp" |
| 83 | SEARCH_PATH = "/api/search" |
| 84 | AI_CHAT_PATH = "/api/ai/chat" |
| 85 | TTS_PATH = "/api/tts" |
| 86 | STT_PATH = "/api/stt" |
| 87 | READ_PATH = "/api/read" |
| 88 | USER_FILES_PATH = "/api/files" |
| 89 | WEBDAV_PATH = "/dav" |
| 90 | SCHEMA_META_PATH = "/api/schema" |
| 91 | FLAGS_PATH = "/api/flags" |
| 92 | ACTIVITY_PATH = "/api/activity" |
| 93 | PREFS_PATH = "/prefs" |
| 94 | PREF_PATH = "/prefs/{key}" |
| 95 | PERMISSIONS_POLICY_PATH = "/permissions/policy" |
| 96 | PERMISSIONS_STATUS_PATH = "/permissions/status" |
| 97 | PERMISSIONS_CHECK_PATH = "/permissions/check" |
| 98 | PERMISSIONS_AUDIT_PATH = "/permissions/audit" |
| 99 | |
| 100 | SOURCE_QUERY = {"source": "true", "format": "json"} |
| 101 | STATE_QUERY = {"state": "true"} |
| 102 | METADATA_QUERY = {"metadata": "true"} |
| 103 | FILES_QUERY = {"files": "true"} |
| 104 | FILE_QUERY = {"file": "name"} |
| 105 | LOGS_QUERY = {"logs": "true", "format": "json", "limit": "100"} |
| 106 | SOURCE_CHANGES_QUERY = {"source_changes": "true", "limit": "100"} |
| 107 | CHANGES_QUERY = {"changes": "true", "limit": "100"} |
| 108 | VERSIONS_QUERY = {"versions": "true", "limit": "10"} |
| 109 | |
| 110 | RESPONSE_FIELDS: dict[str, frozenset[str]] = { |
| 111 | "object_list": frozenset({"status", "objects", "count"}), |
| 112 | "collection_list": frozenset({"status", "collections", "count"}), |
| 113 | "collection": frozenset({"status", "collection"}), |
| 114 | "record_list": frozenset({"status", "collection", "records", "count", "total"}), |
| 115 | "record": frozenset({"status", "collection", "record"}), |
| 116 | "record_changes": frozenset({"status", "collection", "changes", "count", "total"}), |
| 117 | "schema_list": frozenset({"status", "schemas", "count"}), |
| 118 | "schema": frozenset({"status", "schema"}), |
| 119 | "event_list": frozenset({"status", "events", "count", "total"}), |
| 120 | "event": frozenset({"status", "event"}), |
| 121 | "event_retention": frozenset({"status", "retention"}), |
| 122 | "event_delivery_list": frozenset({"status", "deliveries", "count", "total"}), |
| 123 | "event_subscription_list": frozenset( |
| 124 | {"status", "subscriptions", "count", "total"} |
| 125 | ), |
| 126 | "event_subscription": frozenset({"status", "subscription"}), |
| 127 | "package_list": frozenset({"status", "packages", "count"}), |
| 128 | "package": frozenset({"status", "package"}), |
| 129 | "package_dry_run": frozenset({"status", "dry_run", "change"}), |
| 130 | "package_install": frozenset({"status", "install", "changes", "restore_point"}), |
| 131 | "package_restore": frozenset( |
| 132 | {"status", "restore", "changes", "restore_point", "from_change"} |
| 133 | ), |
| 134 | "package_changes": frozenset({"status", "package_id", "changes", "count", "total"}), |
| 135 | "admin_changes": frozenset({"status", "changes", "count", "total"}), |
| 136 | "admin_status": frozenset( |
| 137 | {"status", "timestamp", "version", "health", "inventory", "capabilities", "packages"} |
| 138 | ), |
| 139 | "admin_storage": frozenset({"status", "append_collections"}), |
| 140 | "collection_compact": frozenset( |
| 141 | {"status", "collection", "rows_before", "rows_after", "bytes_before", "bytes_after", "duration_ms"} |
| 142 | ), |
| 143 | "daemon_status": frozenset( |
| 144 | {"status", "timestamp", "daemon", "scheduler", "queue", "events", "cleanup"} |
| 145 | ), |
| 146 | "daemon_scheduler_task_list": frozenset({"status", "tasks", "count", "total"}), |
| 147 | "daemon_scheduler_task": frozenset({"status", "task"}), |
| 148 | "daemon_queue_message_list": frozenset({"status", "messages", "count", "total"}), |
| 149 | "daemon_queue_message": frozenset({"status", "message"}), |
| 150 | "identity": frozenset({"status", "subject", "auth", "permissions"}), |
| 151 | "identity_account_list": frozenset({"status", "accounts", "count"}), |
| 152 | "identity_account": frozenset({"status", "account"}), |
| 153 | "identity_user_list": frozenset({"status", "users", "count"}), |
| 154 | "identity_user": frozenset({"status", "user"}), |
| 155 | "identity_session_list": frozenset({"status", "sessions", "count"}), |
| 156 | "identity_session_create": frozenset({"status", "session", "token"}), |
| 157 | "identity_session": frozenset({"status", "session"}), |
| 158 | "identity_current_session": frozenset({"status", "session"}), |
| 159 | "create_object": frozenset({"status", "object_id", "message"}), |
| 160 | "error": frozenset({"status", "error"}), |
| 161 | "source": frozenset({"status", "object_id", "source"}), |
| 162 | "update_source": frozenset({"status", "message", "version_id", "object_id"}), |
| 163 | "state": frozenset({"status", "object_id", "state"}), |
| 164 | "metadata": frozenset({"status", "object_id", "metadata"}), |
| 165 | "files": frozenset({"status", "object_id", "files", "count"}), |
| 166 | "file_list": frozenset({"status", "files", "count", "total"}), |
| 167 | "logs": frozenset({"status", "object_id", "logs", "count"}), |
| 168 | "source_changes": frozenset({"status", "object_id", "changes", "count", "total"}), |
| 169 | "object_changes": frozenset({"status", "object_id", "changes", "count", "total"}), |
| 170 | "versions": frozenset({"status", "object_id", "versions", "count"}), |
| 171 | "version": frozenset({"status", "object_id", "version"}), |
| 172 | "rollback": frozenset({"status", "message", "version_id", "object_id"}), |
| 173 | "destroy_object": frozenset({"status", "message", "object_id"}), |
| 174 | "permissions_policy": frozenset({"status", "policy"}), |
| 175 | "permissions_status": frozenset( |
| 176 | {"status", "permissions", "identity", "policy", "coverage", "readiness", "warnings"} |
| 177 | ), |
| 178 | "permissions_check": frozenset({"status", "decision"}), |
| 179 | "permissions_audit": frozenset({"status", "entries", "count"}), |
| 180 | "prefs": frozenset({"status", "prefs"}), |
| 181 | "pref": frozenset({"status", "key", "value"}), |
| 182 | "flags": frozenset({"status", "flags"}), |
| 183 | } |
| 184 | |
| 185 | |
| 186 | def required_response_fields(response_name: str) -> frozenset[str]: |
| 187 | """Return required top-level fields for a named compatibility response.""" |
| 188 | try: |
| 189 | return RESPONSE_FIELDS[response_name] |
| 190 | except KeyError as exc: |
| 191 | raise ValueError(f"Unknown HTTP API response shape: {response_name}") from exc |
| 192 | |
| 193 | |
| 194 | def missing_response_fields(response_name: str, payload: Mapping[str, Any]) -> set[str]: |
| 195 | """Return required compatibility fields missing from a response payload.""" |
| 196 | return set(required_response_fields(response_name) - payload.keys()) |