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 analytics;
64pub mod api;
65pub mod auto_menu;
66pub mod block;
67// #193 / #428 — opt-in cache-invalidator backends. Each module is
68// gated on its own cargo feature so the default build doesn't pull
69// the backend-specific deps. Feature flags: `cache_cloudflare`,
70// `cache_varnish`, `cache_gcp`, `cache_azure` (all → reqwest via
71// `rustango/http-client`), `cache_cloudfront` (→ aws-config +
72// aws-sdk-cloudfront).
73pub mod breadcrumbs;
74#[cfg(feature = "cache_azure")]
75pub mod cache_azure;
76#[cfg(feature = "cache_cloudflare")]
77pub mod cache_cloudflare;
78#[cfg(feature = "cache_cloudfront")]
79pub mod cache_cloudfront;
80#[cfg(feature = "cache_gcp")]
81pub mod cache_gcp;
82pub mod cache_invalidate;
83#[cfg(feature = "cache_varnish")]
84pub mod cache_varnish;
85pub mod category;
86pub mod category_translation;
87pub mod children_filtered;
88pub mod collection_view_restriction;
89pub mod comment;
90pub mod config;
91pub mod content_checks;
92pub mod date_filters;
93pub mod dismissible;
94pub mod editing_session;
95pub mod embed;
96pub mod error_pages;
97pub mod feed;
98pub mod forms;
99pub mod fragment_cache;
100pub mod hooks;
101pub mod language_switcher;
102pub mod library;
103pub mod locale;
104pub mod locale_mode;
105mod log_err;
106pub mod lock;
107pub mod macros;
108pub mod markdown;
109pub mod mcp;
110pub mod media;
111pub mod media_storage;
112pub mod menu_item_translation;
113pub mod meta_tags;
114pub mod metrics;
115pub mod migrations;
116pub mod mysql_text;
117pub mod navigation;
118pub mod notification_pref;
119pub mod notify;
120pub mod page;
121pub mod page_builder;
122mod page_delete;
123pub(crate) mod page_form;
124pub mod page_log;
125pub mod page_snippet_m2m;
126pub mod page_subscription;
127pub mod page_tag;
128pub mod page_type;
129pub mod page_type_model;
130pub mod page_url;
131pub mod page_view;
132pub mod pending_change;
133pub(crate) mod passwords;
134pub mod perf;
135pub mod permissions;
136pub mod preview_token;
137pub mod preview_url;
138pub mod redirect;
139pub mod reference_index;
140pub mod render;
141pub mod rendition;
142pub mod rendition_route;
143pub mod resolver;
144pub mod revision;
145pub mod richtext;
146pub mod routable;
147pub mod router;
148pub mod search;
149#[cfg(feature = "search_elasticsearch")]
150pub mod search_elasticsearch;
151pub mod search_promotion;
152pub mod schedule;
153pub mod security_log;
154pub mod seed;
155pub mod signing;
156pub mod site;
157pub mod site_setting;
158pub mod robots;
159pub mod sitemap;
160pub mod snippet;
161pub mod snippet_render;
162pub mod snippet_translation;
163pub mod task_kind;
164pub mod task_queue;
165pub mod tenant_templates;
166pub mod theme;
167pub mod theme_resolve;
168pub mod theme_seed;
169pub mod translation;
170pub mod tree;
171pub mod tree_build;
172pub mod tree_ops;
173pub mod uploaded_file;
174pub mod urls;
175pub mod userbar;
176pub mod view_restriction;
177pub use view_restriction::{RestrictionKind, TypeViewRestriction};
178pub mod view_restriction_guard;
179pub mod widget;
180pub mod workflow;
181pub mod workflow_mail;
182
183#[doc(hidden)]
184pub use ::inventory;
185
186pub use category::{
187    registered_handlers as registered_taxonomy_handlers, Category, PageCategory, Taxonomy,
188    TaxonomyHandler, TaxonomyHandlerRegistration,
189};
190pub use library::{
191    ensure_library_type_row, find_handler as find_library_handler,
192    registered_handlers as registered_library_handlers, LibraryType, LibraryTypeHandler,
193    LibraryTypeHandlerRegistration, ListColumn, ListColumnKind,
194};
195pub use locale::Locale;
196pub use locale_mode::{resolve_request_locale, LocaleMode, RequestLocale};
197pub use media::{Media, MediaCollection};
198pub use category_translation::CategoryTranslation;
199pub use menu_item_translation::MenuItemTranslation;
200pub use navigation::{Menu, MenuItem};
201pub use page::{Page, PageStatus};
202pub use page_type::{
203    all_children, default_children, find_handler, published_children, registered_handlers, DisplayField,
204    ExtensionField, ExtensionFieldKind, InlinePanelSpec, PageTypeHandler,
205    PageTypeHandlerRegistration, PageTypeOverrides, TabSpec,
206};
207pub use page_view::{Accept, PageViewKind, PageViewMode};
208pub use permissions::{
209    user_can, user_can_in_collection, user_can_matrix, Action, CollectionPermission, PagePermission,
210};
211pub use redirect::{
212    bump_hit_count as bump_redirect_hit_count, find_for_path as find_redirect_for_path, Redirect,
213};
214pub use revision::Revision;
215pub use snippet::Snippet;
216pub use theme::{emit_css as emit_theme_css, BrandColor, Theme};
217pub use theme_resolve::{resolve_for_page as resolve_theme_for_page, ResolvedTheme};
218pub use theme_seed::ensure_themes_seeded;
219pub use translation::Translation;
220
221/// `#[derive(PageType)]` — declarative page-type definition.
222/// See [`crate::page_type::PageTypeOverrides`] for the override trait
223/// authors implement alongside.
224pub use rustango_cms_macros::PageType;
225
226/// `#[derive(Block)]` — declarative block definition. Walks
227/// `#[block(...)]` + `#[field(widget = …)]` attrs to emit the `Block`
228/// trait impl + `register_block!` inventory submission in one go.
229/// Coexists with the [`Block`] trait through
230/// Rust's separate macro / type namespaces (same pattern as
231/// `#[derive(PageType)]` alongside [`PageType`](struct@PageType)).
232pub use rustango_cms_macros::Block;
233
234/// Re-exports for the `#[derive(PageType)]` macro's generated code.
235/// Not part of the public API — addressing anything in here from user
236/// code is a footgun.
237#[doc(hidden)]
238pub mod __private {
239    pub use async_trait;
240    pub use inventory;
241    pub use rustango::core::Model;
242    pub use rustango::sql::{ExecError, FetcherPool, Pool};
243    pub use serde_json;
244}
245pub use page_type_model::PageType;
246pub use render::render;
247pub use resolver::resolve_path;
248pub use router::{router, router_at, router_at_cached, router_cached, PublicRouter};
249pub use schedule::spawn_schedule_sweeper;
250pub use seed::{ensure_seeded, SeedError};
251// Custom admin pages extension point (#23). Re-export the trait,
252// context, and section enum so host crates can import the surface
253// they need to implement without reaching into `admin::admin_page`.
254pub use admin::admin_page::{
255    find_admin_page, registered_admin_pages, AdminPageCtx, AdminPageHandler,
256    AdminPageHandlerRegistration, SidebarSection,
257};
258pub use block::{
259    find_block, registered_blocks, validate_block_registry, Block, BlockCountConstraint,
260    BlockError, BlockField, BlockFieldMeta, BlockRegistration, BlockRenderCtx,
261};
262pub use tree::{MaterializedPath, PathError};
263pub use tree_ops::{
264    cascade_url_path_to_descendants, compute_url_path, rebuild_all_url_paths,
265    validate_child_placement, NewPage, TreeError,
266};
267pub use widget::{Widget, WidgetKind};