Module prelude

Source

Expand description

use arcly_http::prelude::*; brings in everything a user needs.

Re-exports§

pub use crate::app::App;
pub use crate::app::LaunchConfig;

Modules§

header: Standard header-name constants: header::CONTENT_TYPE, header::LOCATION, header::CONTENT_RANGE, header::CACHE_CONTROL, header::ACCEPT_RANGES, the header::ACCESS_CONTROL_* family, and the rest of the IANA registry.

Structs§

Accepted: 202 Accepted — for async / queued work.
ArclyDbPool: Primary + replicas for one logical database. Build at boot (plugin on_init), register into DataSourceRegistry<ArclyDbPool>, freeze.
ArclyObservabilityPlugin: Drop-in observability plugin. Add to App::launch_with_plugins to get structured logs, Prometheus metrics, OTLP traces, and health endpoints with zero changes to handler code.
ArclyPluginContext
AuditPipeline: Lock-free front door for audit records.
AuditRecord: One immutable audit entry. prev_hash chains each record to its predecessor (SHA-256), so post-hoc tampering breaks the chain visibly.
BadRequest
Body: The body type used in axum requests and responses.
Bulkhead
Bytes: A cheaply cloneable and sliceable chunk of contiguous memory.
CacheInterceptor: The interceptor itself — a unit struct so it can be referenced from a static in macro-generated code (see wrap_interceptors in the macros crate).
CacheStats: Telemetry snapshot for the cache. Plugins / handlers can expose this.
Conflict
ConsumerRuntime: Drives one transport against the link-time handler registry.
CookieConfig: Configuration for CookieService. Build once at startup.
CookieService: Signs and verifies HTTP cookie values.
CorsConfig: CORS policy, frozen at launch.
Created: 201 Created with an optional Location header.
CryptoVault: Process-wide encryption service. Provide once via ctx.provide(CryptoVault::bootstrap(source).await?), resolve anywhere with Inject<CryptoVault> / ctx.inject::<CryptoVault>().
DataError: Classified datasource failure — callers can finally distinguish “retry somewhere else” from “this will never work”, which retry policies, circuit breakers, and replica failover need.
DataKey: One unwrapped AES-256 DEK version. Material is zeroized on drop (secrecy) and never serialized.
DataSourceRegistry: Frozen tenant→datasource map. Built once at boot, provided via DI, read lock-free on every request.
DbHealthCheck: Readiness probe over every pool in a DataSourceRegistry: pings each primary and reports the first failure as Unhealthy naming the pool.
DistributedLock: const-constructible named lock. The backend comes from DI (Arc<dyn DLockBackend>), so the same static works across environments.
DistributedRateLimit: Cluster-wide limiter. Build as a static and call from handlers:
DynamicRouteTable: Process-wide table of runtime-mounted routes. Automatically provided in the DI container — resolve with Inject<DynamicRouteTable> (or ctx.inject::<DynamicRouteTable>()) and mount/unmount at any time.
EncryptedField: Self-describing ciphertext for one field: enc:v1:<key_id>:<key_version>:<b64(nonce ‖ ciphertext ‖ tag)>. Records the key version so rotation never forces immediate re-encryption.
EnvAttributes
EnvelopeResponse: Wrap successful JSON responses in { "data": ... }. Errors pass through untouched so RFC 7807 ProblemDetails reaches the client verbatim.
EventContext: What an #[EventPattern] handler receives — DI + payload + trace, no HTTP types anywhere.
EventHandlerDescriptor: Static descriptor emitted by the #[EventPattern] expansion and collected at link time — the runtime freezes these into its dispatch map at start.
FieldError
Forbidden
FrozenDiContainer: Immutable, lock-free DI container. Reads are O(1) and inlined.
GatewayTimeout
HeaderMap: A specialized multimap for header names and values.
HeaderName: Represents an HTTP header field name
HeaderValue: Represents an HTTP header field value.
HealthRegistry: Process-wide health-check registry. Accessible via global().
HttpException: Boxed HttpError. Handlers return Result<T, HttpException>; ? works across any user-defined error via the blanket From<E: HttpError> impl.
InboundMessage: One inbound message, transport-agnostic.
Inject: Constructor-style dependency injection wrapper. Resolved from the frozen DI container at request entry.
Internal
Json: JSON response wrapper. Json(body) writes Content-Type: application/json and serialises body with serde_json. Same surface as axum’s Json so the route macro’s return-type walker (Json<T> | Result<Json<T>, _>) keeps working without changes.
JwtAuthGuard: Checks that the incoming request carried a valid JWT.
JwtConfig
JwtService: Signs and validates JWTs. Provide this into the DI container so the framework boundaries (boundary.rs, ws.rs) can auto-populate RequestContext::claims() on every incoming request.
KeyId: Identifies one DEK lineage. Conventional scopes: tenant:<id> (tenant-wide) and subject:<id> (per-person, shreddable).
LatencyLog: Log method + path + status + latency on each request.
LockGuard: Live ownership of a distributed lock. Dropping it stops the heartbeat and releases the key (compare-and-delete — never deletes a successor’s lock).
MaskRule: A field rule: where + how.
Masker: Hot-swappable redaction point. Provide via ctx.provide(Masker::new(…)).
MaskingPolicy: Versioned, immutable rule set (hot-swapped whole, like PolicySet).
Method: The Request Method (VERB)
MigrationReport
MigrationRunner
MultipartForm: A fully parsed multipart/form-data body.
NextHandler: Continuation handed to an interceptor. Calling .run(ctx) invokes the next layer (or the handler itself if this is the innermost interceptor).
NoContent: 204 No Content. Carries no body.
NotFound
OAuth2Service: Registry of OAuth2 providers keyed by provider.name().
OAuth2UserInfo: Normalised user information returned by any OAuth2 provider.
OpenApiInfo: Top-level OpenAPI document configuration. Build at main.rs and pass to App::launch_with_info (in the arcly-http facade).
OutboxEntry: One event enqueued in the same transaction as the business write.
OutboxRelay: Background poll → publish → ack loop. At-least-once: an entry is acked only after a successful publish, so a crash between the two replays it — consumers must dedupe on idempotency_key.
Page: A page of results plus the metadata a client needs to walk the rest.
PageParams: Query parameters for an offset-paginated list endpoint.
Part: One part of a parsed multipart body — a form field or an uploaded file.
PluginError
PolicyEngine: Hot-swappable decision point. Provide via ctx.provide(PolicyEngine::new(…)).
PolicyInput: Everything a rule may inspect for one decision.
PolicySet: An immutable, versioned rule set. Default-deny: actions with no matching rule are denied — the zero-trust posture auditors expect.
ProblemDetails
Provenance: Who/where/why for one unit of work — identical shape across transports.
RateLimit: Per-instance fixed-window limiter. Zero locks: a (window_start, count) pair is packed into a single AtomicU64 and updated via CAS.
ReadAfterWritePin: Per-request replica-lag protection: once any Write is acquired through this pin, all subsequent Reads are upgraded to the primary.
RequestContext: The one and only context passed to every handler.
RequestParts: Component parts of an HTTP Request
ResponseBuilder: An HTTP response builder
RoleGuard: Checks that the authenticated principal’s "role" claim matches a required value.
Rotating: Atomically swappable key material.
SecretVersion: One fetched secret value plus a monotonically increasing version.
SecurityConfig: Full security header configuration.
ServiceUnavailable
Session: A single server-side session. Thread-safe via an interior RwLock.
SessionAuthGuard: Passes if the request has a loaded server-side session.
SessionConfig: Configuration for SessionManager.
SessionManager: Orchestrates session lifecycle: cookie extraction, store lookup, creation, persistence, and deletion.
StatusCode: An HTTP status code (status-code in RFC 9110 et al.).
TelemetryLog: Emit a structured log line for every request via the tracing crate.
TenantConfig: Per-tenant static configuration.
TenantGuard: Requires a resolved tenant AND cross-checks it against the JWT.
TenantId: Interned tenant identifier (no heap allocation for IDs ≤ 23 bytes).
TenantRegistry: Tenant registry with dynamic provisioning.
TooManyRequests
TraceInterceptor: Full-stack observability interceptor: structured log + OTLP span + Prometheus.
Unauthorized
Uri: The URI component of a request.
Validated: A payload T that has been deserialized and validated.
Validation

