nitr-std 0.0.0-beta.2

The built-in `nitr.*` standard library for Nitr: dbg, fetch, template, json, http, log, crypto, and the SQLite driver.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
// SPDX-License-Identifier: MIT OR Apache-2.0
// This file is part of Nitr.
// See https://nitrweb.com/ for more information
// Copyright (C) 2024-present Jose Quintana <joseluisq.net>

//! The `conn` builtin: SQLite statements and transactions. Blocking
//! rusqlite calls run on the blocking thread pool; each Lua state owns its
//! own connection, and requests are serialized per state, so a transaction
//! never interleaves with other statements.

use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
use std::sync::{Arc, Mutex};

use mlua::{AnyUserData, Function, Lua, Table, UserData, UserDataMethods, Value};
use rusqlite::Connection;
use tracing::Instrument as _;

use crate::db::types::{Conn, SqlValue, params_from_table, row_to_lua};
use nitr_core::Result;

pub(crate) mod execute;
pub mod migrate;
pub mod pragmas;
pub(crate) mod query;
pub(crate) mod query_one;
pub(crate) mod query_row;
pub(crate) mod types;

use crate::config::SqlitePragmas;

/// Set while a transaction is open on the connection.
type TxFlag = Arc<AtomicBool>;

pub(crate) struct LuaDatabase {
    conn: Conn,
    in_transaction: TxFlag,
}

/// One (possibly nested) transaction scope handed to the Lua callback of
/// `db:transaction(fn)` / `tx:transaction(fn)`.
pub(crate) struct LuaTransaction {
    conn: Conn,
    /// Names nested savepoints uniquely within this scope.
    savepoints: AtomicUsize,
}

/// Runs a blocking database operation on the blocking thread pool so it
/// stalls a blocking-pool thread instead of an async worker. Only plain
/// `Send` data crosses the boundary — never a Lua handle.
async fn run_blocking<T, F>(
    conn: Conn,
    kind: &'static str,
    sql: String,
    params: Vec<SqlValue>,
    f: F,
) -> mlua::Result<T>
where
    T: Send + 'static,
    F: FnOnce(&Connection, &str, &[SqlValue]) -> Result<T, rusqlite::Error> + Send + 'static,
{
    // The `db_query` span: which statement kind ran and for how long.
    // Deliberately no SQL text and no bind values — statements can embed
    // secrets, and logs outlive them. DEBUG so the per-request
    // decomposition is opt-in via the level filter.
    let span = tracing::debug_span!("db_query", kind, elapsed_ms = tracing::field::Empty);
    let started = std::time::Instant::now();
    let result = tokio::task::spawn_blocking(move || {
        let conn = conn.lock().map_err(|_| {
            mlua::Error::RuntimeError("failed to lock the database connection".into())
        })?;
        f(&conn, &sql, &params).map_err(|err| {
            mlua::Error::RuntimeError(format!("SQL statement `{sql}` failed: {err}"))
        })
    })
    .instrument(span.clone())
    .await
    .map_err(mlua::Error::external)?;
    span.record("elapsed_ms", started.elapsed().as_millis() as u64);
    result
}

/// Executes a control statement (`BEGIN`, `COMMIT`, `SAVEPOINT ...`).
async fn exec_batch(conn: Conn, sql: String) -> mlua::Result<()> {
    run_blocking(conn, "tx", sql, Vec::new(), |conn, sql, _| {
        conn.execute_batch(sql)
    })
    .await
}

/// Registers `execute`/`query`/`query_row`/`query_one` on a userdata type
/// that exposes a connection — shared between `db` and transactions.
///
/// `conn_of` may refuse: the outer `nitr.db` handle does so while a
/// transaction is open on the same connection.
fn add_stmt_methods<T, M>(methods: &mut M, conn_of: fn(&T) -> mlua::Result<Conn>)
where
    T: UserData + 'static,
    M: UserDataMethods<T>,
{
    // The connection is cloned out before each async block so no
    // userdata borrow lives across an await point.
    methods.add_async_method("execute", move |_, this, args: (String, Option<Table>)| {
        let conn = conn_of(&this);
        async move {
            let (sql, params) = args;
            let params = params_from_table(params.as_ref())?;
            let affected = run_blocking(conn?, "execute", sql, params, execute::call).await?;
            Ok(affected)
        }
    });

    methods.add_async_method(
        "query_row",
        move |lua, this, args: (String, Option<Table>)| {
            let conn = conn_of(&this);
            async move {
                let (sql, params) = args;
                let params = params_from_table(params.as_ref())?;
                let row = run_blocking(conn?, "query_row", sql, params, query_row::call).await?;
                row_to_lua(&lua, row)
            }
        },
    );

    methods.add_async_method(
        "query_one",
        move |lua, this, args: (String, Option<Table>)| {
            let conn = conn_of(&this);
            async move {
                let (sql, params) = args;
                let params = params_from_table(params.as_ref())?;
                let row = run_blocking(conn?, "query_one", sql, params, query_one::call).await?;
                row_to_lua(&lua, row)
            }
        },
    );

    methods.add_async_method("query", move |lua, this, args: (String, Option<Table>)| {
        let conn = conn_of(&this);
        async move {
            let (sql, params) = args;
            let params = params_from_table(params.as_ref())?;
            let rows = run_blocking(conn?, "query", sql, params, query::call).await?;
            let table = lua.create_table()?;
            for (i, row) in rows.into_iter().enumerate() {
                table.raw_set(i + 1, row_to_lua(&lua, row)?)?;
            }
            Ok(table)
        }
    });
}

