Crate autumn_web

Expand description

§Autumn

An opinionated, convention-over-configuration web framework for Rust.

Autumn assembles proven Rust crates (Axum, Maud, Diesel, htmx, Tailwind) into a Spring Boot-style developer experience with proc-macro-driven conventions and customization options at every level.

§Quick start

use autumn_web::prelude::*;

#[get("/")]
async fn index() -> Markup {
    html! { h1 { "Hello, Autumn!" } }
}

#[autumn_web::main]
async fn main() {
    autumn_web::app()
        .routes(routes![index])
        .run()
        .await;
}

§Architecture overview

Layer	Crate	Purpose
HTTP server	Axum	Routing, extractors, middleware
HTML templates	Maud	Type-safe, compiled HTML via `html!` macro
Database	Diesel	Async Postgres via `diesel-async` + deadpool
Client interactivity	htmx	Embedded JS served from same-origin `/static/js/` routes
Styling	Tailwind CSS	Downloaded + managed by `autumn-cli`

§Modules

app – Application builder for configuring and launching the server.
config – Layered configuration: defaults, autumn.toml, env overrides.
db – Database connection pool and the Db request extractor.
error – Framework error type (AutumnError) and result alias.
extract – Re-exported Axum extractors (Form, Json, Path, Query, and optional multipart support).
health – Compatibility alias for readiness plus legacy health helpers.
metrics – One-line app-defined counters, gauges, and timers, exposed automatically on /actuator/prometheus and /actuator/metrics.
middleware – Built-in middleware (request IDs).
pagination – Standardized page/size extractor and response wrapper.
prelude – Glob import for the most common types.

§Zero-config defaults

An Autumn app runs out of the box with no configuration file. Every setting has a sensible default (port 3000, info log level, etc.). Override via autumn.toml or AUTUMN_* environment variables. See config::AutumnConfig for the full list.

Re-exports§

