1#![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
61static SQLITE_DIALECT: SqliteDialect = SqliteDialect;
63
64const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
66
67#[derive(Debug, Error)]
69#[non_exhaustive]
70pub enum TursoError {
71 #[error("turso configuration error: {0}")]
73 Config(String),
74
75 #[error("turso transport error: {0}")]
77 Transport(String),
78
79 #[error("turso protocol error: {0}")]
81 Protocol(String),
82
83 #[error("turso query error: {message}{}", .code.as_deref().map(|c| format!(" ({c})")).unwrap_or_default())]
85 Query {
86 message: String,
88 code: Option<String>,
90 },
91
92 #[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#[derive(Debug, Default)]
105pub struct TursoPoolBuilder {
106 url: Option<String>,
107 auth_token: Option<String>,
108 timeout: Option<Duration>,
109}
110
111impl TursoPoolBuilder {
112 #[must_use]
114 pub fn new() -> Self {
115 Self::default()
116 }
117
118 #[must_use]
123 pub fn url(mut self, url: impl Into<String>) -> Self {
124 self.url = Some(url.into());
125 self
126 }
127
128 #[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 #[must_use]
139 pub fn timeout(mut self, timeout: Duration) -> Self {
140 self.timeout = Some(timeout);
141 self
142 }
143
144 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
176fn 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 endpoint: String,
206 database_url: String,
208 auth_token: Option<String>,
209}
210
211impl 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 .finish_non_exhaustive()
227 }
228}
229
230#[derive(Debug, Clone)]
235pub struct TursoPool {
236 inner: Arc<TursoPoolInner>,
237}
238
239impl TursoPool {
240 #[must_use]
242 pub fn builder() -> TursoPoolBuilder {
243 TursoPoolBuilder::new()
244 }
245
246 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 #[must_use]
257 pub fn url(&self) -> &str {
258 &self.inner.database_url
259 }
260
261 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 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
315fn 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 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 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}