Skip to main content

lariv_rs/
lib.rs

1#![feature(impl_trait_in_assoc_type)]
2#![recursion_limit = "512"]
3
4//! Lariv application kernel — configuration, HTTP server wiring, and aggregated plugin registries.
5//!
6//! **lariv-rs** is a compile-time plugin web application framework built on **Axum**,
7//! **SeaORM**, **Maud**, and **HTMX 4**.
8//!
9//! # Architecture
10//!
11//! The app lifecycle has three phases:
12//!
13//! 1. **Builder** — [`App`](app::App) holds an HList of capability stores (hooks + items).
14//!    Plugins call [`define_plugin_install!`](plugin_install::define_plugin_install) to register
15//!    deferred hooks for routes, templates, migrations, CLI commands, etc.
16//! 2. **Mount** — [`App::mount`](app::App::mount) resolves hooks, folds capabilities to
17//!    [`Tagged`](tag::Tagged) outputs, and produces a [`MountedApp`](app::MountedApp).
18//! 3. **Runtime** — Axum serves HTTP; handlers extract mounted state via [`Cap`](http::Cap).
19//!
20//! # Quickstart
21//!
22//! ```ignore
23//! use lariv_rs::app::App;
24//! use lariv_rs::plugins::{dashboard, users};
25//!
26//! #[tokio::main]
27//! async fn main() -> anyhow::Result<()> {
28//!     let app = App::new_web_app();
29//!     let app = users::install(app);
30//!     let app = dashboard::install(app);
31//!     let app = app.load_config("config.toml").await?;
32//!     let mounted = app.mount();
33//!     mounted.run_migrations().await?;
34//!     mounted.run_seeds().await?;
35//!     mounted.run().await
36//! }
37//! ```
38//!
39//! See [`app`] for lifecycle details and [`plugins`] for bundled plugins.
40//!
41//! # Beginner guides
42//!
43//! Step-by-step tutorials for new plugin authors live in the [`docs`] module:
44//!
45//! - [`docs::quickstart`] — Hello World plugin tutorial
46//! - [`docs`] — project layout and guide index
47//!
48//! # Core modules
49//!
50//! | Module | Role |
51//! |--------|------|
52//! | [`app`] | Builder and mounted app lifecycle |
53//! | [`capability`] | Capability stores, hooks, mount folding |
54//! | [`tag`] | Type-level tagging via [`tag::Tagged`] |
55//! | [`traits`] | HList lookup, add, replace, remove |
56//! | [`http`] | Route registry and Axum router |
57//! | [`template`] | Maud page template registry |
58//! | [`layers`] | Compile-time view middleware stacks |
59//! | [`components`] | Maud UI builders (fields, tables, shells) |
60//! | [`web`] | HTMX-aware page rendering helpers |
61//! | [`html_form`] | Form macro and widget traits |
62//! | [`rt`] | Large-stack process entry helpers ([`main`]) |
63//! | [`config`] | TOML configuration loading |
64//! | [`db`] | SeaORM connection capability |
65//! | [`migration`] | Composite SeaORM migrator |
66//! | [`command`] | CLI command registration |
67//! | [`hooks`] | State attachment and seed hooks |
68//! | [`apps`] | Dashboard app tile catalog |
69//! | [`export`] | XLSX export table catalog |
70//! | [`llm_tools`] | Gemini function-calling tools |
71//! | [`rune_env`] | Rune script native bindings |
72//! | [`grapesjs`] | Website builder block/component registries |
73//! | [`genai`] | Gemini HTTP client |
74//! | [`views`] | Named view registry (PWA offline page) |
75//!
76//! # Plugin authoring
77//!
78//! | Module | Role |
79//! |--------|------|
80//! | [`plugin_install`] | [`define_plugin_install!`] macro |
81//! | [`plugin_routes`] | [`define_plugin_routes!`] DSL reference |
82//! | [`define_plugin_routes`] | Proc-macro re-export |
83//!
84//! # Bundled plugins
85//!
86//! | Plugin | Module | Purpose |
87//! |--------|--------|---------|
88//! | Users & auth | [`plugins::users`] | JWT/scrypt auth, roles, user CRUD |
89//! | Dashboard | [`plugins::dashboard`] | Apps launchpad and home redirects |
90//! | Blog | [`plugins::blog`] | Articles and hierarchical tags |
91//! | Filesystem | [`plugins::filesystem`] | DB-backed virtual filesystem |
92//! | Website | [`plugins::website`] | DB routes, Minijinja pages, GrapesJS builder |
93//! | LLM assistant | [`plugins::llm_assistant`] | Gemini chat, skills, WebSocket |
94//! | OTP recovery | [`plugins::otp`] | SMS/email one-time password recovery |
95//! | PWA | [`plugins::pwa`] | Manifest, service worker, offline page |
96//! | Export | [`plugins::export`] | XLSX data export UI |
97//! | Signup | [`plugins::signup`] | Public self-service signup |
98//!
99//! Proc-macro derives expand to `::lariv_rs::…` paths; this crate aliases itself as `lariv_rs` for in-tree use.
100extern crate self as lariv_rs;
101
102pub mod app;
103pub mod apps;
104pub mod capability;
105pub mod command;
106pub mod components;
107pub mod config;
108pub mod datetime;
109pub mod db;
110pub mod docs;
111pub mod duration;
112pub mod export;
113pub mod genai;
114pub mod grapesjs;
115pub mod hooks;
116pub mod html_form;
117pub mod http;
118pub mod layers;
119#[cfg(feature = "cap-llm")]
120pub mod llm_tools;
121#[cfg(not(feature = "cap-llm"))]
122#[path = "llm_tools_stub.rs"]
123pub mod llm_tools;
124pub mod migration;
125pub mod picker;
126pub mod plugin_install;
127pub mod plugin_routes;
128pub mod plugins;
129pub mod rt;
130#[cfg(feature = "cap-llm")]
131pub mod rune_env;
132#[cfg(not(feature = "cap-llm"))]
133#[path = "rune_env_stub.rs"]
134pub mod rune_env;
135pub mod tag;
136pub mod template;
137pub mod traits;
138pub mod views;
139pub mod web;
140
141/// Generate route tags, proof type, and [`RouteRegistrar`](http::RouteRegistrar) hook.
142///
143/// See [`plugin_routes`] for the full DSL reference.
144pub use lariv_rs_macros::define_plugin_routes;
145
146/// Attribute macro: run `async fn main` on a thread with a raised stack size.
147///
148/// Deep HList install/mount chains overflow the default ~8 MiB stack. This macro
149/// raises the process stack soft limit, spawns a dedicated thread, and drives a
150/// Tokio runtime with the requested stack.
151///
152/// # Attributes
153///
154/// - `stack_size = <expr>` — bytes (default: [`rt::DEFAULT_STACK_SIZE`], 64 MiB)
155/// - `flavor = "current_thread" | "multi_thread"` — Tokio runtime (default: `"current_thread"`)
156/// - `thread_name = "..."` — OS thread name (default: `"lariv-server"`)
157///
158/// # Examples
159///
160/// ```ignore
161/// #[lariv_rs::main(stack_size = 64 * 1024 * 1024)]
162/// async fn main() -> anyhow::Result<()> {
163///     // install / mount / run
164///     Ok(())
165/// }
166///
167/// #[lariv_rs::main(stack_size = 64 * 1024 * 1024, flavor = "multi_thread")]
168/// async fn main() -> anyhow::Result<()> {
169///     Ok(())
170/// }
171/// ```
172pub use lariv_rs_macros::main;
173
174/// Re-exported for [`define_plugin_install!`](plugin_install::define_plugin_install) `cap_attach` /
175/// `cap_hook` unique type-parameter names (used via `$crate::paste` from the macro).
176pub use paste;