Expand description
Typed configuration, shared application state, and safe application errors.
Structs§
- ApiError
Response - JSON wire envelope for Capy’s standardized errors. It never carries native causes.
- ApiSettings
- Small application-owned API metadata. Documentation is disabled by default.
- AppConfig
- Application and database settings, resolved before startup.
- AppContext
- Cheaply cloned state shared by every request.
- AppSettings
- HTTP server and logging settings. Environment variables use
APP_. - Auth
Settings - Small, typed settings for the optional conventional identity system.
- Auth
Throttle Limit - Fixed-window abuse budget. Zero never implicitly disables a limit.
- Auth
Throttle Settings - Separate fixed windows for CSRF bootstrap, registration, login, reset request and reset completion. Limits apply per action; account keys span client IPs. Application-owned verification endpoints need their own request-level limiter.
- Client
IpResolver - Validated, reusable resolver. Forged headers from untrusted peers are ignored. Trusted chains are walked right to left; the first untrusted address is the client. Missing/ambiguous identities fail closed with a generic 503, never a shared bucket.
- Client
IpSettings - Client identity policy under
[client_ip]in config/http.toml. - Context
- Extract typed application state using
Context(ctx): Context. - Database
Settings - SeaORM connection settings. Environment variables use
DATABASE_. - Error
Kind - Safe error category carried on an HTTP response for request diagnostics.
- Event
Bus - Extract the same registry installed by
App::onfor application-owned transitions. - Event
Context - Transaction-oriented services. No application pool is exposed. Reuse
transactionfor repository calls andctx.jobs().dispatch(job)(with the jobs extension trait) for atomic enqueue. Avoid network I/O and capturing a pool: reacquiring a connection can deadlock even on PostgreSQL when its pool is full. - Events
- Immutable, cheaply cloned registration snapshot. Each listener is called once per
dispatch, in registration order. The first rejection/failure stops dispatch;
the owner MUST roll back. Cancellation also requires rollback. Only explicit
EventError::Rejectvalues become public application errors. Unexpected errors and unwinding panics become a generic 500 (panic=abort still aborts the process). - Http
Settings - Small HTTP policy surface, expressed in seconds and bytes to avoid ambiguous units.
- Jobs
Settings - Durable worker policy. Jobs are activated by
App::jobs, never implicitly. - Mail
Secret - A configuration credential. Debug is redacted; serialization is for config merging.
- Mail
Settings - Conventional outbound mail settings; activated by
App::mail. - Password
Settings - Per-application Argon2id admission and resource limits (
AUTH_PASSWORD_*). - Server
Settings - Listener settings. Unspecified host/port retain legacy
APP_HOST/APP_PORT. - Service
- Extract a typed registered service from an HTTP request.
- Services
- Immutable, cheaply cloned application dependencies keyed by their Rust type. Each application factory owns its registry; there is no process-wide state.
- Smtp
Settings - SMTP settings. TLS is mandatory in production; no opportunistic downgrade.
- Storage
Settings - Optional private object-store configuration (
config/storage.toml,STORAGE_*).
Enums§
- AppError
- Errors with predictable HTTP statuses and safe public messages.
- Client
IpStrategy - Exactly one trusted header convention; no fallback between competing headers.
- Event
Error - Listener outcome. Only
Rejectexposes application-authored public text.?on database/anyhow/unexpected application errors takes the private failure path. A nested operation’s already-typedAppError::Rejectedremains a rejection. - Event
Rejection - An intentional, public application policy rejection. Only these statuses may be exposed by listeners. Codes and messages must be static, safe application text, never dependency errors, credentials or account-existence diagnostics.
- Hash
Concurrency - Automatic hardware/budget selection or an explicit worker count.
- Same
Site - Cookie policy. Cross-site cookies are intentionally outside the built-in path.
Traits§
- Event
- Explicit opt-in to transactional application events. No serialization is required. Event values must not contain passwords, session/CSRF credentials or reset tokens.
Type Aliases§
- Event
Future - A listener future borrowing the event, configuration and native transaction.
- Event
Result - Result returned by a transactional lifecycle listener.
- Result
- The result type used by application handlers and startup.
- Validation
Errors - Field names (including dotted nested paths) mapped to validation messages.