ordinary_config/app/template/

mod.rs

// Copyright (C) 2026 Ordinary Labs, LLC.
//
// SPDX-License-Identifier: AGPL-3.0-only

use crate::{Check, HttpCache, HttpCors, HttpCsp, StoredCache};
use ordinary_types::Kind;
use serde::{Deserialize, Serialize};

/// Field used within the scope of a single template.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
#[derive(Deserialize, Serialize, Debug, Clone)]
pub struct TemplateField {
    /// Field name
    pub name: String,
    /// Specifies the type of the value.
    pub kind: Kind,
    /// JSON value for template field.
    pub value: serde_json::Value,
}

/// Query expression to be used in template bindings.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
#[derive(Deserialize, Serialize, Debug, Clone)]
pub enum QueryExpression {
    Gte,
    Gt,
    Lte,
    Lt,
    Eq,
    BeginsWith,
}

/// Binding options for template field refs.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
#[derive(Deserialize, Serialize, Debug, Clone)]
pub enum TemplateRefFieldBind {
    /// Bind this property to a token claim field.
    Token {
        /// Name of the token claims field that this model/content
        /// property should bind to.
        ///
        /// (i.e "account" if you'd like to have an "/account" route
        /// that interprets the request based on the logged-in user's
        /// token claims/fields).
        field: String,
        /// Include if this property is queryable.
        #[serde(skip_serializing_if = "Option::is_none")]
        #[serde(default)]
        expression: Option<QueryExpression>,
    },
    /// Bind this property to a route segment (i.e /{something})
    Segment {
        /// Specifies the name of the route segment that this property is binding to.
        name: String,
        /// Include if this property is queryable.
        #[serde(skip_serializing_if = "Option::is_none")]
        #[serde(default)]
        expression: Option<QueryExpression>,
    },
    /// Bind this property to a route segment (i.e /{something})
    Param {
        /// Specifies the key of the query string param that this property is binding to.
        key: String,
        /// Include if this property is queryable.
        #[serde(skip_serializing_if = "Option::is_none")]
        #[serde(default)]
        expression: Option<QueryExpression>,
    },
}

/// Declaration for which fields from a content definition
/// or data model to include.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
#[derive(Deserialize, Serialize, Debug, Clone, Default)]
pub struct TemplateRefField {
    /// Specifies index for reference field. Index
    /// must be unique across fields for a given reference.
    pub idx: u8,
    /// Name of field to be included.
    pub name: String,
    /// Option to bind this field's value to a route
    /// segment, querystring parameter or token field.
    ///
    /// **IMPORTANT:** this property is being deprecated.
    /// Switch to using the `TemplateRef::predicate` config
    /// field, instead.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub bind: Option<TemplateRefFieldBind>,
    /// List of any nested subfields to include for this field.
    #[cfg_attr(feature = "utoipa", schema(no_recursion))]
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub fields: Option<Vec<TemplateRefField>>,
}

/// How templates reference Content Definitions
/// and Data Models, and the specific fields it
/// wants to include.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
#[derive(Deserialize, Serialize, Debug, Clone, Default)]
pub struct TemplateRef {
    /// Specifies the index position for the referenced
    /// data. Index must be unique across flags, params, data models and
    /// content definitions.
    pub idx: u8,
    /// Name of the model or content definition.
    pub name: String,
    /// for requesting all top-level content items
    ///
    /// note: only supported for content. models use relationships.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub all: Option<String>,
    /// Wires up the request parts (token claims, path segments, query string params)
    /// to the content or model that is being referenced.
    ///
    /// ```jsonc
    /// {
    ///     // route segment
    ///     "predicate": [["content_field_name", { "Segment": { "name": "route_segment" } }]]
    /// }
    /// ```
    ///
    /// Is ignored when `all` is set for content.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub predicate: Option<Vec<(String, TemplateRefFieldBind)>>,
    /// Which fields to include.
    ///
    /// *Note:* If not specified will request all fields.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub fields: Option<Vec<TemplateRefField>>,
}

