rustango 0.65.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
//! On-disk migration file format.
//!
//! One JSON file per migration, named so a lexical sort gives the
//! apply order (`0001_initial.json`, `0002_add_bio_to_author.json`).
//! Each file holds the **full schema snapshot** at that point, so it
//! can stand alone as a starting state and a rollback can recover the
//! metadata of a dropped field without reading its predecessors.
//!
//! `forward` is one ordered list of [`Operation`]s, mixing schema and
//! data steps. That lets one migration do the usual "add a nullable
//! column, backfill it, then set NOT NULL".
//!
//! ```json
//! {
//!   "name": "0002_backfill_slugs",
//!   "created_at": "2026-04-28T10:00:00Z",
//!   "prev": "0001_initial",
//!   "atomic": true,
//!   "snapshot": { "tables": [/* SchemaSnapshot */] },
//!   "forward": [
//!     { "schema": { "AddColumn": { "table": "article", "column": "slug" } } },
//!     { "data":   { "sql": "UPDATE article SET slug = ...",
//!                   "reverse_sql": "UPDATE article SET slug = NULL",
//!                   "reversible": true } }
//!   ]
//! }
//! ```

use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use super::diff::SchemaChange;
use super::error::MigrateError;
use super::snapshot::SchemaSnapshot;

/// One migration on disk.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Migration {
    /// Lex-sortable file stem, e.g. `0002_add_bio_to_author`. Apply order.
    pub name: String,
    /// RFC3339 timestamp written by `make_migrations`. For humans
    /// only; the runner ignores it.
    pub created_at: String,
    /// Predecessor migration name. `None` for `0001_initial`.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub prev: Option<String>,
    /// Wrap the migration in a transaction. Default `true`. Set
    /// `false` for statements that cannot run in one, such as
    /// `CREATE INDEX CONCURRENTLY`.
    #[serde(default = "default_atomic")]
    pub atomic: bool,
    /// Whether this runs against the registry or every tenant.
    /// Defaults to `Tenant`, which covers most schema work.
    #[serde(default, skip_serializing_if = "MigrationScope::is_default")]
    pub scope: MigrationScope,
    /// The migrations this one **replaces**, for a squash.
    ///
    /// A squash folds a run of old migrations into one file that
    /// reaches the same end state. On a fresh database it just runs.
    /// On a database that already applied the replaced migrations the
    /// runner reconciles instead: it records the squash and tombstones
    /// the old ledger rows, running no DDL. See
    /// [`crate::migrate::migrate_pool`] and the `--fake` flag.
    ///
    /// Empty for an ordinary migration, and then left out of the JSON.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub replaces: Vec<String>,
    /// The other leaves a `--merge` node joins; `prev` names the last one.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub merges: Vec<String>,
    /// Full schema snapshot **after** `forward` has been applied.
    pub snapshot: SchemaSnapshot,
    /// Ordered operations, schema and data mixed.
    pub forward: Vec<Operation>,
}

/// Where a migration runs.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "lowercase")]
pub enum MigrationScope {
    /// Runs once against the registry database. For registry-only
    /// tables such as `rustango_orgs` or `rustango_operators`.
    Registry,
    /// Runs against every active org's storage. The default, and
    /// almost all user schema work.
    #[default]
    Tenant,
}

impl MigrationScope {
    /// Used by serde's `skip_serializing_if` to keep the default
    /// (`Tenant`) out of migration files.
    #[must_use]
    pub fn is_default(&self) -> bool {
        matches!(self, Self::Tenant)
    }
}

fn default_atomic() -> bool {
    true
}

/// One step inside [`Migration::forward`].
///
/// Externally tagged with lowercase variant names so the JSON reads as
/// `{"schema": …}` / `{"data": …}` / `{"callback": …}`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Operation {
    /// A schema change, in the same shape as the diff IR
    /// ([`SchemaChange`]). Rendered by `render_changes` at apply time.
    Schema(SchemaChange),
    /// Raw SQL the user wrote by hand, usually a backfill.
    Data(DataOp),
    /// Calls a named Rust callback at apply time. Register it with
    /// [`crate::register_migration_callback!`] at startup.
    Callback(CallbackOp),
}

/// Names the Rust callback an [`Operation::Callback`] runs. The runner
/// looks the name up in [`crate::migrate::callbacks`] at apply time;
/// an unknown name is a [`crate::migrate::MigrateError::Validation`].
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CallbackOp {
    /// Forward-callback name. Required.
    pub name: String,
    /// Reverse-callback name. With `None`, rollback fails rather than
    /// skipping the step.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub reverse_name: Option<String>,
}

