fraiseql-server 2.18.0

//! Schema loader for compiled GraphQL schemas.

use std::path::{Path, PathBuf};

use fraiseql_core::{capability::SectionActivity, schema::CompiledSchema};
use tracing::{debug, info, warn};

/// Error loading schema.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum SchemaLoadError {
    /// Schema file not found.
    #[error("Schema file not found: {0}")]
    NotFound(PathBuf),

    /// IO error reading file.
    #[error("Failed to read schema file: {0}")]
    IoError(#[from] std::io::Error),

    /// JSON parsing error.
    #[error("Failed to parse schema JSON: {0}")]
    ParseError(#[from] serde_json::Error),

    /// Schema validation error.
    #[error("Invalid schema: {0}")]
    ValidationError(String),
}

/// The compiled schema's `"functions"` section.
///
/// Re-exported from [`fraiseql_functions`], which owns the shape: the compiler
/// writes it, this loader reads it, and `fraiseql functions invoke` reads it back.
/// It was defined here until #1325, when the authoring path would have made it the
/// third hand-maintained copy.
pub use fraiseql_functions::FunctionsConfig;

/// A compiled schema with all optional platform extensions parsed out.
///
/// Use [`CompiledSchemaLoader::load_extended`] to obtain this type. It bundles the
/// core [`CompiledSchema`] together with the optional `functions` configuration
/// embedded in the compiled schema JSON.
#[derive(Debug)]
pub struct ExtendedCompiledSchema {
    /// Core compiled GraphQL schema (types, queries, mutations, subscriptions).
    pub schema: CompiledSchema,

    /// Serverless functions configuration, if the `"functions"` key is present.
    pub functions: Option<FunctionsConfig>,
}

/// Loader for compiled GraphQL schemas from JSON files.
///
/// Loads and caches a compiled schema from a JSON file on disk.
/// Used during server startup to prepare the schema for query execution.
#[derive(Debug, Clone)]
pub struct CompiledSchemaLoader {
    /// Path to the compiled schema JSON file.
    path: PathBuf,
}

impl CompiledSchemaLoader {
    /// Create a new schema loader pointing to a schema file.
    ///
    /// # Arguments
    ///
    /// * `path` - Path to the compiled schema JSON file
    ///
    /// # Example
    ///
    /// ```no_run
    /// // Requires: schema.compiled.json file on disk.
    /// # use fraiseql_server::schema::loader::CompiledSchemaLoader;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let loader = CompiledSchemaLoader::new("schema.compiled.json");
    /// let schema = loader.load().await?;
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub fn new<P: AsRef<Path>>(path: P) -> Self {
        Self {
            path: path.as_ref().to_path_buf(),
        }
    }

    /// Load schema from file.
    ///
    /// Reads the schema JSON file, parses it, and returns a `CompiledSchema`.
    ///
    /// # Errors
    ///
    /// Returns [`SchemaLoadError::NotFound`] if the file does not exist.
    /// Returns [`SchemaLoadError::IoError`] if the file cannot be read.
    /// Returns [`SchemaLoadError::ParseError`] if the JSON is malformed.
    /// Returns [`SchemaLoadError::ValidationError`] if schema validation fails.
    ///
    /// # Example
    ///
    /// ```no_run
    /// // Requires: schema.compiled.json file on disk.
    /// # use fraiseql_server::schema::loader::CompiledSchemaLoader;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let loader = CompiledSchemaLoader::new("schema.compiled.json");
    /// let schema = loader.load().await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn load(&self) -> Result<CompiledSchema, SchemaLoadError> {
        info!(path = %self.path.display(), "Loading compiled schema");

        // Check if file exists
        if !self.path.exists() {
            return Err(SchemaLoadError::NotFound(self.path.clone()));
        }

        // Read file asynchronously
        let contents =
            tokio::fs::read_to_string(&self.path).await.map_err(SchemaLoadError::IoError)?;

        debug!(
            path = %self.path.display(),
            size_bytes = contents.len(),
            "Schema file read successfully"
        );

        // Parse JSON and validate it's valid JSON first
        serde_json::from_str::<serde_json::Value>(&contents)?;

        // Create CompiledSchema from JSON string
        let schema = CompiledSchema::from_json(&contents, false)
            .map_err(|e| SchemaLoadError::ValidationError(e.to_string()))?;

        info!(path = %self.path.display(), "Schema loaded successfully");

        Ok(schema)
    }

    /// Load schema and all optional platform extension sections from file.
    ///
    /// In addition to the core schema (types, queries, mutations, subscriptions),
    /// this method parses and validates the `"functions"` top-level key if it is
    /// present. A `"storage"` key is refused (#1008 — nothing reads it; the working
    /// surface is `[storage]` in the server config file). A legacy `"realtime"` key
    /// is ignored with a warning (the subsystem was removed in #605). Unknown
    /// top-level keys are ignored for forward compatibility.
    ///
    /// # Errors
    ///
    /// Returns [`SchemaLoadError::NotFound`] if the file does not exist.
    /// Returns [`SchemaLoadError::IoError`] if the file cannot be read.
    /// Returns [`SchemaLoadError::ParseError`] if the JSON is malformed.
    /// Returns [`SchemaLoadError::ValidationError`] if any of the following fail:
    ///   - A non-null `"storage"` key is present.
    ///   - A function trigger string does not match a recognised pattern.
    pub async fn load_extended(&self) -> Result<ExtendedCompiledSchema, SchemaLoadError> {
        info!(path = %self.path.display(), "Loading extended compiled schema");

        if !self.path.exists() {
            return Err(SchemaLoadError::NotFound(self.path.clone()));
        }

        let contents =
            tokio::fs::read_to_string(&self.path).await.map_err(SchemaLoadError::IoError)?;

        debug!(
            path = %self.path.display(),
            size_bytes = contents.len(),
            "Schema file read for extended loading"
        );

        // Parse once as a raw JSON value so we can extract platform sections without
        // touching the CompiledSchema deserialization path.
        let raw: serde_json::Value = serde_json::from_str(&contents)?;

        // Core schema (always required).
        let schema = CompiledSchema::from_json(&contents, false)
            .map_err(|e| SchemaLoadError::ValidationError(e.to_string()))?;

        // The compiled-schema `storage` section is refused rather than parsed (#1008).
        //
        // It used to be deserialized, validated, and stored on
        // `ExtendedCompiledSchema.storage` — where nothing read it. `main.rs` takes
        // `.schema` and `.functions`; the storage backend is built from `[storage]` in
        // the *server config file*. So an author who read "configuration is embedded in
        // the compiled schema" and declared buckets here got a clean compile, a clean
        // boot, and either no storage backend or an unrelated one. Parsing and
        // validating it is what made it look honoured.
        //
        // Refused rather than warned-and-ignored, unlike the `realtime` key below: that
        // one names a subsystem that no longer exists, so an author can only recompile,
        // while this one names a live subsystem configured elsewhere. Naming the working
        // surface is the difference between a refusal and a usable one (#612).
        if raw.get("storage").is_some_and(|v| !v.is_null()) {
            return Err(SchemaLoadError::ValidationError(
                "the compiled schema declares a `storage` section, which no part of the \
                 server reads: the storage backend is built from `[storage]` in the server \
                 config file (or its FRAISEQL_STORAGE_* environment overrides). Move the \
                 bucket configuration there and remove this section, which would otherwise \
                 be silently dropped at boot."
                    .to_string(),
            ));
        }

        // Parse and validate the optional sections.
        let functions = raw
            .get("functions")
            .filter(|v| !v.is_null())
            .map(|v| {
                let cfg: FunctionsConfig = serde_json::from_value(v.clone())?;
                validate_functions_config(&cfg)?;
                Ok::<_, SchemaLoadError>(cfg)
            })
            .transpose()?;

        // The compiled-schema `"realtime"` section is no longer supported (#605): the
        // dormant `/realtime/v1` subsystem was removed. fraiseql-cli never emitted this
        // section (cli and server are version-locked on the format), so only a
        // hand-authored or stale schema could contain one — warn and ignore rather than
        // fail, keeping boot resilient while still surfacing the staleness.
        if raw.get("realtime").is_some_and(|v| !v.is_null()) {
            warn!(
                path = %self.path.display(),
                "compiled-schema `realtime` section is no longer supported and is ignored; \
                 recompile with the current fraiseql-cli"
            );
        }

        // #1329: the query ↔ `request:query` pairing, in both directions, from the
        // same implementation the compiler calls. Outside the `map` above on
        // purpose: a query declaring `function = "<name>"` in an artifact with **no**
        // functions section is one of the two failures this checks, and inside the
        // `Option` it would never be asked.
        validate_query_bindings(&schema, functions.as_ref())?;

        // #1326: a build that cannot RUN a declared section refuses to boot, rather
        // than loading it and dropping it. See `refuse_unservable_sections`.
        refuse_unservable(&raw)?;

        info!(
            path = %self.path.display(),
            has_functions = functions.is_some(),
            "Extended schema loaded successfully"
        );

        Ok(ExtendedCompiledSchema { schema, functions })
    }

    /// Get the path to the schema file.
    #[must_use]
    pub fn path(&self) -> &Path {
        &self.path
    }
}

