portal/src/content.rs

use serde::{Deserialize, Serialize};

/// One page: a prompt plus the paths on from it. `id` doubles as the URL
/// path it's served at ("/" is the landing page). Loaded from a plain
/// YAML file per question in a content directory kept in its own git
/// repo (see ../portal-content) - editing content is a content-repo
/// commit, not a Rust rebuild.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Question {
    pub id: String,
    #[serde(default)]
    pub route: Option<String>,
    pub name: String,
    #[serde(default)]
    pub description: String,
    /// Kanidm group required to view/submit this question - `None` means
    /// open to anyone, matching every question today. Content-driven
    /// on purpose: a gated page like "/review" is just a Question with
    /// this set, not a bespoke Rust route.
    #[serde(default)]
    pub qualifies: Option<String>,
    #[serde(default)]
    pub alternatives: Vec<Alternative>,
}

/// Whether `user` may view/submit `question`. `true` when the question
/// has no `qualifies` requirement. Mirrors `chat::is_authorized_for_room`
/// in cnats - same synchronous, I/O-free shape, same staleness tradeoff
/// (group membership is fixed at login, not re-checked live).
pub fn is_qualified(user: Option<&crate::auth::User>, question: &Question) -> bool {
    match &question.qualifies {
        None => true,
        Some(group) => user.is_some_and(|u| u.groups.iter().any(|g| g == group)),
    }
}

/// One path through a question: a short pitch, an optional next question
/// to advance to on submit, and the form (via `features`) that collects
/// what's needed to get there.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Alternative {
    pub name: String,
    #[serde(default)]
    pub description: String,
    #[serde(default)]
    pub action: Option<String>,
    #[serde(default)]
    pub consequence: Vec<String>,
    #[serde(default)]
    pub encouragements: Vec<String>,
    #[serde(default)]
    pub features: Vec<Feature>,
    /// Names a NATS KV bucket to also durably store this submission
    /// into, beyond the ephemeral NATS event every submission already
    /// gets published as - just a bucket name, not a keyword the
    /// runtime special-cases (see `src/answers.rs`). Content-driven
    /// rather than matching on the alternative's name/copy, which would
    /// silently break if the wording changes later.
    #[serde(default)]
    pub record_as: Option<String>,
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Feature {
    pub name: String,
    #[serde(default)]
    pub description: String,
    #[serde(default)]
    pub requirements: Vec<Requirement>,
    /// Live data this feature pulls in. Read-only unless `transitions`
    /// is non-empty, in which case listed answers get one action button
    /// per transition (see `src/resource.rs`, `src/answers.rs`).
    #[serde(default)]
    pub resource: Option<ResourceSpec>,
}

/// Declares a NATS KV-backed live-data read. The bucket/key here are
/// only ever read server-side, from content the server itself loaded at
/// startup - `get_resource` (`src/resource.rs`) takes a question id +
/// feature name from the client, never a bucket/key directly, so a
/// visitor can never probe an arbitrary bucket by naming it. There is
/// no render-mode/"kind" tag here on purpose - what a resource displays
/// as follows from its data's own shape (a plain value, or a list of
/// `answers::Answer`s), not from a Rust-side special case per content
/// item.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct ResourceSpec {
    pub bucket: String,
    /// A single item; omit to list the whole bucket.
    #[serde(default)]
    pub key: Option<String>,
    /// Kanidm group required to read this resource.
    #[serde(default)]
    pub requires_group: Option<String>,
    /// Must be explicitly set for an anonymous-readable resource - a
    /// spec with neither this nor `requires_group` is unreachable by
    /// design (fail closed, not fail open). Reads only - mutations
    /// (`transitions` below) always require `requires_group` regardless
    /// of this flag.
    #[serde(default)]
    pub public: bool,
    /// States a listed answer may move to, and the button label for
    /// each - empty means the resource is read-only. The allow-list a
    /// `transition_answer` call is checked against, so a client can
    /// never move an answer to a state content didn't declare.
    #[serde(default)]
    pub transitions: Vec<Transition>,
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Transition {
    pub to: String,
    pub label: String,
}

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Requirement {
    pub name: String,
    #[serde(default)]
    pub label: Option<String>,
    #[serde(default)]
    pub placeholder: Option<String>,
    #[serde(default = "default_requirement_type", rename = "type")]
    pub kind: String,
    #[serde(default)]
    pub optional: bool,
    /// `type: file` only - accept multiple files.
    #[serde(default)]
    pub multiple: bool,
    /// `type: file` only - HTML `accept` hint (UX only, not a security
    /// boundary - the upload handler re-checks content-type itself).
    #[serde(default)]
    pub accept: Option<String>,
}

fn default_requirement_type() -> String {
    "text".to_string()
}

impl Requirement {
    pub fn display_label(&self) -> String {
        self.label.clone().unwrap_or_else(|| self.name.clone())
    }
}

/// Reads every `*.yaml` file in `dir` as a `Question`, keyed by its own
/// `id`. Runs once at startup; no hot-reload yet - restart the process
/// (or add a watcher later) to pick up content changes.
#[cfg(feature = "ssr")]
pub fn load_questions(
    dir: &std::path::Path,
) -> anyhow::Result<std::collections::HashMap<String, Question>> {
    let mut out = std::collections::HashMap::new();
    for entry in std::fs::read_dir(dir)
        .map_err(|e| anyhow::anyhow!("reading content dir {}: {e}", dir.display()))?
    {
        let entry = entry?;
        let path = entry.path();
        if path.extension().and_then(|e| e.to_str()) != Some("yaml") {
            continue;
        }
        let raw = std::fs::read_to_string(&path)?;
        let question: Question = serde_yaml::from_str(&raw)
            .map_err(|e| anyhow::anyhow!("parsing {}: {e}", path.display()))?;
        out.insert(question.id.clone(), question);
    }
    Ok(out)
}