Actix Web Integration

Relevant source files

The following files were used as context for generating this wiki page:

• generator/src/templates/actix.rs
• examples/mysql/src/main.rs
• generator/src/writer.rs
• cli/src/main.rs
• generator/src/lib.rs
• generator/src/templates/actix_cargo.toml

Seaography provides native support for the Actix Web framework, allowing developers to quickly deploy GraphQL servers backed by SeaORM entities. The integration is facilitated through a template-based generation system and the async-graphql-actix-web bridge.

Introduction

The Actix Web integration within Seaography serves as a distribution layer for the dynamically generated GraphQL schema. It handles HTTP request routing, provides a GraphQL Playground for testing queries, and manages the lifecycle of the DatabaseConnection and GraphQL Schema within the Actix application state. Sources: README.md, generator/src/templates/actix.rs:13-75

Server Architecture and Initialization

The initialization process for an Actix-based Seaography server involves configuring environment variables, establishing a database connection, and building the GraphQL schema. The server utilizes lazy_static to manage configuration values such as database URLs and query limits.

Application Lifecycle

1. Environment Loading: The server loads variables from a .env file using dotenv.
2. Database Connection: A sea_orm::Database connection is established using the DATABASE_URL.
3. Schema Generation: The query_root::schema function is called to build the async_graphql::dynamic::Schema based on the database entities.
4. Server Startup: An HttpServer is instantiated, binding the schema and database to the application data.

Sources: generator/src/templates/actix.rs:43-75, examples/mysql/src/main.rs:40-70

Request Handling Flow

The following diagram illustrates how an incoming HTTP request is routed through Actix to the GraphQL executor:

The graphql_handler extracts the GraphQLRequest from the Actix payload and submits it to the async-graphql schema for execution. Sources: generator/src/templates/actix.rs:37-41, examples/mysql/src/main.rs:34-38

Core Components

API Endpoints

The Actix integration defines a unified resource path (typically /) that handles both documentation/testing and data execution based on the HTTP method.

Endpoint	Method	Function	Description
/	GET	graphql_playground	Serves the interactive GraphQL Playground HTML.
/	POST	graphql_handler	Processes GraphQL queries and mutations.

Sources: generator/src/templates/actix.rs:65-72, examples/mysql/src/main.rs:61-68

Configuration Parameters

The integration relies on specific environment variables to control server behavior and security constraints.

Variable	Default	Description
DATABASE_URL	(Required)	The connection string for MySQL, Postgres, or SQLite.
URL	localhost:8000	The address where the server is hosted.
ENDPOINT	/	The URL path for the GraphQL service.
DEPTH_LIMIT	None	Maximum allowed depth for GraphQL queries.
COMPLEXITY_LIMIT	None	Maximum allowed complexity for GraphQL queries.

Sources: generator/src/templates/actix.rs:21-35, generator/src/writer.rs:163-176

Code Generation Logic

The seaography-generator package contains the logic for creating the Actix-specific boilerplate.

Template Generation

The generate_main function in the Actix template module uses the quote! macro to produce a valid Rust main.rs file. It dynamically injects the generated crate name to link the schema defined in the project's library.
Sources: generator/src/templates/actix.rs:13-16, generator/src/lib.rs:38-42

Cargo Configuration

The generator also creates a Cargo.toml tailored for Actix Web, including necessary dependencies like async-graphql-actix-web and tracing-subscriber.

[dependencies]
actix-web = { version = "4.11" }
async-graphql-actix-web = { version = "7.0" }
sea-orm = { features = ["runtime-tokio-native-tls", "seaography"] }

Sources: generator/src/templates/actix_cargo.toml:8-17, generator/src/writer.rs:136-146

CLI Usage

To generate an Actix-based project using the CLI, the --framework flag must be set to actix.

seaography-cli -o ./output -e ./entities -u mysql://user:pass@host/db --framework actix my-project

The CLI maps the WebFrameworkEnum::Actix selection to the corresponding generator logic to write the Actix-specific main.rs. Sources: cli/src/main.rs:38-40, cli/src/main.rs:130-132

Conclusion

The Actix Web integration provides a robust, production-ready entry point for Seaography applications. By automating the boilerplate for request handling, schema execution, and playground serving, it allows developers to focus on the underlying data models and business logic while benefiting from the performance and ecosystem of the Actix framework.