Changelog¶

All notable changes to Cello are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.0.1] - 2026-02-21 -- Production-Ready Stable Release¶

Cello v1.0.1 is the first production-ready stable release of the framework. After ten iterative pre-release versions, the entire public API is now frozen under Semantic Versioning. No breaking changes will be introduced until v2.0. This release consolidates 32,000+ lines of Rust and 6,000+ lines of Python into a cohesive, enterprise-grade web framework capable of sustaining 170,000+ requests per second with 4 workers (5 processes) -- 1.9x faster than BlackSheep+Granian, 3.1x faster than FastAPI+Granian, and 5.9x faster than Robyn.

Performance¶

170,000+ requests/second benchmark throughput (4 workers, 5 processes, wrk 12t/400c/10s), achieving C-level performance on the hot path
SIMD JSON (simd-json 0.13): hardware-accelerated JSON parsing and serialization, up to 10x faster than Python's json module
Zero-copy radix tree routing (matchit 0.7): O(log n) route matching with compile-time optimization and zero allocations per lookup
Arena allocators (bumpalo 3): per-request arena allocation eliminates heap fragmentation and reduces allocator pressure
Handler metadata caching: async detection (inspect.iscoroutine) and DI parameter introspection are computed once per handler and cached, eliminating per-request reflection overhead
Lazy query parsing: query string decoding is skipped entirely when the query string is empty
Lazy body reading: GET, HEAD, OPTIONS, and DELETE requests skip body reading entirely
Pre-allocated headers: HashMap::with_capacity() eliminates rehashing during header collection
Fast-path skip for empty middleware chains, guards, and lifecycle hooks: no overhead when features are unused
Atomic has_py_singletons check: replaces RwLock with AtomicBool for DI singleton existence, removing lock contention
Multi-process workers (SO_REUSEPORT): fork N worker processes, each with its own GIL and Tokio runtime, with kernel-level connection distribution for near-linear core scaling
Direct Python-to-JSON bytes serialization: handler dict/list returns are serialized directly to JSON bytes in a single pass, skipping intermediate serde_json::Value tree allocation
Sampled latency recording: write lock contention eliminated by sampling every 64^th request instead of recording all
TCP_NODELAY on accepted connections: Nagle's algorithm disabled for lower latency
HTTP/1.1 keep-alive and pipeline flush: connection reuse and pipelining enabled by default
Zero-copy response body building: response bodies use Bytes::copy_from_slice for efficient transfer
Thread-local cached regex: OpenAPI path parameter regex compiled once per thread instead of per call
Async middleware lock optimization: middleware chain collects Arc references under a short read lock, then releases the lock before any await
Optimized release profile: lto = "fat", panic = "abort", strip = true, codegen-units = 1, overflow-checks = false

Security Hardened¶

Path traversal prevention: static file serving validates all paths against directory traversal attacks (../, encoded variants)
CRLF header injection protection: response header values are validated to prevent HTTP response splitting
CORS specification compliance: strict adherence to the CORS specification including proper preflight handling, wildcard restrictions, and origin validation
Constant-time token comparison (subtle 2): JWT, API key, and session token validation uses constant-time equality to prevent timing side-channel attacks
CSRF cryptographic tokens: CSRF protection uses cryptographically random tokens with HMAC-SHA256 verification
Secure session cookie defaults: cookies are created with HttpOnly, Secure, and SameSite=Lax by default, preventing XSS, man-in-the-middle, and CSRF attacks
Content Security Policy (CSP): configurable CSP header builder prevents XSS and data injection attacks
HSTS: HTTP Strict Transport Security headers enforce HTTPS connections
X-Frame-Options, X-Content-Type-Options, X-XSS-Protection: additional security headers enabled by default

Core Features¶

HTTP routing: full support for GET, POST, PUT, DELETE, PATCH, HEAD, and OPTIONS methods via decorator-based route registration
Blueprint route grouping: Flask-inspired blueprints for organizing routes into modular groups with shared prefixes and middleware
Response types: JSON, Text, HTML, Redirect, Binary, Streaming, XML, and NoContent response builders
Dependency injection: Depends() function with automatic parameter resolution, singleton support, and hierarchical scoping
Background tasks: fire-and-forget async task execution that runs after the response is sent
Template engine: Jinja2 template rendering integration for server-side HTML generation
Lifecycle hooks: @app.on_event("startup") and @app.on_event("shutdown") decorators for application lifecycle management
Route constraints: typed path parameters with int, UUID, and regex constraints
RFC 7807 Problem Details: structured error responses following the RFC 7807 standard

