rustango 0.67.0

Batteries-included web framework for Rust: ORM + migrations + auto-admin + multi-tenancy + audit log + auth (sessions, JWT, OAuth2/OIDC, HMAC) + APIs (ViewSet, OpenAPI auto-derive, JSON:API) + jobs (in-mem + Postgres) + email + media (S3 / R2 / B2 / MinIO + presigned uploads + collections + tags) + production middleware (CSRF, CSP, rate-limiting, compression, idempotency, etc.).
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
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
//! `get_or_create` / `update_or_create` helpers.
//!
//! Extracted from `executor/mod.rs` as part of #116 step 2. Both
//! helpers go through `FetcherPool::fetch` then either return
//! the existing row or invoke the caller's `create_fn` / `update_fn`
//! closure.

use super::{
    atomic, select_rows_tx_with_related, ExecError, FetcherPool, LoadRelated, MaybeMyFromRow,
    MaybeMyLoadRelated, MaybePgFromRow, MaybeSqliteFromRow, MaybeSqliteLoadRelated, PoolTx,
};
use crate::core::{Model, SelectQuery};
use crate::sql::Pool;

/// v0.45 — `get_or_create`. Runs the queryset; if it
/// matches exactly one row return `(row, false)`; if it matches none
/// invoke `create_fn` to materialize a new instance + insert it and
/// return `(created, true)`. Matching multiple rows is a
/// programming error and returns
/// [`ExecError::MultipleRowsReturned`].
///
/// Not atomic: another writer can insert between the SELECT and the
/// INSERT. When `create_fn` fails on a UNIQUE or primary-key violation,
/// the query runs again and the row it now finds is returned, so a
/// UNIQUE constraint over the filtered columns makes concurrent callers safe.
/// Inside an [`atomic`](super::atomic) block on `pool`, the reads join the
/// block and `create_fn` runs in a savepoint: its writes roll back when it
/// fails and the block stays usable. Do not hold the block's guard across it.
/// In a PG repeatable-read block a lost race returns the unique violation,
/// and in a serializable one a serialization failure (40001): no read sees
/// the winner's row there.
///
/// The closure receives an **owned** `Pool` (cheap to clone — it's
/// an `Arc` internally). That sidesteps Rust's async-closure
/// lifetime inference: borrowed `&Pool` inside a future returned
/// from a closure trips the compiler's `'1 must outlive '2` rule.
///
/// # Example
///
/// ```ignore
/// let (post, created) = rustango::sql::get_or_create(
///     Post::objects().filter("slug", "hello"),
///     |pool| async move {
///         let mut p = Post {
///             id: Auto::Unset,
///             slug: "hello".into(),
///             title: "Hello".into(),
///         };
///         p.insert(&pool).await?;
///         Ok(p)
///     },
///     &pool,
/// ).await?;
/// ```
///
/// # Errors
/// - [`ExecError::MultipleRowsReturned`] when the filter matches >1 row.
/// - Whatever the `create_fn` closure returns when matching no rows.
/// - Whatever [`FetcherPool::fetch`] returns.
pub async fn get_or_create<T, F, Fut>(
    qs: crate::query::QuerySet<T>,
    create_fn: F,
    pool: &Pool,
) -> Result<(T, bool), ExecError>
where
    T: Model
        + MaybePgFromRow
        + MaybeMyFromRow
        + MaybeSqliteFromRow
        + LoadRelated
        + MaybeMyLoadRelated
        + MaybeSqliteLoadRelated
        + Send
        + Unpin,
    F: FnOnce(Pool) -> Fut,
    Fut: std::future::Future<Output = Result<T, ExecError>>,
{
    match fetch_at_most_one(qs.clone(), "get_or_create", pool).await? {
        Some(row) => Ok((row, false)),
        None => match create(create_fn, pool).await {
            Ok(row) => Ok((row, true)),
            Err(e) => Ok((lost_race(qs, e, "get_or_create", pool, true).await?, false)),
        },
    }
}

