⚡ Scyph
An opinionated, batteries-included backend library for building production-grade web services with Axum.
⚠️ Project Status: Alpha (
v0.1.x)
scyphis currently in active Alpha. It is battle-tested daily in two production codebases. We are gathering real-world performance metrics and telemetry, and plan to enter Beta in approximately 6 months. APIs may evolve slightly during this period.
💡 What is Scyph? (And What It Isn't)
Scyph is a library, NOT a framework.
In standard backend frameworks (like Loco, Poem, or Actix-web wrappers), the framework controls your application's lifecycle: it owns main(), generates hidden boilerplate through heavy macros, dictates project directory layouts, and forces you into rigid architectural constraints (Inversion of Control).
Scyph takes the opposite approach. You retain complete control over:
- Your
main()entrypoint - Your Tokio async runtime
- Your standard
axum::Router - Your domain logic, data models, and folder layout
Instead of hijacking your code, Scyph provides opinionated, battle-tested, modular building blocks that snap directly into native Axum routers and extractors.
🎯 Why Was Scyph Created?
Every time a new backend service needed to be launched, the story was always the same:
An entire week was burned just setting up boilerplate.
Writing the same JWT auth validation, hashing passwords with Argon2, structuring RFC 7807 problem details error envelopes, configuring SQLx connection pools and transaction helpers, wiring up non-blocking tracing with request ID propagation, writing multipart S3 streaming extractors, setting up Redis rate limiters, webhooks, and Kubernetes health checks... over and over again.
While existing Rust web frameworks existed, none of them felt right:
- They felt too magical or intrusive: They hid essential request lifecycles behind macro-heavy abstractions or code generators.
- We couldn't agree with their design philosophies: Many enforced monolithic paradigms, rigid ORMs, or opinionated directory structures that got in the way when microservices or custom data layers were needed.
- Fragile dependencies & C-binding issues: Many frameworks or libraries relied on native OpenSSL or complex C toolchains rather than pure-Rust, memory-safe TLS and crypto primitives.
Scyph was built to eliminate that boilerplate week permanently, giving you a production-hardened foundation in minutes while keeping your codebase idiomatic, explicit, and lightweight.
🚀 How Scyph Differentiates Itself
| Feature | Monolithic Frameworks | Bare Axum | Scyph |
|---|---|---|---|
| Control Model | Inversion of Control (Framework owns main) |
You own main |
You own main & Router (Pure Library) |
| Boilerplate | Low, but rigid & hidden | High (days to weeks of repetitive plumbing) | Near zero boilerplate, fully explicit |
| Modularity | Monolithic lock-in | Assemble everything from scratch | Independent sub-crates + umbrella facade |
| API Standards | Ad-hoc responses & error formats | DIY response types | Built-in RFC 7807 Problem Details & Envelopes |
| Telemetry & IDs | Manual tracing wiring | Manual setup | Zero-config non-blocking tracing + UUIDv7 IDs |
| Security & TLS | Often defaults to OpenSSL | Depends on crates chosen | Pure-Rust memory-safe TLS (rustls / aws-lc-rs) |
| Database Ergonomics | Heavy ORMs with high compile times | Raw SQLx boilerplate | SQLx pooling + dynamic search/sort/filter/paginate |
📦 Modular Architecture
Scyph is organized as a unified workspace of decoupled crates. You can import the full umbrella crate scyph with feature flags, or import only the individual crates your service needs:
| Crate | Crates.io | Feature Flag | Primary Capabilities |
|---|---|---|---|
scyph-core |
(Always included) | RFC 7807 AppError, ApiResponse<T>, PagedResponse<T>, Claims trait |
|
scyph-auth |
auth |
JWT issuance/validation, Argon2id hashing, Moka cache, AuthUser extractor |
|
scyph-abac |
abac, cedar |
Attribute-Based Access Control, SQL query FilterBuilder, Cedar policies |
|
scyph-db |
db, query |
PostgreSQL pool builder, transactions, migrations, dynamic search & filtering | |
scyph-extractors |
extractors |
ValidatedJson<T>, SanitizedJson<T>, ValidatedQuery<T>, ValidatedPath<T> |
|
scyph-health |
health |
Kubernetes /health/live & /health/ready endpoint registries |
|
scyph-notify |
notify, email, fcm |
SMTP delivery via Lettre & Tera templates, Firebase Cloud Messaging (FCM) | |
scyph-ratelimit |
ratelimit |
IP & key rate-limiting with reverse proxy header detection (X-Forwarded-For) — smart layers are safe only when the proxy unconditionally overwrites those headers |
|
scyph-realtime |
realtime |
Redis Pub/Sub WebSocket broadcaster with per-session bounded message queues | |
scyph-storage |
storage, s3, image |
AWS S3 & MinIO streaming multipart upload extractors & thumbnail generation | |
scyph-telemetry |
telemetry |
Non-blocking tracing, UUIDv7 request ID tracking, auto-meta JSON injection | |
scyph-utils |
utils |
HMAC webhook verification, background worker tasks, Redis idempotency, Bloom filter (in-memory + Valkey/Redis) |
⚡ Quickstart Example
Add scyph to your Cargo.toml:
[]
= { = "0.1", = ["full"] }
= { = "1", = ["full"] }
= "0.8"
Create your Axum service in src/main.rs:
use ;
use *;
async
// Handlers use Scyph extractors & RFC 7807 response envelopes
async
🌸 Bloom Filters
utils includes an in-memory BloomFilter and a durable ValkeyBloomFilter.
Use them as fast "definitely not seen" checks; keep the database unique
constraint as the source of truth.
use *;
// In-memory, warmed from an iterator.
let emails = vec!;
let seen = from_iter;
assert!;
// Shared across Axum tasks.
let shared = new;
shared.insert;
assert!;
use *;
async
🎛️ Feature Flags
| Feature | Default | Description |
|---|---|---|
default |
Yes | Enables auth, db, health, telemetry, extractors, utils |
full |
No | Enables all crates and sub-features across the entire framework |
auth |
Yes | JWT token generation, Argon2id hashing, Moka cache, role-based guards |
db |
Yes | PostgreSQL connection pooling and transaction lifecycle helpers |
query |
No | Dynamic QueryBuilder filtering, sorting, searching, and pagination |
health |
Yes | Kubernetes liveness/readiness endpoint registries |
telemetry |
Yes | Non-blocking tracing, UUIDv7 request IDs, and auto-meta response injection |
extractors |
Yes | Sanitized and validated JSON body, query, and path extractors |
utils |
Yes | HMAC webhooks, background worker tasks, Redis idempotency keys, Bloom filters (in-memory + Valkey/Redis) |
abac |
No | Attribute-Based Access Control policies and SQL filter builder |
cedar |
No | Amazon Cedar policy engine evaluation in scyph-abac |
notify |
No | Notification abstractions |
email |
No | SMTP transactional emails via Lettre & Tera templates |
fcm |
No | Firebase Cloud Messaging push notifications |
realtime |
No | Redis Pub/Sub WebSocket broadcaster |
storage |
No | Object storage traits and multipart upload extractors |
s3 |
No | AWS S3 and MinIO backend in scyph-storage |
image |
No | Automatic image thumbnail generation and resizing |
ratelimit |
No | IP-based rate limiting middleware |
🤝 Contributing & AI Policy
Contributions, issues, and feature proposals are welcome! Before submitting a pull request, please keep our standards in mind:
A Note on AI Usage: While we heavily use AI as a tool for boilerplate scaffolding, documentation, and repetitive plumbing, we are very strict against AI slop.
Every submission must be thoughtful, intentional, and strictly verified. If a pull request looks or feels like unreviewed, low-effort AI-generated slop—hallucinated implementations, shallow abstractions, or untested code—it will be rejected immediately. Take pride in your code, benchmark and test your changes, and make sure you truly understand everything you submit.
🛡️ License
Dual-licensed under either:
- MIT License (LICENSE-MIT)
- Apache License, Version 2.0 (LICENSE-APACHE)
at your option.