Middleware Suite (16 Built-in)¶

All middleware is implemented in Rust for maximum performance:

CORS (cors.rs): Cross-Origin Resource Sharing with configurable origins, methods, headers, credentials, and max-age
Compression (flate2): gzip response compression for responses exceeding configurable size thresholds
Logging: structured request/response logging with configurable formats
JWT Authentication (auth.rs): JWT token validation with configurable algorithms, API key auth, and Basic auth
Rate Limiting (rate_limit.rs): three algorithms -- token bucket, sliding window, and adaptive (load-based adjustment monitoring CPU, memory, and latency)
Session Management (session.rs): secure cookie-based sessions with configurable TTL, HttpOnly, Secure, and SameSite defaults
Security Headers (security.rs): Content-Security-Policy, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy
CSRF Protection (csrf.rs): cryptographic token generation and validation with HMAC-SHA256
ETag Caching (etag.rs): automatic ETag generation and 304 Not Modified responses for conditional requests
Smart Caching (cache.rs): route-specific caching with TTL, tag-based invalidation, and @cache decorator
Body Size Limits (body_limit.rs): configurable request body size limits to prevent memory exhaustion
Static File Serving (static_files.rs): efficient file serving with MIME type detection, caching headers, and path traversal prevention
Request ID Tracing (request_id.rs): UUID-based request ID generation and propagation via X-Request-ID header
Prometheus Metrics (prometheus.rs): request count, latency histograms, and in-flight request gauges at /metrics
Circuit Breaker (circuit_breaker.rs): fault tolerance with configurable failure threshold, reset timeout, and half-open state
Global Exception Handler (exception_handler.rs): centralized error handling with custom exception-to-response mapping

Real-time¶

WebSocket support (tokio-tungstenite 0.21): full-duplex WebSocket connections with message handling
Server-Sent Events (SSE): unidirectional server-to-client event streaming for real-time updates
Multipart form handling (multer 3): streaming multipart file upload parsing

Data Layer¶

Database connection pooling: async PostgreSQL connection pool with configurable pool size, max lifetime, idle timeout, and health monitoring
Redis integration: async Redis client with connection pooling, Pub/Sub, cluster mode, and Sentinel support
Transaction support: context-managed database transactions with automatic rollback on failure and nested savepoint support

Enterprise Patterns¶

Event Sourcing: aggregate root pattern, event store with configurable backends (PostgreSQL, in-memory), event replay, snapshots, and event versioning
CQRS: command/query separation with dedicated CommandBus and QueryBus, handler registration via decorators, and event-driven synchronization
Saga Pattern: distributed transaction coordination with step-by-step execution, compensation logic, automatic rollback, persistent state, and configurable retries

API Protocols¶

GraphQL engine: query, mutation, and subscription support with DataLoader for N+1 prevention, schema builder, and WebSocket subscriptions
gRPC support: GrpcService base class, @grpc_method decorator, bidirectional streaming, gRPC-Web for browser clients, and reflection service

Message Queues¶

Kafka integration: @kafka_consumer and @kafka_producer decorators with consumer group management and dead letter queue handling
RabbitMQ integration: configurable RabbitMQ client with message acknowledgement
AWS SQS integration: SQS adapter with LocalStack support for local development

Observability¶

OpenTelemetry tracing: distributed tracing with context propagation, OTLP export, and automatic HTTP instrumentation
Health checks: Kubernetes-compatible liveness, readiness, and startup probes at /health/live, /health/ready, /health/startup
Prometheus metrics: request throughput, latency percentiles, error rates, and custom metrics at /metrics
Structured logging: JSON-formatted logging with trace context injection and per-component log levels

Server¶

Cluster mode: multi-worker deployment with pre-fork process management via ClusterConfig
TLS (rustls 0.22): native TLS termination without OpenSSL dependency
HTTP/2 (h2 0.4): full HTTP/2 protocol support with multiplexing and server push
HTTP/3 (quinn 0.10): QUIC-based HTTP/3 protocol support for reduced connection latency

Developer Experience¶