/// [`get_or_create`] inside an open transaction: the read and `create_fn`
/// both run on `tx`. `create_fn` runs in a savepoint: when it loses an
/// insert race (a unique violation) it is rolled back and the winner's row
/// read instead, so `tx` stays usable. A PG repeatable-read transaction
/// returns the unique violation instead, a serializable one a
/// serialization failure (40001).
///
/// ```ignore
/// let (post, created) = rustango::sql::get_or_create_tx(
///     Post::objects().filter("slug", "hello"),
///     |tx| Box::pin(async move {
///         rustango::sql::insert_tx(tx, &query).await?;
///         Ok(post)
///     }),
///     &mut tx,
/// ).await?;
/// ```
///
/// # Errors
/// As [`get_or_create`].
pub async fn get_or_create_tx<'t, T, F>(
    qs: crate::query::QuerySet<T>,
    create_fn: F,
    tx: &mut PoolTx<'t>,
) -> Result<(T, bool), ExecError>
where
    T: Model
        + MaybePgFromRow
        + MaybeMyFromRow
        + MaybeSqliteFromRow
        + LoadRelated
        + MaybeMyLoadRelated
        + MaybeSqliteLoadRelated
        + Send
        + Unpin,
    F: for<'a> FnOnce(
        &'a mut PoolTx<'t>,
    ) -> std::pin::Pin<
        Box<dyn std::future::Future<Output = Result<T, ExecError>> + Send + 'a>,
    >,
{
    let select = qs.compile()?;
    match at_most_one(
        select_rows_tx_with_related(tx, &select).await?,
        "get_or_create",
    )? {
        Some(row) => Ok((row, false)),
        None => create_or_winner_tx(select, create_fn, tx, "get_or_create", true).await,
    }
}

/// [`update_or_create`] inside an open transaction: the read, `update_fn`
/// and `create_fn` all run on `tx`. A lost insert race updates the winner's
/// row, as in [`get_or_create_tx`], with the same PG repeatable-read and
/// serializable errors.
///
/// # Errors
/// As [`update_or_create`].
pub async fn update_or_create_tx<'t, T, UF, CF>(
    qs: crate::query::QuerySet<T>,
    update_fn: UF,
    create_fn: CF,
    tx: &mut PoolTx<'t>,
) -> Result<(T, bool), ExecError>
where
    T: Model
        + MaybePgFromRow
        + MaybeMyFromRow
        + MaybeSqliteFromRow
        + LoadRelated
        + MaybeMyLoadRelated
        + MaybeSqliteLoadRelated
        + Send
        + Unpin,
    UF: for<'a> FnOnce(
        &'a mut PoolTx<'t>,
        T,
    ) -> std::pin::Pin<
        Box<dyn std::future::Future<Output = Result<T, ExecError>> + Send + 'a>,
    >,
    CF: for<'a> FnOnce(
        &'a mut PoolTx<'t>,
    ) -> std::pin::Pin<
        Box<dyn std::future::Future<Output = Result<T, ExecError>> + Send + 'a>,
    >,
{
    let select = qs.compile()?;
    let found = select_rows_tx_with_related(tx, &select).await?;
    let existing = match at_most_one(found, "update_or_create")? {
        Some(row) => row,
        None => {
            match create_or_winner_tx(select, create_fn, tx, "update_or_create", false).await? {
                (row, true) => return Ok((row, true)),
                (row, false) => row,
            }
        }
    };
    Ok((update_fn(tx, existing).await?, false))
}

/// `create_fn` in a savepoint of `tx`; on a unique violation, the row a
/// concurrent writer inserted first, with `(row, created)`.
async fn create_or_winner_tx<'t, T, F>(
    select: SelectQuery,
    create_fn: F,
    tx: &mut PoolTx<'t>,
    op: &'static str,
    share: bool,
) -> Result<(T, bool), ExecError>
where
    T: Model
        + MaybePgFromRow
        + MaybeMyFromRow
        + MaybeSqliteFromRow
        + LoadRelated
        + MaybeMyLoadRelated
        + MaybeSqliteLoadRelated
        + Send
        + Unpin,
    F: for<'a> FnOnce(
        &'a mut PoolTx<'t>,
    ) -> std::pin::Pin<
        Box<dyn std::future::Future<Output = Result<T, ExecError>> + Send + 'a>,
    >,
{
    // Its own name: a nested call on the same transaction must not replace it (MySQL).
    let point = tx.next_savepoint("rustango_create");
    tx.execute_unprepared(&format!("SAVEPOINT {point}")).await?;
    let err = match create_fn(tx).await {
        Ok(row) => {
            tx.execute_unprepared(&format!("RELEASE SAVEPOINT {point}"))
                .await?;
            return Ok((row, true));
        }
        Err(e) => e,
    };
    let undo = format!("ROLLBACK TO SAVEPOINT {point}; RELEASE SAVEPOINT {point}");
    // A deadlock or lost connection may have ended the whole transaction:
    // `create_fn`'s error says why, not the failed rollback.
    if tx.execute_unprepared(&undo).await.is_err() || !err.is_unique_violation() {
        return Err(err);
    }
    let select = winner_read(select, tx.dialect(), share);
    let row = at_most_one(select_rows_tx_with_related(tx, &select).await?, op)?.ok_or(err)?;
    Ok((row, false))
}

