Skip to main content

rustango_cms/
revision.rs

1//! `Revision` — versioned snapshots of `cms_page` rows.
2//!
3//! Captured on every page save in the admin. Each revision stores the
4//! full page state as JSON; [`prune`] bounds storage.
5
6use chrono::{DateTime, Utc};
7use rustango::sql::Auto;
8use rustango::Model;
9use serde::{Deserialize, Serialize};
10
11/// One row per save of a `Page`. `sequence` is a per-page monotonic
12/// counter starting at 1.
13#[derive(Model, Debug, Clone, Serialize, Deserialize)]
14#[rustango(
15    table = "cms_revision",
16    app = "cms",
17    admin(
18        list_display = "page_id, sequence, created_by, created_at",
19        ordering = "-created_at",
20        list_filter = "page_id",
21    )
22)]
23pub struct Revision {
24    #[rustango(primary_key)]
25    pub id: Auto<i64>,
26
27    /// The page this revision belongs to. FK so revisions get
28    /// cascade-deleted with their page.
29    #[rustango(fk = "cms_page", on = "id", index)]
30    pub page_id: i64,
31
32    /// Per-page sequence number, starting at 1 for the first save.
33    /// Combined with `page_id` to identify a revision; UNIQUE
34    /// (page_id, sequence) through [`ensure_unique_sequence`].
35    pub sequence: i32,
36
37    /// Full serialized state of the `cms_page` row at this point in
38    /// time.
39    pub snapshot: serde_json::Value,
40
41    /// `rustango_users.id` of the editor who triggered this save.
42    /// `None` for system / script writes.
43    pub created_by: Option<i64>,
44
45    #[rustango(auto_now_add)]
46    pub created_at: Auto<DateTime<Utc>>,
47}
48
49impl Revision {
50    /// One-line label used by the admin's `display = "label"` and the
51    /// revisions panel. Format: `"#N · YYYY-MM-DD HH:MM UTC"`.
52    #[must_use]
53    pub fn label(&self) -> String {
54        let when = self
55            .created_at
56            .get()
57            .map(|t| t.format("%Y-%m-%d %H:%M UTC").to_string())
58            .unwrap_or_default();
59        format!("#{} · {}", self.sequence, when)
60    }
61}
62
63/// Capture one revision for `page`: a full-state snapshot under the
64/// page's next `sequence`.
65///
66/// Two saves of one page can race for the same sequence. The UNIQUE
67/// (page_id, sequence) index from [`ensure_unique_sequence`] refuses the
68/// second insert, and it retries with the sequence after the winner's.
69///
70/// # Errors
71/// Driver / query failures or serialization errors.
72pub async fn capture(
73    pool: &rustango::sql::Pool,
74    page: &crate::page::Page,
75    created_by: Option<i64>,
76) -> Result<Revision, rustango::sql::ExecError> {
77    use rustango::core::Column as _;
78    use rustango::sql::{sqlx, Auto};
79
80    // Enough for every writer of one page to lose once.
81    const ATTEMPTS: usize = 10;
82    let page_id = page.id.get().copied().unwrap_or_default();
83    let snapshot = serde_json::to_value(page)
84        .map_err(|e| rustango::sql::ExecError::Driver(sqlx::Error::Decode(Box::new(e))))?;
85
86    let mut attempt = 0;
87    loop {
88        attempt += 1;
89        // Only the newest row: the history can run to thousands (#762).
90        let latest: Option<Revision> = Revision::objects()
91            .where_(Revision::page_id.eq(page_id))
92            .order_by(&[("sequence", true)])
93            .first(pool)
94            .await?;
95        let mut row = Revision {
96            id: Auto::Unset,
97            page_id,
98            sequence: latest.map_or(1, |r| r.sequence + 1),
99            snapshot: snapshot.clone(),
100            created_by,
101            created_at: Auto::Unset,
102        };
103        match row.insert(pool).await {
104            Ok(()) => return Ok(row),
105            Err(e) if attempt < ATTEMPTS && is_unique_violation(&e) => continue,
106            Err(e) => return Err(e),
107        }
108    }
109}
110
111/// Whether `e` is a UNIQUE-constraint refusal, on any backend.
112fn is_unique_violation(e: &rustango::sql::ExecError) -> bool {
113    let msg = e.to_string().to_ascii_lowercase();
114    // postgres: "duplicate key value violates unique constraint";
115    // sqlite: "UNIQUE constraint failed"; mysql: "Duplicate entry".
116    msg.contains("unique constraint") || msg.contains("duplicate entry") || msg.contains("duplicate key value")
117}
118
119/// Name of the UNIQUE (page_id, sequence) index on `cms_revision`.
120const UNIQUE_SEQUENCE_INDEX: &str = "cms_revision_page_sequence_uniq";
121
122/// Give `cms_revision` its UNIQUE (page_id, sequence) index, so a
123/// concurrent save can't reuse a sequence. Pages that already hold
124/// duplicates are renumbered first, in (sequence, id) order, which keeps
125/// their history's order. Idempotent.
126///
127/// # Errors
128/// Driver failures other than "index already exists".
129pub async fn ensure_unique_sequence(
130    pool: &rustango::sql::Pool,
131) -> Result<(), rustango::sql::ExecError> {
132    if create_unique_sequence_index(pool).await.is_ok() {
133        return Ok(());
134    }
135    renumber_duplicate_sequences(pool).await?;
136    create_unique_sequence_index(pool).await
137}
138
139async fn create_unique_sequence_index(
140    pool: &rustango::sql::Pool,
141) -> Result<(), rustango::sql::ExecError> {
142    // MySQL has no CREATE INDEX IF NOT EXISTS; its "already exists" is
143    // swallowed below instead.
144    let if_not_exists = if pool.dialect().name() == "mysql" { "" } else { "IF NOT EXISTS " };
145    let sql = format!(
146        "CREATE UNIQUE INDEX {if_not_exists}{UNIQUE_SEQUENCE_INDEX} ON cms_revision (page_id, sequence)"
147    );
148    match rustango::sql::raw_execute_pool(pool, &sql, Vec::new()).await {
149        Ok(_) => Ok(()),
150        Err(e) if e.to_string().to_ascii_lowercase().contains("duplicate key name") => Ok(()),
151        Err(e) => Err(e),
152    }
153}
154
155async fn renumber_duplicate_sequences(
156    pool: &rustango::sql::Pool,
157) -> Result<(), rustango::sql::ExecError> {
158    use rustango::core::Column as _;
159    use rustango::sql::FetcherPool as _;
160
161    let pages: Vec<(i64,)> = rustango::sql::raw_query_pool(
162        "SELECT page_id FROM cms_revision GROUP BY page_id, sequence HAVING COUNT(*) > 1",
163        Vec::new(),
164        pool,
165    )
166    .await?;
167    let mut seen = std::collections::HashSet::new();
168    for (page_id,) in pages {
169        if !seen.insert(page_id) {
170            continue;
171        }
172        let rows: Vec<Revision> = Revision::objects()
173            .where_(Revision::page_id.eq(page_id))
174            .order_by(&[("sequence", false), ("id", false)])
175            .fetch(pool)
176            .await?;
177        for (n, mut row) in rows.into_iter().enumerate() {
178            let want = i32::try_from(n + 1).unwrap_or(i32::MAX);
179            if row.sequence != want {
180                row.sequence = want;
181                row.save(pool).await?;
182            }
183        }
184    }
185    Ok(())
186}
187
188// ---------------------------------------------------------------
189// #122 — revision garbage collection. High-edit-volume pages
190// accumulate unbounded history; pruning trims back to a configurable
191// cap. The rules:
192//   1. Keep the most recent `keep_latest` revisions (default 50).
193//   2. When `keep_published` is true, never delete a revision whose
194//      snapshot has `status == "published"`.
195//   3. Always keep the single most recent published revision (the
196//      rollback anchor) regardless of #1's window.
197// ---------------------------------------------------------------
198
199/// Default `keep_latest` cap when the caller doesn't override it.
200pub const DEFAULT_KEEP_LATEST: usize = 50;
201
202/// Outcome of one [`prune`] sweep against a page.
203#[derive(Debug, Clone, Copy, Default)]
204pub struct PruneOutcome {
205    /// Rows present before the sweep ran.
206    pub total: usize,
207    /// Rows actually deleted by this sweep.
208    pub deleted: usize,
209}
210
211/// Prune old revisions for one page. Returns the count of rows
212/// deleted (0 when the page is already under the cap).
213///
214/// # Errors
215/// Driver / query failures.
216pub async fn prune(
217    pool: &rustango::sql::Pool,
218    page_id: i64,
219    keep_latest: usize,
220    keep_published: bool,
221) -> Result<PruneOutcome, rustango::sql::ExecError> {
222    use rustango::core::Column as _;
223    use rustango::sql::FetcherPool as _;
224    let mut rows: Vec<Revision> = Revision::objects()
225        .where_(Revision::page_id.eq(page_id))
226        .order_by(&[("sequence", true)]) // desc
227        .fetch(pool)
228        .await?;
229    let total = rows.len();
230    if total == 0 {
231        return Ok(PruneOutcome::default());
232    }
233    let keep = keep_latest.max(1);
234    // Anchor: most recent published-status snapshot. We always keep
235    // this regardless of position, so an emergency rollback target is
236    // never accidentally GC'd.
237    let anchor_id: Option<i64> = rows
238        .iter()
239        .find(|r| r.snapshot.get("status").and_then(|v| v.as_str()) == Some("published"))
240        .and_then(|r| r.id.get().copied());
241    let mut deleted = 0;
242    // Walk from oldest to newest so the latest `keep` stay. Iterate
243    // tail-first by reversing then dropping front entries.
244    rows.reverse();
245    let cutoff = total.saturating_sub(keep);
246    for (idx, row) in rows.into_iter().enumerate() {
247        if idx >= cutoff {
248            break;
249        }
250        if Some(row.id.get().copied().unwrap_or_default()) == anchor_id {
251            continue;
252        }
253        if keep_published
254            && (row.snapshot.get("status").and_then(|v| v.as_str()) == Some("published"))
255        {
256            continue;
257        }
258        row.delete(pool).await?;
259        deleted += 1;
260    }
261    Ok(PruneOutcome { total, deleted })
262}
263
264/// Run [`prune`] against every page in the tenant. Best-effort —
265/// per-page failures log + continue so one bad page doesn't abort
266/// the whole sweep. Returns the aggregated `(pages_scanned, rows_deleted)`.
267///
268/// # Errors
269/// Driver / query failures on the initial page-id lookup. Per-page
270/// pruning errors are logged + swallowed.
271pub async fn prune_all_pages(
272    pool: &rustango::sql::Pool,
273    keep_latest: usize,
274    keep_published: bool,
275) -> Result<(usize, usize), rustango::sql::ExecError> {
276    use rustango::sql::FetcherPool as _;
277    let pages: Vec<crate::page::Page> = crate::page::Page::objects().fetch(pool).await?;
278    let mut total_pages = 0;
279    let mut total_deleted = 0;
280    for p in pages {
281        let Some(pid) = p.id.get().copied() else {
282            continue;
283        };
284        total_pages += 1;
285        match prune(pool, pid, keep_latest, keep_published).await {
286            Ok(outcome) => total_deleted += outcome.deleted,
287            Err(e) => tracing::warn!(
288                target: "rustango_cms::revision",
289                page_id = pid,
290                error = %e,
291                "revision prune failed; continuing"
292            ),
293        }
294    }
295    Ok((total_pages, total_deleted))
296}
297
298// ---------------------------------------------------------------
299// #74 — revision diff. Lightweight, side-by-side, field-level JSON
300// comparison between two snapshots. Rich-text + StreamField
301// awareness deferred to a follow-up; v1 treats those as opaque
302// JSON values and just flags "changed."
303// ---------------------------------------------------------------
304
305/// One field's diff outcome for the compare view.
306#[derive(Debug, Clone, serde::Serialize)]
307#[serde(tag = "kind", rename_all = "snake_case")]
308pub enum FieldDiff {
309    /// Same value on both sides — surfaced so the template can
310    /// optionally collapse them under a "show all fields" toggle.
311    Unchanged { field: String, value: String },
312    /// Different value. Both sides rendered for side-by-side.
313    Changed { field: String, a: String, b: String },
314    /// Only in B (a was null / missing).
315    Added { field: String, b: String },
316    /// Only in A (b is null / missing).
317    Removed { field: String, a: String },
318}
319
320impl FieldDiff {
321    /// Field name accessor for template grouping.
322    #[must_use]
323    pub fn field(&self) -> &str {
324        match self {
325            Self::Unchanged { field, .. }
326            | Self::Changed { field, .. }
327            | Self::Added { field, .. }
328            | Self::Removed { field, .. } => field,
329        }
330    }
331
332    /// True for the three non-`Unchanged` variants — drives the
333    /// "show only changed" filter in the template.
334    #[must_use]
335    pub fn is_change(&self) -> bool {
336        !matches!(self, Self::Unchanged { .. })
337    }
338}
339
340/// `(id, page_id, sequence)` of every revision of the given pages — light
341/// columns only, never the snapshots. The history screen uses it for the
342/// "latest" flag and the Compare link, which have to be right for a row at
343/// the edge of a page.
344///
345/// # Errors
346/// Driver / query failures.
347pub async fn page_sequences(
348    pool: &rustango::sql::Pool,
349    page_ids: &[i64],
350) -> Result<Vec<(i64, i64, i32)>, rustango::sql::ExecError> {
351    use rustango::core::{Column as _, SqlValue};
352    let int = |v: &SqlValue| match v {
353        SqlValue::I64(n) => Some(*n),
354        SqlValue::I32(n) => Some(i64::from(*n)),
355        SqlValue::I16(n) => Some(i64::from(*n)),
356        _ => None,
357    };
358    let mut out = Vec::new();
359    for chunk in page_ids.chunks(500) {
360        let rows = Revision::objects()
361            .where_(Revision::page_id.is_in(chunk.to_vec()))
362            .values_list(&["id", "page_id", "sequence"])
363            .fetch(pool)
364            .await?;
365        for row in rows {
366            if let [id, page_id, sequence] = row.as_slice() {
367                if let (Some(id), Some(page_id), Some(seq)) = (int(id), int(page_id), int(sequence)) {
368                    out.push((id, page_id, i32::try_from(seq).unwrap_or_default()));
369                }
370            }
371        }
372    }
373    Ok(out)
374}
375
376#[cfg(all(test, feature = "sqlite"))]
377mod page_sequence_tests {
378    use super::*;
379    use rustango::core::Model as _;
380
381    #[tokio::test]
382    async fn sequences_of_the_asked_pages_come_back_without_snapshots() {
383        // A file, not `:memory:`: each pooled connection to `:memory:` is its own database.
384        let path = std::env::temp_dir().join(format!("rcms-revseq-{}.db", std::process::id()));
385        let _ = std::fs::remove_file(&path);
386        let pool = rustango::sql::Pool::connect(&format!("sqlite:{}?mode=rwc", path.display())).await.expect("pool");
387        // The columns `page_sequences` reads, without the page foreign key:
388        // only revisions are under test, and no `cms_page` rows exist.
389        let table = Revision::SCHEMA.table;
390        rustango::sql::raw_execute_pool(
391            &pool,
392            &format!(
393                "CREATE TABLE {table} (id INTEGER PRIMARY KEY AUTOINCREMENT, page_id INTEGER NOT NULL, \
394                 sequence INTEGER NOT NULL, snapshot TEXT NOT NULL, created_by INTEGER, created_at TEXT NOT NULL)"
395            ),
396            Vec::new(),
397        )
398        .await
399        .expect("ddl");
400        for (page_id, sequence) in [(1_i64, 1_i32), (1, 2), (2, 1), (3, 1)] {
401            rustango::sql::raw_execute_pool(
402                &pool,
403                &format!(
404                    "INSERT INTO {table} (page_id, sequence, snapshot, created_at) \
405                     VALUES ({page_id}, {sequence}, '{{\"big\":\"snapshot\"}}', '2026-11-07T00:00:00Z')"
406                ),
407                Vec::new(),
408            )
409            .await
410            .expect("revision");
411        }
412        let mut got = page_sequences(&pool, &[1, 2]).await.expect("sequences");
413        got.sort();
414        let pairs: Vec<(i64, i32)> = got.iter().map(|&(_, p, s)| (p, s)).collect();
415        assert_eq!(pairs, [(1, 1), (1, 2), (2, 1)], "page 3 was not asked for");
416        assert!(page_sequences(&pool, &[]).await.expect("empty").is_empty());
417        let _ = std::fs::remove_file(&path);
418    }
419}
420
421#[cfg(test)]
422mod prune_tests {
423    use super::*;
424
425    /// Pure helper that the prune logic uses internally — confirm
426    /// the cutoff math is right for a few representative shapes.
427    fn cutoff_for(total: usize, keep: usize) -> usize {
428        total.saturating_sub(keep.max(1))
429    }
430
431    #[test]
432    fn no_cutoff_when_under_keep() {
433        assert_eq!(cutoff_for(10, 50), 0);
434    }
435
436    #[test]
437    fn cutoff_drops_oldest_only() {
438        // 100 rows, keep 50 → cutoff = 50 (oldest 50 deleted).
439        assert_eq!(cutoff_for(100, 50), 50);
440    }
441
442    #[test]
443    fn keep_zero_treated_as_one() {
444        assert_eq!(cutoff_for(10, 0), 9);
445    }
446
447    #[test]
448    fn default_keep_latest_is_sensible() {
449        assert!((10..=200).contains(&DEFAULT_KEEP_LATEST));
450    }
451}
452
453/// Fields surfaced in the diff view. Tree-shape columns
454/// (`id`, `path`, `depth`, `parent_id`, `sort_order`, `url_path`)
455/// are intentionally excluded — Revert leaves those alone, so
456/// diffing them just adds noise. Audit-stamp columns (`created_at`,
457/// `updated_at`) are excluded for the same reason.
458const DIFF_FIELDS: &[&str] = &[
459    "title",
460    "slug",
461    "status",
462    "page_type_id",
463    "seo_title",
464    "seo_description",
465    "robots_index",
466    "sitemap_priority",
467    "theme_id",
468    "show_in_menus",
469    "go_live_at",
470    "expire_at",
471    "published_at",
472    "locale_variant_of",
473];
474
475/// Format a `serde_json::Value` for display in the diff cell. Strings
476/// render verbatim; numbers / bools use their JSON shape; objects +
477/// arrays are pretty-printed (StreamField bodies are JSON arrays —
478/// the v1 cell shows the formatted JSON). `Null` renders as `—`.
479fn format_value(value: &serde_json::Value) -> String {
480    use serde_json::Value;
481    match value {
482        Value::Null => "—".to_owned(),
483        Value::String(s) => s.clone(),
484        Value::Bool(b) => b.to_string(),
485        Value::Number(n) => n.to_string(),
486        other => serde_json::to_string_pretty(other).unwrap_or_else(|_| other.to_string()),
487    }
488}
489
490/// Compare two page revision snapshots field-by-field. Returns one
491/// `FieldDiff` per declared diff field (see `DIFF_FIELDS`), in
492/// declaration order.
493///
494/// Both arguments are the raw `snapshot` JSON from the
495/// [`Revision`] row.
496#[must_use]
497pub fn diff_snapshots(a: &serde_json::Value, b: &serde_json::Value) -> Vec<FieldDiff> {
498    use serde_json::Value;
499    DIFF_FIELDS
500        .iter()
501        .map(|field| {
502            let av = a.get(field).cloned().unwrap_or(Value::Null);
503            let bv = b.get(field).cloned().unwrap_or(Value::Null);
504            let a_null = matches!(av, Value::Null);
505            let b_null = matches!(bv, Value::Null);
506            let same = av == bv;
507            let field = (*field).to_owned();
508            if same {
509                FieldDiff::Unchanged {
510                    field,
511                    value: format_value(&av),
512                }
513            } else if a_null && !b_null {
514                FieldDiff::Added {
515                    field,
516                    b: format_value(&bv),
517                }
518            } else if b_null && !a_null {
519                FieldDiff::Removed {
520                    field,
521                    a: format_value(&av),
522                }
523            } else {
524                FieldDiff::Changed {
525                    field,
526                    a: format_value(&av),
527                    b: format_value(&bv),
528                }
529            }
530        })
531        .collect()
532}