acton_htmx/
lib.rs

1//! acton-htmx: Opinionated Rust web framework for HTMX applications
2//!
3//! This framework builds on battle-tested components from the Acton ecosystem:
4//! - **acton-service**: Configuration, observability, middleware, connection pools
5//! - **acton-reactive**: Actor-based background jobs, sessions, and real-time features
6//!
7//! # Design Principles
8//!
9//! 1. **Convention Over Configuration**: Smart defaults everywhere
10//! 2. **Security by Default**: CSRF, secure sessions, security headers enabled
11//! 3. **HTMX-First Architecture**: Response helpers and patterns for hypermedia
12//! 4. **Type Safety Without Ceremony**: Compile-time guarantees via Rust's type system
13//! 5. **Idiomatic Excellence**: Generated code exemplifies Rust best practices
14//!
15//! # Quick Start
16//!
17//! ```rust,no_run
18//! use acton_htmx::prelude::*;
19//! use acton_reactive::prelude::ActonApp;
20//!
21//! #[tokio::main]
22//! async fn main() -> anyhow::Result<()> {
23//!     // Launch the Acton runtime
24//!     let mut runtime = ActonApp::launch();
25//!
26//!     // Initialize application state (spawns session manager agent)
27//!     let state = ActonHtmxState::new(&mut runtime).await?;
28//!
29//!     // Build router with HTMX handlers and session middleware
30//!     let app = axum::Router::new()
31//!         .route("/", axum::routing::get(index))
32//!         .layer(SessionLayer::new(&state))
33//!         .with_state(state);
34//!
35//!     // Start server
36//!     let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await?;
37//!     axum::serve(listener, app).await?;
38//!
39//!     // Shutdown the agent runtime
40//!     runtime.shutdown_all().await?;
41//!
42//!     Ok(())
43//! }
44//!
45//! async fn index() -> &'static str {
46//!     "Hello, HTMX!"
47//! }
48//! ```
49//!
50//! # Features
51//!
52//! - `postgres` - `PostgreSQL` database support (default)
53//! - `sqlite` - `SQLite` database support
54//! - `mysql` - `MySQL` database support
55//! - `redis` - Redis session and cache support (default)
56//! - `otel-metrics` - OpenTelemetry metrics collection
57//!
58//! # Architecture
59//!
60//! See the [architecture overview](../../../.claude/architecture-overview.md) for details.
61
62// Lint configuration is handled at the workspace level in Cargo.toml
63
64// Public modules (exported in public API)
65pub mod auth;
66pub mod config;
67pub mod email;
68pub mod error;
69pub mod extractors;
70pub mod forms;
71pub mod handlers;
72pub mod health;
73pub mod htmx;
74pub mod jobs;
75pub mod oauth2;
76pub mod observability;
77pub mod state;
78pub mod storage;
79pub mod template;
80
81// Public modules for actors and agents
82pub mod agents;
83
84// Public middleware module (needed for session layer)
85pub mod middleware;
86
87// Testing utilities module (available in test builds)
88#[cfg(test)]
89pub mod testing;
90
91pub mod prelude {
92    //! Convenience re-exports for common types and traits
93    //!
94    //! Commonly used types and traits for building applications
95    //!
96    //! # Examples
97    //!
98    //! ```rust
99    //! use acton_htmx::prelude::*;
100    //! ```
101
102    // HTMX extractors and responders (from axum-htmx)
103    pub use crate::htmx::{
104        // Middleware
105        AutoVaryLayer,
106        // Request extractors
107        HxBoosted,
108        HxCurrentUrl,
109        HxHistoryRestoreRequest,
110        // Response helpers
111        HxLocation,
112        HxPrompt,
113        HxPushUrl,
114        HxRedirect,
115        HxRefresh,
116        HxReplaceUrl,
117        HxRequest,
118        HxRequestGuardLayer,
119        HxReselect,
120        HxResponseTrigger,
121        HxReswap,
122        HxRetarget,
123        HxTarget,
124        HxTrigger,
125        HxTriggerName,
126        // acton-htmx extensions
127        HxSwapOob,
128        SwapStrategy,
129    };
130
131    // Template traits
132    pub use crate::template::{HxTemplate, TemplateRegistry};
133
134    // Form handling
135    pub use crate::forms::{
136        FieldBuilder, FieldError, FormBuilder, FormField, FormRenderOptions, FormRenderer,
137        InputType, SelectOption, ValidationErrors,
138    };
139
140    // Authentication extractors
141    pub use crate::auth::{Authenticated, OptionalAuth, Session};
142
143    // Extractors
144    pub use crate::extractors::{FileUpload, FileUploadError, FlashExtractor, MultiFileUpload, SessionExtractor};
145
146    // Storage
147    pub use crate::storage::{FileStorage, LocalFileStorage, StorageError, StoredFile, UploadedFile};
148
149    // Error types
150    pub use crate::error::ActonHtmxError;
151
152    // Application state
153    pub use crate::state::ActonHtmxState;
154
155    // Session middleware
156    pub use crate::middleware::{SessionConfig, SessionLayer};
157
158    // Background jobs
159    pub use crate::jobs::{Job, JobAgent, JobError, JobId, JobResult, JobStatus};
160
161    // Email system
162    pub use crate::email::{
163        AwsSesBackend, ConsoleBackend, Email, EmailError, EmailSender, EmailTemplate,
164        SendEmailJob, SimpleEmailTemplate, SmtpBackend,
165    };
166
167    // OAuth2 authentication
168    pub use crate::oauth2::{
169        GitHubProvider, GoogleProvider, OAuthAccount, OAuthConfig, OAuthError, OAuthProvider,
170        OAuthState, OAuthToken, OAuthUserInfo, OidcProvider, ProviderConfig,
171        OAuth2Agent, initiate_oauth, handle_oauth_callback, unlink_oauth_account,
172    };
173
174    // Re-export key dependencies for framework users
175    // These allow users to avoid adding these crates to their Cargo.toml
176    pub use acton_reactive;
177    pub use anyhow;
178    pub use askama;
179    pub use axum;
180    pub use serde;
181    pub use serde_json;
182    pub use sqlx;
183    pub use thiserror;
184    pub use tokio;
185    pub use tower;
186    pub use tower_http;
187    pub use tracing;
188    pub use tracing_subscriber;
189    pub use validator;
190
191    // Convenience for JSON responses
192    pub use serde_json::json;
193}
acton_htmx/lib.rs

acton_htmx/
lib.rs
