Skip to main content

Expanding the TeaQL Ecosystem: Seamless Integration with Axum Web and Redis Distributed Cache

· 4 min read
TeaQL Team
TeaQL Team
Core Team

As the core architecture of TeaQL continues to mature, we are excited to announce two heavy-weight extension modules to the TeaQL ecosystem: the Web Module (teaql-web-integration-axum) and the Red Module (teaql-cache-integration-redis).

The addition of these two modules marks a significant milestone. TeaQL not only excels at the low-level data flow and auditing but also starts to provide out-of-the-box, exceptional experiences for developers and AI agents in top-level web request routing and distributed scaling.

1. The Web Module: Bridging the HTTP Layer and the Security Sandbox​

In traditional architectures, the web layer (controllers/routing) and the underlying business logic layer are often completely disconnected. Developers must manually extract tokens, trace IDs, and User-Agents from HTTP headers, then assemble and pass them down to the service layer.

teaql-web-integration-axum changes this completely. It seamlessly integrates the Rust community's outstanding Axum web framework with TeaQL's core security sandbox (UserContext).

Feature 1: TeaContext Extractor​

We implemented a native Axum extractor in the Web module. When a request hits your router, all critical metadata is automatically parsed from the HTTP message and encapsulated into a high-integrity, tamper-proof UserContext:

// Axum router handler
pub async fn load_tasks(ctx: TeaContext, payload: Json<TaskRequest>) -> impl IntoResponse {
    // Here, ctx has already parsed X-User-Id, X-Trace-Id, and the client's IP!
    // Directly proceed to core authorization and audit security base:
    let tasks = Q::tasks().execute_for_list(&ctx.0).await.unwrap();
    
    WebResponse::of_list(tasks)
}

Feature 2: Fully Compatible WebResponse​

During microservice evolution or frontend refactoring, API incompatibility is a major pain point. Our WebResponse struct has a built-in IntoResponse mapping mechanism for automatic status code resolution (including automatic intercepting of AxumTeaError). More importantly: its JSON serialization structure perfectly matches the previous Java Legacy API.

Whether it's a frontend application or an AI agent calling the endpoint via OpenAPI, no parser logic needs to be rewritten just because the backend transitioned to Rust.

Feature 3: Native Support for Facets (Aggregated Categorization)​

In modern e-commerce, dashboards, or complex business queries, we often need to return not just a list of items but also grouped metadata (such as status counts or temporal distributions) for rendering sidebars. In the search domain, this is referred to as Facets.

teaql-web-integration-axum provides first-class support for Facets. It accepts SmartList directly from the TeaQL Core engine (which comes with multi-dimensional facet data embedded) and formats it into the web response automatically:

// Get task list, with the engine calculating status-aggregated facets at the same time
let smart_list = Q::tasks().with_status_facets().execute_for_smart_list(&ctx).await?;

// Convert it into a standard Web API response containing both data and facets with one line of code
WebResponse::from_smart_list(smart_list)

Once the frontend receives the JSON, the data array is used to render the main list, and the facets dictionary is immediately ready to populate the sidebar filter options.

2. The Red Module: Distributed Cache with a Single Line of Code​

As concurrency increases, single-machine in-memory cache often reaches its limits. To address this, we launched the teaql-cache-integration-redis module.

The core philosophy of this module is: do not change any upper-level business code; simply replace the underlying provider to transition smoothly from single-machine to distributed caching.

It fully implements TeaQL's runtime DataStore trait. Developers and AI agents write the exact same, simple and unified syntax:

// Business code always uses this single syntax, independent of physical storage
ctx.put("daily_task_stats", stats_value, Some(3600)).await;
let stats = ctx.get("daily_task_stats").await;

At the initialization level, the architect only needs to inject the RedisDataStore:

let redis_store = RedisDataStore::new("redis://127.0.0.1:6379/0").await?;
let runtime = TeaRuntime::builder()
    .with_data_store(redis_store) // Instantly switch to distributed caching
    .build();

Summary: Moving Toward the Ultimate Agentic State​

The introduction of these two new modules is far more than just adding a couple of adapters. Their essence lies in reducing the external entropy of the system:

  • The Web module collapses raw, messy HTTP protocols into a structured UserContext.
  • The Red module abstracts complex Redis drivers into a unified DataStore interface.

When an AI agent writes business code on top of TeaQL, it only faces one clean pathway: grab the Context, access data, and return a Response. No protocol bickering, no switching between different SDKs.

TeaQL digests all the low-level heavy lifting inside the framework kernel, allowing the future of software development to truly focus on business value.