/// A compiled-schema section that only a feature-gated subsystem can serve (#1326).
///
/// `compiled_in` is evaluated with `cfg!`, not `#[cfg]`, so both arms type-check in
/// every build and the OFF arm is never a branch nothing compiles.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct GatedSection {
    /// The top-level key in `schema.compiled.json`.
    pub name:        &'static str,
    /// The `fraiseql-server` Cargo feature whose subsystem serves it.
    pub feature:     &'static str,
    /// Whether this build has that feature.
    pub compiled_in: bool,
    /// What an operator should do — a published image tag, or the build flag.
    pub remedy:      String,
    /// Whether a present declaration is actually asking for something to run.
    pub activity:    SectionActivity,
}

/// Every compiled-schema section whose *only* consumers sit behind a
/// `fraiseql-server` Cargo feature, and whether this build has that feature.
///
/// Derived from [`crate::capability::REGISTRY`]: a capability's `compiled_sections`
/// are exactly the sections nothing outside it can serve. The manifest tests hold the
/// registry to `CompiledSchema`, so a new section has to be classified there or as
/// servable by every build.
///
/// `reload_gate.rs` also names most of these, but it only *compares* them across a hot
/// reload — it does not serve them, so it is not a consumer for this purpose.
pub(crate) fn gated_sections() -> Vec<GatedSection> {
    crate::capability::REGISTRY
        .iter()
        .flat_map(|r| {
            r.meta.compiled_sections.iter().map(|section| GatedSection {
                name:        section.key,
                feature:     r.meta.feature,
                compiled_in: r.compiled_in,
                remedy:      r.meta.remedy(),
                activity:    section.activity,
            })
        })
        .collect()
}

