use chrono::{DateTime, Utc};
use rustango::core::Column as _;
use rustango::sql::{Auto, FetcherPool as _, Pool};
use rustango::Model;
use serde::{Deserialize, Serialize};
use std::collections::{HashMap, HashSet};
use crate::tree::{depth_of, descendants_like, MaterializedPath};
pub const DEFAULT_MAX_DEPTH: i32 = 10;
const WALK_DEPTH_CAP: usize = 64;
#[derive(Model, Debug, Clone, Serialize, Deserialize)]
#[rustango(
table = "cms_taxonomy",
app = "cms",
display = "verbose_name",
admin(
list_display = "slug, verbose_name, hierarchical, max_depth",
search_fields = "slug, verbose_name",
ordering = "slug",
)
)]
pub struct Taxonomy {
#[rustango(primary_key)]
pub id: Auto<i64>,
#[rustango(max_length = 100, unique)]
pub slug: String,
#[rustango(max_length = 200)]
pub verbose_name: String,
#[rustango(default = "true")]
pub hierarchical: bool,
#[rustango(default = "10")]
pub max_depth: i32,
#[rustango(max_length = 80, default = "''")]
pub icon: String,
#[rustango(max_length = 255, default = "''")]
pub description: String,
#[rustango(max_length = 120, default = "''")]
pub ext_table: String,
#[rustango(auto_now_add)]
pub created_at: Auto<DateTime<Utc>>,
#[rustango(auto_now)]
pub updated_at: Auto<DateTime<Utc>>,
}
#[derive(Model, Debug, Clone, Serialize, Deserialize)]
#[rustango(
table = "cms_category",
app = "cms",
display = "name",
admin(
list_display = "taxonomy_id, name, slug, depth, sort_order",
search_fields = "name, slug",
ordering = "taxonomy_id, path",
list_filter = "taxonomy_id",
)
)]
pub struct Category {
#[rustango(primary_key)]
pub id: Auto<i64>,
#[rustango(fk = "cms_taxonomy", on = "id", index)]
pub taxonomy_id: i64,
#[rustango(max_length = 200)]
pub name: String,
#[rustango(max_length = 200, index)]
pub slug: String,
#[rustango(max_length = 1024, default = "''")]
pub description: String,
#[rustango(fk = "cms_media", on = "id")]
pub featured_image_id: Option<i64>,
#[rustango(fk = "cms_media", on = "id")]
pub thumbnail_id: Option<i64>,
#[rustango(fk = "cms_category", on = "id", index)]
pub parent_id: Option<i64>,
#[rustango(max_length = 510, index)]
pub path: String,
pub depth: i32,
pub sort_order: i32,
#[rustango(auto_now_add)]
pub created_at: Auto<DateTime<Utc>>,
#[rustango(auto_now)]
pub updated_at: Auto<DateTime<Utc>>,
}
#[derive(Debug, thiserror::Error)]
pub enum CategoryError {
#[error(transparent)]
Db(#[from] rustango::sql::ExecError),
#[error(transparent)]
Sqlx(#[from] rustango::sql::sqlx::Error),
#[error("category {0} not found")]
NotFound(i64),
#[error("unknown taxonomy id {0} — is it registered/seeded?")]
UnknownTaxonomy(i64),
#[error("cannot move a category beneath itself or its own descendant")]
CycleAttempt,
#[error("taxonomy `{0}` is flat — categories cannot have a parent")]
FlatNoParent(String),
#[error("max depth {0} exceeded for taxonomy `{1}`")]
MaxDepthExceeded(i32, String),
#[error("a sibling category already uses slug `{0}`")]
DuplicateSlug(String),
#[error("category {0} still has {1} child categor(ies) — reparent or delete them first")]
HasChildren(i64, usize),
#[error("category path segment overflow (id out of range)")]
PathOverflow,
}
impl From<crate::tree::PathError> for CategoryError {
fn from(_: crate::tree::PathError) -> Self {
CategoryError::PathOverflow
}
}
#[derive(Debug, Clone, Serialize)]
pub struct CategoryNode {
#[serde(flatten)]
pub category: Category,
pub children: Vec<CategoryNode>,
}
#[must_use]
pub fn normalize_slug(raw: &str) -> String {
let mut out = String::with_capacity(raw.len());
let mut prev_dash = false;
for ch in raw.trim().chars() {
let c = ch.to_ascii_lowercase();
if c.is_ascii_alphanumeric() {
out.push(c);
prev_dash = false;
} else if matches!(c, ' ' | '-' | '_') && !prev_dash && !out.is_empty() {
out.push('-');
prev_dash = true;
}
}
while out.ends_with('-') {
out.pop();
}
if out.is_empty() {
"category".to_owned()
} else {
out
}
}
async fn taxonomy(pool: &Pool, taxonomy_id: i64) -> Result<Taxonomy, CategoryError> {
Taxonomy::objects()
.where_(Taxonomy::id.eq(taxonomy_id))
.first(pool)
.await?
.ok_or(CategoryError::UnknownTaxonomy(taxonomy_id))
}
async fn fetch(pool: &Pool, taxonomy_id: i64, id: i64) -> Result<Option<Category>, CategoryError> {
Ok(Category::objects()
.where_(Category::id.eq(id))
.where_(Category::taxonomy_id.eq(taxonomy_id))
.first(pool)
.await?)
}
pub async fn children_of(
pool: &Pool,
taxonomy_id: i64,
parent: Option<i64>,
) -> Result<Vec<Category>, CategoryError> {
let qs = Category::objects()
.where_(Category::taxonomy_id.eq(taxonomy_id))
.order_by(&[("sort_order", false), ("id", false)]);
let rows = match parent {
Some(pid) => qs.where_(Category::parent_id.eq(pid)).fetch(pool).await?,
None => qs.where_(Category::parent_id.is_null()).fetch(pool).await?,
};
Ok(rows)
}
pub async fn all_in_taxonomy(
pool: &Pool,
taxonomy_id: i64,
) -> Result<Vec<Category>, CategoryError> {
Ok(Category::objects()
.where_(Category::taxonomy_id.eq(taxonomy_id))
.order_by(&[("path", false)])
.fetch(pool)
.await?)
}
async fn slug_taken(
pool: &Pool,
taxonomy_id: i64,
parent: Option<i64>,
slug: &str,
exclude_id: Option<i64>,
) -> Result<bool, CategoryError> {
let siblings = children_of(pool, taxonomy_id, parent).await?;
Ok(siblings
.iter()
.any(|c| c.slug == slug && c.id.get().copied() != exclude_id))
}
#[derive(Debug, Clone, Default)]
pub struct NewCategory {
pub name: String,
pub slug: String,
pub description: String,
pub featured_image_id: Option<i64>,
pub thumbnail_id: Option<i64>,
pub parent_id: Option<i64>,
}
pub async fn create(
pool: &Pool,
taxonomy_id: i64,
new: NewCategory,
) -> Result<Category, CategoryError> {
let tax = taxonomy(pool, taxonomy_id).await?;
let base = if new.slug.trim().is_empty() {
&new.name
} else {
&new.slug
};
let slug = normalize_slug(base);
let (parent_path, parent_depth) = match new.parent_id {
None => (None, 0),
Some(pid) => {
if !tax.hierarchical {
return Err(CategoryError::FlatNoParent(tax.slug.clone()));
}
let parent = fetch(pool, taxonomy_id, pid)
.await?
.ok_or(CategoryError::NotFound(pid))?;
(Some(parent.path.clone()), parent.depth)
}
};
let new_depth = parent_depth + 1;
if new_depth > tax.max_depth.max(1) {
return Err(CategoryError::MaxDepthExceeded(
tax.max_depth,
tax.slug.clone(),
));
}
if slug_taken(pool, taxonomy_id, new.parent_id, &slug, None).await? {
return Err(CategoryError::DuplicateSlug(slug));
}
let sort_order = children_of(pool, taxonomy_id, new.parent_id).await?.len() as i32;
let mut tx = rustango::sql::transaction_pool(pool).await?;
let mut cat = Category {
id: Auto::Unset,
taxonomy_id,
name: new.name,
slug,
description: new.description,
featured_image_id: new.featured_image_id,
thumbnail_id: new.thumbnail_id,
parent_id: new.parent_id,
path: String::new(),
depth: new_depth,
sort_order,
created_at: Auto::Unset,
updated_at: Auto::Unset,
};
cat.insert_tx(&mut tx).await?;
let id = cat.id.get().copied().unwrap_or_default();
let path = match &parent_path {
Some(pp) => MaterializedPath::child_of(pp, id)?,
None => MaterializedPath::root(id)?,
};
cat.depth = path.depth();
cat.path = path.into_string();
cat.save_tx(&mut tx).await?;
tx.commit().await?;
Ok(cat)
}
pub async fn update(
pool: &Pool,
taxonomy_id: i64,
id: i64,
new: NewCategory,
) -> Result<Category, CategoryError> {
let mut cat = fetch(pool, taxonomy_id, id)
.await?
.ok_or(CategoryError::NotFound(id))?;
let base = if new.slug.trim().is_empty() {
&new.name
} else {
&new.slug
};
let slug = normalize_slug(base);
if slug != cat.slug && slug_taken(pool, taxonomy_id, cat.parent_id, &slug, Some(id)).await? {
return Err(CategoryError::DuplicateSlug(slug));
}
cat.name = new.name;
cat.slug = slug;
cat.description = new.description;
cat.featured_image_id = new.featured_image_id;
cat.thumbnail_id = new.thumbnail_id;
cat.save_pool(pool).await?;
Ok(cat)
}
pub async fn move_to(
pool: &Pool,
taxonomy_id: i64,
id: i64,
new_parent: Option<i64>,
) -> Result<(), CategoryError> {
let tax = taxonomy(pool, taxonomy_id).await?;
let cat = fetch(pool, taxonomy_id, id)
.await?
.ok_or(CategoryError::NotFound(id))?;
let mut subtree: Vec<Category> = Category::objects()
.where_(Category::taxonomy_id.eq(taxonomy_id))
.where_(Category::path.like(descendants_like(&cat.path)))
.where_(Category::path.ne(cat.path.clone()))
.order_by(&[("path", false)])
.fetch(pool)
.await?;
let (new_path, new_depth) = match new_parent {
None => (MaterializedPath::root(id)?, 1),
Some(pid) => {
if !tax.hierarchical {
return Err(CategoryError::FlatNoParent(tax.slug.clone()));
}
let parent = fetch(pool, taxonomy_id, pid)
.await?
.ok_or(CategoryError::NotFound(pid))?;
if pid == id || parent.path.starts_with(&cat.path) {
return Err(CategoryError::CycleAttempt);
}
(
MaterializedPath::child_of(&parent.path, id)?,
parent.depth + 1,
)
}
};
let height = subtree
.iter()
.map(|d| d.depth)
.max()
.map_or(0, |m| m - cat.depth);
if new_depth + height > tax.max_depth.max(1) {
return Err(CategoryError::MaxDepthExceeded(
tax.max_depth,
tax.slug.clone(),
));
}
let old_prefix = cat.path.clone();
let new_path = new_path.into_string();
if new_path == old_prefix {
return Ok(());
}
rustango::atomic!(pool, |tx| {
let mut guard = tx.lock().await?;
let tx = &mut *guard;
let mut moved = cat.clone();
moved.parent_id = new_parent;
moved.path = new_path.clone();
moved.depth = new_depth;
moved.save_tx(tx).await?;
for row in &mut subtree {
if let Some(suffix) = row.path.strip_prefix(&old_prefix) {
row.path = format!("{new_path}{suffix}");
row.depth = depth_of(&row.path);
row.save_tx(tx).await?;
}
}
Ok::<(), rustango::sql::ExecError>(())
})
.await?;
Ok(())
}
pub async fn delete(
pool: &Pool,
taxonomy_id: i64,
id: i64,
reparent: bool,
) -> Result<usize, CategoryError> {
let cat = fetch(pool, taxonomy_id, id)
.await?
.ok_or(CategoryError::NotFound(id))?;
let children = children_of(pool, taxonomy_id, Some(id)).await?;
if !children.is_empty() && !reparent {
return Err(CategoryError::HasChildren(id, children.len()));
}
if reparent {
for child in &children {
let cid = child.id.get().copied().unwrap_or_default();
move_to(pool, taxonomy_id, cid, cat.parent_id).await?;
}
}
rustango::atomic!(pool, |tx| {
let mut guard = tx.lock().await?;
let tx = &mut *guard;
crate::category::assign::delete_for_category_tx(tx, id).await?;
crate::category_translation::delete_for_category_tx(tx, id).await?;
let row = cat.clone();
row.delete_tx(tx).await?;
Ok::<(), rustango::sql::ExecError>(())
})
.await?;
Ok(1)
}
#[must_use]
pub fn build_tree(rows: Vec<Category>) -> Vec<CategoryNode> {
let mut by_parent: HashMap<Option<i64>, Vec<Category>> = HashMap::new();
for r in rows {
by_parent.entry(r.parent_id).or_default().push(r);
}
let mut visited: HashSet<i64> = HashSet::new();
build_level(&by_parent, None, 0, &mut visited)
}
fn build_level(
by_parent: &HashMap<Option<i64>, Vec<Category>>,
parent: Option<i64>,
depth: usize,
visited: &mut HashSet<i64>,
) -> Vec<CategoryNode> {
if depth >= WALK_DEPTH_CAP {
tracing::error!(
target: "rustango_cms::category",
depth, "category tree exceeded depth cap — truncating (corrupted parent_id cycle?)"
);
return Vec::new();
}
let Some(children) = by_parent.get(&parent) else {
return Vec::new();
};
let mut out = Vec::with_capacity(children.len());
for cat in children {
let id = cat.id.get().copied().unwrap_or_default();
if !visited.insert(id) {
tracing::error!(
target: "rustango_cms::category",
category_id = id, "category already visited — skipping (cycle in parent_id)"
);
continue;
}
let kids = build_level(by_parent, Some(id), depth + 1, visited);
out.push(CategoryNode {
category: cat.clone(),
children: kids,
});
}
out
}
#[cfg(all(test, feature = "sqlite"))]
mod tests {
use super::*;
use rustango::core::Model as _;
use rustango::migrate::ddl::create_table_if_not_exists_sql_with_dialect;
async fn mem_pool() -> Pool {
let pool = Pool::connect("sqlite::memory:").await.expect("mem pool");
for schema in [
&crate::page_type_model::PageType::SCHEMA,
&crate::media::Media::SCHEMA,
&crate::theme::Theme::SCHEMA,
&crate::page::Page::SCHEMA,
&Taxonomy::SCHEMA,
&Category::SCHEMA,
&crate::category::assign::PageCategory::SCHEMA,
&crate::locale::Locale::SCHEMA,
&crate::category_translation::CategoryTranslation::SCHEMA,
] {
let ddl = create_table_if_not_exists_sql_with_dialect(pool.dialect(), schema);
for stmt in ddl.split(';').map(str::trim).filter(|s| !s.is_empty()) {
rustango::sql::raw_execute_pool(&pool, stmt, Vec::new())
.await
.expect("ddl");
}
}
pool
}
async fn mk_taxonomy(pool: &Pool, slug: &str, hierarchical: bool, max_depth: i32) -> i64 {
let mut t = Taxonomy {
id: Auto::Unset,
slug: slug.to_owned(),
verbose_name: slug.to_owned(),
hierarchical,
max_depth,
icon: String::new(),
description: String::new(),
ext_table: String::new(),
created_at: Auto::Unset,
updated_at: Auto::Unset,
};
t.insert_pool(pool).await.expect("insert taxonomy");
t.id.get().copied().unwrap()
}
fn nc(name: &str, parent: Option<i64>) -> NewCategory {
NewCategory {
name: name.to_owned(),
parent_id: parent,
..Default::default()
}
}
#[tokio::test]
async fn create_materializes_path_and_typed_columns() {
let pool = mem_pool().await;
let tax = mk_taxonomy(&pool, "category", true, 10).await;
let mut europe_nc = nc("Europe", None);
europe_nc.description = "The continent".to_owned();
let europe = create(&pool, tax, europe_nc).await.expect("root");
assert_eq!(europe.path, "0001/");
assert_eq!(europe.depth, 1);
assert_eq!(europe.slug, "europe");
assert_eq!(europe.description, "The continent");
assert_eq!(europe.featured_image_id, None);
let france = create(&pool, tax, nc("France", europe.id.get().copied()))
.await
.expect("child");
assert_eq!(france.path, "0001/0002/");
assert_eq!(france.depth, 2);
}
#[tokio::test]
async fn duplicate_sibling_slug_rejected_across_parents_ok() {
let pool = mem_pool().await;
let tax = mk_taxonomy(&pool, "category", true, 10).await;
let a = create(&pool, tax, nc("A", None)).await.unwrap();
let b = create(&pool, tax, nc("B", None)).await.unwrap();
create(&pool, tax, nc("News", a.id.get().copied()))
.await
.expect("first");
let dup = create(&pool, tax, nc("News", a.id.get().copied())).await;
assert!(
matches!(dup, Err(CategoryError::DuplicateSlug(_))),
"got {dup:?}"
);
create(&pool, tax, nc("News", b.id.get().copied()))
.await
.expect("under B ok");
}
#[tokio::test]
async fn move_into_own_descendant_is_cycle_rejected() {
let pool = mem_pool().await;
let tax = mk_taxonomy(&pool, "category", true, 10).await;
let root = create(&pool, tax, nc("Root", None)).await.unwrap();
let mid = create(&pool, tax, nc("Mid", root.id.get().copied()))
.await
.unwrap();
let leaf = create(&pool, tax, nc("Leaf", mid.id.get().copied()))
.await
.unwrap();
let res = move_to(
&pool,
tax,
root.id.get().copied().unwrap(),
leaf.id.get().copied(),
)
.await;
assert!(
matches!(res, Err(CategoryError::CycleAttempt)),
"got {res:?}"
);
}
#[tokio::test]
async fn move_rewrites_subtree_paths() {
let pool = mem_pool().await;
let tax = mk_taxonomy(&pool, "category", true, 10).await;
let a = create(&pool, tax, nc("A", None)).await.unwrap();
let b = create(&pool, tax, nc("B", None)).await.unwrap();
let ac = create(&pool, tax, nc("AC", a.id.get().copied()))
.await
.unwrap();
move_to(
&pool,
tax,
a.id.get().copied().unwrap(),
b.id.get().copied(),
)
.await
.expect("move");
let moved_a = fetch(&pool, tax, a.id.get().copied().unwrap())
.await
.unwrap()
.unwrap();
let moved_ac = fetch(&pool, tax, ac.id.get().copied().unwrap())
.await
.unwrap()
.unwrap();
assert!(moved_a.path.starts_with(&b.path));
assert!(moved_ac.path.starts_with(&moved_a.path));
assert_eq!(moved_ac.depth, moved_a.depth + 1);
}
#[tokio::test]
async fn flat_taxonomy_rejects_parent() {
let pool = mem_pool().await;
let tax = mk_taxonomy(&pool, "tags", false, 1).await;
let a = create(&pool, tax, nc("A", None)).await.unwrap();
let res = create(&pool, tax, nc("B", a.id.get().copied())).await;
assert!(
matches!(res, Err(CategoryError::FlatNoParent(_))),
"got {res:?}"
);
}
#[tokio::test]
async fn max_depth_enforced() {
let pool = mem_pool().await;
let tax = mk_taxonomy(&pool, "shallow", true, 2).await;
let a = create(&pool, tax, nc("A", None)).await.unwrap();
let b = create(&pool, tax, nc("B", a.id.get().copied()))
.await
.unwrap();
let res = create(&pool, tax, nc("C", b.id.get().copied())).await;
assert!(
matches!(res, Err(CategoryError::MaxDepthExceeded(2, _))),
"got {res:?}"
);
}
#[tokio::test]
async fn delete_blocks_with_children_then_reparents() {
let pool = mem_pool().await;
let tax = mk_taxonomy(&pool, "category", true, 10).await;
let root = create(&pool, tax, nc("Root", None)).await.unwrap();
let child = create(&pool, tax, nc("Child", root.id.get().copied()))
.await
.unwrap();
let blocked = delete(&pool, tax, root.id.get().copied().unwrap(), false).await;
assert!(
matches!(blocked, Err(CategoryError::HasChildren(_, 1))),
"got {blocked:?}"
);
delete(&pool, tax, root.id.get().copied().unwrap(), true)
.await
.expect("reparent delete");
let promoted = fetch(&pool, tax, child.id.get().copied().unwrap())
.await
.unwrap()
.unwrap();
assert_eq!(promoted.parent_id, None);
assert_eq!(promoted.depth, 1);
}
#[tokio::test]
async fn build_tree_survives_corrupted_cycle() {
let pool = mem_pool().await;
let tax = mk_taxonomy(&pool, "category", true, 10).await;
let a = create(&pool, tax, nc("A", None)).await.unwrap();
let b = create(&pool, tax, nc("B", a.id.get().copied()))
.await
.unwrap();
let aid = a.id.get().copied().unwrap();
let bid = b.id.get().copied().unwrap();
rustango::sql::raw_execute_pool(
&pool,
&format!("UPDATE cms_category SET parent_id = {bid} WHERE id = {aid}"),
Vec::new(),
)
.await
.unwrap();
let rows = Category::objects()
.where_(Category::taxonomy_id.eq(tax))
.fetch(&pool)
.await
.unwrap();
let tree = build_tree(rows); assert!(
tree.is_empty(),
"cyclic rows have no root → empty but returns"
);
}
}