GraphQL Subscriptions
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
GraphQL Subscriptions in Seaography provide a mechanism for real-time data streaming between the server and clients. While Seaography primarily focuses on bridging SeaORM and async-graphql for queries and mutations, it also supports the definition and registration of custom subscription fields to handle event-driven updates.
The framework utilizes a dynamic schema engine, allowing developers to extend the base schema with subscription capabilities without the overhead of static code generation. This enables real-time features such as live updates for database entities or project-specific events within the GraphQL API.
Sources: src/lib.rs:18-24, CHANGELOG.md:129-130
Architecture and Configuration
The subscription system is integrated into the Builder pattern used by Seaography to construct the GraphQL schema. Developers can add subscription fields to the schema builder before finishing it.
Schema Registration
The Builder struct contains a subscriptions field, which is a vector of async_graphql::dynamic::SubscriptionField. This allows for the registration of multiple custom subscription streams.
The diagram shows how the Builder aggregates subscription fields before they are finalized into the GraphQL schema.
Sources: examples/sea-draw/src/schema.rs:293-295, generator/src/writer.rs:125-127
Component Summary
| Component | Description |
|---|---|
Builder | The main orchestrator for assembling the dynamic GraphQL schema. |
BuilderContext | Stores configuration and global state used during schema construction. |
SubscriptionField | A dynamic field definition from async-graphql representing a subscription endpoint. |
register_entity | Macro or function used to prepare entities; subscriptions are usually added manually to the builder. |
Sources: src/lib.rs:253-256, examples/sea-draw/src/schema.rs:293-295
Implementing Subscriptions
Subscriptions are typically implemented by defining a function that returns a collection of SubscriptionField objects. These fields define the resolver logic, which usually involves a stream of data.
Data Flow
The data flow for a subscription involves a client establishing a persistent connection (often via WebSockets) and receiving a stream of events.
The sequence diagram illustrates the lifecycle of a subscription, from initial request to the continuous delivery of event data.
Sources: examples/sea-draw/src/subscriptions.rs:1-10, CHANGELOG.md:129-130
Example: Custom Subscription Registration
In the schema definition, the subscriptions are extended on the builder instance.
builder
.subscriptions
.extend(subscriptions::subscriptions(&CONTEXT));
Sources: examples/sea-draw/src/schema.rs:293-295
Technical Details
Key Functions and Structures
Builder::new: Initializes the schema builder with a database connection and context.builder.subscriptions.extend(): The primary method for injecting custom subscription logic into the Seaography-managed schema.async_graphql::dynamic::SubscriptionField: The underlying type used to represent a subscription in the dynamic schema.
Sources: generator/src/writer.rs:109-120, examples/sea-draw/src/schema.rs:293-295
Conclusion
GraphQL Subscriptions in Seaography allow the framework to go beyond static database mapping and provide real-time interactivity. By leveraging the dynamic nature of async-graphql, Seaography maintains its performance benefits while offering a flexible way to integrate event-driven architecture directly into the generated GraphQL API.
Sources: src/lib.rs:18-24, CHANGELOG.md:129-130