fraiseql_core/schema/compiled/

schema_domain.rs

//! Domain-specific methods for [`CompiledSchema`].
//!
//! Fact table management, observers, federation metadata, security configuration,
//! RLS, role scopes, tenancy, SDL generation, and schema validation.

#[cfg(feature = "federation")]
use std::collections::HashMap;
use std::fmt::Write as _;

use super::schema::{CURRENT_FRAISEQL_VERSION, CompiledSchema};
use crate::{
    compiler::fact_table::FactTableMetadata,
    schema::{
        observer_types::ObserverDefinition,
        security_config::{RoleDefinition, SecurityConfig},
    },
};

impl CompiledSchema {
    /// Refuse a compiled schema this build did not produce (#1304).
    ///
    /// The compiled schema is a build artifact of the fraiseql release that
    /// wrote it, so the only artifact whose meaning this runtime can vouch for
    /// is its own build's. The check is an equality, deliberately: a runtime
    /// that decided whether another build's artifact were close enough would be
    /// making the judgement #1303 got wrong, silently, on the operator's behalf.
    ///
    /// An artifact carrying no stamp is refused too. It is the *older* case —
    /// nothing this project has shipped since v2.1 omits the field — and
    /// accepting it, as the format-version check it replaces did, left the
    /// guard admitting the stalest artifacts while refusing merely-stale ones.
    ///
    /// # Errors
    ///
    /// Returns an operator-facing message naming both builds and the recompile,
    /// unless the artifact was produced by this one.
    pub fn validate_producer_version(&self) -> Result<(), String> {
        match self.fraiseql_version.get() {
            Some(v) if v == CURRENT_FRAISEQL_VERSION => Ok(()),
            Some(v) => Err(format!(
                "Compiled schema was produced by fraiseql {v}, but this runtime is fraiseql \
                 {CURRENT_FRAISEQL_VERSION}. A compiled schema is a build artifact of the \
                 release that produced it: this runtime reads fields {v} never wrote, and \
                 reads their absence as a setting rather than as a gap. Recompile the schema \
                 with fraiseql-cli {CURRENT_FRAISEQL_VERSION}."
            )),
            None => Err(format!(
                "Compiled schema carries no `fraiseql_version` stamp, so the build that \
                 produced it cannot be established; this runtime is fraiseql \
                 {CURRENT_FRAISEQL_VERSION}. The stamp was introduced in fraiseql 2.15.0, so \
                 an unstamped artifact was written by an earlier release or by hand — either \
                 way this runtime cannot vouch for what its fields, and its missing fields, \
                 mean here. Recompile it with fraiseql-cli {CURRENT_FRAISEQL_VERSION}."
            )),
        }
    }

    /// Register fact table metadata.
    ///
    /// # Arguments
    ///
    /// * `table_name` - Fact table name (e.g., `tf_sales`)
    /// * `metadata` - Typed `FactTableMetadata`
    pub fn add_fact_table(&mut self, table_name: String, metadata: FactTableMetadata) {
        self.fact_tables.insert(table_name, metadata);
    }

    /// Get fact table metadata by name.
    ///
    /// # Arguments
    ///
    /// * `name` - Fact table name
    ///
    /// # Returns
    ///
    /// Fact table metadata if found
    #[must_use]
    pub fn get_fact_table(&self, name: &str) -> Option<&FactTableMetadata> {
        self.fact_tables.get(name)
    }

    /// List all fact table names.
    ///
    /// # Returns
    ///
    /// Vector of fact table names
    #[must_use]
    pub fn list_fact_tables(&self) -> Vec<&str> {
        self.fact_tables.keys().map(String::as_str).collect()
    }

    /// Check if schema contains any fact tables.
    #[must_use]
    pub fn has_fact_tables(&self) -> bool {
        !self.fact_tables.is_empty()
    }

    /// Find an observer definition by name.
    #[must_use]
    pub fn find_observer(&self, name: &str) -> Option<&ObserverDefinition> {
        self.observers.iter().find(|o| o.name == name)
    }

    /// Get all observers for a specific entity type.
    #[must_use]
    pub fn find_observers_for_entity(&self, entity: &str) -> Vec<&ObserverDefinition> {
        self.observers.iter().filter(|o| o.entity == entity).collect()
    }