/// Which statement an unsent query will run.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum QueryKind {
    Query,
    QueryRow,
    QueryOne,
    Execute,
}

impl QueryKind {
    fn parse(name: Option<&str>) -> mlua::Result<Self> {
        match name.unwrap_or("query") {
            "query" => Ok(QueryKind::Query),
            "query_row" => Ok(QueryKind::QueryRow),
            "query_one" => Ok(QueryKind::QueryOne),
            "execute" => Ok(QueryKind::Execute),
            other => Err(mlua::Error::RuntimeError(format!(
                "unknown query kind `{other}`: expected \"query\", \"query_row\", \
                 \"query_one\" or \"execute\""
            ))),
        }
    }
}

/// The work an unsent query represents, lifted out of the Lua handle so it
/// can be awaited without holding a userdata borrow.
pub struct PendingQuery {
    conn: Conn,
    kind: QueryKind,
    sql: String,
    params: Vec<SqlValue>,
}

impl PendingQuery {
    /// Runs the statement and converts the result to a Lua value.
    pub async fn run(self, lua: &Lua) -> mlua::Result<Value> {
        let PendingQuery {
            conn,
            kind,
            sql,
            params,
        } = self;
        match kind {
            QueryKind::Execute => {
                let affected = run_blocking(conn, "execute", sql, params, execute::call).await?;
                Ok(Value::Integer(affected as i64))
            }
            QueryKind::QueryRow => {
                let row = run_blocking(conn, "query_row", sql, params, query_row::call).await?;
                row_to_lua(lua, row).map(Value::Table)
            }
            QueryKind::QueryOne => {
                let row = run_blocking(conn, "query_one", sql, params, query_one::call).await?;
                row_to_lua(lua, row).map(Value::Table)
            }
            QueryKind::Query => {
                let rows = run_blocking(conn, "query", sql, params, query::call).await?;
                let table = lua.create_table()?;
                for (i, row) in rows.into_iter().enumerate() {
                    table.raw_set(i + 1, row_to_lua(lua, row)?)?;
                }
                Ok(Value::Table(table))
            }
        }
    }
}

/// An unsent query handle, the database counterpart of an unsent `fetch`.
///
/// Exists so `nitr.await_all` can run a query and an HTTP call at the same
/// time instead of one after the other. It carries no Lua state, which is
/// what keeps `await_all` a fixed set of Rust-side jobs rather than a
/// general concurrency primitive.
pub(crate) struct LuaPendingQuery(Mutex<Option<PendingQuery>>);

impl LuaPendingQuery {
    /// Takes the pending work; a handle can only be run once.
    pub(crate) fn take(&self) -> mlua::Result<PendingQuery> {
        self.0
            .lock()
            .map_err(|_| mlua::Error::RuntimeError("the query handle lock is poisoned".into()))?
            .take()
            .ok_or_else(|| {
                mlua::Error::RuntimeError(
                    "this query handle has already been awaited; build a new one".into(),
                )
            })
    }
}

impl UserData for LuaPendingQuery {
    fn add_methods<M: UserDataMethods<Self>>(methods: &mut M) {
        // Awaiting one handle on its own, for symmetry with fetch:send().
        methods.add_async_method("send", |lua, handle, ()| {
            let pending = handle.take();
            async move { pending?.run(&lua).await }
        });
    }
}

/// Registers `query_async` on a userdata type that exposes a connection.
fn add_async_query_method<T, M>(methods: &mut M, conn_of: fn(&T) -> mlua::Result<Conn>)
where
    T: UserData + 'static,
    M: UserDataMethods<T>,
{
    // db:query_async(sql, params?, kind?) -> unsent handle for await_all.
    methods.add_method(
        "query_async",
        move |_, this, (sql, params, kind): (String, Option<Table>, Option<String>)| {
            Ok(LuaPendingQuery(Mutex::new(Some(PendingQuery {
                conn: conn_of(this)?,
                kind: QueryKind::parse(kind.as_deref())?,
                sql,
                params: params_from_table(params.as_ref())?,
            }))))
        },
    );
}

