Breeze

A ridiculously fast, event-driven Go web framework built for maximum throughput, minimal allocations, native WebSockets, and production-ready APIs.

---

Breeze is a modern, high-performance Go web framework engineered for developers who demand speed without sacrificing developer experience. Built on an event-driven architecture, Breeze minimizes allocations, optimizes every request path, and provides first-class support for REST APIs, WebSockets, middleware, and automatic OpenAPI documentation.

Whether you're building microservices, real-time applications, or high-throughput APIs, Breeze is designed to handle millions of requests efficiently while keeping your code clean and maintainable.

Table of Contents

• Installation
• Quick Start
• Docker
• CLI — Scaffolding & Code Generation
• Features
  • Built for Extreme Performance
  • High-Performance Routing
  • Native WebSocket Engine
    • Built-in OpenAPI / Scalar
    • gRPC Code Generation
  • Production Middleware
  • Built-in Developer Dashboard
  • Developer Experience
  • Performance Optimizations
• Support the Project
• Contributing
• Security Scanning
• License

Installation

Requires Go 1.25.12 or later.

go get github.com/nelthaarion/breeze

The module pulls in gnet v2 for the event loop, go-json for fast JSON marshaling, brotli for compression, and golang-jwt/jwt for authentication.

📖 Full documentation: https://nelthaarion.github.io/breeze

Quick Start

A complete working server in under 20 lines:

package main

import (
    "runtime"

    "github.com/nelthaarion/breeze"
    middleware "github.com/nelthaarion/breeze/middlewares"
)

func main() {
    router := breeze.NewRouter()

    router.Use(middleware.RecoveryMiddleware())
    router.Use(middleware.LoggingMiddleware())

    router.Handle(breeze.GET, "/", func(ctx *breeze.Context) {
        ctx.JSON(map[string]string{"status": "ok"})
    })

    router.Handle(breeze.GET, "/users/:id", func(ctx *breeze.Context) {
        ctx.JSON(map[string]string{"id": ctx.Param("id")})
    })

    pool := breeze.NewWorkerPool(runtime.NumCPU())
    app  := breeze.New(router, pool)
    app.Run(3000, true) // port, multiCore
}

Run it:

go run main.go
# → curl http://localhost:3000/        → {"status":"ok"}
# → curl http://localhost:3000/users/42 → {"id":"42"}

Docker

The repository ships a multi-stage Dockerfile and docker-compose.yml that containerize the example server in ./cmd (~25 MB image, static binary, non-root user, built-in healthcheck):

# Plain Docker
docker build -t breeze-example .
docker run --rm -p 3000:3000 breeze-example

# Or with Compose
docker compose up --build

Breeze itself is a library — to containerize your own application, point the BREEZE_TARGET build argument at any main package in the module:

docker build --build-arg BREEZE_TARGET=./cmd/dashboard-example -t my-app .

🧰 CLI — Scaffolding & Code Generation

Breeze ships a rails-style CLI for scaffolding projects and generating CRUD boilerplate.

go install github.com/nelthaarion/breeze/cmd/breeze@latest

Start a new project:

breeze new myapp                    # minimal REST API layout (default)
breeze new myapp --template=views   # + views/components/template engine

Generate a full CRUD resource — structs, handlers, an in-memory store, and OpenAPI docs, wired into the router automatically:

breeze generate resource User name:string email:string age:int

Generate a bare handler stub (no structs, no docs):

breeze generate handler Session --methods=get,create

Generate gRPC server/client scaffolding from an interface declared in any *_grpc.go file — no naming convention on methods, just a grpc_type comment (Unary, ServerSideStreaming, ClientSideStreaming, or Bidirectional) above each method:

breeze generate grpc UserService

The resource and handler generators write to handlers/<name>.go and register routes in a single routes_generated.go file — your hand-written main.go is never touched. Re-running generate for the same resource replaces its block, so it's safe to regenerate after adding fields (pass --force to overwrite the handler file too). The grpc generator writes its own server/client/adapter files alongside the *_grpc.go interface it was generated from, and also supports --force to overwrite them.

Supported field types: string, int, int64, float64, bool, time.Time.

Features

🚀 Built for Extreme Performance