    /// Get all observers for a specific event type (INSERT, UPDATE, DELETE).
    #[must_use]
    pub fn find_observers_for_event(&self, event: &str) -> Vec<&ObserverDefinition> {
        self.observers.iter().filter(|o| o.event == event).collect()
    }

    /// Check if schema contains any observers.
    #[must_use]
    pub const fn has_observers(&self) -> bool {
        !self.observers.is_empty()
    }

    /// Get total number of observers.
    #[must_use]
    pub const fn observer_count(&self) -> usize {
        self.observers.len()
    }

    /// Get federation metadata from schema.
    ///
    /// # Returns
    ///
    /// Federation metadata if configured in schema
    #[cfg(feature = "federation")]
    #[must_use]
    pub fn federation_metadata(&self) -> Option<crate::federation::FederationMetadata> {
        self.federation.as_ref().filter(|fed| fed.enabled).map(|fed| {
            use crate::federation::types::{
                FederatedType, FieldFederationDirectives, KeyDirective,
            };

            // Entities carry an `@key` (and, for an extended entity, `extend type` +
            // `@external` on the borrowed key/fields). Per-field directives are
            // rebuilt from the entity's `external_fields` / `shareable_fields` so the
            // SDL renderer can append `@external` / `@shareable` to each field line.
            let mut types: Vec<FederatedType> = fed
                .entities
                .iter()
                .map(|e| {
                    let mut field_directives: HashMap<String, FieldFederationDirectives> =
                        HashMap::new();
                    for f in &e.external_fields {
                        field_directives.entry(f.clone()).or_default().external = true;
                    }
                    for f in &e.shareable_fields {
                        field_directives.entry(f.clone()).or_default().shareable = true;
                    }
                    FederatedType {
                        name: e.name.clone(),
                        keys: vec![KeyDirective {
                            fields:     e.key_fields.clone(),
                            resolvable: true,
                        }],
                        is_extends: e.extends,
                        external_fields: e.external_fields.clone(),
                        shareable_fields: e.shareable_fields.clone(),
                        inaccessible_fields: Vec::new(),
                        field_directives,
                        type_shareable: false,
                    }
                })
                .collect();

            // Non-entity `@shareable` value types (e.g. a shared `MutationError`):
            // no `@key`, never a member of the `_Entity` union — they only receive a
            // type-level `@shareable` so both subgraphs can define the identical type
            // without an `INVALID_FIELD_SHARING` composition error.
            for name in &fed.shareable_types {
                types.push(FederatedType {
                    name:                name.clone(),
                    keys:                Vec::new(),
                    is_extends:          false,
                    external_fields:     Vec::new(),
                    shareable_fields:    Vec::new(),
                    inaccessible_fields: Vec::new(),
                    field_directives:    HashMap::new(),
                    type_shareable:      true,
                });
            }

            crate::federation::FederationMetadata {
                enabled: fed.enabled,
                version: fed.version.clone().unwrap_or_else(|| "v2".to_string()),
                types,
            }
        })
    }

