fraiseql_functions/host/

mod.rs

//! Host context trait for function runtime access to FraiseQL services.

use std::future::Future;

use fraiseql_error::Result;

use crate::types::{EventPayload, LogEntry, LogLevel};

#[cfg(feature = "host-live")]
pub mod before_mutation;

#[cfg(feature = "host-live")]
pub mod live;
// Gated with `live` because both read `HostContextConfig` (the SSRF allowlist and
// the timeouts) out of it, and `request_query` additionally names `fraiseql-core`'s
// `GuestQueryBridge` — which is exactly what `host-live` pulls in.
#[cfg(feature = "host-live")]
pub mod outbound_http;
#[cfg(feature = "host-live")]
pub mod request_query;

// Not feature-gated: the object-safe host contract is what a *caller* needs to
// hand a live host to `FunctionObserver::invoke_with_context`, and the
// `before:mutation` chain (#1328) does that from `fraiseql-server`'s ungated
// `routes::before_mutation`. Compiling a trait definition and a blanket impl
// costs a build with no runtime nothing; making the caller feature-gated would
// have cost it a second, drifting host shape.
pub mod dyn_context;

#[cfg(any(feature = "runtime-wasm", feature = "runtime-deno"))]
pub mod runtime_pinned;

/// The guest-facing projection of an authenticated identity, shared by every host
/// that answers `fraiseql_auth_context`.
///
/// One function, not one per host: the set of claims a guest may see is a
/// security decision, and a second copy of it is a second place to forget
/// `ip_address` is not in it. Deliberately excludes everything sensitive — the IP
/// address, the raw token, the issuer/audience.
///
/// `email` / `display_name` are the connected user's verified identity — the
/// per-user sending address a paired outbound email must use (see
/// [`crate::outbound::resolve_sender_identity`]). They are `null` when the
/// authenticated identity carries none.
#[cfg(feature = "host-live")]
#[must_use]
pub fn auth_context_json(context: &fraiseql_core::security::SecurityContext) -> serde_json::Value {
    serde_json::json!({
        "sub": context.user_id,
        "user_id": context.user_id, // Alias for convenience
        "roles": context.roles,
        "scopes": context.scopes,
        "tenant_id": context.tenant_id,
        "email": context.email,
        "display_name": context.display_name,
        "expires_at": context.expires_at.to_rfc3339(),
        "authenticated_at": context.authenticated_at.to_rfc3339(),
    })
}

/// Response from an HTTP request.
#[derive(Debug, Clone)]
pub struct HttpResponse {
    /// HTTP status code.
    pub status:  u16,
    /// Response headers.
    pub headers: Vec<(String, String)>,
    /// Response body.
    pub body:    Vec<u8>,
}

/// Trait for providing host services to functions (queries, storage, HTTP, etc.).
///
/// This trait is implemented by the FraiseQL server to allow functions to call
/// back into the server's services during execution.
///
/// The `#[trait_variant::make]` macro generates `SendHostContext` which is
/// object-safe for `Box<dyn SendHostContext>` dynamic dispatch.
#[allow(clippy::trait_duplication_in_bounds)] // Reason: trait_variant::make expands to bounds that look duplicated to clippy
#[trait_variant::make(SendHostContext: Send)]
pub trait HostContext: Send + Sync {
    /// Execute a GraphQL query.
    ///
    /// # Errors
    ///
    /// Returns `Err` if the query fails to execute.
    fn query(
        &self,
        graphql: &str,
        variables: serde_json::Value,
    ) -> impl Future<Output = Result<serde_json::Value>> + Send;

    /// Execute a raw SQL query.
    ///
    /// # Errors
    ///
    /// Returns `Err` if the query fails to execute or is classified as insecure.
    fn sql_query(
        &self,
        sql: &str,
        params: &[serde_json::Value],
    ) -> impl Future<Output = Result<Vec<serde_json::Value>>> + Send;

