arcly_http/
lib.rs

1//! **arcly-http** — NestJS ergonomics meets Rust safety & speed.
2//!
3//! An enterprise-grade web framework on [axum]: declarative controllers,
4//! zero-lock dependency injection, one shared request pipeline for every
5//! entry point, and the operational machinery (multi-tenancy, transactional
6//! outbox, ABAC, PII masking, field-level encryption, graceful shutdown
7//! governance) that production systems otherwise hand-roll.
8//!
9//! ```ignore
10//! use arcly_http::prelude::*;
11//!
12//! #[Injectable]
13//! pub struct GreetService;
14//! impl GreetService {
15//!     fn greet(&self, name: &str) -> String { format!("hello, {name}") }
16//! }
17//!
18//! #[Controller("/hello")]
19//! impl HelloController {
20//!     #[Get("/:name")]
21//!     async fn hello(&self, #[Param] name: String, svc: Inject<GreetService>) -> String {
22//!         svc.greet(&name)
23//!     }
24//! }
25//!
26//! #[Module(controllers(HelloController), providers(GreetService))]
27//! pub struct AppModule;
28//!
29//! #[tokio::main]
30//! async fn main() -> std::io::Result<()> {
31//!     App::launch::<AppModule>("0.0.0.0:3000").await // Swagger UI at /docs
32//! }
33//! ```
34//!
35//! ## Design invariants
36//!
37//! - **One request pipeline** — HTTP routes, plugin routes, and WebSocket
38//!   handshakes authenticate through the same boundary; a security fix lands
39//!   everywhere at once.
40//! - **No locks on the request path** — frozen `&'static` DI container,
41//!   atomics, and `ArcSwap` snapshots only.
42//! - **Handlers never see axum** — [`RequestContext`] is the only request
43//!   surface, so the HTTP layer can evolve without breaking user code.
44//!
45//! ## Module layout
46//!
47//! | Module          | Responsibility                                              |
48//! |-----------------|--------------------------------------------------------------|
49//! | [`app`]         | Launch contract, [`LaunchConfig`] governance knobs           |
50//! | [`auth`]        | Identity & access: JWT, cookies, sessions, OAuth2, ABAC, guards |
51//! | [`core`]        | DI engine + plugin lifecycle (HTTP-agnostic)                 |
52//! | [`web`]         | HTTP layer: boundary, context, errors, interceptors, CORS    |
53//! | [`data`]        | DB facade (SQLx/SeaORM/Diesel), tenancy, migrations, outbox  |
54//! | [`messaging`]   | Event consumer mesh, retries, dead-letter                    |
55//! | [`compliance`]  | PII masking + field-level envelope encryption                |
56//! | [`realtime`]    | WebSocket gateways + SSE                                      |
57//! | [`observability`] | Structured logs, Prometheus, OTLP, health, trace propagation |
58//! | [`resilience`]  | Circuit breaker, rate limiting, bulkhead, distributed locks  |
59//! | [`security`]    | Security headers                                              |
60//!
61//! ## Cargo features
62//!
63//! | Feature | Effect |
64//! |---|---|
65//! | *(none)* | Full framework, no database driver |
66//! | `db-sqlx` / `db-sqlx-postgres` / `db-sqlx-mysql` / `db-sqlx-sqlite` | SQLx-backed [`data`] layer |
67//! | `db-seaorm` | SeaORM driver |
68//! | `db-diesel` | Diesel (r2d2) driver |
69//!
70//! Most applications only need `use arcly_http::prelude::*;`.
71//!
72//! [axum]: https://docs.rs/axum
73
74pub mod app;
75pub mod auth;
76pub mod compliance;
77pub mod core;
78pub mod data;
79pub mod docs;
80pub mod http;
81pub mod messaging;
82pub mod observability;
83pub mod pipeline;
84pub mod realtime;
85pub mod resilience;
86pub mod testing;
87pub mod web;
88
89// ─── Path-compat shims ─────────────────────────────────────────────────────────
90// The auth subsystem was consolidated from five root files into `auth/`.
91// These re-exports keep every pre-existing import path compiling unchanged:
92// `arcly_http::cookie::CookieService`, `arcly_http::guards::Guard`, etc.
93pub use auth::cookie;
94
95// Path-compat shims for the module re-org (root files moved into their
96// owning domains). Every pre-existing import path keeps compiling:
97// `arcly_http::security::…`, `arcly_http::validation::…`,
98// `arcly_http::openapi::…`, `arcly_http::event::…`.
99pub use auth::guards;
100pub use auth::oauth;
101pub use auth::session;
102pub use docs::openapi;
103pub use messaging::event;
104pub use web::security;
105pub use web::validation;
106
107// Convenience re-exports.
108pub use core::plugins;
109pub use web::cache;
110pub use web::interceptors;
111
112// Re-exports needed by macro expansions.
113#[doc(hidden)]
114pub use axum as __axum;
115pub use futures;
116pub use inventory;
117pub use schemars;
118pub use serde_json;
119pub use validator;
120
121pub use app::{App, LaunchConfig};
122pub use web::{Error, RequestContext};
123
124#[doc(hidden)]
125#[inline]
126pub fn __schema_for<T: schemars::JsonSchema>() -> serde_json::Value {
127    serde_json::to_value(schemars::schema_for!(T)).unwrap_or(serde_json::Value::Null)
128}
129
130/// Single stable surface for `arcly-http-macros` codegen.
131///
132/// Every symbol the proc-macros emit is re-exported here, so internal files
133/// can move freely without touching the macro crate — only this module's
134/// `pub use` lines need to follow.
135#[doc(hidden)]
136pub mod __macro_support {
137    pub use crate::auth::guards::Guard;
138    pub use crate::auth::policy::check_policies;
139    pub use crate::compliance::crypto::EncryptRecord;
140    pub use crate::compliance::masking::mask_response;
141    // Explicit list — ONLY what macro expansions actually reference.
142    // A glob here silently turned every engine internal into a contract
143    // with the macro crate; new drivers/transports must not widen this
144    // surface by accident.
145    pub use crate::core::engine::{
146        FrozenDiContainer, HttpMethod, Module, ModuleDescriptor, ParamLoc, ParamSpec,
147        ProviderDescriptor, Resolver, RouteDescriptor, RouteSpec,
148    };
149    pub use crate::data::tx::run_transactional;
150    pub use crate::http::Json;
151    pub use crate::messaging::{EventContext, EventError, EventHandlerDescriptor};
152    pub use crate::observability::audit::emit_route_audit;
153    pub use crate::realtime::gateway::{GatewayDescriptor, GatewayRuntime, MessageHandler};
154    pub use crate::realtime::{ArclyGateway, WsClient};
155    pub use crate::resilience::timeout::run_with_timeout;
156    pub use crate::resilience::{BreakerOpen, CircuitBreaker};
157    pub use crate::web::context::RequestContext;
158    pub use crate::web::extract::{
159        extract_body_validated, extract_header, extract_param, extract_query_validated, Inject,
160    };
161    pub use crate::web::idempotency::run_idempotent;
162    pub use crate::web::interceptors::{Interceptor, NextHandler};
163    pub use crate::web::Error;
164}
165
166/// `use arcly_http::prelude::*;` brings in everything a user needs.
167pub mod prelude {
168    pub use crate::app::{App, LaunchConfig};
169    pub use crate::auth::cookie::{CookieConfig, CookieService, SameSite};
170    pub use crate::auth::guards::{
171        JwtAuthGuard, RoleGuard, SessionAuthGuard, JWT_AUTH, SESSION_AUTH,
172    };
173    pub use crate::auth::oauth::{OAuth2Provider, OAuth2Service, OAuth2UserInfo};
174    pub use crate::auth::policy::{
175        check_policies, Decision, EnvAttributes, PolicyEngine, PolicyInput, PolicySet, PolicySource,
176    };
177    pub use crate::auth::secrets::{spawn_secret_watcher, Rotating, SecretSource, SecretVersion};
178    pub use crate::auth::session::{Session, SessionConfig, SessionManager, SessionStore};
179    pub use crate::auth::{JwtConfig, JwtService};
180    pub use crate::cache::{stats as cache_stats, CacheInterceptor, CacheStats};
181    pub use crate::compliance::{
182        CryptoError, CryptoVault, DataKey, EncryptRecord, EncryptedField, KekSource, KeyId,
183        MaskRule, MaskStrategy, Masker, MaskingPolicy,
184    };
185    pub use crate::core::engine::FrozenDiContainer;
186    pub use crate::core::plugins::{ArclyPlugin, ArclyPluginContext, PluginError, PluginStage};
187    pub use crate::data::db::{ArclyDbPool, DbDriver, DbHealthCheck, OwnedDbConn};
188    #[cfg(feature = "db-sqlx")]
189    pub use crate::data::migrate::{Migration, MigrationReport, MigrationRunner};
190    pub use crate::data::outbox::{
191        with_transaction, OutboxEntry, OutboxPublisher, OutboxRelay, OutboxStore, OutboxTx,
192        TransactionalDataSource,
193    };
194    pub use crate::data::tx::{in_transaction, with_current_tx, ArclyTransaction};
195    pub use crate::data::{
196        AccessIntent, DataError, DataSource, DataSourceRegistry, ReadAfterWritePin,
197    };
198    pub use crate::http::{IntoResponse, Json, Response};
199    pub use crate::interceptors::{
200        EnvelopeResponse, Interceptor, LatencyLog, NextHandler, TelemetryLog, TraceInterceptor,
201    };
202    pub use crate::messaging::{
203        ConsumerRuntime, EventContext, EventHandlerDescriptor, InboundMessage, MessageTransport,
204    };
205    pub use crate::observability::audit::{AuditOutcome, AuditPipeline, AuditRecord, AuditSink};
206    pub use crate::observability::health::{HealthCheck, HealthRegistry, HealthStatus};
207    pub use crate::observability::plugin::ArclyObservabilityPlugin;
208    pub use crate::openapi::{ApiKeyIn, OpenApiInfo, SecurityScheme};
209    pub use crate::pipeline::Provenance;
210    pub use crate::resilience::{
211        Bulkhead, DLockBackend, DistributedLock, DistributedRateLimit, FailurePolicy, LockGuard,
212        RateDecision, RateLimit, RateLimitBackend,
213    };
214    pub use crate::security::{configure as configure_security, FrameOptions, SecurityConfig};
215    pub use crate::validation::Validated;
216    pub use crate::web::boundary::BoundaryFilter;
217    pub use crate::web::cors::CorsConfig;
218    pub use crate::web::dynamic::{DynamicRouteTable, DYNAMIC_PREFIX};
219    pub use crate::web::error::{
220        BadRequest, Conflict, FieldError, Forbidden, GatewayTimeout, HttpError, HttpException,
221        Internal, NotFound, ProblemDetails, ServiceUnavailable, TooManyRequests, Unauthorized,
222        Validation,
223    };
224    pub use crate::web::idempotency::{IdempotencyDecision, IdempotencyStore};
225    pub use crate::web::responses::{Accepted, Created, NoContent};
226    pub use crate::web::tenant::{
227        TenantConfig, TenantGuard, TenantId, TenantRegistry, TenantStrategy, TENANT,
228    };
229    pub use crate::web::{Error, Inject, RequestContext};
230    pub use arcly_http_macros::{
231        circuit_breaker, AuditLog, CacheKey, CacheTTL, Controller, Delete, Deprecated,
232        EncryptFields, EventConsumer, EventPattern, Get, Idempotent, Injectable, MaskFields,
233        Module, Patch, Post, Put, RequirePolicies, Timeout, Transactional, UseInterceptors,
234        Version,
235    };
236    pub use schemars::JsonSchema;
237    pub use validator::Validate;
238}
arcly_http/lib.rs

arcly_http/
lib.rs