pub use channels::Broadcast;
pub use channels::BroadcastError;
pub use channels::BroadcastPayload;
pub use channels::ChannelBackendConfigError;
pub use channels::ChannelMessage;
pub use channels::ChannelPublishError;
pub use channels::ChannelStats;
pub use channels::Channels;
pub use channels::ChannelsBackend;
pub use channels::LocalChannelsBackend;
pub use edge_support::CacheEdgeKv;
pub use plugin::Plugin;
pub use plugin::Plugins;
pub use repository::RepositoryError;
pub use ledger::LedgerAsOf;
pub use ledger::LedgerBreak;
pub use ledger::LedgerBreakReport;
pub use ledger::LedgerDiff;
pub use ledger::LedgerError;
pub use ledger::LedgerHead;
pub use ledger::LedgerHighWater;
pub use ledger::LedgerPin;
pub use ledger::LedgerRevision;
pub use ledger::LedgerVerification;
pub use ledger::LedgeredRecord;
pub use version_history::ColumnChange;
pub use version_history::VersionEntry;
pub use version_history::VersionFilter;
pub use version_history::VersionOp;
pub use version_history::VersionPage;
pub use version_history::VersionedRecord;
pub use version_history::compute_delete_changes;
pub use version_history::compute_delete_changes_owned;
pub use version_history::compute_diff;
pub use version_history::compute_diff_owned;
pub use version_history::compute_insert_changes;
pub use version_history::compute_insert_changes_owned;
pub use hooks::DraftField;
pub use hooks::FieldDiff;
pub use hooks::MutationContext;
pub use hooks::MutationHooks;
pub use hooks::MutationOp;
pub use hooks::NoHooks;
pub use hooks::Patch;
pub use hooks::UpdateDraft;
pub use http_client as http;
pub use paths::PathExt;
pub use admission::Criticality;
pub use seo::SeoRouteDefaults;
pub use slug::contains_letter_or_number;
pub use slug::slugify;
pub use form::Changeset;
pub use form::ChangesetForm;
pub use form::IntoChangeset;
pub use nested_form::InputsForOptions;
pub use nested_form::RowScope;
pub use nested_form::inputs_for;
pub use nested_form::nested_row_fragment;
pub use nested_form::NestedChangeset;
pub use nested_form::NestedChangesetForm;
pub use nested_form::NestedChild;
pub use nested_form::NestedRow;
pub use nested_form::decode_nested_urlencoded;
pub use app::app;
pub use app::ApiVersion;
pub use app::RegisteredApiVersions;
pub use db::Db;
pub use db::IsolationLevel;
pub use db::TxOptions;
pub use db::savepoint;
pub use db::LazyDb;
pub use db::RuntimeConnection;
pub use db::RuntimeBackend;
pub use error::AutumnError;
pub use error::AutumnResult;
pub use tenant_cell::QuotaExceeded;
pub use tenant_cell::TenantAllocationError;
pub use tenant_cell::TenantArena;
pub use tenant_cell::TenantBytes;
pub use tenant_cell::TenantCell;
pub use tenant_cell::TenantCellHandle;
pub use tenant_cell::TenantCellRegistry;
pub use tenant_cell::TenantString;
pub use pagination::Page;
pub use pagination::PageRequest;
pub use pagination::ListQuery;
pub use pagination::SortDir;
pub use pagination::CursorPage;
pub use preload::NotLoaded;
pub use preload::Preloaded;
pub use pagination::CursorRequest;
pub use validation::Valid;
pub use validation::Validated;
pub use htmx::AUTUMN_WIDGETS_JS_PATH;
pub use htmx::HTMX_CSRF_JS_PATH;
pub use htmx::HTMX_JS;
pub use htmx::HTMX_JS_PATH;
pub use htmx::HTMX_SSE_JS;
pub use htmx::HTMX_SSE_JS_PATH;
pub use htmx::HTMX_VERSION;
pub use htmx::IDIOMORPH_JS;
pub use htmx::IDIOMORPH_JS_PATH;
pub use htmx::HtmxFragments;
pub use htmx::OobSwap;
pub use live::LiveFragment;
pub use mail::Mail;
pub use mail::MailAttachment;
pub use mail::MailConfig;
pub use mail::MailDeliveryQueue;
pub use mail::MailDeliveryQueueHandle;
pub use mail::MailError;
pub use mail::MailTransport;
pub use mail::Mailer;
pub use mail::SmtpConfig;
pub use mail::TlsMode;
pub use mail::Transport;
pub use validation::ValidateExt;
pub use auth::ApiToken;
pub use auth::RequireApiToken;
pub use auth::ApiTokenScopes;
pub use auth::IssueTokenSpec;
pub use auth::TokenMetadata;
pub use auth::VerifiedToken;
pub use auth::issue_scoped_api_token;
pub use auth::list_api_tokens;
pub use auth::rotate_api_token;
pub use auth::DbApiTokenStore;
pub use auth::API_TOKEN_MIGRATIONS;
pub use crate::extract::Json;
pub use crate::extract::Csv;
pub use crate::extract::Path;
pub use crate::extract::Form;
pub use crate::extract::Query;
pub use crate::extract::ClientAddr;
pub use crate::extract::ClientHost;
pub use crate::extract::ClientScheme;
pub use config::ProcessRole;
pub use autumn_edge as edge;

Modules§