    /// Make an HTTP request.
    ///
    /// # Errors
    ///
    /// Returns `Err` if the request fails or is blocked (e.g., SSRF check).
    fn http_request(
        &self,
        method: &str,
        url: &str,
        headers: &[(String, String)],
        body: Option<&[u8]>,
    ) -> impl Future<Output = Result<HttpResponse>> + Send;

    /// Retrieve an object from storage.
    ///
    /// # Errors
    ///
    /// Returns `Err` if the object does not exist or access is denied.
    fn storage_get(&self, bucket: &str, key: &str) -> impl Future<Output = Result<Vec<u8>>> + Send;

    /// Store an object to storage.
    ///
    /// # Errors
    ///
    /// Returns `Err` if the write fails or access is denied.
    fn storage_put(
        &self,
        bucket: &str,
        key: &str,
        body: &[u8],
        content_type: &str,
    ) -> impl Future<Output = Result<()>> + Send;

    /// Send an email.
    ///
    /// The `from` is **host-owned**: it is resolved by the host from the
    /// authenticated identity, never supplied by the guest (a `from` field in the
    /// guest request is ignored). The request carries only `to`/`subject`/body.
    ///
    /// # Errors
    ///
    /// Returns `Err` if no sender-identity resolver or transport is configured, the
    /// sender identity cannot be resolved (fail-closed), or the relay rejects the
    /// message.
    fn send_email(
        &self,
        request: &crate::outbound::SendEmailRequest,
    ) -> impl Future<Output = Result<crate::outbound::SendEmailResponse>> + Send;

    /// Get the current authenticated user's context.
    ///
    /// # Errors
    ///
    /// Returns `Err` if authentication information is unavailable.
    fn auth_context(&self) -> Result<serde_json::Value>;

    /// Get an environment variable.
    ///
    /// Returns `Ok(None)` if the variable is not set.
    ///
    /// # Errors
    ///
    /// Returns `Err` if the variable is blocked from access.
    fn env_var(&self, name: &str) -> Result<Option<String>>;

    /// Get the current event payload (for reference).
    fn event_payload(&self) -> &EventPayload;

    /// Log a message to the tracing subscriber.
    fn log(&self, level: LogLevel, message: &str);

    /// A per-dispatch idempotency token, stable across retries of the same
    /// dispatch and distinct per dispatch.
    ///
    /// `None` on invocation paths that are not durably dispatched (the bare sync
    /// `invoke` path, or a mock host that does not set one). The durable
    /// dispatcher derives the token from the dispatch's stable identity and
    /// injects it so a guest can pass it straight to a downstream money/mail
    /// idempotency header, keeping an at-least-once dispatch at-most-once end to
    /// end. Defaults to `None` so only hosts that carry a token override it.
    fn idempotency_token(&self) -> Option<String> {
        None
    }

    /// Read this source's durable opaque cursor (Model B pull sources, #573).
    ///
    /// Returns the JSON value the source last advanced to via
    /// [`advance_cursor`](Self::advance_cursor), or `None` if it has never advanced.
    /// Defaults to `None` on every host not bound to a source — a non-source
    /// invocation has no cursor — so only source-bound hosts override it.
    ///
    /// # Errors
    ///
    /// Returns `Err` if the cursor load fails on a source-bound host.
    fn cursor(&self) -> impl Future<Output = Result<Option<serde_json::Value>>> + Send {
        async { Ok(None) }
    }

    /// Advance this source's durable cursor to `value` (Model B pull sources, #573).
    ///
    /// The value is opaque and owned by the source. Defaults to failing on a host
    /// not bound to a source, so a guest that is not a scheduled source cannot move
    /// a cursor.
    ///
    /// # Errors
    ///
    /// Returns `Err` on a host not bound to a source (the default), or if the write
    /// fails / lost a concurrent race on a source-bound host.
    fn advance_cursor(&self, value: serde_json::Value) -> impl Future<Output = Result<()>> + Send {
        async move {
            let _ = value;
            Err(fraiseql_error::FraiseQLError::validation(
                "advance_cursor: this function is not a scheduled source (no cursor binding)",
            ))
        }
    }
}