/// The re-read after a lost race: MySQL's repeatable-read snapshot predates
/// the winner's row, so it reads with a lock (`share`, else for update). A
/// lock the caller set is kept.
fn winner_read(mut select: SelectQuery, dialect: &dyn super::Dialect, share: bool) -> SelectQuery {
    if dialect.name() == "mysql" && select.lock_mode.is_none() {
        let mut lock = crate::core::LockMode::default();
        lock.share = share;
        lock.of = vec![select.model.table];
        lock.silent_on_sqlite = true;
        select.lock_mode = Some(lock);
    }
    select
}

/// Run `create_fn`, in a savepoint of the `atomic` block on `pool` if
/// any, so a unique violation leaves the block usable for the retry.
async fn create<T, F, Fut>(create_fn: F, pool: &Pool) -> Result<T, ExecError>
where
    F: FnOnce(Pool) -> Fut,
    Fut: std::future::Future<Output = Result<T, ExecError>>,
{
    atomic::caught(pool, create_fn(pool.clone())).await
}

/// The one row `qs` matches, if any.
async fn fetch_at_most_one<T>(
    qs: crate::query::QuerySet<T>,
    op: &'static str,
    pool: &Pool,
) -> Result<Option<T>, ExecError>
where
    T: Model
        + MaybePgFromRow
        + MaybeMyFromRow
        + MaybeSqliteFromRow
        + LoadRelated
        + MaybeMyLoadRelated
        + MaybeSqliteLoadRelated
        + Send
        + Unpin,
{
    at_most_one(qs.fetch(pool).await?, op)
}

/// The only row of `rows`, if any; more than one is an error.
fn at_most_one<T: Model>(mut rows: Vec<T>, op: &'static str) -> Result<Option<T>, ExecError> {
    match rows.len() {
        0 => Ok(None),
        1 => Ok(Some(rows.remove(0))),
        n => Err(ExecError::MultipleRowsReturned {
            op,
            table: T::SCHEMA.table,
            count: n,
        }),
    }
}

/// After `create_fn` failed with `err`: the row a concurrent writer
/// inserted first when `err` is a unique violation, else `err`.
async fn lost_race<T>(
    qs: crate::query::QuerySet<T>,
    err: ExecError,
    op: &'static str,
    pool: &Pool,
    share: bool,
) -> Result<T, ExecError>
where
    T: Model
        + MaybePgFromRow
        + MaybeMyFromRow
        + MaybeSqliteFromRow
        + LoadRelated
        + MaybeMyLoadRelated
        + MaybeSqliteLoadRelated
        + Send
        + Unpin,
{
    if !err.is_unique_violation() {
        return Err(err);
    }
    // Only a block's re-read joins a snapshot. `update_or_create` takes the
    // update lock at once, so two losers cannot deadlock upgrading.
    let mut select = qs.compile()?;
    if atomic::in_block(pool) {
        select = winner_read(select, pool.dialect(), share);
    }
    at_most_one(
        super::select_rows_pool_with_related(pool, &select).await?,
        op,
    )?
    .ok_or(err)
}