    /// Build the per-entity-type backing source map (`typename` →
    /// [`EntitySource`](crate::federation::EntitySource)) the federation
    /// `_entities` resolver reads from instead of guessing `lower(typename)`
    /// (#504/#507).
    ///
    /// Two sources, query-wins:
    ///
    /// 1. **Query-sourced** (owned entities): the backing relation rides on the root query that
    ///    returns the type, keyed by `return_type`, first-wins — the same query→type binding the
    ///    Relay `node` path uses. The query's `jsonb_column` (which the compiler defaults to
    ///    `"data"`) drives jsonb projection.
    /// 2. **Type-sourced fallback** (#507): an owner-split `extend type … @key` entity resolved in
    ///    a subgraph that does not own it exposes no root query, so there is nothing in (1) to
    ///    source its relation from. Its relation instead rides on the type-level `sql_source` the
    ///    compiler carries from the authoring SDK. This only fills gaps — a query-sourced entry
    ///    always wins.
    ///
    /// Both sources read the entity's `jsonb_column` the same way: a non-empty column selects
    /// jsonb-projection mode (`<col>->'<field>'`), an empty one selects flat-column mode (bare
    /// columns). The compiler defaults both a query's and an extends type's `jsonb_column` to the
    /// standard `"data"` view shape, so a flat-column entity must be authored with an explicit
    /// empty `jsonb_column`.
    #[cfg(feature = "federation")]
    #[must_use]
    pub fn entity_sources(&self) -> HashMap<String, crate::federation::EntitySource> {
        use crate::federation::EntitySource;

        let mut sources: HashMap<String, EntitySource> = HashMap::new();

        // (1) Query-sourced — owned entities. First-wins per return_type.
        for q in &self.queries {
            if let Some(relation) = &q.sql_source {
                sources.entry(q.return_type.clone()).or_insert_with(|| EntitySource {
                    relation:     relation.clone(),
                    jsonb_column: (!q.jsonb_column.is_empty()).then(|| q.jsonb_column.clone()),
                });
            }
        }

        // (2) Type-sourced fallback — owner-split `extend type` entities (#507).
        // Skipped for owned types (their type-level sql_source is empty) and never
        // overrides a query-sourced entry. The empty-jsonb-column → flat-mode rule
        // mirrors the query path above, so flat-column extends entities resolve too.
        for t in &self.types {
            if t.sql_source.as_str().is_empty() {
                continue;
            }
            sources.entry(t.name.to_string()).or_insert_with(|| EntitySource {
                relation:     t.sql_source.to_string(),
                jsonb_column: (!t.jsonb_column.is_empty()).then(|| t.jsonb_column.clone()),
            });
        }

        sources
    }

    /// The SDL a federated subgraph serves as `_service { sdl }`: Apollo Federation v2
    /// directives over the schema's types (#1427).
    ///
    /// The executor's `_service` arm and `fraiseql federation sdl` both call this, so what
    /// a server serves and what the CLI prints from the same artifact cannot differ.
    ///
    /// # Errors
    ///
    /// [`FraiseQLError::Validation`](crate::error::FraiseQLError::Validation) when the
    /// schema has no enabled `[federation]` section.
    #[cfg(feature = "federation")]
    pub fn federation_service_sdl(&self) -> crate::error::Result<String> {
        let metadata =
            self.federation_metadata()
                .ok_or_else(|| crate::error::FraiseQLError::Validation {
                    message: "federation is not enabled in this schema: set `[federation] enabled \
                          = true` and recompile"
                        .to_string(),
                    path:    None,
                })?;
        Ok(crate::federation::generate_service_sdl(&self.raw_schema(), &metadata))
    }

    /// Stub federation metadata when federation feature is disabled.
    #[cfg(not(feature = "federation"))]
    #[must_use]
    pub const fn federation_metadata(&self) -> Option<()> {
        None
    }

    /// Get security configuration from schema.
    ///
    /// # Returns
    ///
    /// Security configuration if present (includes role definitions)
    #[must_use]
    pub const fn security_config(&self) -> Option<&SecurityConfig> {
        self.security.as_ref()
    }

    /// Returns `true` if this schema declares a multi-tenant deployment.
    ///
    /// Multi-tenant schemas require Row-Level Security (RLS) to be active whenever
    /// query result caching is enabled. Without RLS, all tenants sharing the same
    /// query parameters would receive the same cached response.
    ///
    /// True when `[security] multi_tenant = true` **or** a non-`none`
    /// `[tenancy] mode`. The second clause is load-bearing: `tenancy.mode` is the
    /// knob operators actually set, and reading only `security.multi_tenant` — which
    /// no compile path could produce — left both dependent gates permanently off
    /// (#758).
    #[must_use]
    pub fn is_multi_tenant(&self) -> bool {
        self.security
            .as_ref()
            .is_some_and(|s| s.multi_tenant || s.tenancy.mode != crate::schema::TenancyMode::None)
    }

    /// Returns the tenancy isolation mode configured for this schema.
    ///
    /// Defaults to `TenancyMode::None` when no security or tenancy configuration
    /// is present, meaning single-tenant operation with no isolation machinery.
    #[must_use]
    pub fn tenancy_mode(&self) -> crate::schema::TenancyMode {
        self.security
            .as_ref()
            .map_or(crate::schema::TenancyMode::None, |s| s.tenancy.mode)
    }