/// A no-op host context for testing WASM execution without real backends.
///
/// All I/O methods return `Unsupported` errors. Logs are captured in-memory for test verification.
pub struct NoopHostContext {
    event_payload: EventPayload,
    logs:          std::sync::Arc<std::sync::Mutex<Vec<LogEntry>>>,
}

impl NoopHostContext {
    /// Create a new no-op host context for testing.
    #[must_use]
    pub fn new(event_payload: EventPayload) -> Self {
        Self {
            event_payload,
            logs: std::sync::Arc::new(std::sync::Mutex::new(Vec::new())),
        }
    }

    /// Get a copy of all captured logs (for test verification).
    ///
    /// # Panics
    ///
    /// Panics if the Mutex is poisoned (should never happen in normal operation).
    #[must_use]
    pub fn captured_logs(&self) -> Vec<LogEntry> {
        self.logs.lock().expect("log mutex poisoned").clone()
    }
}

// Reason: `HostContext` is async because the live implementation performs I/O —
// GraphQL queries, HTTP calls, secret lookups. Impls whose methods refuse or
// answer from memory still have to present the awaited signature the trait
// defines and every guest call site uses.
#[allow(unknown_lints, clippy::unused_async_trait_impl)]
impl HostContext for NoopHostContext {
    async fn query(
        &self,
        _graphql: &str,
        _variables: serde_json::Value,
    ) -> Result<serde_json::Value> {
        Err(fraiseql_error::FraiseQLError::Unsupported {
            message: "HostContext::query not implemented".to_string(),
        })
    }

    async fn sql_query(
        &self,
        _sql: &str,
        _params: &[serde_json::Value],
    ) -> Result<Vec<serde_json::Value>> {
        Err(fraiseql_error::FraiseQLError::Unsupported {
            message: "HostContext::sql_query not implemented".to_string(),
        })
    }

    async fn http_request(
        &self,
        _method: &str,
        _url: &str,
        _headers: &[(String, String)],
        _body: Option<&[u8]>,
    ) -> Result<HttpResponse> {
        Err(fraiseql_error::FraiseQLError::Unsupported {
            message: "HostContext::http_request not implemented".to_string(),
        })
    }

    async fn storage_get(&self, _bucket: &str, _key: &str) -> Result<Vec<u8>> {
        Err(fraiseql_error::FraiseQLError::Unsupported {
            message: "HostContext::storage_get not implemented".to_string(),
        })
    }

    async fn storage_put(
        &self,
        _bucket: &str,
        _key: &str,
        _body: &[u8],
        _content_type: &str,
    ) -> Result<()> {
        Err(fraiseql_error::FraiseQLError::Unsupported {
            message: "HostContext::storage_put not implemented".to_string(),
        })
    }

    async fn send_email(
        &self,
        _request: &crate::outbound::SendEmailRequest,
    ) -> Result<crate::outbound::SendEmailResponse> {
        Err(fraiseql_error::FraiseQLError::Unsupported {
            message: "HostContext::send_email not implemented".to_string(),
        })
    }

    fn auth_context(&self) -> Result<serde_json::Value> {
        Err(fraiseql_error::FraiseQLError::Unsupported {
            message: "HostContext::auth_context not implemented".to_string(),
        })
    }

    fn env_var(&self, _name: &str) -> Result<Option<String>> {
        Ok(None)
    }

    fn event_payload(&self) -> &EventPayload {
        &self.event_payload
    }

    fn log(&self, level: LogLevel, message: &str) {
        let entry = LogEntry {
            level,
            message: message.to_string(),
            timestamp: chrono::Utc::now(),
        };
        self.logs.lock().expect("log mutex poisoned").push(entry);
    }
}

#[cfg(test)]
mod tests;