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

use fraiseql_core::runtime::subscription::{
    SubscriptionManager, SubscriptionEvent, SubscriptionId,
};
use tokio::sync::broadcast;

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

// Subscribe to events
let subscription_id = manager.subscribe(
    "OrderCreated",
    user_context,
    variables,
).await?;

// Receive events
let mut receiver = manager.receiver();
while let Ok(event) = receiver.recv().await {
    if event.matches_subscription(subscription_id) {
        // Deliver to client
    }
}

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

Modules

protocol

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.

WebhookConfig

Webhook transport adapter configuration.

WebhookPayload

Webhook payload format for event delivery.

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.