    /// Returns the tenancy configuration, if present.
    ///
    /// Returns `None` when no security configuration exists. Returns the
    /// default `TenancyConfig` (mode=none) when security exists but tenancy
    /// is not explicitly configured.
    #[must_use]
    pub fn tenancy_config(&self) -> Option<&crate::schema::TenancyConfig> {
        self.security.as_ref().map(|s| &s.tenancy)
    }

    /// The JWT claim that names a request's tenant: `[fraiseql.tenancy] tenant_claim`,
    /// or [`DEFAULT_TENANT_CLAIM`](crate::schema::security_config::DEFAULT_TENANT_CLAIM)
    /// when the schema declares none.
    ///
    /// The one source for every reader of "which claim is the tenant" (#1388): the
    /// compiler bakes it into row-mode `jwt:<claim>` injects, and the server derives
    /// `SecurityContext::tenant_id` from it.
    #[must_use]
    pub fn tenant_claim(&self) -> &str {
        self.tenancy_config()
            .map_or(crate::schema::security_config::DEFAULT_TENANT_CLAIM, |t| {
                t.tenant_claim.as_str()
            })
    }

    /// Find a role definition by name.
    ///
    /// # Arguments
    ///
    /// * `role_name` - Name of the role to find
    ///
    /// # Returns
    ///
    /// Role definition if found
    #[must_use]
    pub fn find_role(&self, role_name: &str) -> Option<RoleDefinition> {
        self.security.as_ref().and_then(|config| config.find_role(role_name).cloned())
    }

    /// Get scopes for a role.
    ///
    /// # Arguments
    ///
    /// * `role_name` - Name of the role
    ///
    /// # Returns
    ///
    /// Vector of scopes granted to the role
    #[must_use]
    pub fn get_role_scopes(&self, role_name: &str) -> Vec<String> {
        self.security
            .as_ref()
            .map(|config| config.get_role_scopes(role_name))
            .unwrap_or_default()
    }

    /// Check if a role has a specific scope.
    ///
    /// # Arguments
    ///
    /// * `role_name` - Name of the role
    /// * `scope` - Scope to check for
    ///
    /// # Returns
    ///
    /// true if role has the scope, false otherwise
    #[must_use]
    pub fn role_has_scope(&self, role_name: &str, scope: &str) -> bool {
        self.security
            .as_ref()
            .is_some_and(|config| config.role_has_scope(role_name, scope))
    }

    /// Returns `true` if this schema declares that database Row-Level Security
    /// isolates its data (`[security.rls] enabled = true`).
    ///
    /// Used at server startup to validate that caching is safe for multi-tenant
    /// deployments, and to decide whether to verify the declaration against the
    /// live database catalog.
    ///
    /// This is a *declaration*, not a proof: FraiseQL does not author RLS policies,
    /// so nothing in the compiled schema can establish that they exist. That is what
    /// [`CachedDatabaseAdapter::validate_rls_active`] checks against the real
    /// database (#762).
    ///
    /// It previously counted `security.additional["policies"]` — authorization
    /// policies, not RLS, and a section #612 made a hard compile error — so it
    /// answered `false` for every schema any supported workflow could produce
    /// (#758).
    ///
    /// [`CachedDatabaseAdapter::validate_rls_active`]: crate::cache::CachedDatabaseAdapter::validate_rls_active
    ///
    /// # Example
    ///
    /// ```
    /// use fraiseql_core::schema::CompiledSchema;
    ///
    /// let schema = CompiledSchema::default();
    /// assert!(!schema.has_rls_configured());
    /// ```
    #[must_use]
    pub fn has_rls_configured(&self) -> bool {
        self.security.as_ref().is_some_and(|s| s.rls.enabled)
    }