/// User-written SQL plus its inverse. Both go into the statement
/// as-is: no escaping and no parameter binding.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DataOp {
    /// SQL run when the migration is applied forward.
    pub sql: String,
    /// SQL run on rollback. `None` is valid only when `reversible` is
    /// `false`; loading rejects the contradiction.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub reverse_sql: Option<String>,
    /// `false` marks the op one-way. Rollback then fails instead of
    /// quietly skipping it.
    #[serde(default = "default_reversible")]
    pub reversible: bool,
}

fn default_reversible() -> bool {
    true
}

/// Read and parse a migration file.
///
/// # Errors
/// Returns [`MigrateError::Io`] if the file is unreadable, or
/// [`MigrateError::Json`] if its contents don't deserialize. Also
/// rejects an internally-inconsistent `Operation::Data` where
/// `reversible == true` but `reverse_sql` is missing, and a callback in
/// an atomic migration (#1626).
pub fn load(path: &Path) -> Result<Migration, MigrateError> {
    let raw = crate::text_file::read(path)?;
    parse(&raw)
}

/// Parse and validate a migration from a JSON string. Used by
/// [`load`], and by `migrate_embedded` for `include_str!` bytes.
///
/// # Errors
/// Returns [`MigrateError::Json`] on parse failure or
/// [`MigrateError::Validation`] on internal-consistency failures.
pub fn parse(raw: &str) -> Result<Migration, MigrateError> {
    let mig: Migration = serde_json::from_str(raw)?;
    validate(&mig)?;
    Ok(mig)
}

/// Serialize and write a migration file (pretty-printed).
///
/// # Errors
/// Returns [`MigrateError::Io`] on write failure or
/// [`MigrateError::Json`] on serialization failure.
pub fn write(path: &Path, migration: &Migration) -> Result<(), MigrateError> {
    let raw = serde_json::to_string_pretty(migration)?;
    std::fs::write(path, raw)?;
    Ok(())
}

/// A new temp dir with a random name, owner-only on Unix: a leftover or
/// planted dir is never reused, so only this run's files are applied.
pub(crate) fn private_tempdir(prefix: &str) -> std::io::Result<tempfile::TempDir> {
    let mut builder = tempfile::Builder::new();
    builder.prefix(prefix);
    // tempfile makes dirs (unlike files) with the default 0777 less the umask.
    #[cfg(unix)]
    builder.permissions(std::os::unix::fs::PermissionsExt::from_mode(0o700));
    builder.tempdir()
}

/// Load every `*.json` migration in `dir`, sorted lexicographically by
/// file name (which is the canonical apply order).
///
/// A missing `dir` gives an empty list, which is what a fresh project
/// needs. Each file is validated by [`load`], and the `prev` chain by
/// [`validate_chain`], so a migration naming a predecessor that is not
/// there fails here with a clear error instead of deep inside
/// `unapply` or `migrate_to`.
///
/// # Errors
/// Returns [`MigrateError::Io`] on read failure, [`MigrateError::Json`]
/// on parse failure, or [`MigrateError::Validation`] if any file is
/// internally inconsistent or the chain is broken.
pub fn list_dir(dir: &Path) -> Result<Vec<Migration>, MigrateError> {
    if !dir.exists() {
        return Ok(Vec::new());
    }
    let mut paths: Vec<PathBuf> = std::fs::read_dir(dir)?
        .filter_map(Result::ok)
        .map(|e| e.path())
        .filter(|p| p.extension().and_then(|s| s.to_str()) == Some("json"))
        .collect();
    paths.sort();
    let mut out = Vec::with_capacity(paths.len());
    for p in paths {
        out.push(load(&p)?);
    }
    validate_chain(&out, &dir.display().to_string())?;
    Ok(out)
}

/// [`list_dir`] over several directories. Loads each one, then sorts
/// the merged list by `name`, so apply order does not depend on which
/// app contributed which file.
///
/// Each directory's `prev` chain is checked on its own. Chains are not
/// required to link across directories: two independent apps have no
/// reason to chain through each other.
///
/// # Errors
/// Whatever [`list_dir`] returns for any of the inputs.
pub fn list_dirs<I, P>(dirs: I) -> Result<Vec<Migration>, MigrateError>
where
    I: IntoIterator<Item = P>,
    P: AsRef<Path>,
{
    let mut out: Vec<Migration> = Vec::new();
    for dir in dirs {
        out.extend(list_dir(dir.as_ref())?);
    }
    out.sort_by(|a, b| a.name.cmp(&b.name));
    Ok(out)
}

/// [`list_dir`] of each of `dirs`, kept in their order: the order a
/// tenancy project applies its folders in.
///
/// # Errors
/// Whatever [`list_dir`] returns for any of them.
pub(crate) fn list_each(dirs: &[PathBuf]) -> Result<Vec<Migration>, MigrateError> {
    let mut out = Vec::new();
    for dir in dirs {
        out.extend(list_dir(dir)?);
    }
    Ok(out)
}

