yeti_types/

inventory.rs

//! Process-wide deployment inventory.
//!
//! Captures the full discoverable shape of a yeti
//! deployment (databases, apps, tables, interfaces, functions) in a
//! single deterministic-order struct so MCP-attached agents can ask
//! one question and get the whole map.
//!
//! Same one-shot pattern as [`crate::app_snapshot`]: yeti-host writes
//! once at startup-complete, tooling crates (yeti-mcp, audit, etc.)
//! read lock-free thereafter. Yeti does not hot-add apps post-boot,
//! so a `OnceLock` is sufficient — swap to `ArcSwap` if/when that
//! changes.
//!
//! The shape is intentionally agent-friendly:
//! - sorted vectors (not maps) so JSON serialization is stable;
//! - effective transport flags resolved at build time (the `@export`
//!   default-true rule already applied), so consumers don't have to
//!   re-derive availability;
//! - cross-cutting indexes (`tables`, `interfaces`, `functions`)
//!   materialized rather than implied so agents don't have to walk
//!   the app tree.

use std::sync::{Arc, OnceLock};

use serde::{Deserialize, Serialize};

/// The full deployment inventory. Populated once by yeti-host at
/// startup-complete via [`set_deployment_inventory`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DeploymentInventory {
    /// Hash identifying this deployment (currently hardcoded
    /// `"local"` until Fabric multi-deployment hosting plumbs a real
    /// value through; see the `TransactionLog` convention).
    pub deployment_hash: String,
    /// Distinct databases referenced by any registered table, sorted by name.
    pub databases: Vec<DatabaseEntry>,
    /// Registered applications, sorted by id.
    pub apps: Vec<AppEntry>,
    /// Every `@table` across every app, sorted by `(app_id, name)`.
    pub tables: Vec<TableEntry>,
    /// Every interface surface (table × transport, custom function),
    /// sorted by `logical_name`.
    pub interfaces: Vec<InterfaceEntry>,
    /// Every custom Resource (`resources/*.rs`), sorted by `(app_id, name)`.
    pub functions: Vec<FunctionEntry>,
}

/// One database namespace and the tables it hosts.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DatabaseEntry {
    /// Database name (e.g. `"yeti-auth"`, `"demo-basic"`).
    pub name: String,
    /// Sorted list of table names backed by this database.
    pub table_names: Vec<String>,
}

/// One registered application.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AppEntry {
    /// Application id (URL slug).
    pub id: String,
    /// Human-readable name from `[package.metadata.app] name`.
    pub name: String,
    /// Mount-point prefix (`/yeti-auth`, etc.). Empty for the root app.
    pub route_prefix: String,
    /// App version from `[package] version` in Cargo.toml (string
    /// form; currently "latest" for most apps until proper versioning).
    pub version: String,
    /// `true` when `[package.metadata.app] plugin = true` — the app
    /// provides shared services rather than user-facing endpoints.
    pub is_plugin: bool,
    /// Sorted list of table names this app declares.
    pub table_names: Vec<String>,
    /// Sorted list of custom resource function names this app declares
    /// (from `resources/*.rs`).
    pub function_names: Vec<String>,
}

/// One `@table` declaration, with effective (post-default-resolution)
/// transport flags.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TableEntry {
    /// Table type name (`User`, `Role`, `DemoItem`).
    pub name: String,
    /// Database namespace this table lives in.
    pub database: String,
    /// Owning application id.
    pub app_id: String,
    /// Field summaries (name, type, required, indexed).
    pub fields: Vec<FieldSummary>,
    /// Effective transport availability — `@export` default-true
    /// already applied. A flag is `true` iff the table is reachable
    /// on that transport at this deployment.
    pub transports: TransportFlags,
}

/// One field of a `TableEntry`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FieldSummary {
    /// Field name.
    pub name: String,
    /// GraphQL type as declared (`String`, `Int`, `Float`, `MyEnum`,
    /// possibly with `!` non-null marker stripped).
    pub type_name: String,
    /// `true` iff the field is non-null in the schema (had a trailing `!`).
    pub required: bool,
    /// `true` iff the field carries an `@indexed` (or `@primary` /
    /// `@vector`) directive.
    pub indexed: bool,
}

/// Per-transport availability flags. All seven transports default to
/// `true` whenever `@export` is present on a table (no args means
/// "exported everywhere"); explicit `false` args opt out.
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
#[allow(clippy::struct_excessive_bools)]
pub struct TransportFlags {
    /// REST CRUD over HTTP/HTTPS.
    pub rest: bool,
    /// GraphQL field on the per-app `/graphql` endpoint.
    pub graphql: bool,
    /// WebSocket subscription.
    pub ws: bool,
    /// Server-Sent Events streaming.
    pub sse: bool,
    /// MQTT publish/subscribe topic.
    pub mqtt: bool,
    /// MCP tool surface (`{table}_{op}`).
    pub mcp: bool,
    /// gRPC method (config-only until the bridge ships).
    pub grpc: bool,
}

