Struct Server 

pub struct Server<A: DatabaseAdapter> { /* private fields */ }

FraiseQL HTTP Server.

Server<A> is generic over a DatabaseAdapter implementation, which allows swapping database backends and injecting mock adapters in tests.

Feature: observers

When compiled with the observers Cargo feature, the server mounts observer management and runtime-health API endpoints under /api/observers. These endpoints require a live PostgreSQL connection pool (sqlx::PgPool).

Pass Some(pg_pool) as the db_pool argument to Server::new when the observers feature is enabled. Passing None causes the observer routes to be skipped at startup (an error is logged) rather than panicking, but the rest of the server continues to function normally.

The PostgreSQL pool is distinct from the generic DatabaseAdapter: the adapter handles application queries, while the pool is used exclusively by the observer subsystem to store and retrieve reactive rule metadata.

Implementations

impl<A: DatabaseAdapter + Clone + Send + Sync + 'static> Server<A>

pub async fn new( config: ServerConfig, schema: CompiledSchema, adapter: Arc<A>, db_pool: Option<PgPool>, ) -> Result<Self>

Create new server.

Relay pagination queries will return a Validation error at runtime. Use Server::with_relay_pagination when the adapter implements RelayDatabaseAdapter and relay support is required.

Arguments

• config - Server configuration
• schema - Compiled GraphQL schema
• adapter - Database adapter
• db_pool — forwarded to the observer runtime; None when observers are disabled.

Errors

Returns error if OIDC validator initialization fails (e.g., unable to fetch discovery document or JWKS).

Example

// Requires: running PostgreSQL database and compiled schema file.
let config = ServerConfig::default();
let schema = CompiledSchema::from_json(schema_json)?;
let adapter = Arc::new(PostgresAdapter::new(db_url).await?);

let server = Server::new(config, schema, adapter, None).await?;
server.serve().await?;

pub fn with_subscription_lifecycle( self, lifecycle: Arc<dyn SubscriptionLifecycle>, ) -> Self

Set lifecycle hooks for WebSocket subscriptions.

pub const fn with_max_subscriptions_per_connection(self, max: u32) -> Self

Set maximum subscriptions allowed per WebSocket connection.

pub fn with_pool_tuning( self, config: PoolPressureMonitorConfig, ) -> Result<Self, String>

Enable adaptive connection pool sizing.

When config.enabled is true, the server will spawn a background polling task that samples pool metrics and recommends or applies resizes.

Errors

Returns an error string if the configuration fails validation (e.g. min >= max).

impl<A: DatabaseAdapter + RelayDatabaseAdapter + Clone + Send + Sync + 'static> Server<A>

pub async fn with_relay_pagination( config: ServerConfig, schema: CompiledSchema, adapter: Arc<A>, db_pool: Option<PgPool>, ) -> Result<Self>

Create a server with relay pagination support enabled.

The adapter must implement RelayDatabaseAdapter. Currently, only PostgresAdapter and CachedDatabaseAdapter<PostgresAdapter> satisfy this bound.

Relay queries issued against a server created with Server::new return a Validation error at runtime; those issued against a server created with this constructor succeed.

Arguments

• config - Server configuration
• schema - Compiled GraphQL schema
• adapter - Database adapter (must implement RelayDatabaseAdapter)
• db_pool - Database connection pool (optional, required for observers)

Errors

Returns error if OIDC validator initialization fails.

Example

// Requires: running PostgreSQL database and compiled schema file.
let adapter = Arc::new(PostgresAdapter::new(db_url).await?);
let server = Server::with_relay_pagination(config, schema, adapter, None).await?;
server.serve().await?;

impl<A: DatabaseAdapter + Clone + Send + Sync + 'static> Server<A>

pub async fn serve(self) -> Result<()>

Start server and listen for requests.

Uses SIGUSR1-aware shutdown signal when a schema path is configured, enabling zero-downtime schema reloads via kill -USR1 <pid>.

Errors

Returns error if server fails to bind or encounters runtime errors.

pub async fn serve_with_shutdown<F>(self, shutdown: F) -> Result<()>

where F: Future<Output = ()> + Send + 'static,

Start server with a custom shutdown future.

Enables programmatic shutdown (e.g., for --watch hot-reload) by accepting any future that resolves when the server should stop.

Errors

Returns error if server fails to bind or encounters runtime errors.

pub async fn serve_on_listener<F>( self, listener: TcpListener, shutdown: F, ) -> Result<()>

where F: Future<Output = ()> + Send + 'static,

Start server on an externally created listener.

Used in tests to discover the bound port before serving. Skips TLS, Flight, and observer startup — suitable for unit/integration tests only.

Errors

Returns error if the server encounters a runtime error.

pub async fn shutdown_signal()

Listen for shutdown signals (Ctrl+C or SIGTERM)