web.rs

Overview

This file implements a GraphQL web server interface that serves queries against a SQLite database and integrates with an SDK client context. It provides two main GraphQL endpoints: a legacy playground (/graphql_old) and a modern GraphiQL interface (/graphql). The server is built using the Warp web framework and supports two modes controlled by a feature flag: an "extended" API mode with enhanced query capabilities, and a "standard" API mode with basic query support.

The file handles asynchronous connections to a SQLite database, GraphQL schema construction with data loaders for efficient batch loading, HTTP routing for GraphQL requests and UIs, and error recovery. It is designed for efficient operation in a multi-threaded asynchronous environment.

Functions

open_db

async fn open_db(db_path: PathBuf) -> anyhow::Result<Pool<Sqlite>>

Purpose

Attempts to asynchronously open a read-only connection pool to a SQLite database file located at db_path. It retries up to three times with a 3-second interval between attempts if the connection fails.

Parameters

• db_path: PathBuf — The file path to the SQLite database.

Returns

• anyhow::Result<Pool<Sqlite>> — On success, returns a connection pool to the SQLite database. On failure, returns an error wrapped in anyhow::Result.

Implementation Details

• Constructs a connection string that opens the database in read-only mode (?mode=ro).

• Uses a tokio::time::interval to retry connection attempts every 3 seconds.

• Logs errors on failure and aborts after 3 failed attempts.

• Uses sqlx::SqlitePool::connect for asynchronous connection pooling.

• Uses anyhow::Context to provide contextual error messages.

Usage Example

let db_path = PathBuf::from("data/mydb.sqlite");
let pool = open_db(db_path).await?;

start

pub async fn start(
    bind_to: String,
    db_path: PathBuf,
    sdk_client: Arc<ClientContext>,
) -> anyhow::Result<()>

Purpose

Starts the Warp-based HTTP server that serves the GraphQL API and UI endpoints. It binds to the specified socket address and serves GraphQL requests against the database and SDK client context.

Parameters

• bind_to: String — The socket address to bind the server to, e.g., "127.0.0.1:8080".

• db_path: PathBuf — The SQLite database file path.

• sdk_client: Arc<ClientContext> — Shared reference to an SDK client context used for queries.

Returns

• anyhow::Result<()> — Returns Ok(()) once the server has been started and runs indefinitely, or an error if startup fails.

Implementation Details

• Opens the SQLite connection pool by calling open_db.

• Parses the bind address into a SocketAddr.

• Defines two HTTP GET endpoints:

  • /graphql_old: Serves the GraphQL Playground HTML UI.

  • /graphql: Serves the GraphiQL HTML UI.

• Conditionally builds one of two GraphQL schemas based on the store_events_only feature flag:

  • If disabled (extended mode):

    • Uses graphql_ext::QueryRoot as the root query.

    • Attaches three data loaders: BlockLoader, MessageLoader, and TransactionLoader for batch loading of related entities.

    • Includes the SDK client context as shared data.

  • If enabled (standard mode):

    • Uses graphql_std::QueryRoot as the root query.

    • Does not include data loaders or SDK client context.

• Wraps the schema with Warp filters to handle GraphQL POST requests.

• Provides error recovery for bad requests and internal server errors.

• Logs the active API mode and bind address.

• Runs the Warp server asynchronously on the specified address.

Usage Example

let bind_address = "127.0.0.1:8000".to_string();
let db_path = PathBuf::from("data/mydb.sqlite");
let sdk_client = Arc::new(ClientContext::new(...));
start(bind_address, db_path, sdk_client).await?;

Important Implementation Details and Algorithms

• Database Connection Retry Logic:
  The open_db function implements a retry mechanism using tokio::time::interval to handle transient failures when opening the SQLite database. It tries three times with a delay of 3 seconds between attempts before giving up.

• GraphQL Schema Construction:
  The file conditionally builds two different GraphQL schemas (graphql_ext or graphql_std) depending on the feature flag store_events_only. This enables switching between a richer API with data loaders and a simpler standard API.

• DataLoader Usage for Efficiency:
  In extended mode, the schema is enriched with DataLoader instances for blocks, messages, and transactions. These loaders batch and cache database queries to optimize GraphQL query performance and reduce redundant calls.

• Warp Filters for Routing and Error Handling:
  The Warp filter combinators elegantly compose the HTTP routes for GraphQL queries, playground UI, and error recovery. This modular approach supports asynchronous request handling and clean error responses.

• Integration with SDK Client:
  The SDK client context (ClientContext) is passed into the GraphQL schema as shared data, allowing resolvers to invoke SDK functionality as part of query execution.

Interactions with Other Parts of the System

• GraphQL Schema Modules:
  The file references two schema modules: graphql_ext and graphql_std, representing extended and standard GraphQL APIs, respectively. These schemas define the GraphQL query roots and types used here.

• DataLoader Modules:
  It imports BlockLoader, MessageLoader, and TransactionLoader from the schema::graphql submodules for batch loading of blockchain-related data entities.

• SDK Client:
  The tvm_client::ClientContext is injected into the schema to enable GraphQL resolvers to access blockchain or SDK-related data and operations.

• Warp Web Framework:
  The file uses Warp for HTTP server functionality, filter routing, and response handling.

• SQLx Database Pool:
  The SQLite connection pool is created and managed using sqlx::SqlitePool, enabling asynchronous database access.

Visual Diagram

flowchart TD
A[Start Function] --> B[open_db]
B --> C{Feature Flag: store_events_only}
C -- false --> D[Build Extended Schema]
C -- true --> E[Build Standard Schema]
D --> F[Attach DataLoaders & SDK Client]
E --> G[Attach Pool Only]
F & G --> H[Create GraphQL POST Filter]
H --> I[Define /graphql_old Playground Endpoint]
H --> J[Define /graphql GraphiQL Endpoint]
I & J --> K[Compose Routes with Error Handling]
K --> L[Run Warp Server Bind to Address]

Summary of Components

References to Relevant Topics

• The GraphQL schema roots and data loaders are defined under the schema.graphql topic.

• Database connection pooling and SQLx usage follow patterns described in database.connection.

• Warp web server routing and filters are detailed in web.warp.

• The SDK client context and its usage can be found in sdk.client.

• Error handling patterns follow the error.handling standards.