Module subscription 

Subscription runtime for event-driven GraphQL subscriptions.

FraiseQL subscriptions are compiled projections of database events, not traditional resolver-based subscriptions. Events originate from database transactions (via LISTEN/NOTIFY or CDC) and are delivered through transport adapters.

Architecture

Database Transaction (INSERT/UPDATE/DELETE)
    ↓ (commits)
LISTEN/NOTIFY (PostgreSQL)
    ↓
SubscriptionManager (event routing)
    ↓
SubscriptionMatcher (filter evaluation)
    ↓ (parallel delivery)
├─ graphql-ws Adapter (WebSocket)
├─ Webhook Adapter (HTTP POST)
└─ Kafka Adapter (event streaming)

Example

// Illustrative — subscription infrastructure requires a live schema + transport.
// Use SubscriptionManager::new(Arc::new(schema)) for the full API.

// Create subscription manager
let manager = SubscriptionManager::new(Arc::new(schema));

// Subscribe to events (synchronous, not async)
let subscription_id = manager.subscribe(
    "OrderCreated",
    user_context_json,
    variables_json,
    "connection-id",
)?;

// Receive events via broadcast channel
let mut receiver = manager.receiver();
while let Ok(payload) = receiver.recv().await {
    if payload.subscription_id == subscription_id {
        // Deliver to client
    }
}

// Unsubscribe (synchronous)
manager.unsubscribe(subscription_id)?;

Modules

protocol

GraphQL over WebSocket subscription protocol types.

Structs

ActiveSubscription

A client’s active subscription.

DeliveryResult

Result of delivering an event to multiple transports.

KafkaAdapter

Kafka transport adapter stub (without kafka feature).

KafkaConfig

Kafka transport adapter configuration.

KafkaMessage

Kafka message format for event delivery.

SubscriptionEvent

An event from the database that may trigger subscriptions.

SubscriptionId

Unique identifier for a subscription instance.

SubscriptionManager

Manages active subscriptions and event routing.

SubscriptionPayload

Delivery payload sent to transport adapters.

TransportManager

Multi-transport delivery manager.

WebhookAdapter

Webhook transport adapter for HTTP POST delivery.

WebhookPayload

Webhook payload format for event delivery.

WebhookTransportConfig

Webhook transport adapter configuration.

Enums

SubscriptionError

Errors that can occur during subscription operations.

SubscriptionOperation

Database operation that triggered the event.

Traits

TransportAdapter

Transport adapter trait for delivering subscription events.

Functions

extract_rls_conditions

Extract (field, value) equality conditions from an RLS WhereClause.

Type Aliases

BoxDynTransportAdapter

Type alias for boxed dynamic transport adapter.

WebhookConfig

Backward-compatible type alias — use WebhookTransportConfig in new code.