What a plugin is

//! The blog app. Owns the `Post` model + a couple of HTML pages.
 
use serde::{Deserialize, Serialize};
use serde_json::json;
use umbral::plugin::{AppContext, Plugin, PluginError};
use umbral::prelude::*;
use umbral::web::{Html, Json, Path, Router, StatusCode, get};
 
// --- Model -----------------------------------------------------------------
 
/// The plugin owns its model. `App::builder()` auto-discovers it
/// through the `Plugin::models()` hook below - no `.model::<Post>()`
/// line on the builder.
#[derive(Debug, Clone, Serialize, Deserialize, sqlx::FromRow, umbral::orm::Model)]
pub struct Post {
    pub id: i64,
    pub title: String,
    pub body: String,
    pub author_email: String,
}
 
// --- Route handlers -- accessing the ORM from inside the plugin ------------
 
/// HTML list view. `Post::objects()` reaches the ambient pool that
/// `App::build()` published - no `&Pool` arg through the handler chain,
/// no `State<DbPool>` extractor, no global look-up at the call site.
async fn list_posts() -> Result<Html<String>, (StatusCode, String)> {
    let posts = Post::objects()
        .order_by(post::ID.desc())
        .limit(50)
        .fetch()
        .await
        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
 
    let mut html = String::from("<h1>Posts</h1><ul>");
    for p in &posts {
        html.push_str(&format!("<li>{} - {}</li>", p.id, p.title));
    }
    html.push_str("</ul>");
    Ok(Html(html))
}
 
/// JSON detail view. Same ORM, different terminal - `.first()` rather than
/// `.fetch()` because we want one row or 404.
async fn post_detail(Path(id): Path<i64>) -> Result<Json<Post>, (StatusCode, String)> {
    let found = Post::objects()
        .filter(post::ID.eq(id))
        .first()
        .await
        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
    found
        .map(Json)
        .ok_or((StatusCode::NOT_FOUND, format!("no post with id {id}")))
}
 
// --- REST customisation, bundled in the plugin ----------------------------
 
/// What the plugin's REST endpoints should look like. Lives WITH the
/// plugin so main.rs doesn't have to thread customisation per-table.
/// Register from main.rs via `.plugin(RestPlugin::default()
/// .resource(blog::rest_resource()))`.
pub fn rest_resource() -> umbral_rest::ResourceConfig {
    umbral_rest::ResourceConfig::new("post")
        // Hide the raw author email; show the domain only.
        .transform("author_email", |v| {
            let s = v.as_str().unwrap_or("");
            match s.split_once('@') {
                Some((_, d)) => json!(format!("***@{d}")),
                None => v.clone(),
            }
        })
        // Add a `summary` field derived from the body's first line.
        .computed("summary", |row| {
            let body = row.get("body").and_then(|v| v.as_str()).unwrap_or("");
            let first_line = body.lines().next().unwrap_or("");
            json!(first_line.chars().take(120).collect::<String>())
        })
}
 
// --- The Plugin trait ------------------------------------------------------
 
pub struct BlogPlugin;
 
impl Plugin for BlogPlugin {
    fn name(&self) -> &'static str {
        "blog"
    }
 
    /// Auto-registration: every model this plugin owns goes here.
    /// `App::builder()` walks `Plugin::models()` on every registered
    /// plugin and feeds the results into the migration registry -
    /// you do NOT also call `.model::<Post>()` from main.rs.
    fn models(&self) -> Vec<umbral::migrate::ModelMeta> {
        vec![umbral::migrate::ModelMeta::for_::<Post>()]
    }
 
    fn routes(&self) -> Router {
        Router::new()
            .route("/blog", get(list_posts))
            .route("/blog/{id}", get(post_detail))
    }
 
    /// Runs after every other plugin has booted and the ambient pool
    /// + model registry are live. The classic "seed on first run"
    /// idiom - bulk_create is idempotent here because we check count
    /// first; in production you'd guard this behind a feature flag
    /// or move it to a separate `seed` management command.
    fn on_ready(&self, _ctx: &AppContext) -> Result<(), PluginError> {
        umbral::plugin::block_on_ready(async {
            let count = Post::objects().count().await?;
            if count == 0 {
                Post::objects()
                    .bulk_create(vec![Post {
                        id: 0,
                        title: "Hello".into(),
                        body: "First post.".into(),
                        author_email: "alice@example.com".into(),
                    }])
                    .await?;
            }
            Ok::<_, Box<dyn std::error::Error + Send + Sync>>(())
        })
        .map_err(|e| -> PluginError { Box::new(std::io::Error::other(e.to_string())) })?;
        Ok(())
    }
}

let app = App::builder()
    .settings(settings)
    .database("default", pool)
    .plugin(blog::BlogPlugin)                     // model + routes + on_ready
    .plugin(
        umbral_rest::RestPlugin::default()
            .resource(blog::rest_resource()),    // REST customisation
    )
    .build()?;