/// v0.45 — `update_or_create`. Runs the queryset; if
/// it matches exactly one row, invoke `update_fn` to mutate it +
/// save the changes and return `(updated, false)`; if it matches
/// none, invoke `create_fn` and return `(created, true)`. Matching
/// multiple rows returns [`ExecError::MultipleRowsReturned`].
///
/// Not atomic, as [`get_or_create`]: a create that loses to a concurrent
/// insert on a UNIQUE constraint updates the winner's row instead.
///
/// Both closures receive an **owned** `Pool` for the same
/// async-lifetime reason as [`get_or_create`].
///
/// # Example
///
/// ```ignore
/// let (post, created) = rustango::sql::update_or_create(
///     Post::objects().filter("slug", "hello"),
///     |pool, mut existing| async move {
///         existing.title = "New title".into();
///         existing.save(&pool).await?;
///         Ok(existing)
///     },
///     |pool| async move {
///         let mut p = Post { /* defaults */ };
///         p.insert(&pool).await?;
///         Ok(p)
///     },
///     &pool,
/// ).await?;
/// ```
///
/// # Errors
/// As [`get_or_create`].
pub async fn update_or_create<T, UF, UFut, CF, CFut>(
    qs: crate::query::QuerySet<T>,
    update_fn: UF,
    create_fn: CF,
    pool: &Pool,
) -> Result<(T, bool), ExecError>
where
    T: Model
        + MaybePgFromRow
        + MaybeMyFromRow
        + MaybeSqliteFromRow
        + LoadRelated
        + MaybeMyLoadRelated
        + MaybeSqliteLoadRelated
        + Send
        + Unpin,
    UF: FnOnce(Pool, T) -> UFut,
    UFut: std::future::Future<Output = Result<T, ExecError>>,
    CF: FnOnce(Pool) -> CFut,
    CFut: std::future::Future<Output = Result<T, ExecError>>,
{
    let existing = match fetch_at_most_one(qs.clone(), "update_or_create", pool).await? {
        Some(row) => row,
        None => match create(create_fn, pool).await {
            Ok(row) => return Ok((row, true)),
            Err(e) => lost_race(qs, e, "update_or_create", pool, false).await?,
        },
    };
    Ok((update_fn(pool.clone(), existing).await?, false))
}

impl<T> crate::query::QuerySet<T>
where
    T: Model
        + MaybePgFromRow
        + MaybeMyFromRow
        + MaybeSqliteFromRow
        + LoadRelated
        + MaybeMyLoadRelated
        + MaybeSqliteLoadRelated
        + Send
        + Unpin,
{
    /// Chainable form of [`get_or_create`]. Sugar for
    /// `get_or_create(self, create_fn, pool)` so call sites read as
    /// `Post::objects().filter(...).get_or_create(|pool| ..., &pool)`.
    ///
    /// Returns `(row, created)` where `created` is `true` when the
    /// closure was invoked.
    ///
    /// # Errors
    /// As [`get_or_create`].
    pub async fn get_or_create<F, Fut>(
        self,
        create_fn: F,
        pool: &Pool,
    ) -> Result<(T, bool), ExecError>
    where
        F: FnOnce(Pool) -> Fut,
        Fut: std::future::Future<Output = Result<T, ExecError>>,
    {
        get_or_create(self, create_fn, pool).await
    }

    /// Eloquent `Model::firstOrCreate($attributes, $values)` alias
    /// for [`Self::get_or_create`]. Identical semantics; the
    /// separate name keeps Laravel muscle-memory call sites
    /// readable.
    ///
    /// # Errors
    /// As [`Self::get_or_create`].
    pub async fn first_or_create<F, Fut>(
        self,
        create_fn: F,
        pool: &Pool,
    ) -> Result<(T, bool), ExecError>
    where
        F: FnOnce(Pool) -> Fut,
        Fut: std::future::Future<Output = Result<T, ExecError>>,
    {
        self.get_or_create(create_fn, pool).await
    }

    /// Chainable form of [`update_or_create`]. Sugar for
    /// `update_or_create(self, update_fn, create_fn, pool)`.
    ///
    /// Returns `(row, created)` where `created` is `true` when the
    /// `create_fn` closure was invoked (i.e. no row matched the
    /// queryset).
    ///
    /// # Errors
    /// As [`update_or_create`].
    pub async fn update_or_create<UF, UFut, CF, CFut>(
        self,
        update_fn: UF,
        create_fn: CF,
        pool: &Pool,
    ) -> Result<(T, bool), ExecError>
    where
        UF: FnOnce(Pool, T) -> UFut,
        UFut: std::future::Future<Output = Result<T, ExecError>>,
        CF: FnOnce(Pool) -> CFut,
        CFut: std::future::Future<Output = Result<T, ExecError>>,
    {
        update_or_create(self, update_fn, create_fn, pool).await
    }
}