/// Refuse a compiled schema that declares a section this build cannot serve.
///
/// # Why this lives at the READ site
///
/// The whole #1326 defect is that the *use* site is compiled out: `LoadedSchema.functions`
/// is `#[cfg(feature = "functions-runtime")]`, so a guard placed beside it disappears in
/// exactly the build that needs one. `load_extended` parses and validates the section
/// unconditionally, so it is the one place that can see a declaration a lean binary is
/// about to drop.
///
/// This is the posture `subsystems/loader.rs` already states in prose — "a declared
/// function that can never run is a misconfiguration, not something to skip silently" —
/// and the one #871 applied to `http:` triggers and #1008 to a `storage` section. The
/// lean build was simply outside it: it boots clean, logs nothing, and every declared
/// function never fires.
///
/// # Errors
///
/// Returns [`SchemaLoadError::ValidationError`] naming every unservable section, the
/// feature each needs and the remedy.
pub(crate) fn refuse_unservable_sections(
    raw: &serde_json::Value,
    sections: &[GatedSection],
) -> Result<(), SchemaLoadError> {
    let unservable: Vec<&GatedSection> = sections
        .iter()
        .filter(|section| !section.compiled_in)
        .filter(|section| {
            // A `null` is not a declaration — the same rule the `storage` refusal uses, so
            // a serializer that emits every key with an empty value does not fail the boot.
            // Nor is a section that is switched off, or carries nothing to run.
            raw.get(section.name)
                .filter(|v| !v.is_null())
                .is_some_and(|value| section.activity.is_active(value))
        })
        .collect();
    if unservable.is_empty() {
        return Ok(());
    }
    let named = unservable
        .iter()
        .map(|s| format!("`{}` (needs the `{}` feature: {})", s.name, s.feature, s.remedy))
        .collect::<Vec<_>>()
        .join("; ");
    Err(SchemaLoadError::ValidationError(format!(
        "the compiled schema declares sections this build was compiled without, so nothing \
         can run them: {named}. They would otherwise be loaded, validated and then silently \
         dropped — the server would boot clean and every declared entry would never fire. To \
         run without them, remove the sections and recompile the schema."
    )))
}

