nelthaarion/breeze

Breeze — High-Performance Golang Network Framework - nelthaarion/breeze

69 stars · 7 forks · Go Topics: go, api, golang, template, performance, opensource, framework, web, dashboard, scalar, web-framework, openapi3, golang-web, go-framework, opensource-projects

README

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.

Fork the repository Create a feature branch (git checkout -b feat/my-thing) Commit your changes with a clear message 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.

source

nelthaarion/breeze: Breeze — High-Performance Golang Network Framework - nelthaarion/breeze