Skip to main content

ruprizzle_d1/
lib.rs

1//! Cloudflare D1 adapter for the `ruprizzle` ORM.
2//!
3//! [`D1Pool`] implements [`ruprizzle::Executor`] against a D1 database through the
4//! [Cloudflare REST API][api]: each statement is one
5//! `POST /accounts/{account}/d1/database/{database}/query`, authenticated with an
6//! API token.
7//!
8//! [api]: https://developers.cloudflare.com/api/resources/d1/
9//!
10//! # What this adapter does and does not do
11//!
12//! This is the adapter for code that talks to D1 **from outside** a Worker — a CLI, a
13//! migration job, a server. Inside a Worker you have a D1 binding, which is faster
14//! and needs no token; this crate does not use bindings.
15//!
16//! Every statement is one HTTP request, so there is no interactive transaction:
17//! `BEGIN` and `COMMIT` sent separately would not share a connection and are not
18//! supported. D1's HTTP interface also takes no binary parameter, so [`ruprizzle`]
19//! `Bytes` values are refused rather than mangled — store them encoded in a text
20//! column. The same goes for a non-finite `F64` (`NaN`, `±inf`): JSON has no form
21//! for it, and before `1.5.2` it was sent as `null` and stored as `NULL`.
22//!
23//! Parameters and results cross the API as JSON numbers, which D1's JavaScript
24//! runtime holds as doubles. An integer beyond ±2^53 (9 007 199 254 740 992) is
25//! therefore rounded by D1 itself, on the way in and on the way out, before this
26//! adapter sees it. Store such values (64-bit IDs, snowflakes) as text.
27//!
28//! # Example
29//!
30//! ```no_run
31//! use ruprizzle::Executor;
32//! use ruprizzle::value::Value;
33//! use ruprizzle_d1::D1Pool;
34//!
35//! # async fn doc() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
36//! let pool = D1Pool::builder()
37//!     .account_id(std::env::var("CLOUDFLARE_ACCOUNT_ID")?)
38//!     .database_id(std::env::var("D1_DATABASE_ID")?)
39//!     .api_token(std::env::var("CLOUDFLARE_API_TOKEN")?)
40//!     .build()?;
41//!
42//! let rows = pool
43//!     .fetch_all_raw("SELECT id, email FROM users WHERE id = ?".into(), vec![Value::I64(7)])
44//!     .await?;
45//! # let _ = rows;
46//! # Ok(())
47//! # }
48//! ```
49
50#![forbid(unsafe_code)]
51#![warn(clippy::pedantic)]
52
53mod api;
54
55use std::borrow::Cow;
56use std::sync::Arc;
57use std::time::Duration;
58
59use futures_core::future::BoxFuture;
60use futures_util::StreamExt as _;
61use ruprizzle::executor::{BoxRowStream, Executor, RawRow, RowBatch};
62use ruprizzle::value::Value;
63use ruprizzle_dialect::{DbDialect, SqliteDialect};
64use thiserror::Error;
65
66use api::{Envelope, QueryRequest};
67
68/// Dialect instance for D1, which is `SQLite`.
69static SQLITE_DIALECT: SqliteDialect = SqliteDialect;
70
71/// The Cloudflare API root, overridable for testing and for private gateways.
72const DEFAULT_ENDPOINT: &str = "https://api.cloudflare.com/client/v4";
73
74/// How long to wait for a single statement before giving up.
75const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
76
77/// Errors raised by the D1 adapter.
78#[derive(Debug, Error)]
79#[non_exhaustive]
80pub enum D1Error {
81    /// The pool was configured with something it cannot use.
82    #[error("d1 configuration error: {0}")]
83    Config(String),
84
85    /// The request never completed: DNS, TLS, connection or timeout.
86    #[error("d1 transport error: {0}")]
87    Transport(String),
88
89    /// Cloudflare answered, but not with an envelope we can read.
90    #[error("d1 protocol error: {0}")]
91    Protocol(String),
92
93    /// Cloudflare reported the statement as failed.
94    #[error("d1 query error: {0}")]
95    Query(String),
96
97    /// The operation has no representation in D1's HTTP interface.
98    #[error("unsupported by the D1 HTTP adapter: {0}")]
99    Unsupported(String),
100}
101
102impl From<D1Error> for ruprizzle::Error {
103    fn from(err: D1Error) -> Self {
104        ruprizzle::Error::Message(err.to_string())
105    }
106}
107
108/// Builder for [`D1Pool`].
109#[derive(Debug, Default)]
110pub struct D1PoolBuilder {
111    account_id: Option<String>,
112    database_id: Option<String>,
113    api_token: Option<String>,
114    endpoint: Option<String>,
115    timeout: Option<Duration>,
116}
117
118impl D1PoolBuilder {
119    /// Creates a builder with no configuration.
120    #[must_use]
121    pub fn new() -> Self {
122        Self::default()
123    }
124
125    /// Sets the Cloudflare account that owns the database.
126    #[must_use]
127    pub fn account_id(mut self, id: impl Into<String>) -> Self {
128        self.account_id = Some(id.into());
129        self
130    }
131
132    /// Sets the D1 database UUID.
133    #[must_use]
134    pub fn database_id(mut self, id: impl Into<String>) -> Self {
135        self.database_id = Some(id.into());
136        self
137    }
138
139    /// Sets the API token, sent as a bearer credential on every request.
140    ///
141    /// The token needs the `D1:edit` permission on the account.
142    #[must_use]
143    pub fn api_token(mut self, token: impl Into<String>) -> Self {
144        self.api_token = Some(token.into());
145        self
146    }
147
148    /// Overrides the API root. Defaults to `https://api.cloudflare.com/client/v4`.
149    #[must_use]
150    pub fn endpoint(mut self, url: impl Into<String>) -> Self {
151        self.endpoint = Some(url.into());
152        self
153    }
154
155    /// Overrides the per-statement timeout. Defaults to 30 seconds.
156    #[must_use]
157    pub fn timeout(mut self, timeout: Duration) -> Self {
158        self.timeout = Some(timeout);
159        self
160    }
161
162    /// Builds the pool.
163    ///
164    /// This does not contact Cloudflare; the first statement does. Nothing here can
165    /// tell you the token is valid or the database exists.
166    ///
167    /// # Errors
168    ///
169    /// Returns [`D1Error::Config`] when the account, database or token is missing,
170    /// and when the HTTP client cannot be constructed (which on most platforms means
171    /// no usable TLS root store).
172    pub fn build(self) -> Result<D1Pool, D1Error> {
173        let account_id = self
174            .account_id
175            .ok_or_else(|| D1Error::Config("no `account_id` was configured".into()))?;
176        let database_id = self
177            .database_id
178            .ok_or_else(|| D1Error::Config("no `database_id` was configured".into()))?;
179        let api_token = self.api_token.ok_or_else(|| {
180            D1Error::Config("no `api_token` was configured; the D1 REST API is not open".into())
181        })?;
182
183        let root = self.endpoint.unwrap_or_else(|| DEFAULT_ENDPOINT.to_owned());
184        let query_url = format!(
185            "{}/accounts/{account_id}/d1/database/{database_id}/query",
186            root.trim_end_matches('/')
187        );
188
189        let http = reqwest::Client::builder()
190            .timeout(self.timeout.unwrap_or(DEFAULT_TIMEOUT))
191            .build()
192            .map_err(|e| D1Error::Config(format!("cannot build the HTTP client: {e}")))?;
193
194        Ok(D1Pool {
195            inner: Arc::new(D1PoolInner {
196                http,
197                query_url,
198                account_id,
199                database_id,
200                api_token,
201            }),
202        })
203    }
204}
205
206struct D1PoolInner {
207    http: reqwest::Client,
208    /// The full `…/query` URL every statement is posted to.
209    query_url: String,
210    account_id: String,
211    database_id: String,
212    api_token: String,
213}
214
215/// Redacts the API token.
216///
217/// `D1Pool` is held inside application state that is routinely logged, and a derived
218/// `Debug` would put a Cloudflare credential in the log line.
219impl std::fmt::Debug for D1PoolInner {
220    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
221        f.debug_struct("D1PoolInner")
222            .field("query_url", &self.query_url)
223            .field("account_id", &self.account_id)
224            .field("database_id", &self.database_id)
225            .field("api_token", &"<redacted>")
226            // `http` is omitted: a `reqwest::Client` renders as an opaque blob that
227            // tells a reader nothing the URL has not already said.
228            .finish_non_exhaustive()
229    }
230}
231
232/// A handle to a Cloudflare D1 database over the REST API.
233///
234/// Cloning is cheap and shares one connection pool, so clone this rather than
235/// building a second one.
236#[derive(Debug, Clone)]
237pub struct D1Pool {
238    inner: Arc<D1PoolInner>,
239}
240
241impl D1Pool {
242    /// Returns a new [`D1PoolBuilder`].
243    #[must_use]
244    pub fn builder() -> D1PoolBuilder {
245        D1PoolBuilder::new()
246    }
247
248    /// The Cloudflare account this pool queries.
249    #[must_use]
250    pub fn account_id(&self) -> &str {
251        &self.inner.account_id
252    }
253
254    /// The D1 database this pool queries.
255    #[must_use]
256    pub fn database_id(&self) -> &str {
257        &self.inner.database_id
258    }
259
260    /// Sends one statement and returns Cloudflare's result for it.
261    async fn query(&self, sql: &str, binds: &[Value]) -> Result<api::QueryResult, D1Error> {
262        let params = binds
263            .iter()
264            .map(api::to_json)
265            .collect::<Result<Vec<_>, _>>()?;
266
267        let response = self
268            .inner
269            .http
270            .post(&self.inner.query_url)
271            .bearer_auth(&self.inner.api_token)
272            .json(&QueryRequest {
273                sql: sql.to_owned(),
274                params,
275            })
276            .send()
277            .await
278            .map_err(|e| D1Error::Transport(e.to_string()))?;
279
280        let status = response.status();
281        let text = response
282            .text()
283            .await
284            .map_err(|e| D1Error::Transport(format!("cannot read the response body: {e}")))?;
285
286        // Cloudflare returns its `{success, errors}` envelope on 4xx as well, and
287        // that envelope carries the useful message, so it is parsed first and the
288        // status is only reported when the body is unreadable.
289        match serde_json::from_str::<Envelope>(&text) {
290            Ok(envelope) => envelope.single_result(),
291            Err(e) if status.is_success() => Err(D1Error::Protocol(format!(
292                "cannot parse the D1 response: {e}; body was {}",
293                truncate(&text, 512)
294            ))),
295            Err(_) => Err(D1Error::Protocol(format!(
296                "Cloudflare answered {status}: {}",
297                truncate(&text, 512)
298            ))),
299        }
300    }
301}
302
303/// Shortens `text` to at most `limit` characters, on a character boundary.
304fn truncate(text: &str, limit: usize) -> Cow<'_, str> {
305    match text.char_indices().nth(limit) {
306        Some((end, _)) => Cow::Owned(format!("{}…", &text[..end])),
307        None => Cow::Borrowed(text),
308    }
309}
310
311impl Executor for D1Pool {
312    fn dialect(&self) -> &dyn DbDialect {
313        &SQLITE_DIALECT
314    }
315
316    fn fetch_all_raw(
317        &self,
318        sql: Cow<'static, str>,
319        binds: Vec<Value>,
320    ) -> BoxFuture<'_, Result<RowBatch, ruprizzle::Error>> {
321        Box::pin(async move {
322            let result = self.query(&sql, &binds).await?;
323            Ok(RowBatch::Edge(result.into_edge_rows()))
324        })
325    }
326
327    fn execute_raw(
328        &self,
329        sql: Cow<'static, str>,
330        binds: Vec<Value>,
331    ) -> BoxFuture<'_, Result<u64, ruprizzle::Error>> {
332        Box::pin(async move { Ok(self.query(&sql, &binds).await?.meta.changes) })
333    }
334
335    fn stream_raw(&self, sql: Cow<'static, str>, binds: Vec<Value>) -> BoxRowStream<'_> {
336        // D1 returns the whole result set in one response, so this fetches and then
337        // yields. It is a streaming interface, not a streaming transport: memory use
338        // is that of the full result.
339        Box::pin(
340            futures_util::stream::once(self.fetch_all_raw(sql, binds)).flat_map(|batch| {
341                let rows = match batch {
342                    Ok(RowBatch::Edge(rows)) => {
343                        rows.into_iter().map(RawRow::Edge).map(Ok).collect()
344                    }
345                    Ok(_) => vec![Err(ruprizzle::Error::Message(
346                        "the D1 adapter only produces edge rows".into(),
347                    ))],
348                    Err(e) => vec![Err(e)],
349                };
350                futures_util::stream::iter(rows)
351            }),
352        )
353    }
354}
355
356#[cfg(test)]
357mod tests {
358    use super::*;
359
360    fn pool() -> D1Pool {
361        D1Pool::builder()
362            .account_id("acct")
363            .database_id("db-uuid")
364            .api_token("secret-token")
365            .build()
366            .unwrap()
367    }
368
369    #[test]
370    fn the_query_url_is_built_from_the_account_and_database() {
371        let pool = pool();
372        assert_eq!(
373            pool.inner.query_url,
374            "https://api.cloudflare.com/client/v4/accounts/acct/d1/database/db-uuid/query"
375        );
376    }
377
378    #[test]
379    fn an_overridden_endpoint_keeps_the_path_shape() {
380        let pool = D1Pool::builder()
381            .account_id("a")
382            .database_id("b")
383            .api_token("t")
384            .endpoint("http://127.0.0.1:9999/")
385            .build()
386            .unwrap();
387        assert_eq!(
388            pool.inner.query_url,
389            "http://127.0.0.1:9999/accounts/a/d1/database/b/query"
390        );
391    }
392
393    #[test]
394    fn every_credential_is_required() {
395        assert!(matches!(
396            D1Pool::builder().database_id("b").api_token("t").build(),
397            Err(D1Error::Config(_))
398        ));
399        assert!(matches!(
400            D1Pool::builder().account_id("a").api_token("t").build(),
401            Err(D1Error::Config(_))
402        ));
403        assert!(matches!(
404            D1Pool::builder().account_id("a").database_id("b").build(),
405            Err(D1Error::Config(_))
406        ));
407    }
408
409    #[test]
410    fn the_api_token_is_not_in_debug_output() {
411        let rendered = format!("{:?}", pool());
412        assert!(
413            !rendered.contains("secret-token"),
414            "the API token must not be in Debug output: {rendered}"
415        );
416    }
417
418    #[test]
419    fn the_dialect_is_sqlite() {
420        assert_eq!(pool().dialect().name(), "sqlite");
421    }
422}