    /// Get raw GraphQL schema SDL.
    ///
    /// # Returns
    ///
    /// Raw schema string if available, otherwise generates from type definitions,
    /// including the root `Query`/`Mutation` types.
    ///
    /// Root operations are stored in [`self.queries`](Self::queries) /
    /// [`self.mutations`](Self::mutations) rather than as `Query`/`Mutation` object
    /// types in [`self.types`](Self::types), so they are rendered here explicitly.
    /// Omitting them produces an SDL that advertises no root fields — which makes the
    /// federation `_service` SDL (built from this output) fail gateway composition
    /// with `NO_QUERIES`.
    #[must_use]
    pub fn raw_schema(&self) -> String {
        self.schema_sdl.clone().unwrap_or_else(|| {
            // Generate basic SDL from type definitions if not provided
            let mut sdl = String::new();

            // Non-built-in scalar declarations. The rendered operations and fields
            // reference custom and standard-but-non-built-in scalars (`DateTime`,
            // `JSON`, `Decimal`, rich scalars, …); a gateway composing the subgraph
            // reports `Unknown type` for any it isn't declared.
            for name in self.referenced_scalars() {
                let _ = writeln!(sdl, "scalar {name}");
            }
            if !self.enums.is_empty()
                || !self.interfaces.is_empty()
                || !self.input_types.is_empty()
                || !self.unions.is_empty()
                || !self.types.is_empty()
            {
                sdl.push('\n');
            }

            // Enum types
            for enum_def in &self.enums {
                let _ = writeln!(sdl, "enum {} {{", enum_def.name);
                for value in &enum_def.values {
                    let _ = writeln!(sdl, "  {}", value.name);
                }
                sdl.push_str("}\n\n");
            }

            // Interface types
            for iface in &self.interfaces {
                let _ = writeln!(sdl, "interface {} {{", iface.name);
                for field in &iface.fields {
                    let _ = writeln!(sdl, "  {}: {}", field.name, field.field_type);
                }
                sdl.push_str("}\n\n");
            }

            // Input object types (`field_type` is a pre-rendered GraphQL string;
            // normalise the trailing non-null marker against the `nullable` flag).
            for input in &self.input_types {
                let _ = writeln!(sdl, "input {} {{", input.name);
                for field in &input.fields {
                    let base = field.field_type.trim_end_matches('!');
                    let non_null = if field.nullable { "" } else { "!" };
                    let _ = writeln!(sdl, "  {}: {base}{non_null}", field.name);
                }
                sdl.push_str("}\n\n");
            }

            // Union types (covers synthesized mutation result unions)
            for union_def in &self.unions {
                let _ = writeln!(
                    sdl,
                    "union {} = {}",
                    union_def.name,
                    union_def.member_types.join(" | ")
                );
            }
            if !self.unions.is_empty() {
                sdl.push('\n');
            }

            // Add output/object types
            for type_def in &self.types {
                let _ = writeln!(sdl, "type {} {{", type_def.name);
                for field in &type_def.fields {
                    let _ = writeln!(sdl, "  {}: {}", field.name, field.field_type);
                }
                sdl.push_str("}\n\n");
            }

            // Root Query type (rendered from `self.queries`, never present in `types`)
            if !self.queries.is_empty() {
                sdl.push_str("type Query {\n");
                for q in &self.queries {
                    let _ = writeln!(
                        sdl,
                        "  {}",
                        render_operation_field(
                            &q.name,
                            &q.graphql_arguments(self),
                            &q.return_type,
                            q.returns_list,
                            q.nullable,
                        )
                    );
                }
                sdl.push_str("}\n\n");
            }

            // Root Mutation type (rendered from `self.mutations`). Mutation payloads
            // are single, non-null values, so they render as `Name(args): Return!`.
            if !self.mutations.is_empty() {
                sdl.push_str("type Mutation {\n");
                for m in &self.mutations {
                    let _ = writeln!(
                        sdl,
                        "  {}",
                        render_operation_field(&m.name, &m.arguments, &m.return_type, false, false)
                    );
                }
                sdl.push_str("}\n\n");
            }

            sdl
        })
    }