Enums§

AccessIntent: Whether the caller intends to read or mutate.
ApiKeyIn
ArclyTransaction: One live driver transaction. Dropping without commit rolls back.
AuditOutcome
CryptoError
DataErrorKind: Failure classes. #[non_exhaustive]: match with a _ arm.
DbDriver: One concrete connection pool. Variants are feature-gated; constructors live in data::drivers::*.
Decision
Error
FailurePolicy: What to do when the backend is unreachable.
FrameOptions: Controls what X-Frame-Options header is emitted.
HealthStatus
IdempotencyDecision
MaskStrategy: How a matched field is transformed.
OwnedDbConn: An acquired handle, decoupled from the pool’s lifetime so it can be held across .await points and moved into transactions.
PluginStage
RateDecision: Outcome of one counted hit against the shared limiter.
SameSite
SecurityScheme: HTTP authentication scheme exposed in components.securitySchemes.
TenantStrategy: How the tenant identifier is carried on the wire.

Constants§

DYNAMIC_PREFIX: Namespace prefix for all dynamic routes.

Statics§

JWT_AUTH: Ready-to-use singleton for JwtAuthGuard. Import and call:
SESSION_AUTH: Ready-to-use singleton for SessionAuthGuard.
TENANT: Ready-to-use singleton.