impl TransportFlags {
    /// Project the canonical [`TransportSet`](crate::transport::TransportSet)
    /// into the serialized per-transport bool shape. The one conversion
    /// from the canonical set to this wire representation.
    #[must_use]
    pub const fn from_set(set: crate::transport::TransportSet) -> Self {
        use crate::transport::Transport;
        Self {
            rest: set.contains(Transport::Rest),
            graphql: set.contains(Transport::GraphQl),
            ws: set.contains(Transport::Ws),
            sse: set.contains(Transport::Sse),
            mqtt: set.contains(Transport::Mqtt),
            mcp: set.contains(Transport::Mcp),
            grpc: set.contains(Transport::Grpc),
        }
    }
}

/// Kind discriminator for `InterfaceEntry`.
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum InterfaceKind {
    /// Auto-generated CRUD surface for a `@table`.
    Table,
    /// Custom Resource implementation (`resources/*.rs`).
    CustomFunction,
}

/// One reachable surface (table on a transport, or a custom function).
///
/// Materializes the cross product of (table, transport) plus one entry
/// per custom function so agents can search by logical name without
/// re-deriving URLs.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InterfaceEntry {
    /// Stable lookup key. For tables: `{app_id}.{Table}`. For custom
    /// functions: `{app_id}.{function_name}`.
    pub logical_name: String,
    /// Whether this surface comes from a `@table` or a custom function.
    pub kind: InterfaceKind,
    /// Source identifier — same shape as `logical_name` today; kept
    /// separate so future tooling can decorate `logical_name`
    /// (e.g. with operation suffixes) without losing the back-pointer.
    pub source: String,
    /// REST endpoint when available (`/{app}/{Table}`).
    pub rest_url: Option<String>,
    /// GraphQL field path (`/{app}/graphql#Query.{Table}`).
    pub graphql_field: Option<String>,
    /// WebSocket URL (`wss://host/{app}/{Table}`); host portion is a
    /// placeholder template `{host}` since the inventory builder
    /// doesn't know the listener address at build time.
    pub ws_url: Option<String>,
    /// SSE URL (`/{app}/{Table}?stream=sse`).
    pub sse_url: Option<String>,
    /// MQTT topic (`{app_id}/{Table}`).
    pub mqtt_topic: Option<String>,
    /// MCP tool name (`{table_lower}_get`); arbitrary one of the six
    /// CRUD tools generated per table — the canonical "discovery
    /// breadcrumb" entry. Agents should call `tools/list` for the full set.
    pub mcp_tool: Option<String>,
    /// gRPC method path stub. Best-effort: `/{app}.{Table}/Get` style.
    /// The actual gRPC bridge isn't implemented yet — no dispatcher
    /// ships and the server-wide `grpc.enabled` config flag is
    /// ignored, with a startup `tracing::warn!` on the legacy key.
    /// This field documents the planned shape so
    /// inventory consumers can render a stable column.
    pub grpc_method: Option<String>,
}

/// One custom Resource implementation surfaced by an app.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FunctionEntry {
    /// Function/resource name as registered.
    pub name: String,
    /// Owning application id.
    pub app_id: String,
    /// REST endpoint URL.
    pub rest_url: String,
    /// HTTP verbs the function answers. Determined per-function at
    /// registration time. Inventory currently emits an empty list — the
    /// `AutoRouter` doesn't expose per-resource verb tables. Agents
    /// should treat empty as "unknown; try GET first."
    pub verbs: Vec<String>,
    /// Optional human description.
    pub description: Option<String>,
}

static DEPLOYMENT_INVENTORY: OnceLock<Arc<DeploymentInventory>> = OnceLock::new();

/// Install the process-wide inventory snapshot. Called once by
/// yeti-host after the startup phase completes; subsequent calls
/// silently no-op (`OnceLock::set` fails after the first init).
pub fn set_deployment_inventory(inv: DeploymentInventory) {
    let _ = DEPLOYMENT_INVENTORY.set(Arc::new(inv));
}

/// Borrow the installed inventory, if any. Returns `None` when called
/// before [`set_deployment_inventory`] — typically because the reader
/// fired before startup completed. Tool handlers should surface this
/// as a transient error.
#[must_use]
pub fn get_deployment_inventory() -> Option<Arc<DeploymentInventory>> {
    DEPLOYMENT_INVENTORY.get().map(Arc::clone)
}