OpenAPI/Swagger auto-generation: automatic OpenAPI 3.0 schema generation from route definitions with interactive Swagger UI
RBAC guards: composable RoleGuard and PermissionGuard with And/Or combinators for fine-grained access control
DTO validation: Pydantic integration for request payload validation with automatic 422 Unprocessable Entity error responses
20 example applications: comprehensive examples covering every feature from basic routing to advanced enterprise patterns
394 tests passing: full integration test suite covering all framework features

API Stability¶

All public APIs are now stable and follow Semantic Versioning
Classes and functions exported in cello.__all__ are frozen
Route decorator signatures, Request/Response APIs, middleware configuration, Blueprint API, Depends(), and the guard system are all part of the stable public API
No breaking changes will be introduced until v2.0.0

Fixed¶

Handler introspection overhead: per-request inspect module import eliminated via handler metadata caching
O(n) latency tracking: Vec::remove(0) replaced with VecDeque ring buffer for O(1) operations
Async middleware chain: eliminated per-request cloning of the entire middleware vector
DI container lock contention: RwLock replaced with AtomicBool for singleton existence check
GIL acquisition for empty lifecycle hook lists: empty hook lists now return immediately without touching the GIL
println! on circuit breaker hot path: replaced with tracing::warn! to avoid I/O blocking on state transitions
OpenAPI regex recompilation: path parameter regex now compiled once per thread via thread_local!

[0.10.0] - February 2026¶

Added¶

Event Sourcing with Aggregate base class and @event_handler decorator
Event base class for typed domain events with automatic serialization
EventStore for persisting and retrieving events with configurable backends
EventSourcingConfig for storage URL, snapshot interval, and replay settings
Snapshot support for optimized aggregate loading at scale
Event replay to rebuild aggregate state from the event log
CQRS with Command and Query base classes
CommandBus and QueryBus for dispatching operations to registered handlers
@command_handler and @query_handler decorators for handler registration
CqrsConfig for timeout settings and event synchronization
Saga Pattern with Saga base class and SagaStep definitions
SagaConfig for storage, retries, delay, and timeout settings
SagaResult with success status, completed steps, and error details
Automatic compensation (rollback) when any saga step fails
Persistent saga state for crash recovery
Event browser in development mode at /events
Saga dashboard in development mode at /sagas

Fixed¶

GraphQL subscription disconnects under high message throughput
gRPC reflection service not listing all methods after hot reload
Kafka consumer group rebalancing causing duplicate message processing
Health check endpoint returning 200 when event store is unreachable
Improved error message when saga compensation fails with non-retryable error

[0.9.0] - February 2026¶

Added¶

GraphQL support with Query, Mutation, Subscription decorators
DataLoader for N+1 query prevention with batching and caching
Schema builder with fluent API for composing GraphQL schemas
gRPC support with GrpcService base class and @grpc_method decorator
GrpcServer and GrpcChannel for server/client communication
GrpcConfig with reflection, gRPC-Web, and keepalive support
Kafka integration with @kafka_consumer and @kafka_producer decorators
RabbitMQ integration with RabbitMQConfig
AWS SQS integration with SqsConfig and LocalStack support
Message class with text, json, ack, nack methods
MessageResult constants (ACK, NACK, REJECT, REQUEUE, DEAD_LETTER)
Producer and Consumer classes for manual message control
GrpcError with all standard gRPC status codes

Fixed¶

Database connection pool not releasing connections on handler timeout
Redis hgetall returning empty dict for non-existent keys
@transactional decorator not propagating exceptions in nested async calls
Health check endpoint returning 200 when database is down
Memory leak in long-running WebSocket connections
Improved error message when maturin develop is not run before import

[0.8.0] - 2026-02-15¶

Added¶

Features¶

Database Connection Pooling (Enhanced):
High-performance async database connections with improved pool management.
Support for PostgreSQL, MySQL, and SQLite.
Configurable pool size, max lifetime, and idle timeout.
Redis Integration:
Async Redis client with connection pooling.
Pub/Sub support for real-time messaging.
Cluster mode and Sentinel support.
Transaction Support:
Context-managed database transactions.
Automatic rollback on failure.
Nested transaction support via savepoints.

Fixed¶

CORS Origins: Fixed handling of multiple allowed origins in CORS middleware.
Logs Typo: Corrected "loogs" typo in logging middleware output.
Response.error: Fixed Response.error method to properly set error status codes.