/// Server flags can only be used in templates whose cache is
/// set to "Never".
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
#[derive(Deserialize, Serialize, Debug, Clone)]
pub struct TemplateFlagRef {
    /// Specifies the index position for the referenced
    /// data. Index must be unique across flags, data models and
    /// content definitions.
    pub idx: u8,
    /// Name of the flag.
    pub name: String,
}

#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
#[derive(Deserialize, Serialize, Debug, Clone)]
pub struct TemplateCache {
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub stored: Option<StoredCache>,

    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub http: Option<HttpCache>,
}

#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
#[derive(Deserialize, Serialize, Debug, Clone, Default)]
pub enum TemplateFfiVersion {
    V1,
    #[default]
    V2,
}

/// Input serialization format. Output is always an array of bytes.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
#[derive(Deserialize, Serialize, Debug, Clone, Default)]
pub enum TemplateFfiSerialization {
    #[default]
    FlexBufferVector,
    /// only supported for V2 and up
    Json,
}

#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
#[derive(Deserialize, Serialize, Debug, Clone, Default)]
pub struct TemplateFfi {
    pub version: TemplateFfiVersion,
    pub serialization: TemplateFfiSerialization,
}

#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
#[derive(Deserialize, Serialize, Debug, Clone, Default)]
pub enum BindgenLang {
    #[default]
    #[serde(rename = "rust")]
    Rust,
}

#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
#[derive(Deserialize, Serialize, Debug, Clone, Default)]
pub enum ManagedTemplate {
    /// Compiles a Rust crate as a `WASIp2` component, containing an
    /// [Askama](https://askama.rs/en/stable/) template.
    #[default]
    #[serde(rename = "v2-rust-askama")]
    V2RustAskama,
}

impl ManagedTemplate {
    #[must_use]
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::V2RustAskama => "v2-rust-askama",
        }
    }
}

#[cfg(feature = "cli")]
impl clap::ValueEnum for ManagedTemplate {
    fn value_variants<'a>() -> &'a [Self] {
        &[Self::V2RustAskama]
    }

    fn to_possible_value(&self) -> Option<clap::builder::PossibleValue> {
        match self {
            Self::V2RustAskama => Some(clap::builder::PossibleValue::new("v2-rust-askama")),
        }
    }
}

