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<CachedDatabaseAdapter<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).

Panics

Panics if the adapter Arc has been cloned before calling this constructor (refcount > 1). The builder must have exclusive ownership to unwrap the adapter for CachedDatabaseAdapter construction.

Example

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

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

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

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_tenant_executor_factory( self, factory: TenantExecutorFactory<A>, ) -> Self

Attach the per-tenant executor factory used to provision tenants at runtime (PUT /api/v1/admin/tenants/{key}).

Build it with make_executor_factory from the concrete adapter type (which must implement FromPoolConfig). When the multi-tenant runtime is enabled ([tenancy.runtime] enabled = true), build_app_state installs it into AppState. Call this before serve.

pub fn with_realtime(self, state: RealtimeState) -> Self

Attach a pre-built realtime WebSocket state to the server.

When set, build_base_router will merge realtime_router(state) at /realtime/v1. Call this after constructing the server but before calling serve or serve_with_shutdown.

pub fn with_broadcast(self, config: BroadcastConfig) -> Self

Enable ephemeral broadcast channels (POST /realtime/v1/broadcast).

pub fn with_presence(self, config: PresenceConfig) -> Self

Enable room-based presence tracking.

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).

pub fn with_social_login(self, social_login: Arc<SocialLoginState>) -> Self

Attach a unified social-login provider registry.

When set, the server mounts GET /auth/v1/authorize which redirects users to the specified OAuth provider’s authorization URL with a CSRF state token.

Example

use fraiseql_auth::social::{SocialLoginState, SocialProviderRegistry};
let state = Arc::new(SocialLoginState { ... });
let server = server.with_social_login(state);

pub fn with_anon_signup(self, state: Arc<AnonSignupState>) -> Self

Attach anonymous signup state to mount POST /auth/v1/signup.

When set, any client can obtain a guest session without credentials. The returned user_id carries an anon_ prefix and the session lasts 7 days. Signups are rate-limited per client IP.

pub fn with_mfa(self, mfa_state: Arc<MfaRouteState>) -> Self

Attach TOTP MFA state to mount the /auth/v1/mfa/ endpoints.

Mounts four routes:

• POST /auth/v1/mfa/enroll — begin enrollment, returns otpauth:// URI
• POST /auth/v1/mfa/confirm — confirm enrollment with a live TOTP code
• POST /auth/v1/mfa/challenge — issue a short-lived challenge token
• POST /auth/v1/mfa/verify — verify code and issue session
• POST /auth/v1/mfa/unenroll — remove MFA from an account

pub fn with_storage(self, backend: Arc<dyn StorageBackend>) -> Self

Attach an object storage backend and mount /storage/v1/ routes.

When set, the server mounts GET, POST, DELETE /storage/v1/object/*key and GET /storage/v1/object/sign/*key endpoints backed by the given backend.

Use StorageConfig and create_backend to construct the backend from a TOML configuration block.

pub const fn with_storage_max_upload_bytes(self, bytes: usize) -> Self

Override the maximum allowed upload size for storage endpoints.

Defaults to 100 MiB. Uploads exceeding this size are rejected with HTTP 413 before the body is forwarded to the storage backend.

pub fn with_storage_state(self, state: StorageState) -> Self

Attach a pre-built StorageState and mount the bucket-scoped /storage/v1/* routes (object upload/download/ delete, list, presign) with per-bucket access policy and RLS.

This is the full storage path (metadata-backed, bucket-aware); it differs from with_storage, which mounts the simpler legacy object router. Authentication is applied by mount_storage_state: a configured storage_token acts as an admin bearer and, when an OIDC validator is present, per-user tokens populate the request’s StorageUser for RLS.

pub fn with_revocation_manager( self, manager: Arc<TokenRevocationManager>, ) -> Self

Install a pre-built token-revocation manager, replacing whatever the generic construction path produced.

Used by the PostgreSQL runtime path to install the Postgres-backed store (#357): revocation_manager_from_schema defers the postgres backend because it needs a database connection, so main.rs builds it with build_postgres_revocation_manager and installs it here.

impl<A: DatabaseAdapter + RelayDatabaseAdapter + Clone + Send + Sync + 'static> Server<CachedDatabaseAdapter<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.

Panics

Panics if the adapter Arc has been cloned before calling this constructor (refcount > 1). The builder must have exclusive ownership to unwrap the adapter for CachedDatabaseAdapter construction.

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)