[0.6.0] - 2025-12-25¶

Added¶

Features¶

Smart Caching System:
@cache decorator for route-specific caching.
TTL support and tag-based invalidation (invalidate_cache).
Async middleware implementation for high performance.
Intelligent Adaptive Rate Limiting:
Adaptive algorithm that adjusts limits based on server load.
Monitors CPU, Memory, and Latency.
DTO Validation System:
Pydantic integration for request payload validation.
Automatic 422 Unprocessable Entity responses with detailed error messages.
Circuit Breaker:
Fault tolerance middleware to detect and isolate failing services.
Configurable failure threshold, reset timeout, and failure codes.
Lifecycle Hooks:
@app.on_event("startup") and @app.on_event("shutdown") decorators.
Database connection management and cleanup support.

Changed¶

Refactored Middleware architecture to support fully async execution (AsyncMiddleware).
Enhanced CacheMiddleware to support case-insensitive header checking.

[0.4.0] - 2024-12-16¶

Added¶

Enterprise Configuration Classes¶

TimeoutConfig - Request/response timeout settings
LimitsConfig - Connection and body size limits
ClusterConfig - Multi-worker deployment configuration
TlsConfig - TLS/SSL certificate configuration
Http2Config - HTTP/2 protocol settings
Http3Config - HTTP/3 (QUIC) protocol settings
JwtConfig - JWT authentication configuration
RateLimitConfig - Rate limiting with token bucket and sliding window
SessionConfig - Cookie-based session management
SecurityHeadersConfig - Security headers configuration
CSP - Content Security Policy builder
StaticFilesConfig - Static file serving configuration

Rust Modules¶

src/context.rs - Request context and dependency injection container
src/error.rs - RFC 7807 Problem Details error handling
src/lifecycle.rs - Hooks and lifecycle events (startup, shutdown, signals)
src/timeout.rs - Timeout and limits configuration
src/routing/ - Advanced routing with constraints (int, uuid, regex)
src/middleware/ - Complete middleware suite:
auth.rs - JWT, Basic, API Key authentication
rate_limit.rs - Token bucket, sliding window algorithms
session.rs - Cookie-based sessions
static_files.rs - Static file serving with caching
security.rs - CSP, HSTS, security headers
body_limit.rs - Request body size limits
request_id.rs - Unique request ID generation
csrf.rs - CSRF protection
etag.rs - ETag caching
cors.rs - CORS handling
src/response/ - Streaming responses, XML serialization
src/request/ - Lazy parsing, typed parameters, streaming multipart
src/server/ - Cluster mode, protocol support (TLS, HTTP/2, HTTP/3)

Dependencies (Cargo.toml)¶

jsonwebtoken - JWT authentication
dashmap - Concurrent HashMap for rate limiting
quick-xml - XML serialization
quinn - HTTP/3 (QUIC) support
tokio-rustls - TLS support
rustls - TLS implementation
tokio-util - Cancellation tokens
uuid - UUID generation
rand - Random number generation
base64 - Base64 encoding
hmac, sha2 - HMAC and SHA2 hashing
regex - Route constraints
h2 - HTTP/2 support

Documentation¶

Complete docs/ folder with guides
API reference documentation
Deployment guide
Security documentation

Examples¶

examples/enterprise.py - Enterprise configuration demo
examples/security.py - Security features demo
examples/middleware_demo.py - Middleware system demo
examples/cluster_demo.py - Cluster mode demo
examples/streaming_demo.py - Streaming responses demo

Changed¶

Updated to version 0.4.0
Updated python/cello/__init__.py with new exports
Updated examples to version 0.4.0

Notes¶

The enterprise modules have some internal API compatibility issues that need follow-up work. These modules are structurally complete but require integration work.

[0.3.0] - Previous Release¶

Features¶

SIMD-accelerated JSON parsing
Middleware system (CORS, logging, compression)
Blueprint-based routing
WebSocket support
Server-Sent Events (SSE)
Multipart form handling
Async handler support

[0.2.0] - Earlier Release¶

Features¶

Basic HTTP routing
Request/Response handling
Path and query parameters
JSON responses

[0.1.0] - Initial Release¶

Features¶

Core HTTP server with Tokio/Hyper
Basic routing
PyO3 Python bindings