|
| 1 | +"""Cloudflare D1 explorer — read-only introspection over the D1 HTTP API. |
| 2 | +
|
| 3 | +D1 is SQLite that lives on Cloudflare's edge and is only reachable from a Worker |
| 4 | +or over the REST query endpoint. A Python process (our Discord bot) uses the |
| 5 | +**HTTP Query API**: |
| 6 | +
|
| 7 | + POST /client/v4/accounts/{account_id}/d1/database/{database_id}/query |
| 8 | + Authorization: Bearer <token> |
| 9 | + {"sql": "...", "params": [...]} |
| 10 | +
|
| 11 | +Since D1 *is* SQLite, schema introspection uses ``sqlite_master`` / ``PRAGMA``. |
| 12 | +The HTTP call is injectable (``transport``) so the adapter is unit-testable with |
| 13 | +no network. |
| 14 | +""" |
| 15 | + |
| 16 | +from __future__ import annotations |
| 17 | + |
| 18 | +import asyncio |
| 19 | +import json |
| 20 | +import os |
| 21 | +import urllib.request |
| 22 | +from typing import Any, Callable |
| 23 | + |
| 24 | +from ...core.ports.explorer import Column, Table |
| 25 | + |
| 26 | +_API_ROOT = "https://api.cloudflare.com/client/v4" |
| 27 | + |
| 28 | +# A transport takes (sql, params) and returns the parsed D1 JSON response. |
| 29 | +Transport = Callable[[str, list], dict] |
| 30 | + |
| 31 | + |
| 32 | +class D1Explorer: |
| 33 | + """ExplorerPort backed by Cloudflare D1's HTTP query API.""" |
| 34 | + |
| 35 | + def __init__( |
| 36 | + self, |
| 37 | + account_id: str, |
| 38 | + database_id: str, |
| 39 | + token: str | None = None, |
| 40 | + *, |
| 41 | + transport: Transport | None = None, |
| 42 | + timeout: float = 30.0, |
| 43 | + ) -> None: |
| 44 | + self.account_id = account_id |
| 45 | + self.database_id = database_id |
| 46 | + self._token = token if token is not None else os.environ.get("CLOUDFLARE_API_TOKEN") |
| 47 | + self._timeout = timeout |
| 48 | + self._transport = transport or self._http_transport |
| 49 | + |
| 50 | + # --- ExplorerPort ---------------------------------------------------- |
| 51 | + |
| 52 | + async def list_tables(self) -> list[Table]: |
| 53 | + rows = await self._query( |
| 54 | + "SELECT name FROM sqlite_master WHERE type='table' " |
| 55 | + "AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '_cf_%' ORDER BY name" |
| 56 | + ) |
| 57 | + return [Table(name=r["name"], schema="") for r in rows] |
| 58 | + |
| 59 | + async def describe_table(self, name: str) -> Table: |
| 60 | + rows = await self._query(f"PRAGMA table_info({_ident(name)})") |
| 61 | + cols = [ |
| 62 | + Column(name=r["name"], type=r["type"] or "", nullable=not bool(r["notnull"])) |
| 63 | + for r in rows |
| 64 | + ] |
| 65 | + return Table(name=name, schema="", columns=cols) |
| 66 | + |
| 67 | + async def sample_rows(self, name: str, limit: int = 5) -> list[dict]: |
| 68 | + return await self._query(f"SELECT * FROM {_ident(name)} LIMIT {int(limit)}") |
| 69 | + |
| 70 | + async def execute(self, sql: str, limit: int = 1000) -> list[dict]: |
| 71 | + rows = await self._query(sql) |
| 72 | + return rows[: int(limit)] |
| 73 | + |
| 74 | + # --- internals ------------------------------------------------------- |
| 75 | + |
| 76 | + async def _query(self, sql: str, params: list | None = None) -> list[dict]: |
| 77 | + resp = await asyncio.to_thread(self._transport, sql, params or []) |
| 78 | + if not resp.get("success", False): |
| 79 | + errors = resp.get("errors") or resp.get("messages") or "unknown D1 error" |
| 80 | + raise RuntimeError(f"D1 query failed: {errors}") |
| 81 | + result = resp.get("result") or [] |
| 82 | + if not result: |
| 83 | + return [] |
| 84 | + # The query endpoint returns one result object per statement. |
| 85 | + return result[0].get("results", []) or [] |
| 86 | + |
| 87 | + def _http_transport(self, sql: str, params: list) -> dict: |
| 88 | + if not self._token: |
| 89 | + raise RuntimeError("CLOUDFLARE_API_TOKEN not set (D1 requires an API token)") |
| 90 | + url = ( |
| 91 | + f"{_API_ROOT}/accounts/{self.account_id}" |
| 92 | + f"/d1/database/{self.database_id}/query" |
| 93 | + ) |
| 94 | + body = json.dumps({"sql": sql, "params": params}).encode("utf-8") |
| 95 | + req = urllib.request.Request( |
| 96 | + url, |
| 97 | + data=body, |
| 98 | + method="POST", |
| 99 | + headers={ |
| 100 | + "Authorization": f"Bearer {self._token}", |
| 101 | + "Content-Type": "application/json", |
| 102 | + }, |
| 103 | + ) |
| 104 | + with urllib.request.urlopen(req, timeout=self._timeout) as resp: |
| 105 | + return json.loads(resp.read().decode("utf-8")) |
| 106 | + |
| 107 | + |
| 108 | +def _ident(name: str) -> str: |
| 109 | + """Quote a SQLite identifier, rejecting anything that isn't a plain name. |
| 110 | +
|
| 111 | + introspection helpers interpolate the table name into PRAGMA/SELECT where |
| 112 | + binds aren't allowed, so we hard-validate to avoid injection. |
| 113 | + """ |
| 114 | + if not name.replace("_", "").isalnum(): |
| 115 | + raise ValueError(f"unsafe table identifier: {name!r}") |
| 116 | + return f'"{name}"' |
0 commit comments