/// Refuse a compiled schema, as JSON, that declares a section whose capability this
/// build was compiled without, naming every such section and the feature it needs.
///
/// The boot path calls it from [`CompiledSchemaLoader::load_extended`]; a caller that
/// builds the schema in memory and so bypasses the loader (`fraiseql run`) calls it
/// directly. The sections come from [`crate::capability::REGISTRY`].
///
/// # Errors
///
/// Returns [`SchemaLoadError::ValidationError`] naming each unservable section.
pub fn refuse_unservable(raw: &serde_json::Value) -> Result<(), SchemaLoadError> {
    refuse_unservable_sections(raw, &gated_sections())
}

/// Validate the compiled function definitions.
///
/// Delegates to [`TriggerRegistry::validate_definitions`] — the same rule the
/// compiler applies at `fraiseql compile` time and the same one
/// `build_functions_subsystem` applies when it actually builds the registry. It runs
/// here as well because a compiled schema is an input the server does not produce:
/// a hand-written or stale artifact must still fail at boot rather than reach the
/// dispatcher unvalidated.
///
/// Until #1325 this carried its own `VALID_TRIGGER_PREFIXES` list — a second copy of
/// a grammar it did not own, and one that had already fallen two trigger kinds
/// behind: `after:capture:` (#366) and `after:ingest:` are parsed and dispatched by
/// the registry and were refused here, so a valid schema could not boot.
///
/// # Errors
///
/// Returns `ValidationError` naming the function and what is wrong with it.
fn validate_functions_config(config: &FunctionsConfig) -> Result<(), SchemaLoadError> {
    fraiseql_functions::triggers::registry::TriggerRegistry::validate_definitions(
        &config.definitions,
    )
    .map_err(|error| SchemaLoadError::ValidationError(error.message))
}

/// Validate that every function-backed query pairs with a `request:query` function,
/// and every `request:query` function with a query (#1329).
///
/// The second call site of
/// [`TriggerRegistry::validate_query_bindings`](fraiseql_functions::triggers::registry::TriggerRegistry::validate_query_bindings),
/// for the reason [`validate_functions_config`] is the second call site of the
/// grammar: a compiled schema is an input the server does not produce. A
/// hand-written or stale artifact whose query names a function that was deleted
/// would otherwise boot clean and answer that field with "Query has no SQL source"
/// — an error about the wrong thing, at the first request rather than at boot.
///
/// Takes the whole schema rather than the bindings so the caller cannot build the
/// slice differently than the compiler does.
///
/// # Errors
///
/// Returns `ValidationError` naming each query or function that does not pair.
fn validate_query_bindings(
    schema: &CompiledSchema,
    functions: Option<&FunctionsConfig>,
) -> Result<(), SchemaLoadError> {
    use fraiseql_functions::triggers::registry::{QueryFunctionBinding, TriggerRegistry};

    let bindings: Vec<QueryFunctionBinding<'_>> = schema
        .queries
        .iter()
        .filter_map(|query| {
            query.function.as_deref().map(|function| QueryFunctionBinding {
                query: query.name.as_str(),
                function,
            })
        })
        .collect();

    TriggerRegistry::validate_query_bindings(
        &bindings,
        functions.map_or(&[], |f| f.definitions.as_slice()),
    )
    .map_err(|error| SchemaLoadError::ValidationError(error.message))
}