/// Runs the transaction body between `begin` and `commit`/`rollback`,
/// passing a fresh [`LuaTransaction`] scope and re-raising body errors
/// after rolling back.
async fn run_transaction(
    lua: &Lua,
    conn: Conn,
    f: Function,
    begin: String,
    commit: String,
    rollback: String,
) -> mlua::Result<Value> {
    exec_batch(conn.clone(), begin).await?;
    let scope = lua.create_userdata(LuaTransaction {
        conn: conn.clone(),
        savepoints: AtomicUsize::new(0),
    })?;
    match f.call_async::<Value>(&scope).await {
        Ok(value) => {
            exec_batch(conn, commit).await?;
            Ok(value)
        }
        Err(err) => {
            if let Err(rollback_err) = exec_batch(conn, rollback).await {
                tracing::error!("transaction rollback failed: {rollback_err}");
            }
            Err(err)
        }
    }
}

impl UserData for LuaDatabase {
    fn add_methods<M: UserDataMethods<Self>>(methods: &mut M) {
        // Statements on the outer handle are refused while a transaction is
        // open. They would run on the same connection and therefore *inside*
        // the transaction, silently — so a write meant to be independent
        // would roll back with it, and a read would see uncommitted rows.
        // Phase 6 documented this as a footgun; documenting a trap is not
        // the same as removing it.
        add_stmt_methods(methods, |db: &LuaDatabase| {
            if db.in_transaction.load(Ordering::Acquire) {
                return Err(mlua::Error::RuntimeError(
                    "a transaction is open on this connection: use the `tx` handle passed \
                     to db:transaction(function(tx) ... end), not `nitr.db`. Statements on \
                     the outer handle would join the transaction without saying so."
                        .into(),
                ));
            }
            Ok(db.conn.clone())
        });
        add_async_query_method(methods, |db: &LuaDatabase| {
            if db.in_transaction.load(Ordering::Acquire) {
                return Err(mlua::Error::RuntimeError(
                    "a transaction is open on this connection: use the `tx` handle".into(),
                ));
            }
            Ok(db.conn.clone())
        });

        // db:transaction(function(tx) ... end): commits when the function
        // returns, rolls back (and re-raises) when it errors.
        methods.add_async_method("transaction", |lua, db, f: Function| {
            let conn = db.conn.clone();
            let flag = db.in_transaction.clone();
            async move {
                if flag.swap(true, Ordering::AcqRel) {
                    return Err(mlua::Error::RuntimeError(
                        "a transaction is already open on this connection; nest with \
                         tx:transaction(...) instead"
                            .into(),
                    ));
                }
                let result = run_transaction(
                    &lua,
                    conn,
                    f,
                    "BEGIN".into(),
                    "COMMIT".into(),
                    "ROLLBACK".into(),
                )
                .await;
                flag.store(false, Ordering::Release);
                result
            }
        });
    }
}

impl UserData for LuaTransaction {
    fn add_methods<M: UserDataMethods<Self>>(methods: &mut M) {
        add_stmt_methods(methods, |tx: &LuaTransaction| Ok(tx.conn.clone()));
        add_async_query_method(methods, |tx: &LuaTransaction| Ok(tx.conn.clone()));

        // Nested transactions become savepoints: rolling back the inner
        // scope keeps the outer transaction alive.
        methods.add_async_method("transaction", |lua, tx, f: Function| {
            let conn = tx.conn.clone();
            let n = tx.savepoints.fetch_add(1, Ordering::Relaxed);
            async move {
                let name = format!("nitr_sp_{n}");
                run_transaction(
                    &lua,
                    conn,
                    f,
                    format!("SAVEPOINT {name}"),
                    format!("RELEASE {name}"),
                    format!("ROLLBACK TO {name}; RELEASE {name}"),
                )
                .await
            }
        });
    }
}

/// Opens this state's SQLite connection and builds the `nitr.db` handle.
pub(crate) fn create_database_fn(
    lua: &Lua,
    path: &std::path::Path,
    pragmas: &SqlitePragmas,
) -> Result<AnyUserData> {
    let conn = Arc::new(Mutex::new(pragmas::open(path, pragmas)?));
    let value = lua.create_userdata(LuaDatabase {
        conn,
        in_transaction: Arc::new(AtomicBool::new(false)),
    })?;
    Ok(value)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn query_kinds_parse_strictly_with_a_query_default() {
        assert_eq!(QueryKind::parse(None).expect("default"), QueryKind::Query);
        for (name, kind) in [
            ("query", QueryKind::Query),
            ("query_row", QueryKind::QueryRow),
            ("query_one", QueryKind::QueryOne),
            ("execute", QueryKind::Execute),
        ] {
            assert_eq!(QueryKind::parse(Some(name)).expect(name), kind);
        }
        let err = QueryKind::parse(Some("insert")).expect_err("unknown kind");
        assert!(err.to_string().contains("insert"), "{err}");
    }
}