Skip to main content

ruprizzle_turso/
lib.rs

1//! Turso / libSQL adapter for the `ruprizzle` ORM.
2//!
3//! [`TursoPool`] implements [`ruprizzle::Executor`] by sending each statement to a
4//! libSQL server over the [Hrana 2 HTTP protocol][hrana] — `POST {url}/v2/pipeline`
5//! with the SQL and its bound parameters, and one result set back. It works against
6//! Turso's hosted databases and against any `sqld` you run yourself.
7//!
8//! [hrana]: https://github.com/tursodatabase/libsql/blob/main/docs/HRANA_3_SPEC.md
9//!
10//! # What this adapter does and does not do
11//!
12//! Every statement is one HTTP request. There is no server-side session, so there is
13//! no interactive transaction: `BEGIN` and `COMMIT` sent as separate statements would
14//! land on unrelated connections and are not supported. Batch the work into a single
15//! statement, or use a `SQLite` file through [`ruprizzle::connect`] when you need
16//! multi-statement transactions.
17//!
18//! Embedded replicas — a local `SQLite` file kept in sync with a remote primary — need
19//! the native libSQL library and are out of scope here. If you already have a replica
20//! file, point [`ruprizzle::connect`] at it as an ordinary `SQLite` database.
21//!
22//! # Example
23//!
24//! ```no_run
25//! use ruprizzle::Executor;
26//! use ruprizzle::value::Value;
27//! use ruprizzle_turso::TursoPool;
28//!
29//! # async fn doc() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
30//! let pool = TursoPool::builder()
31//!     .url("libsql://your-db.turso.io")
32//!     .auth_token(std::env::var("TURSO_AUTH_TOKEN")?)
33//!     .build()?;
34//!
35//! let rows = pool
36//!     .fetch_all_raw("SELECT id, email FROM users WHERE id = ?".into(), vec![Value::I64(7)])
37//!     .await?;
38//! # let _ = rows;
39//! # Ok(())
40//! # }
41//! ```
42
43#![forbid(unsafe_code)]
44#![warn(clippy::pedantic)]
45
46mod hrana;
47
48use std::borrow::Cow;
49use std::sync::Arc;
50use std::time::Duration;
51
52use futures_core::future::BoxFuture;
53use futures_util::StreamExt as _;
54use ruprizzle::executor::{BoxRowStream, Executor, RawRow, RowBatch};
55use ruprizzle::value::Value;
56use ruprizzle_dialect::{DbDialect, SqliteDialect};
57use thiserror::Error;
58
59use hrana::{Pipeline, PipelineResponse, Stmt};
60
61/// Dialect instance for Turso / libSQL, which is `SQLite` compatible.
62static SQLITE_DIALECT: SqliteDialect = SqliteDialect;
63
64/// How long to wait for a single statement before giving up.
65const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
66
67/// Errors raised by the Turso adapter.
68#[derive(Debug, Error)]
69#[non_exhaustive]
70pub enum TursoError {
71    /// The pool was configured with something it cannot use.
72    #[error("turso configuration error: {0}")]
73    Config(String),
74
75    /// The request never completed: DNS, TLS, connection or timeout.
76    #[error("turso transport error: {0}")]
77    Transport(String),
78
79    /// The server answered, but not with a `/v2/pipeline` response we can read.
80    #[error("turso protocol error: {0}")]
81    Protocol(String),
82
83    /// The server rejected the statement.
84    #[error("turso query error: {message}{}", .code.as_deref().map(|c| format!(" ({c})")).unwrap_or_default())]
85    Query {
86        /// The message the server sent.
87        message: String,
88        /// The `SQLITE_*` code, when the server sent one.
89        code: Option<String>,
90    },
91
92    /// The operation has no representation in `SQLite` or in stateless HTTP.
93    #[error("unsupported by the Turso HTTP adapter: {0}")]
94    Unsupported(String),
95}
96
97impl From<TursoError> for ruprizzle::Error {
98    fn from(err: TursoError) -> Self {
99        ruprizzle::Error::Message(err.to_string())
100    }
101}
102
103/// Builder for [`TursoPool`].
104#[derive(Debug, Default)]
105pub struct TursoPoolBuilder {
106    url: Option<String>,
107    auth_token: Option<String>,
108    timeout: Option<Duration>,
109}
110
111impl TursoPoolBuilder {
112    /// Creates a builder with no configuration.
113    #[must_use]
114    pub fn new() -> Self {
115        Self::default()
116    }
117
118    /// Sets the database URL.
119    ///
120    /// `libsql://…` and `wss://…` are accepted and rewritten to `https://`; an
121    /// explicit `http://` or `https://` is used as given.
122    #[must_use]
123    pub fn url(mut self, url: impl Into<String>) -> Self {
124        self.url = Some(url.into());
125        self
126    }
127
128    /// Sets the bearer token sent with every request.
129    ///
130    /// Omit it only for a local `sqld` that runs without authentication.
131    #[must_use]
132    pub fn auth_token(mut self, token: impl Into<String>) -> Self {
133        self.auth_token = Some(token.into());
134        self
135    }
136
137    /// Overrides the per-statement timeout. Defaults to 30 seconds.
138    #[must_use]
139    pub fn timeout(mut self, timeout: Duration) -> Self {
140        self.timeout = Some(timeout);
141        self
142    }
143
144    /// Builds the pool.
145    ///
146    /// This does not contact the server; the first statement does. Nothing here can
147    /// tell you the token is valid, so failures surface where the query is issued.
148    ///
149    /// # Errors
150    ///
151    /// Returns [`TursoError::Config`] if no URL was set or its scheme is not one of
152    /// `libsql`, `ws`, `wss`, `http` or `https`, and if the HTTP client cannot be
153    /// constructed (which on most platforms means no usable TLS root store).
154    pub fn build(self) -> Result<TursoPool, TursoError> {
155        let url = self
156            .url
157            .ok_or_else(|| TursoError::Config("no database URL was configured".into()))?;
158        let endpoint = pipeline_endpoint(&url)?;
159
160        let http = reqwest::Client::builder()
161            .timeout(self.timeout.unwrap_or(DEFAULT_TIMEOUT))
162            .build()
163            .map_err(|e| TursoError::Config(format!("cannot build the HTTP client: {e}")))?;
164
165        Ok(TursoPool {
166            inner: Arc::new(TursoPoolInner {
167                http,
168                endpoint,
169                database_url: url,
170                auth_token: self.auth_token,
171            }),
172        })
173    }
174}
175
176/// Rewrites a database URL into the `/v2/pipeline` endpoint to post to.
177///
178/// `libsql://` and `wss://` are the schemes Turso publishes; both speak HTTPS to the
179/// same host. `ws://` and `http://` are for a local `sqld` without TLS.
180fn pipeline_endpoint(url: &str) -> Result<String, TursoError> {
181    let (scheme, rest) = url.split_once("://").ok_or_else(|| {
182        TursoError::Config(format!("`{url}` has no scheme; expected `libsql://…`"))
183    })?;
184    let base = match scheme {
185        "libsql" | "wss" | "https" => "https",
186        "ws" | "http" => "http",
187        other => {
188            return Err(TursoError::Config(format!(
189                "unsupported scheme `{other}`; expected libsql, wss, ws, https or http"
190            )));
191        }
192    };
193    if rest.is_empty() {
194        return Err(TursoError::Config(format!("`{url}` names no host")));
195    }
196    Ok(format!(
197        "{base}://{}/v2/pipeline",
198        rest.trim_end_matches('/')
199    ))
200}
201
202struct TursoPoolInner {
203    http: reqwest::Client,
204    /// The full `…/v2/pipeline` URL every request is posted to.
205    endpoint: String,
206    /// The URL as configured, for diagnostics. Never contains the token.
207    database_url: String,
208    auth_token: Option<String>,
209}
210
211/// Redacts the auth token.
212///
213/// `TursoPool` is held inside application state that is routinely logged, and a
214/// derived `Debug` would put a database credential in the log line.
215impl std::fmt::Debug for TursoPoolInner {
216    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
217        f.debug_struct("TursoPoolInner")
218            .field("endpoint", &self.endpoint)
219            .field("database_url", &self.database_url)
220            .field(
221                "auth_token",
222                &self.auth_token.as_ref().map(|_| "<redacted>"),
223            )
224            // `http` is omitted: a `reqwest::Client` renders as an opaque blob that
225            // tells a reader nothing the endpoint has not already said.
226            .finish_non_exhaustive()
227    }
228}
229
230/// A handle to a libSQL database over Hrana HTTP.
231///
232/// Cloning is cheap and shares one connection pool, so clone this rather than
233/// building a second one.
234#[derive(Debug, Clone)]
235pub struct TursoPool {
236    inner: Arc<TursoPoolInner>,
237}
238
239impl TursoPool {
240    /// Returns a new [`TursoPoolBuilder`].
241    #[must_use]
242    pub fn builder() -> TursoPoolBuilder {
243        TursoPoolBuilder::new()
244    }
245
246    /// Connects using a URL and token, the common case.
247    ///
248    /// # Errors
249    ///
250    /// As [`TursoPoolBuilder::build`].
251    pub fn connect(url: &str, auth_token: impl Into<String>) -> Result<Self, TursoError> {
252        Self::builder().url(url).auth_token(auth_token).build()
253    }
254
255    /// The database URL this pool was configured with.
256    #[must_use]
257    pub fn url(&self) -> &str {
258        &self.inner.database_url
259    }
260
261    /// Sends one statement and returns the server's result.
262    async fn pipeline(
263        &self,
264        sql: &str,
265        binds: &[Value],
266        want_rows: bool,
267    ) -> Result<hrana::ExecuteResult, TursoError> {
268        let args = binds
269            .iter()
270            .map(hrana::to_hrana)
271            .collect::<Result<Vec<_>, _>>()?;
272
273        let body = Pipeline::one(Stmt {
274            sql: sql.to_owned(),
275            args,
276            want_rows,
277        });
278
279        let mut request = self.inner.http.post(&self.inner.endpoint).json(&body);
280        if let Some(token) = &self.inner.auth_token {
281            request = request.bearer_auth(token);
282        }
283
284        let response = request
285            .send()
286            .await
287            .map_err(|e| TursoError::Transport(e.to_string()))?;
288
289        let status = response.status();
290        let text = response
291            .text()
292            .await
293            .map_err(|e| TursoError::Transport(format!("cannot read the response body: {e}")))?;
294
295        if !status.is_success() {
296            // The body is the server's explanation and is worth keeping, but it is
297            // untrusted and unbounded, so it is truncated rather than logged whole.
298            return Err(TursoError::Protocol(format!(
299                "server answered {status}: {}",
300                truncate(&text, 512)
301            )));
302        }
303
304        let parsed: PipelineResponse = serde_json::from_str(&text).map_err(|e| {
305            TursoError::Protocol(format!(
306                "cannot parse the pipeline response: {e}; body was {}",
307                truncate(&text, 512)
308            ))
309        })?;
310
311        hrana::single_execute(parsed)
312    }
313}
314
315/// Shortens `text` to at most `limit` characters, on a character boundary.
316fn truncate(text: &str, limit: usize) -> Cow<'_, str> {
317    match text.char_indices().nth(limit) {
318        Some((end, _)) => Cow::Owned(format!("{}…", &text[..end])),
319        None => Cow::Borrowed(text),
320    }
321}
322
323impl Executor for TursoPool {
324    fn dialect(&self) -> &dyn DbDialect {
325        &SQLITE_DIALECT
326    }
327
328    fn fetch_all_raw(
329        &self,
330        sql: Cow<'static, str>,
331        binds: Vec<Value>,
332    ) -> BoxFuture<'_, Result<RowBatch, ruprizzle::Error>> {
333        Box::pin(async move {
334            let result = self.pipeline(&sql, &binds, true).await?;
335            Ok(RowBatch::Edge(result.into_edge_rows()?))
336        })
337    }
338
339    fn execute_raw(
340        &self,
341        sql: Cow<'static, str>,
342        binds: Vec<Value>,
343    ) -> BoxFuture<'_, Result<u64, ruprizzle::Error>> {
344        Box::pin(async move {
345            // `want_rows: false` so an `INSERT … RETURNING` does not ship a result
346            // set across the network that the caller has said it will not read.
347            let result = self.pipeline(&sql, &binds, false).await?;
348            Ok(result.affected_row_count)
349        })
350    }
351
352    fn stream_raw(&self, sql: Cow<'static, str>, binds: Vec<Value>) -> BoxRowStream<'_> {
353        // Hrana over HTTP returns the whole result set in one response, so this
354        // fetches and then yields. It is a streaming interface, not a streaming
355        // transport: memory use is that of the full result.
356        Box::pin(
357            futures_util::stream::once(self.fetch_all_raw(sql, binds)).flat_map(|batch| {
358                let rows = match batch {
359                    Ok(RowBatch::Edge(rows)) => {
360                        rows.into_iter().map(RawRow::Edge).map(Ok).collect()
361                    }
362                    Ok(_) => vec![Err(ruprizzle::Error::Message(
363                        "the Turso adapter only produces edge rows".into(),
364                    ))],
365                    Err(e) => vec![Err(e)],
366                };
367                futures_util::stream::iter(rows)
368            }),
369        )
370    }
371}
372
373#[cfg(test)]
374mod tests {
375    use super::*;
376
377    #[test]
378    fn turso_urls_are_rewritten_to_the_pipeline_endpoint() {
379        assert_eq!(
380            pipeline_endpoint("libsql://db.turso.io").unwrap(),
381            "https://db.turso.io/v2/pipeline"
382        );
383        assert_eq!(
384            pipeline_endpoint("wss://db.turso.io/").unwrap(),
385            "https://db.turso.io/v2/pipeline"
386        );
387        assert_eq!(
388            pipeline_endpoint("http://127.0.0.1:8080").unwrap(),
389            "http://127.0.0.1:8080/v2/pipeline"
390        );
391    }
392
393    #[test]
394    fn an_unusable_url_is_refused_at_build_time() {
395        assert!(matches!(
396            pipeline_endpoint("db.turso.io"),
397            Err(TursoError::Config(_))
398        ));
399        assert!(matches!(
400            pipeline_endpoint("postgres://db.turso.io"),
401            Err(TursoError::Config(_))
402        ));
403        assert!(matches!(
404            TursoPool::builder().auth_token("t").build(),
405            Err(TursoError::Config(_))
406        ));
407    }
408
409    #[test]
410    fn the_configured_url_is_reported_without_the_token() {
411        let pool = TursoPool::connect("libsql://db.turso.io", "secret-token").unwrap();
412        assert_eq!(pool.url(), "libsql://db.turso.io");
413        let rendered = format!("{pool:?}");
414        assert!(
415            !rendered.contains("secret-token"),
416            "the auth token must not be in Debug output: {rendered}"
417        );
418    }
419
420    #[test]
421    fn the_dialect_is_sqlite() {
422        let pool = TursoPool::connect("libsql://db.turso.io", "t").unwrap();
423        assert_eq!(pool.dialect().name(), "sqlite");
424    }
425}