    /// Collect the non-built-in scalar type names the schema references, so
    /// [`raw_schema`](Self::raw_schema) can declare each one (`scalar Name`) and the
    /// SDL is type-complete.
    ///
    /// A referenced type is treated as a scalar to declare when it is neither a
    /// built-in GraphQL scalar nor a type the schema defines as an object, enum,
    /// input, interface, or union. Names are collected **exactly as the fields render
    /// them** (the verbatim leaf of each field/argument type and each operation return
    /// type) so the declaration and the reference always agree — declaring a canonical
    /// alias (`DateTime`) while a field renders `datetime` would leave the reference
    /// dangling (`Unknown type datetime`). The custom-scalar registry is also included.
    /// The federation `_Any`/`_Entity`/`_Service`/`_FieldSet` built-ins (supplied by the
    /// federation layer) are excluded.
    pub(crate) fn referenced_scalars(&self) -> Vec<String> {
        use std::collections::{BTreeSet, HashSet};

        const BUILTINS: [&str; 5] = ["String", "Int", "Float", "Boolean", "ID"];
        const FED_BUILTINS: [&str; 4] = ["_Any", "_Entity", "_Service", "_FieldSet"];

        // Names the schema defines as composite types — never re-declared as scalars.
        let mut defined: HashSet<&str> = HashSet::new();
        for t in &self.types {
            defined.insert(t.name.as_str());
        }
        for e in &self.enums {
            defined.insert(e.name.as_str());
        }
        for i in &self.input_types {
            defined.insert(i.name.as_str());
        }
        for i in &self.interfaces {
            defined.insert(i.name.as_str());
        }
        for u in &self.unions {
            defined.insert(u.name.as_str());
        }

        // Every type reference, collected as the verbatim leaf name fields render.
        let mut referenced: BTreeSet<String> = BTreeSet::new();
        let add = |rendered: &str, set: &mut BTreeSet<String>| {
            let leaf = leaf_type_name(rendered);
            if !leaf.is_empty() {
                set.insert(leaf);
            }
        };
        for type_def in &self.types {
            for field in &type_def.fields {
                add(&field.field_type.to_string(), &mut referenced);
            }
        }
        for iface in &self.interfaces {
            for field in &iface.fields {
                add(&field.field_type.to_string(), &mut referenced);
            }
        }
        for query in &self.queries {
            // Walk the *rendered* arguments so any scalar synthesized for an
            // `auto_params` query (notably `JSON` for `where`/`orderBy`) is
            // declared — `render_operation_field` renders this same list.
            for arg in &query.graphql_arguments(self) {
                add(&arg.arg_type.to_string(), &mut referenced);
            }
            add(&query.return_type, &mut referenced);
        }
        for mutation in &self.mutations {
            for arg in &mutation.arguments {
                add(&arg.arg_type.to_string(), &mut referenced);
            }
            add(&mutation.return_type, &mut referenced);
        }
        for input in &self.input_types {
            for field in &input.fields {
                add(&field.field_type, &mut referenced);
            }
        }
        for (name, _) in self.custom_scalars.list_all() {
            referenced.insert(name);
        }

        referenced
            .into_iter()
            .filter(|name| {
                !defined.contains(name.as_str())
                    && !BUILTINS.contains(&name.as_str())
                    && !FED_BUILTINS.contains(&name.as_str())
            })
            .collect()
    }
}

/// Render a root operation as a GraphQL SDL field: `name(arg: T!, …): Return`.
///
/// `return_type` is a bare type name; list-ness and nullability are applied here so
/// the rendered signature matches GraphQL conventions (`[User!]!`, `User`, `User!`).
fn render_operation_field(
    name: &str,
    arguments: &[crate::schema::ArgumentDefinition],
    return_type: &str,
    returns_list: bool,
    nullable: bool,
) -> String {
    let non_null = if nullable { "" } else { "!" };
    let ret = if returns_list {
        format!("[{return_type}!]{non_null}")
    } else {
        format!("{return_type}{non_null}")
    };
    if arguments.is_empty() {
        return format!("{name}: {ret}");
    }
    let args = arguments
        .iter()
        .map(|a| format!("{}: {}{}", a.name, a.arg_type, if a.nullable { "" } else { "!" }))
        .collect::<Vec<_>>()
        .join(", ");
    format!("{name}({args}): {ret}")
}

/// Strip GraphQL list and non-null markers from a rendered type string, leaving the
/// bare leaf type name: `[User!]!` → `User`, `datetime` → `datetime`.
fn leaf_type_name(rendered: &str) -> String {
    rendered
        .chars()
        .filter(|c| !matches!(c, '[' | ']' | '!'))
        .collect::<String>()
        .trim()
        .to_string()
}