Traits§

ArclyPlugin: Plugin lifecycle.
AuditSink: Durable destination, implemented by the app. Must be append-only in production deployments — the framework never updates or deletes records.
BoundaryFilter: Pre-body request filter, registered by plugins via ArclyPluginContext::register_boundary_filter.
DLockBackend: Storage backend (Redis in production). Implementations MUST make try_acquire atomic (single Lua script / transaction).
DataSource: One logical database: a primary plus optional read replicas.
EncryptRecord: Implemented by #[EncryptFields(...)] on a DTO. The default methods are the whole write/read contract:
HealthCheck: One named sub-system health probe.
HttpError: Every domain error type implements HttpError. The framework converts to a ProblemDetails body and the appropriate status code.
IdempotencyStore: App-provided storage (Redis SET NX PX in production).
Interceptor: One layer of the aspect chain.
IntoResponse: Convert a value into a Response.
JsonSchema: A type which can be described as a JSON Schema document.
KekSource
MessageTransport: App-provided broker adapter (Kafka / AMQP / NATS / in-process bridge).
Migration
OAuth2Provider: Implement this to add an OAuth2 provider to the application.
OutboxPublisher: Downstream event transport (Kafka, NATS, webhook fan-out, …).
OutboxStore: Committed-but-unpublished entries, fetched/acked by the relay.
OutboxTx: A live database transaction that can also enqueue outbox entries.
PolicySource: External policy origin (rules file, OPA bundle endpoint, DB) — the app implements it; a background watcher feeds PolicyEngine::reload.
RateLimitBackend: Shared counting backend (Redis, Memcached, …). Object-safe via BoxFuture, following the same pattern as SessionStore and OAuth2Provider.
SecretSource: External secret backend — Vault, AWS Secrets Manager, env (dev), …
SessionStore: Backend store for sessions. Implement this to plug in Redis, Postgres, etc.
TransactionalDataSource: A datasource that can open outbox-capable transactions.
Validate: This is the original trait that was implemented by deriving Validate. It will still be implemented for struct validations that don’t take custom arguments. The call is being forwarded to the ValidateArgs<'v_a> trait.

Functions§

