Crate axa 

Axa

Accessories library for Axum websites, databases, microservices, and more.

This is a library, not a framework. A service’s main.rs stays ordinary Axum and calls into this crate: there are no lifecycle hooks or macros, and AppContext is a plain struct passed as ordinary Axum state. Every piece can be read, replaced, or left out on its own.

Example

Declare routes, turn them into a plain axum::Router under the standard middleware, and serve it:

use axa::prelude::*;
use axa::config::{Config, Defaults};
use axa::Environment;

async fn hello() -> Result<Response> {
    format::json(serde_json::json!({ "hello": "world" }))
}

let environment = Environment::Test;
let config = Config::from_lookup(
    &environment,
    &Defaults { database: "", ..Defaults::default() },
    |_| None,
)?;
let ctx = AppContext::new(environment, (), config);
let router = AppRoutes::with_default_routes()
    .add_route(Routes::new().prefix("/api").add("/hello", get(hello)))
    .into_app(ctx)?;

Features

Feature	Adds
queue	The Postgres job queue in queue
postgres-seaorm	A SeaORM-backed AppContext on Postgres, with axa-postgres-seaorm as axa::postgres_seaorm
redis	A Redis cache with mandatory expiry, as axa::redis
postgres-diesel	Diesel on Postgres in pure Rust, as axa::postgres_diesel
postgres-toasty	Toasty on Postgres, as axa::postgres_toasty
tera	Tera templates with safe escaping, as axa::tera
maud	Maud compile-time templates with safe escaping, as axa::maud
tracing	Redaction, request tracking, and asynchronous diagnostics, as axa::tracing
session	Web sessions with safe defaults, as axa::session
postgres-sqlx	sqlx on Postgres: pooling, migrations, and test resets, as axa::postgres_sqlx
idempotency	Idempotency-Key handling over Postgres, as axa::idempotency
openapi	OpenAPI documents, a pinned Swagger UI, and drift checks, as axa::openapi
opentelemetry	OTLP export of traces and request metrics, as axa::opentelemetry
outbox	A transactional outbox and relay on Postgres that keeps a record, as axa::outbox
outbox-encryption	outbox, with payloads sealed at rest under the service’s keys
cursor-pagination	Signed cursor pages with no total, and LIKE escaping, as axa::cursor_pagination
keycloak	Keycloak bearer authentication and ABAC enforcement, as axa::keycloak
paseto	PASETO bearer authentication and ABAC enforcement, as axa::paseto
problem	Nothing: RFC 9457 problem details are always axa::problem, as Error answers with them
prometheus	Prometheus text exposition, as axa::prometheus
ratelimit	In-process request limits and failed-login lockout, as axa::ratelimit
versioning	Accepts-version negotiation, as axa::versioning

Origin

The behaviours here are the ones the Main X Index services relied on in Loco. They were written afresh rather than copied, so this crate can keep its own licence terms.

Re-exports

pub use context::AppContext;

pub use error::Error;

pub use error::Result;

pub use axa_accepts_version_negotiation as versioning;

pub use axa_cursor_pagination as cursor_pagination;

pub use axa_environment as environment;

pub use axa_idempotency_key as idempotency;

pub use axa_keycloak_auth as keycloak;

pub use axa_maud_templates as maud;

pub use axa_mysql_diesel as mysql_diesel;

pub use axa_mysql_seaorm as mysql_seaorm;

pub use axa_mysql_sqlx as mysql_sqlx;

pub use axa_mysql_toasty as mysql_toasty;

pub use axa_openapi_docs as openapi;

pub use axa_opentelemetry as opentelemetry;

pub use axa_paseto_auth as paseto;

pub use axa_postgres_diesel as postgres_diesel;

pub use axa_postgres_seaorm as postgres_seaorm;

pub use axa_postgres_sqlx as postgres_sqlx;

pub use axa_postgres_toasty as postgres_toasty;

pub use axa_problem as problem;

pub use axa_prometheus_metrics as prometheus;

pub use axa_redis_cache as redis;

pub use axa_request_rate_limit as ratelimit;

pub use axa_tera_templates as tera;

pub use axa_tracing as tracing;

pub use axa_transactional_outbox as outbox;

pub use axa_web_session as session;

Modules

boot

What a service exposes so tests can boot it.

cli

The command line every service shares.

client

The address of the client behind a request.

conditional

Conditional requests: ETag, If-None-Match, and If-Match, as RFC 9110 has them.

config

Service configuration, from the process environment.

context

The state every handler receives.

db

Database connections from configuration, for whichever database feature is on.

error

The error type handlers return, and its HTTP mapping.

extract

Extractors that answer a bad request as every other error is answered.

format

Small response helpers for handlers that return Result<Response>.

health

The three health routes, one for each of the probes Kubernetes gives a container:

logger

Logging setup over tracing-subscriber.

middleware

The standard middleware stack.

model

Model-layer errors, the same for every database.

prelude

Common imports for handlers.

query

A small condition builder.

queue

The Postgres job queue, from axa_postgres_job_queue, with BackgroundWorker jobs.

routes

Route tables that become an ordinary Axum Router.

schema

Migration helpers over sea-orm-migration.

server

Serving a router until the process is asked to stop.

store

A small type-keyed store for values shared across handlers.

task

Named command-line tasks.

validation

Model validation, the same for every database, with the shape of Loco’s.

worker

Background jobs.

Enums

Environment

The environment, taken from APP_ENV.