Skip to main content

Crate capy_framework

Crate capy_framework 

Source
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.
ApiErrorResponse
JSON wire envelope for Capy’s standardized errors. It never carries native causes.
ApiRouteInfo
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_.
AuthSettings
Small, typed settings for the optional conventional identity system.
AuthThrottleLimit
Fixed-window abuse budget. Zero never implicitly disables a limit.
AuthThrottleSettings
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.
ClientIpResolver
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.
ClientIpSettings
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.
DatabaseSettings
SeaORM connection settings. Environment variables use DATABASE_.
EventBus
Extract the same registry installed by App::on for application-owned transitions.
EventContext
Transaction-oriented services. No application pool is exposed. Reuse transaction for repository calls and ctx.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::Reject values become public application errors. Unexpected errors and unwinding panics become a generic 500 (panic=abort still aborts the process).
HealthResponse
JSON wire data for process liveness.
HttpSettings
Small HTTP policy surface, expressed in seconds and bytes to avoid ambiguous units.
JobsSettings
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.
MailSettings
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.
PageMeta
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.
PasswordSettings
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.
ReadinessResponse
JSON wire data for a bounded database readiness probe.
RequestObservation
Safe response-header completion data for optional application telemetry.
RouteInfo
A declared route, used by capy routes without 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_at accepts an injected UTC clock for tests.
Schedules
Explicit application-owned schedule registry.
SeedContext
Database transaction and typed settings for explicit application-owned development data.
Seeds
An explicit application-owned seed callback. All writes share one transaction.
ServerSettings
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.
SmtpSettings
SMTP settings. TLS is mandatory in production; no opportunistic downgrade.
TaskContext
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.
ClientIpStrategy
Exactly one trusted header convention; no fallback between competing headers.
EventError
Listener outcome. Only Reject exposes application-authored public text. ? on database/anyhow/unexpected application errors takes the private failure path. A nested operation’s already-typed AppError::Rejected remains a rejection.
EventRejection
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.
HashConcurrency
Automatic hardware/budget selection or an explicit worker count.
MissedRuns
Which missed occurrences a restarted scheduler publishes.
OverlapPolicy
Whether another occurrence may be queued while a prior job is still active.
SameSite
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.
RequestObserver
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§

EventFuture
A listener future borrowing the event, configuration and native transaction.
EventResult
Result returned by a transactional lifecycle listener.
Paginated
JSON contract name for the existing bounded collection response.
PaginationMeta
JSON contract name for the existing pagination metadata.
Result
The result type used by application handlers and startup.
SeedFuture
A seed future borrowing the transaction for the duration of the callback.
ValidationErrors
Field names (including dotted nested paths) mapped to validation messages.

Derive Macros§

ApiSchema
Derive macro for JsonSchema trait.