/// Every migrations directory under `project_root`: the top-level
/// `migrations/`, plus one per app at `<app>/migrations/`.
///
/// Used by `Builder::migrate(project_root)` so a multi-app project
/// migrates in one call. Returns paths rather than loaded migrations,
/// so a caller can filter by scope first.
///
/// The top-level directory comes first, so its bootstraps run before
/// app content; app directories follow in name order.
#[must_use]
pub fn discover_migration_dirs(project_root: &Path) -> Vec<PathBuf> {
    let mut out: Vec<PathBuf> = Vec::new();
    let flat = project_root.join("migrations");
    if flat.is_dir() {
        out.push(flat);
    }
    if let Ok(read) = std::fs::read_dir(project_root) {
        let mut app_dirs: Vec<PathBuf> = read
            .filter_map(Result::ok)
            .filter_map(|entry| {
                let path = entry.path();
                if !path.is_dir() {
                    return None;
                }
                // Skip the top-level migrations dir, already added,
                // and folders that are clearly not apps.
                let name = path.file_name()?.to_str()?;
                // `system` is the framework's own app. Tenancy
                // provisioning applies its migrations by scope under
                // a separate ledger, so it is not a plain app dir.
                if matches!(
                    name,
                    "migrations" | "target" | "src" | ".git" | "node_modules" | "system"
                ) || name.starts_with('.')
                {
                    return None;
                }
                let candidate = path.join("migrations");
                if candidate.is_dir() {
                    Some(candidate)
                } else {
                    None
                }
            })
            .collect();
        app_dirs.sort();
        out.extend(app_dirs);
    }
    out
}

/// The dirs tenancy migrates for `dir`: a `migrations` dir and the
/// `<app>/migrations/` beside it, a project root's dirs, else `dir` alone.
/// Boot, provisioning, `migrate` and `check` all walk this list.
#[must_use]
pub(crate) fn project_migration_dirs(dir: &Path) -> Vec<PathBuf> {
    let found = discover_migration_dirs(project_root_of(dir));
    if found.is_empty() {
        vec![dir.to_path_buf()]
    } else {
        found
    }
}

/// The dir whose `migrations/` and `<app>/migrations/` belong with `dir`:
/// its parent when it is a `migrations` dir, else `dir` itself.
pub(crate) fn project_root_of(dir: &Path) -> &Path {
    match dir.parent() {
        // A bare `migrations` has the parent `""`, which `read_dir` refuses.
        Some(p) if dir.file_name().is_some_and(|n| n == "migrations") => {
            if p.as_os_str().is_empty() {
                Path::new(".")
            } else {
                p
            }
        }
        _ => dir,
    }
}

/// Check that every `prev` names another migration in the same list.
/// `origin` is a directory path or a label, and appears in the error
/// so the reader knows where the migrations came from.
///
/// # Errors
/// Returns [`MigrateError::Validation`] on the first broken link.
pub(crate) fn validate_chain(migrations: &[Migration], origin: &str) -> Result<(), MigrateError> {
    for mig in migrations {
        if let Some(prev) = &mig.prev {
            if !migrations.iter().any(|m| &m.name == prev) {
                return Err(MigrateError::Validation(format!(
                    "broken migration chain: `{}` declares prev=`{prev}` but that migration is missing from {origin}",
                    mig.name,
                )));
            }
        }
    }
    Ok(())
}

/// Extract the leading numeric prefix from a migration name
/// (e.g. `0042_add_slug` → `42`).
#[must_use]
pub fn extract_index(name: &str) -> Option<u32> {
    let prefix: String = name.chars().take_while(char::is_ascii_digit).collect();
    if prefix.is_empty() {
        None
    } else {
        prefix.parse().ok()
    }
}

fn validate(mig: &Migration) -> Result<(), MigrateError> {
    for (i, op) in mig.forward.iter().enumerate() {
        match op {
            Operation::Data(d) => {
                if d.reversible && d.reverse_sql.is_none() {
                    return Err(MigrateError::Validation(format!(
                        "{}: forward[{}]: reversible=true but reverse_sql is missing",
                        mig.name, i,
                    )));
                }
            }
            // The callback runs on a second connection; inside the tx it
            // waits on the tx's locks, forever on PostgreSQL (#1626).
            Operation::Callback(c) if mig.atomic => {
                return Err(MigrateError::Validation(format!(
                    "{}: forward[{}]: callback `{}` needs `\"atomic\": false`; \
                     safe to add to an already-applied file",
                    mig.name, i, c.name,
                )));
            }
            _ => {}
        }
    }
    Ok(())
}