Builder Context
Relevant source files
The following files were used as context for generating this wiki page:
The Builder Context (BuilderContext) serves as the central configuration hub for the Seaography framework. It defines how SeaORM entities, columns, and relationships are mapped to GraphQL types, including naming conventions, type conversions, and lifecycle hooks.
By utilizing a static context, Seaography allows developers to customize the dynamic schema generation process without requiring widespread code generation. The context is typically initialized once as a lazy_static variable and passed to the Builder to orchestrate the creation of the GraphQL Schema.
Sources: src/builder.rs:45-77, src/lib.rs:250-251, generator/src/writer.rs:75-77
Architecture and Core Role
The BuilderContext is a dependency injected into the Builder struct. It governs the behavior of various internal builders (e.g., EntityObjectBuilder, FilterInputBuilder) that process SeaORM metadata into async-graphql dynamic types.
The diagram shows how BuilderContext acts as the configuration layer for the core Builder and its specialized sub-components.
Sources: src/builder.rs:81-83, src/outputs/entity_object.rs:43-46
Configuration Components
The BuilderContext aggregates several specialized configuration structures that control different aspects of the schema generation.
Entity and Field Naming
Naming conventions for GraphQL types and fields are managed through the EntityObjectConfig. This allows for global transformation of SeaORM table and column names (e.g., converting snake_case to PascalCase or camelCase).
| Component | Purpose | Default Behavior |
|---|---|---|
type_name | Formats GraphQL Object names from table names | ToUpperCamelCase |
column_name | Formats GraphQL field names from column names | ToSnakeCase or ToLowerCamelCase based on feature flags |
basic_type_suffix | Suffix for basic (non-relational) versions of entities | "Basic" |
Sources: src/outputs/entity_object.rs:13-39
Types and Column Mapping
The TypesMapConfig (referenced within the context) handles the mapping between Rust/SeaORM types and GraphQL scalars. This includes handling for specific libraries like chrono or time.
- Timestamp Formatting: Supports toggling RFC3339 formatting for UTC and Local date-time values.
- Column Options: Allows overriding specific column behaviors, such as providing custom input/output conversion functions for complex types (e.g., JSON to custom Structs).
Sources: src/outputs/entity_object.rs:185-260, examples/sea-draw/src/schema.rs:90-112
Lifecycle Hooks and Security
The BuilderContext integrates LifecycleHooks, which provide a mechanism for implementing fine-grained authorization and data filtering during the resolution phase.
This diagram illustrates the flow where the resolver consults the hooks defined in the BuilderContext before accessing data.
Hook Interfaces
The context supports the LifecycleHooksInterface, which includes:
entity_guard: Checks if the current user has permission to perform an action (Read, Create, Update, Delete) on an entity.field_guard: Restricts access to specific fields within an entity.entity_filter: Automatically injects SeaORMConditionobjects into queries to implement row-level security (e.g., only showing records belonging to the user's project).
Sources: CHANGELOG.md:41-86, examples/sea-draw/src/schema.rs:133-162
Integration in Schema Generation
In a typical Seaography project, the BuilderContext is instantiated as a static reference and used to initialize the Builder.
// generator/src/writer.rs:75-77
lazy_static! {
static ref CONTEXT: BuilderContext = BuilderContext::default();
}
// src/builder.rs:81-83
impl Builder {
pub fn new(context: &'static BuilderContext, connection: sea_orm::DatabaseConnection) -> Self {
// ...
}
}
Depth and Complexity Limits
The Builder uses the context to enforce security constraints on incoming GraphQL queries by setting limits on:
- Query Depth: Maximum nested level of a query.
- Complexity: Maximum calculated cost of a query.
Sources: src/builder.rs:319-327, generator/src/writer.rs:100-101
Summary
The BuilderContext is the primary configuration mechanism for Seaography. It abstracts the complexity of mapping a relational database schema to a GraphQL schema by providing hooks for naming conventions, type overrides, and security logic. This architecture enables a "code-first" approach where the schema's behavior is defined through a central configuration object rather than through manual boilerplate for every entity.
Sources: src/builder.rs:45-77, src/outputs/entity_object.rs:43-52, CHANGELOG.md:144-150