README
ΒΆ
β‘ microfast
A blazing-fast, production-ready HTTP server built with Go and fasthttp.
Why microfast?
| Feature | Description |
|---|---|
| π High Performance | Built on fasthttp β up to 10x faster than net/http |
| π Secure by Default | Anti-panic recovery, security headers, rate limiting out of the box |
| π Observable | Built-in Prometheus metrics (/metrics) and health probe (/healthz) |
| β»οΈ Graceful Shutdown | Handles SIGINT/SIGTERM, waits for in-flight requests with timeout |
| 𧩠Modular Middleware | Composable chain β add logging, CORS, auth in one line |
| π³ Cloud Native | Tiny scratch-based Docker image, zero external dependencies at runtime |
| βοΈ Zero Config | Works out of the box with sensible defaults, fully tunable via env vars |
Quick Start
Prerequisites
- Go 1.22+ (tested with 1.23)
Install & Run
git clone https://github.com/888zxc/microfast.git
cd microfast
make run
That's it. The server is now running on http://localhost:8080.
Try It
curl http://localhost:8080/ # Welcome page
curl http://localhost:8080/healthz # Health check β "OK"
curl http://localhost:8080/version # Build version (JSON)
curl "http://localhost:8080/api/echo?msg=hello" # Echo API
curl http://localhost:8080/metrics # Prometheus metrics
Configuration
All settings are configurable via environment variables. No config files needed:
| Variable | Default | Description |
|---|---|---|
SERVER_PORT |
8080 |
Listen port |
LIMIT_PER_SEC |
20000 |
Max requests per second |
READ_TIMEOUT |
30s |
Request read timeout |
WRITE_TIMEOUT |
30s |
Response write timeout |
IDLE_TIMEOUT |
120s |
Keep-alive idle timeout |
SHUTDOWN_TIMEOUT |
30s |
Graceful shutdown deadline |
MAX_CONNS_PER_IP |
10000 |
Per-IP connection limit |
MAX_REQS_PER_CONN |
1000 |
Requests per connection |
Example:
SERVER_PORT=9000 LIMIT_PER_SEC=50000 ./microfast-server
Project Structure
microfast/
βββ cmd/server/main.go # Entry point
βββ config/ # Environment-based configuration
βββ internal/
β βββ handler/ # Route handlers + Prometheus metrics
β βββ middleware/ # Composable middleware chain
β βββ limiter/ # Lock-free rate limiter (atomic CAS)
β βββ logger/ # Structured logging (zap)
β βββ server/ # Server lifecycle & graceful shutdown
βββ pkg/version/ # Build-time version injection
βββ scripts/bench.go # Load testing tool
βββ openapi.yaml # OpenAPI 3.0 spec
βββ Makefile # Build, test, lint, docker commands
βββ dockerfile # Multi-stage scratch image
Development
Build
make build # Build binary
make build-version # Build with version injection
Test
make test # Run tests with race detector
make bench # Run benchmarks
make lint # Run golangci-lint
Docker
make docker-build # Build Docker image
make docker-run # Run in container
Middleware Stack
The request pipeline is fully composable:
Request β Recovery β RequestID β Logging β RateLimit β SecureHeaders β CORS β Handler
Each middleware is an independent function β add, remove, or reorder freely in internal/server/server.go.
Benchmarking
Built-in load generator:
# Start server first, then:
go run scripts/bench.go
# Or use wrk / hey:
wrk -t8 -c1000 -d10s http://localhost:8080/
hey -n 100000 -c 500 http://localhost:8080/healthz
API Reference
See openapi.yaml for the full OpenAPI 3.0 specification.
Preview it live at Swagger Editor.
| Endpoint | Method | Description |
|---|---|---|
/ |
GET | Welcome page |
/healthz |
GET | Health check (for K8s probes) |
/version |
GET | Build version (JSON) |
/api/echo |
GET | Echo ?msg= back as JSON |
/metrics |
GET | Prometheus metrics |
Contributing
Contributions are welcome! See CONTRIBUTING.md for guidelines.
Security
To report a vulnerability, see SECURITY.md.
License
MIT Β© ε½ζ¬ε¦ζ€
β Star this repo if you find it useful!
Directories
Click to show internal directories.
Click to hide internal directories.