byte_range: Serve a (possibly partial) byte range from a fully-buffered resource.
bytes_response: Build a Response from a status, content type, and raw bytes.
cache_stats
check_policies: Evaluate every action against the engine; all must Permit.
configure_security: Install a custom security configuration.
in_transaction: true when running inside a #[Transactional] scope.
spawn_secret_watcher: Poll source for key every interval; when the version increases, invoke on_change with the new secret.
with_current_tx: Run work with this request’s transaction (if #[Transactional] opened one). The transaction is moved out of the slot for the duration of the closure and put back afterwards, so the future stays Send.
with_transaction: Run work inside one transaction: commit on Ok, roll back on Err.

Type Aliases§

Response: Type alias for http::Response whose body type defaults to Body, the most common body type used with axum.

Attribute Macros§

AuditLog: #[AuditLog(action = "…", resource = "…")] — emit one compliance audit record per invocation, keyed on the response status. Consumed by #[Controller]; pass-through marker on free fns.
CacheKey: #[CacheKey("template")] — custom key. Marker attribute; see CacheTTL.
CacheTTL: #[CacheTTL(N)] — TTL in seconds. Marker attribute consumed by the route macro and stuffed into RouteSpec.cache_ttl_secs. Pass-through here so the type system accepts it standalone.
Controller: #[Controller("/prefix", tags(..))] — declare an HTTP controller.
Delete: #[Delete("/path")] — map a method (or free function) to an HTTP DELETE route.
Deprecated: #[Deprecated(sunset = "YYYY-MM-DD")] on a #[Controller] impl — adds RFC 8594 Deprecation/Sunset headers to every response from this controller. Marker; consumed by #[Controller].
EncryptFields: #[EncryptFields(key = "tenant:acme", fields("ssn", "items.*.diagnosis"))] on a Serialize + Deserialize struct implements EncryptRecord: record.seal(&vault) returns a serde_json::Value with the declared fields sealed (safe for any durable sink); T::unseal(value, &vault) reverses it. Use seal_with_key/KeyId::subject(...) for per-subject keys minted at runtime (crypto-shredding granularity).
EventConsumer: #[EventConsumer] on an impl block — registers every #[EventPattern] method into the link-time event registry (the messaging analogue of #[Controller]). Methods take EventContext and return Result<(), String>.
EventPattern: #[EventPattern("topic")] — marks a method inside an #[EventConsumer] impl as the handler for one topic. Marker; consumed by #[EventConsumer].
Gateway: #[Gateway("/path")] — declare a WebSocket gateway.
Get: #[Get("/path")] — map a method (or free function) to an HTTP GET route.
Idempotent: #[Idempotent(ttl = "24h")] — Stripe-style Idempotency-Key handling: claim → run → store; retries replay the stored response; concurrent duplicates get 409. Consumed by #[Controller].
Injectable: #[Injectable] — turn a struct into a zero-lock DI provider.
MaskFields: #[MaskFields("email", "card:last4")] — redact these JSON response fields (plus the global Masker rules) before any durable layer sees the body. Consumed by #[Controller].
Module: #[Module(controllers(..), providers(..), imports(..))] — declare a unit of the application DAG.
Multipart: #[Multipart(file("avatar"), text("alt"))] — declare that a handler consumes a multipart/form-data body, for the OpenAPI surface.
Patch: #[Patch("/path")] — map a method (or free function) to an HTTP PATCH route.
Post: #[Post("/path")] — map a method (or free function) to an HTTP POST route.
Put: #[Put("/path")] — map a method (or free function) to an HTTP PUT route.
RequirePolicies: #[RequirePolicies("orders.refund", …)] — ABAC route gate: every listed action must Permit under the hot-reloadable PolicyEngine (default-deny). Consumed by #[Controller].
Subscribe: #[Subscribe("event::name")] — marker consumed by the enclosing #[Gateway] walker. Pass-through so it also type-checks if a tool resolves it directly.
Timeout: #[Timeout("2s")] — route deadline; 504 + future cancellation on expiry. Consumed by #[Controller]; pass-through marker on free fns.
Transactional: #[Transactional] — wrap the handler in a database transaction on the request-tenant’s pool: commit on Ok, rollback on Err/cancellation. Consumed by #[Controller]; pass-through marker on free fns.
UseInterceptors: #[UseInterceptors(A, B)] on a free fn — wraps that handler’s thunk.
Version: #[Version("v1")] on a #[Controller] impl — mounts every route under /v1/... and records the version in each RouteSpec. Marker; consumed by #[Controller].
circuit_breaker: #[circuit_breaker(..)] — wrap a method in a circuit breaker.

Derive Macros§

JsonSchema
Validate

Module prelude

Module prelude Copy item path

Re-exports§

Modules§

Structs§

Enums§

Constants§

Statics§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Derive Macros§

Module prelude