/// Template configuration for Ordinary Applications.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "docs", derive(schemars::JsonSchema))]
#[derive(Deserialize, Serialize, Debug, Clone, Default)]
pub struct TemplateConfig {
    /// Foreign function interface config
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub ffi: Option<TemplateFfi>,
    /// Refers to the template config in another location
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default, rename = "ref")]
    pub r#ref: Option<String>,
    /// Unique index for template.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub idx: Option<u8>,
    /// Template's name.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub name: Option<String>,
    /// Language + Engine for basic templating
    ///
    /// If unset, template is in "ejected" state and
    /// self-managed by user.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub managed: Option<ManagedTemplate>,
    /// Used as the `content-type` header for HTTP responses.
    /// Validated against file extension (if `path` is present).
    // todo: switch this to an enum of mime types
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub mime: Option<String>,
    /// Specifies whether the content in the file should
    /// be "minified"/have whitespace removed.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub minify: Option<bool>,

    /// build scripts for ensuring the WebAssembly components
    /// are composed properly at build time.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub build: Option<Vec<Vec<String>>>,

    /// path to the WASM component binary
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub bin: Option<String>,

    /// which language the input binding WebAssembly
    /// Component should be compiled _from_.
    ///
    /// Note: because the bindings are compiled _to_
    /// a WebAssembly Component, with a companion WIT
    /// file, the resulting bindings can be used by any
    /// language that has WIT support.
    ///
    /// i.e. bindings compiled from Rust can be plugged
    /// into a Golang WebAssembly component.
    ///
    /// **Important**: if your FFI serialization format
    /// is JSON, or you are comfortable writing your own
    /// `FlexBuffer` vector accessors it is not necessary
    /// to generate the bindings (other than for reference
    /// in the `FlexBuffer` vector accessing case).
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub bindgen: Option<BindgenLang>,

    /// Relative path to the template file
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub path: Option<String>,
    /// The route used in the HTTP server to serve this template.
    /// Can use segments to bind to properties on models or content
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub route: Option<String>,
    /// What to check the token fields against. If left blank, route is considered public.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub protected: Option<Check>,
    /// Used to specify the cache policy for this template.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub cache: Option<TemplateCache>,

    /// HTTP Content Security Policy configuration.
    ///
    /// <https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP>
    ///
    /// "Base" defaults to `default-src 'self';` and tacks on SHA-256 integrity
    /// hashes for all inlined scripts and styles (generated at build time) to
    /// `script-src 'self' sha256-b64` and `style-src 'self' sha256-b64`, respectively.
    ///
    /// `https:` is used when not running in `--insecure` mode.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub csp: Option<HttpCsp>,

    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub cors: Option<HttpCors>,

    /// Max duration for the template.
    ///
    /// Unit: seconds
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub timeout: Option<u16>,

    /// Used for template-specific variables that don't need to be shared
    /// beyond the scope of the given template, and don't warrant a content
    /// object.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub fields: Option<Vec<TemplateField>>,
    /// List of global variables to be included with the compiled template
    /// binary. Globals are excluded by default and have to be explicitly
    /// listed in the globals to be accessed from the template.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub globals: Option<Vec<String>>,
    /// List of flags to be referenced by the template.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub flags: Option<Vec<TemplateFlagRef>>,
    /// List of models and what fields the template needs from the models.
    /// This is effectively a query definition.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub models: Option<Vec<TemplateRef>>,
    /// List of content definitions and the content definition fields
    /// that this template will use.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub content: Option<Vec<TemplateRef>>,

    /// Specifies which actions this template is intended to trigger.
    ///
    /// Has no effect at runtime, is only useful for tooling.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub actions: Option<Vec<String>>,

    /// List of build time environment variables to be
    /// replaced directly in the template string.
    ///
    /// format in template: `{{ YOUR_VAR }}`
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub variables: Option<Vec<String>>,

    /// list of names of middleware to include for this template
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(default)]
    pub middlewares: Option<Vec<String>>,
}

impl TemplateConfig {
    pub fn load_managed(&mut self) {
        let template_name = self.name_validated().to_owned();

        if let Some(managed) = &self.managed {
            match managed {
                ManagedTemplate::V2RustAskama => {
                    self.ffi = Some(TemplateFfi {
                        version: TemplateFfiVersion::V2,
                        serialization: TemplateFfiSerialization::FlexBufferVector,
                    });

                    self.bindgen = Some(BindgenLang::Rust);
                    self.build = Some(vec![vec![
                        "sh".into(),
                        format!(".ordinary/{template_name}/build.sh"),
                    ]]);
                    self.bin = Some(format!(".ordinary/{template_name}/component.wasm"));
                }
            }
        }
    }

    /// ## Panics
    ///
    /// This method panics if the `idx` field has not been validated to be present
    #[must_use]
    pub fn idx_validated(&self) -> u8 {
        self.idx.expect("idx should not be 'None' after validation")
    }

    /// ## Panics
    ///
    /// This method panics if the `name` field has not been validated to be present
    #[must_use]
    pub fn name_validated(&self) -> &str {
        self.name
            .as_ref()
            .expect("name should not be 'None' after validation")
    }

    /// ## Panics
    ///
    /// This method panics if the `name` field has not been validated to be present
    #[must_use]
    pub fn route_validated(&self) -> &str {
        self.route
            .as_ref()
            .expect("route should not be 'None' after validation")
    }

    /// ## Panics
    ///
    /// This method panics if the `name` field has not been validated to be present
    #[must_use]
    pub fn mime_validated(&self) -> &str {
        self.mime
            .as_ref()
            .expect("route should not be 'None' after validation")
    }

    /// ## Panics
    ///
    /// This method panics if the `ffi` field has not been validated to be present
    #[must_use]
    pub fn ffi_validated(&self) -> &TemplateFfi {
        self.ffi
            .as_ref()
            .expect("ffi should not be 'None' after validation")
    }
}