a11y: Typed accessible UI primitives (issue #1706).
actuator: Actuator endpoints for operational observability.
admission: Adaptive admission control (issue #3068, ADR 0016).
aeo: Agent readiness (AEO) by default.
agent_authority: The build-time agent authority envelope (issue #1691).
aggregate: Typed grouped aggregate queries (GROUP BY roll-ups), issue #1364.
alerts: Operator alerts for built-in failure conditions.
app: Application builder – the entry point for configuring and running an Autumn server.
assets: Fingerprinted asset pipeline for cache-busted static file delivery.
audit: Structured audit logging with pluggable sinks.
auth: Authentication utilities for Autumn applications.
authorization: Policy-based record-level authorization.
backoff: Capped exponential backoff with full jitter (issue #3054).
batches: Bounded-memory, keyset-based iteration over an entire table.
browser_detect: Locating a usable Chromium/Chrome binary on the host.
build_info: Compile-time build and git provenance for /actuator/info.
bulkhead: Per-tenant bulkheads and shuffle sharding (issue #3072).
cache: Caching infrastructure for the Autumn framework.
canary: Canary deploy primitives: deploy-version labelling and rollback signalling.
capacity: Per-deploy capacity contract — the capacity.lock artifact (issue #1733).
capsule: Deterministic replay capsules: record a failing request (redacted request, clock reads, database traffic, outcome) and replay it offline.
cell_router: A thin router for a cell deployment (issue #3072).
channels: Named broadcast channel registry for real-time messaging.
circuit_breaker
classify: Compile-time data classification (issue #1654).
cluster: Embedded, zero-dependency self-clustering control plane (issue #1762).
commentable: Threaded, polymorphic comments (issue #1367).
confidential: Operator-blind confidential fields (issue #1771).
config: Framework configuration with sensible defaults and profile-based layering.
consent: Cookie-consent tracking and gating (ePrivacy / GDPR Art. 7).
constela: Parse, validate and render Constela documents — the constrained JSON UI language — so an Autumn app can serve an interface a language model wrote.
cost: Per-request cost records and a live cost signal (issue #1720).
credentials: Encrypted credentials store for production secrets.
current: Request-scoped current actor — batteries-included “who did this” scope.
custom_domain: Tenant custom domains with per-domain certificates (issue #1635).
data: Data import/export utilities.
data_retention: Unified data-retention policy for framework-owned data (issue #1605).
db: Database connection pool and extractor.
deadline: Request deadlines (issue #3058).
derivation: Maintained derived read models: #[derivation] (#1769). Maintained derived read models: #[derivation] (issue #1769).
dotenv: Auto-loading of a project-root .env file in local development.
download: Typed file downloads as an IntoResponse.
edge_support: Origin-side glue between an Autumn app and the edge capsule (issue #1790).
encryption: At-rest attribute encryption for #[repository]/#[model] columns.
entropy: Deterministic, injectable randomness (entropy).
error: Framework error type and result alias.
error_pages: Styled error pages and dev-mode error badge overlay.
etag: ETag-based conditional GET helpers for HTML and JSON handlers.
events: Typed domain event bus with decoupled, durable listeners.
experiments: A/B experiments with deterministic bucketing and exposure telemetry.
extract: Autumn’s request extractors.
fake: Deterministic fake-data generation backing factory .fake() support. Deterministic fake-data generation.
fault_injection: Opt-in fault injection for a staging environment (issue #3071).
feature_flags: First-class feature flags with per-actor rollouts and kill switches.
feed: Atom and RSS 2.0 feed rendering for content apps.
flash: Flash messages for Autumn applications.
fleet_layout: On-disk layout of a SQLite database fleet: one database file per tenant, or one per routing slot (ADR 0019).
form: Changeset-style form helpers with validation and Maud rendering.
format: View-layer value formatting helpers (currency, delimited numbers, pluralize, truncate, relative/absolute dates) for Maud templates.
gdpr: GDPR/CCPA data-export and account-erasure registry.
graph: The compile-time application architecture graph (issue #1747).
health: Compatibility health endpoint.
hooks: Mutation hook types for repository lifecycle callbacks.
htmx: Embedded htmx JavaScript.
http_client: Traced outbound HTTP client with retries and test mocks.
http_server: HTTP serve loop with connection limits (issue #3065).
i18n: Locale-aware text resolution (opt-in via the i18n feature flag).
idempotency
include_dir: Re-export of the include_dir crate.
inspector: Dev-mode request inspector with N+1 query detection.
interceptor: “Around” hooks for the pipelines a tower layer cannot reach.
job: On-demand background job infrastructure.
job_tracking: Tracked job handles: unguessable-token status polling for #[job].
ledger: Bitemporal, tamper-evident record ledger for #[repository] writes.
links: Safe, method-aware link helpers: links::link_to anchors and links::button_to CSRF-protected action buttons. link_to / button_to — safe, method-aware link helpers (issue #1138).
live: Declarative live-broadcast trait for #[repository(Model, broadcasts = "topic")].
lock: Named, cluster-wide distributed locks backed by PostgreSQL advisory locks.
log
mail: Transactional email support.
maintenance: Maintenance mode state and file-flag coordinator.
markdown: First-class Markdown rendering with frontmatter parsing and SSG integration.
mcp: Project typed JSON endpoints as Model Context Protocol (MCP) tools so AI agents can call the real, authenticated handler pipeline.
metrics: One-line call-site facade for app-defined counters, gauges, and timers.
middleware: Built-in middleware for Autumn applications.
migrate: Database migration support.
money: Typed money and an embedded double-entry ledger (issue #1837).
negotiate: Content-negotiated success responder (Negotiate / Negotiated / Format). Content-negotiated success responder.
nested_form: Nested (has_many) form binding — a parent struct plus one child collection, decoded and validated in a single extractor.
normalize: Field normalization primitives (issue #1379).
notifications: First-class in-app notification store with a read/unread feed (issue #1148).
openapi: OpenAPI (Swagger) specification auto-generation.
outbox: Transactional outbox and inbox (issue #3062).
pagination: Standardized pagination primitives.
paths: Typed path helpers and the PathExt fluent query-string builder.
payload_version: Opt-in schema-version envelope for persisted job payloads (issue #1205).
pdf: Render server-side templates to downloadable PDF documents.
plugin: Plugin trait for composable Autumn integrations.
plugin_conformance: Plugin conformance checks for Autumn plugin authors.
plugin_contract: The versioned plugin API stability contract (issue #1601).
plugin_sandbox: Capability-sandboxed WASM plugins (issue #1609).
preload: Eager-loading (preload) runtime for #[model] associations.
prelude: Convenience re-exports for Autumn applications.
probe: Liveness, readiness, and startup probes.
push: Web Push: deliver a notification to a subscribed browser even when the app’s tab is closed (issue #1392).
query_budget: Compile-time per-route database query budgets (#1667).
query_string: Structured query-string decoding for Query<T> (issue #1972).
range: HTTP Range request support (RFC 7233) for in-memory and streamed bodies.
read_your_writes: Read-your-own-writes routing support.
redis_health: Redis PING health indicator (issue #3059). Redis health indicator: a PING with a time limit (issue #3059).
redis_tls: Process-wide rustls CryptoProvider guard for TLS Redis (rediss://) URLs — see redis_tls::open_client (issue #2172). Process-wide rustls CryptoProvider guard for TLS Redis URLs.
reexports: Re-exports of upstream crates used in macro-generated code.
repl: Interactive Rhai prompt for autumn console --repl (issue #2148).
replication: Continuous SQLite replication with point-in-time restore (issue #1628). Continuous SQLite replication with point-in-time restore (issue #1628).
reporting: Pluggable error reporting: catch handler panics and route panics + 5xx responses to configured ErrorReporters.
repository: Repository support types for framework-generated CRUD operations.
retention: Declarative data-retention sweeps (issue #1342).
route_listing: Route listing types and collection logic for autumn routes.
runtime_config: Runtime configuration store for live-tunable typed values.
scheduler: Scheduled-task coordination backends.
search: Engine-agnostic search vocabulary.
security: Spring Security-style protection for Autumn applications.
seed: Seed context for populating databases with representative data.
seo: First-class SEO toolkit: sitemap.xml, robots.txt, and meta tag helpers.
session: Cookie-based session management for Autumn applications.
shadow: Live-traffic shadow mirroring and response diffing.
sharding: Horizontal database sharding.
sigv4: AWS Signature Version 4 request signing, shared by the replication and offsite-backup S3 clients (issues #1628 / #1619). AWS Signature Version 4 request signing.
sim: Deterministic simulation testing (sim-testing, issue #1797).
sla: Calendar-aware SLA obligations (issue #1826).
slo: Service level objectives declared in autumn.toml (issue #3069).
slug: URL-safe slug generation (slugify).
sse: Server-Sent Events (SSE) support for Autumn applications.
static_gen: Static site generation support. Static Site Generation (SSG) and Incremental Static Regeneration (ISR).
step_up: Step-up authentication (“sudo mode”) for sensitive operations.
storage: Pluggable file storage backends for Autumn applications.
stories: Widget story gallery (issue #1526).
sync: Offline-first local SQLite store and background sync engine for occasionally-connected apps (e.g. Tauri mobile).
system_info: System information plugin.
task: Scheduled task infrastructure.
telemetry: Telemetry runtime planning and subscriber initialization.
tenancy
tenant_cell: Per-tenant in-process memory accounting cells.
test: First-party integration-testing utilities for Autumn applications.
time: Deterministic, injectable wall-clock time.
time_zone: Per-user time zone resolution and locale-aware date/time rendering.
tls: Inbound (server-side) TLS support (issues #1603 and #1640).
ui: Shared UI primitives for framework-owned HTML surfaces.
upgrade: In-place upgrades: swap a running app to a new binary without dropping connections or in-memory state (#1674).
user_agent: Lightweight User-Agent parsing for login-session device attribution.
validation: Validation support via the validator crate.
version_history: Automatic record version history for #[repository] writes.
webhook: Signed webhook intake for third-party callbacks.
webhook_outbound: Outbound signed webhook delivery with retries, DLQ, and subscription management.
widgets: Active search and autocomplete form primitives with htmx integration.
wire: Build-checked typed contracts between two Autumn services (issue #1755).
wizard: First-class multi-step form wizards with session-backed state and per-step validation.
ws: WebSocket support for Autumn applications.

Macros§

add_blob_column: Build the (up, down) SQL pair to add or drop a Blob column on an existing Postgres table.
always: Assert a hard invariant that must hold at this point in the simulation.
authority_grant: Declare a named authority envelope and register it in the agent-authority manifest.
backend_select: Compile-time backend block selector for generated #[repository]/#[model] CRUD.
declare_cached_read: Register a cached read the proc macros cannot see.
declassify: Declare a declassification boundary and register it in the data-flow manifest.
edge_routes: Collect #[edge] handlers into a Vec<EdgeRoute> (#1790).
embed_locales: Embed the app’s i18n locale bundles (the i18n/ directory, or a custom directory) into the binary at compile time.
embed_static: Embed the app’s static/ directory (including the .autumn-manifest.json written by autumn build --embed) into the binary at compile time.
html: Type-safe HTML templating macro.
impl_preloadable_leaf: Implement Preloadable for a hand-written model as a leaf association target.
jobs: Collect #[job] handlers into a Vec<JobInfo>. Collect #[job] handlers into a Vec<JobInfo>.
listeners: Collect #[listener] handlers into a Vec<events::ListenerInfo>. Collect #[listener] handlers into a Vec<ListenerInfo>.
mail_previews: Collect mailer preview registrations into an AppBuilder. Collect #[mailer_preview] impl blocks into runtime preview registrations.
maybe_for_update: Backend-portable FOR UPDATE seam for generated #[repository] CRUD.
one_off_tasks: Collect #[task] handlers into a Vec<task::OneOffTaskInfo>. Collect #[task] handlers into a Vec<OneOffTaskInfo>.
paths: Emit a pub mod paths { … } re-exporting typed path helpers.
plugin_assets: Embed a plugin crate’s asset directory as a fingerprinted PluginAssets bundle.
routes: Collect route-annotated handlers into a Vec<Route>.
sometimes: Record a reachability target — an interesting state the simulation should sometimes reach across seeds.
state_migration: Declare a total migration from an older live-state shape to the current one, checked by the compiler.
static_params: Convenience macro for building a StaticParams map.
static_routes: Collect #[static_get] handlers into a Vec<StaticRouteMeta>. Collect #[static_get] handlers into a Vec<StaticRouteMeta>.
story: Author a widget story for the /_stories gallery: story!{ "Group", "Name", { ... } }.
t: Translation lookup macro with compile-time key validation.
tasks: Collect #[scheduled] task handlers into a Vec<TaskInfo>. Collect #[scheduled] task handlers into a Vec<TaskInfo>.
wire_client: Generate a typed client for another Autumn service’s endpoints (issue #1755).

Structs§

AppState: Shared application state passed to all route handlers.
PreEscaped: Wrap a pre-escaped string so Maud renders it verbatim.
Redirect: HTTP redirect response.
RepositoryApiMeta: Metadata attached to routes emitted by the #[repository(api = ...)] macro.
Route: A single route binding an HTTP method + path to an Axum handler.
RouteVersionMetadata: Metadata carrying API version, sunset opt-out, and security configuration for a route.
State: State extractor. Re-exported from Axum. Extractor for state.
TransitionEffect: Context payload delivered to an on_commit transition-effect job (issue #1973).

Enums§

RouteIdempotency: Declares how the app-level idempotency layer should replay cached responses for this route.
RouteTimeout: Per-route override for the global inbound request timeout ([server.timeouts] request_timeout_ms).
RouterBuildError: The refusal AppBuilder::plugin_route_infos and route_listing::collect_route_infos return.

Traits§

Lifecycle: Marker trait implemented by every #[lifecycle] enum, exposing that lifecycle’s transition edges as a string-keyed table.

Type Aliases§

Markup: Rendered HTML fragment produced by the html! macro.

Attribute Macros§

agent_operable: Declare what an agent-operable handler is allowed to do, and check it.
api_doc: Enrich a route handler’s auto-generated OpenAPI documentation.
authorize: Enforce a record-level Policy before a handler runs. Coexists with secured: #[secured] answers “are you in?”, #[authorize] answers “are you allowed to act on this record?”
cached: Cache the return value of a function based on its arguments.
cached_impl: Scope every #[cached] method of an impl block by its type.
contract_checked: Check every service call in a function against the callee’s contract (issue #1755).
delete: Annotate an async function as a DELETE route handler.
edge: Mark a read-path GET route as eligible for the edge capsule (#1790).
endpoint: Mark a typed handler as a service endpoint (issue #1755).
event: Declare a typed domain event. See events module. Declare a typed domain event.
feature_flag: Gate a route handler on a named feature flag. If the flag is disabled for the current actor the handler responds with 404 Not Found (default) or delegates to a custom fallback specified with fallback = my_fn.
get: Annotate an async function as a GET route handler.
job: Declare an on-demand background job. See job module. Declare an on-demand background job.
lifecycle: Turn a plain state enum into a statically-verified lifecycle.
listener: Declare an event listener. See events module. Declare an event listener that reacts to a typed #[event].
mailer: Generate ergonomic send_* and deliver_later_* helpers for mailer impls. Generate send_* and deliver_later_* helpers for a mailer impl block.
mailer_preview: Register zero-argument mail template previews for the dev mail UI. Register zero-argument mail preview methods for the dev mail preview UI.
main: Set up the Tokio async runtime for an Autumn application.
model: Derive Diesel and Serde traits for a database model struct.
oauth2_callback: Annotate an OAuth2/OIDC callback handler.
obligation: Declare a business-time obligation on a struct (issue #1826).
patch: Annotate an async function as a PATCH route handler.
post: Annotate an async function as a POST route handler.
public: Declare a route handler as deliberately public (unauthenticated).
put: Annotate an async function as a PUT route handler.
query_budget: Bound a handler’s database query count at compile time.
repository: Derive a repository with CRUD operations and derived queries.
scheduled: Declare a scheduled background task. See task module. Declare a scheduled background task.
secured: Secure a route handler with authentication and optional role checks.
service: Define a service for cross-model orchestration and non-DB side effects.
sim_test: Annotate an async function as a deterministic simulation test (S-1797).
static_get: Annotate an async function as a statically pre-rendered GET route.
step_up: Require fresh (“step-up”) authentication before a route handler runs.
task: Declare a one-off operational task. See task::OneOffTaskInfo. Declare a one-off operational task runnable with autumn task <name>.
throttle: Apply a per-route rate limit that composes with the global limiter.
ws: Annotate an async function as a WebSocket route handler.

Derive Macros§

WireShape: Derive a type’s serde-visible wire shape (issue #1755).

Crate autumn_web

Crate autumn_web Copy item path

§Autumn

§Quick start

§Architecture overview

§Modules

§Zero-config defaults

Re-exports§

Modules§

Macros§

Structs§

Enums§

Traits§

Type Aliases§

Attribute Macros§

Derive Macros§

Crate autumn_web