• ⚡ Event-driven architecture powered by gnet
• 🧠 Zero-copy HTTP request parsing where possible
• 📦 Minimal allocations via pooled Context, HTTPResponse, and route parameter maps (sync.Pool)
• 🔥 Optimized response serialization (precomputed status-line table, preallocated buffer, no fmt.Sprintf)
• 🧵 Configurable Worker Pool backpressure (OverflowBlock / OverflowReject / OverflowSpawn)
• 🌲 Single-allocation middleware chain construction in the router
• 💨 Lock-free fast paths for critical operations
• 🎯 Preallocated buffers & cached status codes
• 📈 Worker Pool for scalable request processing

🌐 High-Performance Routing

• ⚡ Fast HTTP router
• 🎯 Dynamic route parameters
• 🌲 Wildcard routing
• 📂 Static file serving
• 🧩 Global middleware pipeline
• 🔍 Optimized route matching

🔌 Native WebSocket Engine

• ⚡ Zero-overhead HTTP → WebSocket upgrade
• 🔥 Dedicated WebSocket fast path
• 📡 Binary & Text frames
• ❤️ Ping / Pong support
• 🔄 Fragmented frame handling
• 🚪 Graceful close frames
• 🧵 Concurrent connection management

📚 Built-in OpenAPI / Scalar

• 📖 Automatic OpenAPI 3.1 generation
• 📝 Route registration
• 🎯 Schema generation
• 🔍 Typed request & response definitions
• 🌍 Ready for Scalar API Reference

📡 gRPC Code Generation

• 🔎 Auto-detects gRPC services from any *_grpc.go interface file — no naming convention required
• 🏷 Call style (Unary, ServerSideStreaming, ClientSideStreaming, Bidirectional) set per-method via a grpc_type comment annotation
• 🧩 Generates server/client scaffolding and adapters with breeze generate grpc <InterfaceName>

🛡 Production Middleware

• 🚦 Rate Limiter
• 🗜 Compression
• 💾 Response Cache
• 🔑 JWT Authentication
• 🌍 CORS
• 🪖 Security Headers
• 📝 Request Logger
• 💥 Panic Recovery

📊 Built-in Developer Dashboard

• 🔧 Native module under /dashboard (zero-overhead when disabled)
• 📈 Real-time overview: RPS, latency, memory, goroutines, CPU
• 🛣 Routes Explorer with per-route latency stats
• 🧪 API Explorer with multi-language code generation (curl / Go / JS / Python / C# / PHP)
• 📡 Live Requests feed with WebSocket push
• 🗄 Database Browser (paginated; optional inline Create/Update/Delete via DBWriter)
• 🔍 ORM Query Monitor with slow-query detection
• 💾 Cache, Queue, and Scheduler monitors
• 📝 Logs with five tabs (App / HTTP / Errors / Panics / Warnings)
• ❤️ Health checks with green / yellow / red indicators
• ⚡ Go runtime performance metrics with charts
• 🕒 Developer Timeline — per-request profiler with expandable steps
• 🔒 HTTP Basic Auth + secret masking (Authorization, Cookie, API keys…)
• 🌑 Modern dark mode, responsive, single-file SPA (no external deps)

See dashboard/README.md for full documentation.

⚙️ Developer Experience

• 📦 Lightweight architecture
• 🎨 JSON responses out of the box
• 📄 Template rendering
• 📁 Static assets
• 🔍 Request validation
• 🧩 Simple Context API

🧠 Performance Optimizations

• Zero-copy body handling
• Header reuse
• Copy-on-write headers
• Cached HTTP status text
• Unsafe string conversions
• Compact receive buffers
• Optimized HTTP parser
• Single-pass header parsing
• Reduced GC pressure

---

🤝 Contributing

We welcome contributions of all sizes.

Whether it's fixing bugs, improving documentation, optimizing performance, or adding new features — every contribution helps make Breeze better.

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-thing)
3. Commit your changes with a clear message
4. Open a pull request describing what and why

Please open an issue first for non-trivial changes so we can align on the approach before you spend time on code.

🔐 Security Scanning

Breeze now includes automated security checks in GitHub Actions:

• CodeQL static analysis (.github/workflows/codeql.yml)
• govulncheck vulnerability scanning for Go packages and reachable code (.github/workflows/govulncheck.yml)
• Gitleaks secret scanning (.github/workflows/secret-scan.yml)
• Dependabot weekly updates for Go modules and GitHub Actions (.github/dependabot.yml)

For repository admins:

• Enable GitHub Advanced Security secret scanning and push protection in repository settings when available.
• Configure branch protection to require the three security workflow checks before merge.
• Use the triage process in .github/SECURITY_TRIAGE.md to classify and resolve alerts.

License

Breeze is released under the MIT License.

© Nelthaarion