fraiseql_core/runtime/
executor_adapter.rs

1//! Type-erased executor interface.
2//!
3//! This module provides [`ExecutorAdapter`], a trait that allows code driving
4//! query execution (e.g., `fraiseql-server`, tests) to hold an
5//! `Arc<dyn ExecutorAdapter>` without being generic over a concrete
6//! `DatabaseAdapter` type parameter.
7//!
8//! # Design Rationale
9//!
10//! `Executor<A>` is generic over its database adapter. Without type erasure,
11//! every struct that holds an executor — the HTTP server, middleware, test
12//! harnesses — must carry that type parameter, which produces significant
13//! generic noise and makes dynamic dispatch impossible.
14//!
15//! `ExecutorAdapter` solves this by providing a single object-safe trait that
16//! concrete `Executor<A>` implementations can implement, enabling uniform
17//! `Arc<dyn ExecutorAdapter>` storage.
18//!
19//! # Example
20//!
21//! ```no_run
22//! // Requires: a concrete ExecutorAdapter implementation.
23//! use fraiseql_core::runtime::{ExecutionContext, ExecutorAdapter};
24//! use std::sync::Arc;
25//!
26//! async fn run_query(exec: Arc<dyn ExecutorAdapter>, query: &str) -> String {
27//!     let ctx = ExecutionContext::new("query-1".to_string());
28//!     exec.execute_with_context(query, None, &ctx).await.unwrap()
29//! }
30//! ```
31
32use std::pin::Pin;
33
34use crate::{error::Result, runtime::ExecutionContext};
35
36/// Type-erased executor interface.
37///
38/// Allows code that drives query execution (`fraiseql-server`, tests) to hold
39/// `Arc<dyn ExecutorAdapter>` without being generic over `DatabaseAdapter`.
40///
41/// Concrete implementations should implement this trait on their
42/// `Executor<A>` type to participate in the type-erased execution path.
43pub trait ExecutorAdapter: Send + Sync {
44    /// Execute a GraphQL query string with an execution context.
45    ///
46    /// # Arguments
47    ///
48    /// * `query` — the raw GraphQL query document
49    /// * `variables` — optional JSON object of query variables
50    /// * `ctx` — execution context carrying the query ID and cancellation token
51    ///
52    /// # Returns
53    ///
54    /// A JSON-serialised GraphQL response string on success.
55    ///
56    /// # Errors
57    ///
58    /// Returns a [`crate::error::FraiseQLError`] if parsing, validation, or
59    /// SQL execution fails, or if the context's cancellation token has already
60    /// been triggered.
61    fn execute_with_context<'a>(
62        &'a self,
63        query: &'a str,
64        variables: Option<&'a serde_json::Value>,
65        ctx: &'a ExecutionContext,
66    ) -> Pin<Box<dyn std::future::Future<Output = Result<String>> + Send + 'a>>;
67}
fraiseql_core/runtime/executor_adapter.rs

fraiseql_core/runtime/
executor_adapter.rs
