Skip to main content

rustango_cms/
lib.rs

1//! rustango-cms — a multi-tenant, page-tree CMS built on
2//! [rustango](https://docs.rs/rustango).
3//!
4//! Pages live in one tenant-scoped `cms_page` tree (materialized path,
5//! see [`tree`]); each page's kind is a registered [`PageTypeHandler`]
6//! with its own extension table, template and admin form. Every read and
7//! write goes through the tenant's own pool, and the bundled migrations
8//! (see [`migrations`]) are tenant-scoped. The same source runs on
9//! PostgreSQL, MySQL 8+ and SQLite.
10//!
11//! ## Entry points
12//!
13//! | Surface | Where |
14//! |---|---|
15//! | Public site (slug resolver + Tera render, feeds, sitemap, forms) | [`PublicRouter`], or the [`router()`](crate::router()) / [`router_at`] shortcuts |
16//! | Editor admin at `/cms-admin/` | [`admin::router`], gated by [`admin::with_login_required`]; templates via [`admin::register_templates`] |
17//! | Page types | `#[derive(PageType)]` + [`PageTypeOverrides`], or a hand-written [`PageTypeHandler`] + [`register_page_type!`] |
18//! | StreamField bodies | [`block`] — the [`block::Block`] trait, `#[derive(Block)]` or [`register_block!`] |
19//! | Reusable content (library / snippets) | [`library`] ([`LibraryTypeHandler`], [`register_library_type!`]) and [`snippet`] |
20//! | Headless JSON API under `/api/v2/` | [`api::router`] / [`api::router_with`] |
21//! | MCP server for AI agents at [`mcp::MCP_PREFIX`] | [`mcp::router`] |
22//! | Per-tenant setup — page-type rows, roles, default locale, host seeders (late tenants seed on first request) | [`ensure_seeded`] |
23//! | Extension hooks (publish, serve, admin menu, dashboard) | [`hooks`] |
24//!
25//! ## Minimal wiring
26//!
27//! ```ignore
28//! use std::sync::Arc;
29//!
30//! let mut tera = tera::Tera::new("templates/**/*.html")?;
31//! rustango_cms::admin::register_templates(&mut tera)?;
32//! let tera = Arc::new(tera);
33//!
34//! let cms_admin = rustango_cms::admin::with_login_required(
35//!     rustango_cms::admin::router(tera.clone()),
36//!     "/login",
37//! );
38//! let app = cms_admin
39//!     .merge(rustango_cms::api::router())
40//!     .merge(rustango_cms::mcp::router(&settings.mcp)) // CSRF-exempt MCP_PREFIX
41//!     .merge(rustango_cms::PublicRouter::new(tera).build());
42//! // Hand `app` to `rustango::manage::Cli::new().tenancy().api(app)`
43//! // and call `rustango_cms::ensure_seeded` from its `.seed(..)` hook.
44//! ```
45//!
46//! [`admin::router`] is unauthenticated on its own; always wrap it in
47//! [`admin::with_login_required`].
48//!
49//! ## Cargo features
50//!
51//! | Feature | Effect |
52//! |---|---|
53//! | `postgres` (default), `sqlite`, `mysql` | Database backend, forwarded to rustango |
54//! | `storage_s3` | S3-compatible media storage for [`media_storage::install_from_env`] |
55//! | `cache_cloudflare`, `cache_varnish`, `cache_cloudfront`, `cache_gcp`, `cache_azure` | Front-cache purge backends ([`cache_invalidate`]) |
56//! | `search_elasticsearch` | Elasticsearch search backend (`search_elasticsearch` module) |
57//! | `avif` | AVIF image renditions |
58//! | `test_utils` | rustango's `Tenant::for_test` for integration tests |
59
60pub mod a11y;
61pub mod access;
62pub mod admin;
63pub mod admin_bar;
64pub mod analytics;
65pub mod api;
66pub mod auto_menu;
67pub mod block;
68pub mod branding;
69// #193 / #428 — opt-in cache-invalidator backends. Each module is
70// gated on its own cargo feature so the default build doesn't pull
71// the backend-specific deps. Feature flags: `cache_cloudflare`,
72// `cache_varnish`, `cache_gcp`, `cache_azure` (all → reqwest via
73// `rustango/http-client`), `cache_cloudfront` (→ aws-config +
74// aws-sdk-cloudfront).
75pub mod breadcrumbs;
76#[cfg(feature = "cache_azure")]
77pub mod cache_azure;
78#[cfg(feature = "cache_cloudflare")]
79pub mod cache_cloudflare;
80#[cfg(feature = "cache_cloudfront")]
81pub mod cache_cloudfront;
82#[cfg(feature = "cache_gcp")]
83pub mod cache_gcp;
84pub mod cache_invalidate;
85#[cfg(feature = "cache_varnish")]
86pub mod cache_varnish;
87pub mod category;
88pub mod category_translation;
89pub mod children_filtered;
90pub mod collection_view_restriction;
91pub mod comment;
92pub mod config;
93pub mod content_checks;
94pub mod date_filters;
95pub mod dismissible;
96pub mod editing_session;
97pub mod embed;
98pub mod error_pages;
99pub mod feed;
100pub mod forms;
101pub mod fragment_cache;
102pub mod hooks;
103pub mod language_switcher;
104pub mod library;
105pub mod locale;
106pub mod locale_mode;
107mod log_err;
108pub mod lock;
109pub mod macros;
110pub mod markdown;
111pub mod mcp;
112pub mod media;
113pub mod media_storage;
114pub mod media_usage;
115pub mod menu_item_translation;
116pub mod meta_tags;
117pub mod metrics;
118pub mod migrations;
119pub mod mysql_text;
120pub mod navigation;
121pub mod notification_pref;
122pub mod notify;
123pub mod page;
124pub(crate) mod page_baseline;
125pub mod page_builder;
126mod page_delete;
127pub(crate) mod page_form;
128pub mod page_log;
129pub mod page_snippet_m2m;
130pub mod page_subscription;
131pub mod page_tag;
132pub mod page_type;
133pub mod page_type_model;
134pub mod page_url;
135pub mod page_view;
136pub mod path_prefix;
137pub mod pending_change;
138pub(crate) mod passwords;
139pub mod perf;
140pub mod permissions;
141pub mod preview_token;
142pub mod preview_url;
143pub mod redirect;
144pub mod reference_index;
145pub mod render;
146pub mod rendition;
147pub mod rendition_route;
148pub mod resolver;
149pub mod revision;
150pub mod richtext;
151pub mod routable;
152pub mod router;
153pub mod search;
154#[cfg(feature = "search_elasticsearch")]
155pub mod search_elasticsearch;
156pub mod search_promotion;
157pub mod schedule;
158pub mod security_log;
159pub mod seed;
160pub mod signing;
161pub mod site;
162pub mod site_setting;
163pub mod template_inspector;
164pub mod starter;
165pub mod robots;
166pub mod sitemap;
167pub mod snippet;
168pub mod snippet_render;
169pub mod snippet_translation;
170pub mod task_kind;
171pub mod task_queue;
172pub mod tenant_templates;
173pub mod theme;
174pub mod theme_resolve;
175pub mod theme_seed;
176pub mod translation;
177pub mod tree;
178pub mod tree_build;
179pub mod tree_ops;
180pub mod uploaded_file;
181pub mod urls;
182pub mod userbar;
183pub mod view_restriction;
184pub use view_restriction::{RestrictionKind, TypeViewRestriction};
185pub mod view_restriction_guard;
186pub mod widget;
187pub mod workflow;
188pub mod workflow_mail;
189
190#[doc(hidden)]
191pub use ::inventory;
192
193pub use category::{
194    registered_handlers as registered_taxonomy_handlers, Category, PageCategory, Taxonomy,
195    TaxonomyHandler, TaxonomyHandlerRegistration,
196};
197pub use library::{
198    ensure_library_type_row, find_handler as find_library_handler,
199    registered_handlers as registered_library_handlers, LibraryType, LibraryTypeHandler,
200    LibraryTypeHandlerRegistration, ListColumn, ListColumnKind,
201};
202pub use locale::Locale;
203pub use locale_mode::{resolve_request_locale, LocaleMode, RequestLocale};
204pub use media::{Media, MediaCollection};
205pub use category_translation::CategoryTranslation;
206pub use menu_item_translation::MenuItemTranslation;
207pub use navigation::{Menu, MenuItem};
208pub use page::{Page, PageStatus};
209pub use page_type::{
210    all_children, default_children, find_handler, published_children, published_children_page,
211    registered_handlers, ChildOrder, ChildrenPage, DisplayField,
212    ExtensionField, ExtensionFieldKind, InlinePanelSpec, InlineRowSaved, InlineRowSummary, PageTypeHandler,
213    PageTypeHandlerRegistration, PageTypeOverrides, TabSpec,
214};
215pub use page_view::{Accept, PageViewKind, PageViewMode};
216pub use permissions::{
217    user_can, user_can_in_collection, user_can_matrix, Action, CollectionPermission, PagePermission,
218};
219pub use redirect::{
220    bump_hit_count as bump_redirect_hit_count, find_for_path as find_redirect_for_path, Redirect,
221};
222pub use revision::Revision;
223pub use snippet::Snippet;
224pub use theme::{emit_css as emit_theme_css, BrandColor, Theme};
225pub use theme_resolve::{resolve_for_page as resolve_theme_for_page, ResolvedTheme};
226pub use theme_seed::ensure_themes_seeded;
227pub use translation::Translation;
228
229/// `#[derive(PageType)]` — declarative page-type definition.
230/// See [`crate::page_type::PageTypeOverrides`] for the override trait
231/// authors implement alongside.
232pub use rustango_cms_macros::PageType;
233
234/// `#[derive(Block)]` — declarative block definition. Walks
235/// `#[block(...)]` + `#[field(widget = …)]` attrs to emit the `Block`
236/// trait impl + `register_block!` inventory submission in one go.
237/// Coexists with the [`Block`] trait through
238/// Rust's separate macro / type namespaces (same pattern as
239/// `#[derive(PageType)]` alongside [`PageType`](struct@PageType)).
240pub use rustango_cms_macros::Block;
241pub use rustango_cms_macros::CmsAdmin;
242
243/// Re-exports for the `#[derive(PageType)]` macro's generated code.
244/// Not part of the public API — addressing anything in here from user
245/// code is a footgun.
246#[doc(hidden)]
247pub mod __private {
248    pub use async_trait;
249    pub use inventory;
250    pub use rustango::core::Model;
251    pub use rustango::sql::{CounterPool, ExecError, FetcherPool, Pool};
252    pub use serde_json;
253}
254pub use page_type_model::PageType;
255pub use render::render;
256pub use resolver::resolve_path;
257pub use router::{router, router_at, router_at_cached, router_cached, PublicRouter};
258pub use schedule::spawn_schedule_sweeper;
259pub use seed::{ensure_seeded, SeedError};
260// Custom admin pages extension point (#23). Re-export the trait,
261// context, and section enum so host crates can import the surface
262// they need to implement without reaching into `admin::admin_page`.
263pub use admin::admin_page::{
264    find_admin_page, registered_admin_pages, AdminForm, AdminPageCtx, AdminPageHandler,
265    AdminPageHandlerRegistration, MessageLevel, SidebarSection,
266};
267// #940 — generic model editor: `#[derive(CmsAdmin)]` and its hooks.
268pub use admin::cms_admin::{
269    delete_record, save_record, CmsAdmin, CmsAdminMeta, CmsAdminOverrides, CmsAdminPage, FieldError,
270};
271pub use block::{
272    find_block, registered_blocks, validate_block_registry, Block, BlockCountConstraint,
273    BlockError, BlockField, BlockFieldMeta, BlockRegistration, BlockRenderCtx,
274};
275pub use tree::{MaterializedPath, PathError};
276pub use tree_ops::{
277    cascade_url_path_to_descendants, compute_url_path, rebuild_all_url_paths,
278    validate_child_placement, NewPage, TreeError,
279};
280pub use widget::{Widget, WidgetKind};