Expand description
An opinionated full-stack Rust web framework with strong conventions and sensible defaults.
Capy integrates routing, validation, configuration, and database tooling with a predictable application structure.
Depend on this package as capy = { package = "capy-framework", version = "0.10.0" }.
The prelude contains the common API; named re-exports retain native escape hatches.
Re-exports§
pub use capy_mail as mail;pub use capy_jobs as jobs;pub use capy_storage as storage;pub use capy_auth as auth;pub use capy_db as db;pub use schema;pub use axum;pub use chrono;pub use sea_orm;pub use sea_orm_migration as migration;pub use serde;pub use serde_json;pub use tokio;pub use tower;pub use tower_http;pub use tracing;pub use uuid;pub use validator;pub use capy_testing as testing;
Modules§
- notifications
- Small mail notifications, with explicit synchronous or queued delivery at the call site.
- prelude
- The small set of types most API handlers need.
Structs§
- ApiDocument
- Standard OpenAPI 3.1 document. Advanced applications can customize its JSON.
- ApiError
Response - JSON wire envelope for Capy’s standardized errors. It never carries native causes.
- ApiRoute
Info - Public metadata displayed by
capy routes --api. - ApiSettings
- Small application-owned API metadata. Documentation is disabled by default.
- App
- Application builder: configuration, database, tracing, migrations, and HTTP.
- 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. - Created
- A JSON response with HTTP 201 Created.
- Database
Settings - SeaORM connection settings. Environment variables use
DATABASE_. - 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). - Health
Response - JSON wire data for process liveness.
- 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. - Json
- Deserialize or return JSON, using Capy’s safe rejection envelope.
Put this extractor last because it consumes the body. Native extraction is
available as
capy::axum::Json. - Mail
Settings - Conventional outbound mail settings; activated by
App::mail. - NoContent
- An empty response with HTTP 204 No Content.
- Page
- A bounded collection response. The caller supplies a paginated query’s rows.
- Page
Meta - Conventional pagination metadata. Empty collections have one empty page.
- Pagination
- Validated, one-based page parameters. Use
Query<Pagination>in a handler. Defaults to page 1 and 20 items; page size must be 1..=100. - Password
Settings - Per-application Argon2id admission and resource limits (
AUTH_PASSWORD_*). - Path
- Deserialize path parameters with safe Capy JSON rejections.
Native extraction remains available as
capy::axum::extract::Path. - Query
- Deserialize a query string with safe Capy JSON rejections.
Native extraction remains available as
capy::axum::extract::Query. - Readiness
Response - JSON wire data for a bounded database readiness probe.
- Request
Observation - Safe response-header completion data for optional application telemetry.
- Route
Info - A declared route, used by
capy routeswithout connecting to a database. - Routes
- A native Axum router together with a small, explicit route inventory.
- Schedule
- One stable named cron schedule and its ordinary job payload.
- Scheduler
- Deterministic scheduler;
tick_ataccepts an injected UTC clock for tests. - Schedules
- Explicit application-owned schedule registry.
- Seed
Context - Database transaction and typed settings for explicit application-owned development data.
- Seeds
- An explicit application-owned seed callback. All writes share one transaction.
- 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.
- Task
Context - Application dependencies for manually invoked named tasks.
- Tasks
- Registry of manually invoked operational tasks; no process-global state.
- Validated
- Deserialize and validate a JSON body before invoking the handler. Put this extractor last, since it consumes the request body.
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.
- Missed
Runs - Which missed occurrences a restarted scheduler publishes.
- Overlap
Policy - Whether another occurrence may be queued while a prior job is still active.
- Same
Site - Cookie policy. Cross-site cookies are intentionally outside the built-in path.
Traits§
- ApiSchema
- A type which can be described as a JSON Schema document.
- Event
- Explicit opt-in to transactional application events. No serialization is required. Event values must not contain passwords, session/CSRF credentials or reset tokens.
- Request
Observer - Application-owned telemetry adapter. Callbacks must be fast, nonblocking, and must not panic. Enqueue bounded events in your adapter for async exporters. No vendor, exporter, global registry, or background worker is installed by Capy.
Functions§
- health
- The default health response; it deliberately performs no database query.
- ready
- Readiness for standard DB-backed applications, with an independent probe deadline.
Mount beside
health, conventionally at/api/ready. Driver details never enter the response. Liveness remains independent of the database.
Type Aliases§
- Event
Future - A listener future borrowing the event, configuration and native transaction.
- Event
Result - Result returned by a transactional lifecycle listener.
- Paginated
- JSON contract name for the existing bounded collection response.
- Pagination
Meta - JSON contract name for the existing pagination metadata.
- Result
- The result type used by application handlers and startup.
- Seed
Future - A seed future borrowing the transaction for the duration of the callback.
- Validation
Errors - Field names (including dotted nested paths) mapped to validation messages.
Derive Macros§
- ApiSchema
- Derive macro for
JsonSchematrait.