Built for raw speed. Shipped clean.

3× faster. Not a typo.

Measured on a simple JSON endpoint, same machine, same payload.

• Breeze
  ~630k req/s
• Fiber
  ~210k req/s
• Echo
  ~140k req/s
• Gin
  ~120k req/s
• net/http
  ~85k req/s

* Approximate. Run benchmarks in your environment for authoritative numbers.

Installation

Requires Go 1.24.3 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.

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
}

Server Config

app.Run(port, multiCore) starts the gnet event loop with sensible defaults baked in.

app.Run(8080, true)   // multicore — one loop per CPU, recommended
app.Run(8080, false)  // single-core — useful for dev / debugging

Router

Create a router, register global middleware, then define routes. Routes support static segments, named parameters, and wildcards.

Methods

router := breeze.NewRouter()

// Global middleware (runs on every route)
router.Use(middleware.LoggingMiddleware())

// Static segment
router.Handle(breeze.GET,    "/health",        healthHandler)

// Named parameter — :id available via ctx.Param("id")
router.Handle(breeze.GET,    "/users/:id",     getUser)
router.Handle(breeze.POST,   "/users",         createUser)
router.Handle(breeze.PUT,    "/users/:id",     updateUser)
router.Handle(breeze.DELETE, "/users/:id",     deleteUser)

// Wildcard — *filepath captures everything after /files/
router.Handle(breeze.GET, "/files/*filepath", fileHandler)

// Per-route middleware (runs only on this route)
router.Handle(breeze.POST, "/admin/action", adminHandler,
    authMiddleware, auditMiddleware,
)

Route Matching Priority

Routes are matched in registration order. A static segment always beats a named parameter when both could match — register more specific routes first.

Context

Every handler receives a *breeze.Context. It carries the connection, parsed request, response, route params, and controls the middleware chain.

Response Helpers

// JSON — sets Content-Type: application/json, status 200
ctx.JSON(map[string]any{"id": 1, "name": "Alice"})

// Plain text
ctx.WriteString("Hello, World!")

// HTML
ctx.HTML([]byte("<h1>Hello</h1>"))

// Override status code (call after JSON/WriteString/HTML)
ctx.Status(201)

// Add/override a header
ctx.SetHeader("X-Request-Id", "uuid-123")

Middleware Chain

// Advance to the next handler in the chain
ctx.Next()

// Short-circuit — skip all remaining handlers
ctx.Abort()

// Typical middleware pattern
func AuthMiddleware(ctx *breeze.Context) {
    token := ctx.Req.Header["authorization"]
    if token == "" {
        ctx.Status(401)
        ctx.WriteString("Unauthorized")
        ctx.Abort()  // ← stops the chain here
        return
    }
    ctx.Next()  // ← continue to next handler
}

Request

ctx.Req is a *breeze.HTTPRequest parsed from raw bytes with zero unnecessary allocations.

method := ctx.Req.Method          // breeze.Method ("GET", "POST", …)
path   := ctx.Req.Path            // "/users/123"
ct     := ctx.Req.Header["content-type"]  // headers are lowercased

var payload CreateUserRequest
json.Unmarshal(ctx.Req.Body, &payload)

page  := ctx.Query("page")   // "2"
limit := ctx.Query("limit")  // "20"

Response

ctx.Res is a *breeze.HTTPResponse. Breeze serializes it to raw HTTP/1.1 bytes using strconv.AppendInt — no fmt.Sprintf, pre-sized buffer, array-indexed status text.

You rarely set ctx.Res directly — use the helpers (JSON, WriteString, HTML, Status, SetHeader) instead.

Params & Query

// Route: /users/:id/posts/:postId
userID := ctx.Param("id")         // "abc"
postID := ctx.Param("postId")     // "42"

// Query: /search?q=go&page=2
q    := ctx.Query("q")            // "go"
page := ctx.Query("page")         // "2"

// Middleware can pass data downstream
ctx.SetParam("userID", "from-auth")
uid := ctx.GetParam("userID")     // "from-auth"

all := ctx.GetParams()            // map[string]string (copy)

Template Engine new

Breeze ships a full server-side HTML template engine powered by Go's html/template package. It supports layouts, reusable components, automatic SPA partial rendering, a reactive client-side data store, and hot-reload dev mode — with zero external dependencies.

Setup & Config

Create a TemplateEngine with NewTemplateEngine, then wire it into the router. All fields have sensible defaults.

engine := breeze.NewTemplateEngine(breeze.TemplateConfig{
    ViewsDir:      "views",             // default: "views"
    ComponentsDir: "components",        // default: "components"
    LayoutFile:    "views/layout.html", // default: ViewsDir/layout.html
                                        // set "" to disable layout wrapping
    DevMode: false,                     // true: re-parse on every render (hot reload)
    FuncMap: template.FuncMap{          // optional: add custom template funcs
        "upper": strings.ToUpper,
    },
})

Directory Structure

Breeze expects two separate directories — one for full-page views and one for reusable components. The layout file lives inside the views directory.

Every component file uses {{define "name"}}…{{end}}. View files use {{define "content"}}…{{end}}. The layout file uses {{define "layout"}}…{{end}}.

Views & Layout

A view is a .html file inside ViewsDir that defines a "content" block. The layout wraps every view by embedding that block via {{template "content" .}}.

Layout file — views/layout.html

{{define "layout"}}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My App</title>
  <link rel="stylesheet" href="/public/app.css">
</head>
<body>
  {{component "nav" .}}
  <div id="breeze-app">
    {{template "content" .}}    <!-- view content goes here -->
  </div>
</body>
</html>
{{end}}

View file — views/home.html

{{define "content"}}
<div class="page">
  <h1>Welcome, {{ .Data.Name }}!</h1>

  {{component "card" (map "title" "Hello" "body" "World")}}<!-- component with inline data -->

  <ul>
  {{range .Data.Items}}
    <li>{{ .Name }} — ${{ .Price }}</li>
  {{end}}
  </ul>
</div>
{{end}}

Inside templates, .Data holds the value returned by your handler's data function. The outer . is a TemplateData struct which also exposes .IsPartial.

TemplateData wrapper

Every render wraps your data in a TemplateData struct before passing it to the template. You access your data through .Data, not . directly:

Disabling the layout

Set LayoutFile: "" in TemplateConfig to render views without a shared layout. The view template itself is executed directly.

Components

Components are reusable HTML fragments that live in ComponentsDir. Each file defines a named template block using {{define "name"}}…{{end}}.

Component file — components/card.html

{{define "card"}}
<div class="card">
  <h3>{{ .title }}</h3>
  <p>{{ .body }}</p>
</div>
{{end}}

Using a component inside a view

Use the built-in component function (or its alias partial) to embed a component inline:

<!-- Pass the parent data straight through -->
{{component "nav" .}}

<!-- Build a map inline with the map helper -->
{{component "card" (map "title" "Hello" "body" "World")}}

<!-- Pass a field from your page data -->
{{component "stats" .Data.StatsPayload}}

<!-- partial is an alias for component -->
{{partial "card" (map "title" "Alt syntax" "body" "Same thing")}}

Rendering a component from a handler

To serve a component as a bare HTML fragment (no layout, no SPA script) — useful for polling endpoints:

engine.RenderComponent(ctx, "stats", StatsData{Count: 42, Time: "12:00:00"})

Built-in Template Functions

Breeze registers these functions automatically in addition to Go's standard template functions:

Custom functions

Add your own functions via TemplateConfig.FuncMap:

engine := breeze.NewTemplateEngine(breeze.TemplateConfig{
    FuncMap: template.FuncMap{
        "upper":   strings.ToUpper,
        "format":  func(t time.Time) string { return t.Format("Jan 2, 2006") },
        "dollars": func(cents int) string { return fmt.Sprintf("$%.2f", float64(cents)/100) },
    },
})

// Use in a template:
// {{upper .Data.Name}}
// {{format .Data.CreatedAt}}

Route Helpers

Three methods on *Router integrate the template engine with routing:

router.View — full-page view route

Registers a GET route that renders a named view, wrapped in the layout. The optional data function receives the request context and returns data for the template.

// Static view — no data
router.View("/", engine, "home", nil)

// Dynamic view — data function called on each request
router.View("/about", engine, "about", func(ctx *breeze.Context) any {
    return map[string]any{"title": "About Us", "Year": 2026}
})

// View with database fetch
router.View("/users", engine, "users", func(ctx *breeze.Context) any {
    return db.GetAllUsers()
})

router.Fragment — bare HTML fragment route

Registers a GET route that renders a single component as a bare HTML fragment — no layout, no SPA script injection. Designed to be consumed by breeze.fetch() or breeze.poll() on the client.

// Serve the "stats" component at /fragments/stats
router.Fragment("/fragments/stats", engine, "stats", func(ctx *breeze.Context) any {
    return StatsData{Count: getActiveUsers(), Time: time.Now().Format("15:04:05")}
})

// Then poll it from any template:
// <div id="stats-box"></div>
// <script>breeze.poll('/fragments/stats', '#stats-box', 2000)</script>

ctx.Render — render from a handler

Renders a view directly inside any handler, with full control over what data is passed.

router.Handle(breeze.GET, "/search", func(ctx *breeze.Context) {
    q := ctx.Query("q")
    ctx.Render(engine, "home", map[string]any{
        "SearchQuery": q,
        "Results":     db.Search(q),
    })
})

Page Data

When a full page is rendered, Breeze serializes your data as JSON and embeds it in the page inside a non-executing script tag. This makes the data available to client-side JavaScript without a separate API call.

<script id="__breeze_data__" type="application/json">{"name":"Alice","count":42}</script>

Read it client-side with breeze.data():

const all  = breeze.data();        // { name: "Alice", count: 42 }
const name = breeze.data("name"); // "Alice"

The data object is also available from any breeze.watch() subscriber and can be replaced with breeze.setData(newData).

SPA Runtime

On every full-page render, Breeze injects a self-contained JavaScript runtime just before </body>. It turns your multi-page app into a single-page app automatically — no configuration required.

How SPA navigation works

• Every <a href="…"> click is intercepted by a document-level event listener.
• The runtime sends a fetch() to the same URL with the header X-Breeze-Partial: true.
• The server detects the header and returns only the {{define "content"}}…{{end}} block — no layout, no runtime script.
• The client replaces #breeze-app's innerHTML with the fragment and calls history.pushState.
• The browser URL updates; back/forward navigation is handled via popstate.

Opt out of SPA navigation

Add data-no-spa to any link to trigger a full browser navigation instead:

<a href="/download/report.pdf" data-no-spa>Download PDF</a>

Links that are already excluded automatically: external URLs, target="_blank", anchors (href="#..."), mailto:, tel:.

Lifecycle hooks

Register callbacks on the global Breeze object (note the capital B) before navigation fires:

// Return false from any before-hook to cancel the navigation / submit
Breeze.onBeforeNavigate(function(e) {
    console.log('navigating to', e.url);
    // return false; // ← uncomment to cancel
});

Breeze.onAfterNavigate(function(e) {
    console.log('navigated to', e.url);
    analytics.track('pageview', e.url);
});

Breeze.onBeforeSubmit(function(e) {
    console.log('submitting', e.form, 'to', e.url);
});

Breeze.onAfterSubmit(function(e) {
    console.log('submitted to', e.url, 'html length:', e.html.length);
});

Loading state

During any navigation or form fetch, Breeze adds breeze-loading to document.body. Use it in CSS to show a visual indicator:

/* Dim the content while loading */
body.breeze-loading #breeze-app {
    opacity: 0.55;
    transition: opacity .15s;
}

/* Or show a top progress bar */
body.breeze-loading::before {
    content: '';
    position: fixed; top: 0; left: 0; right: 0; height: 3px;
    background: var(--accent);
    animation: loading-bar .8s ease infinite;
}

DOM events

Script Lifecycle

When the SPA runtime swaps content into #breeze-app, it re-runs scripts found in the new fragment according to these rules:

<!-- Runs on every SPA navigation — good for starting polls -->
<script data-spa-run="always">
  breeze.poll('/fragments/stats', '#stats-box', 2000);
</script>

<!-- Runs once per page lifecycle — good for analytics, one-time init -->
<script data-spa-run="once">
  analytics.init({ page: window.location.pathname });
</script>

<!-- No attribute — only runs on hard page load (default) -->
<script>
  const ws = breeze.ws('/ws', { onMessage: e => console.log(e.data) });
</script>

SPA Forms

The runtime automatically intercepts <form> submits and handles them without a full page reload — progressive enhancement means forms still work without JavaScript.

GET forms

Form fields are serialized to a query string and the result is navigated to via the SPA router:

<form action="/search" method="GET">
  <input name="q" placeholder="Search…">
  <button type="submit">Search</button>
</form>
<!-- Navigates to /search?q=value without a reload -->

POST forms

Submitted via fetch(). The response HTML is swapped into #breeze-app. Control the request body encoding with data-content-type:

<!-- Default: application/x-www-form-urlencoded -->
<form action="/contact" method="POST">
  <input name="email" type="email">
  <button type="submit">Subscribe</button>
</form>

<!-- JSON body: form fields serialised as a JSON object -->
<form action="/api/users" method="POST" data-content-type="application/json">
  <input name="name" type="text">
  <input name="email" type="email">
  <button type="submit">Create user</button>
</form>

Opting out

The runtime skips interception automatically for:

• enctype="multipart/form-data" — file uploads are always sent as a real browser submit.
• target="_blank" — opens in a new tab, not swapped in.
• External action URLs (different origin).
• data-spa="false" — explicit opt-out for any form.

<form action="/download" method="POST" data-spa="false">
  <button type="submit">Download (full reload)</button>
</form>

Client API — breeze.*

The runtime injects a window.breeze object with utilities for fetching fragments, polling, navigation, reactive data, re-rendering, and WebSocket connections.

Fragment fetching

// Fetch a fragment and swap it into a target element
await breeze.fetch('/fragments/stats', '#stats-box');

// With options
await breeze.fetch('/api/partial', '#target', {
    method: 'POST',
    body: JSON.stringify({ id: 42 }),
    headers: { 'Content-Type': 'application/json' },
    onSuccess: (html, el) => console.log('updated', el),
    onError:   (err, el) => console.error(err),
});

Polling

// Auto-refresh every 2 seconds
breeze.poll('/fragments/stats', '#stats-box', 2000);

// Stop polling on a target element
breeze.stop('#stats-box');

Navigation & swap

// Programmatic SPA navigation (pushes history)
breeze.navigate('/about');

// Directly swap HTML into an element (no fetch)
breeze.swap('#target', '<p>Hello</p>');

Reactive data store

// Read page data (embedded as JSON at render time)
const data = breeze.data();           // entire object
const name = breeze.data("name");     // single key

// Replace store and optionally re-render a component
await breeze.setData({ count: 99 }, '#stats-box', 'stats');

// Watch for data changes
const unsubscribe = breeze.watch(data => {
    document.title = `Count: ${data.count}`;
});
// Later: unsubscribe();

Client-side re-render

Renders a view or component on the client using embedded template sources — no server round-trip. If the template source is not embedded, falls back to the POST /breeze/render endpoint automatically.

// Re-render the "card" component with new data into #my-card
await breeze.render('card', { title: 'Updated', body: 'New content' }, '#my-card');

// Re-render using the current store data
await breeze.render('stats', undefined, '#stats-box');

WebSocket

const conn = breeze.ws('/ws', {
    onOpen:    (e) => console.log('connected'),
    onMessage: (e) => console.log('msg:', e.data),
    onClose:   (e) => console.log('closed'),
    onError:   (e) => console.error(e),
});

conn.send('hello server');   // send a text message
conn.close();                // gracefully close
// conn.socket — access the raw WebSocket object

The WebSocket connection auto-reconnects with exponential backoff (1 s → 30 s max) if the connection drops.

Full client API reference

Re-render Endpoint

Call router.EnableReRender(engine) once at startup to register POST /breeze/render. The client-side breeze.render() uses this endpoint when the template source is not embedded locally.

engine := breeze.NewTemplateEngine(breeze.TemplateConfig{...})
router.EnableReRender(engine)  // registers POST /breeze/render

The endpoint accepts a JSON body with either "component" or "view" (component takes precedence):

// Render a component
{ "component": "card", "data": { "title": "Hello", "body": "World" } }

// Render a view's content block
{ "view": "home", "data": { "name": "Alice" } }

You can also call it directly from JavaScript without using breeze.render():

const res = await fetch('/breeze/render', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ component: 'stats', data: { Count: 99, Time: '12:00' } }),
});
document.querySelector('#stats-box').innerHTML = await res.text();

Dev Mode

Set DevMode: true in TemplateConfig to disable template caching. Every request re-parses the template files from disk, so changes to .html files are reflected immediately without restarting the server.

engine := breeze.NewTemplateEngine(breeze.TemplateConfig{
    DevMode: true, // disable in production — parsing on every request is expensive
})

Preload

Call engine.Preload() at startup (after all routes are registered) to parse all views and components eagerly. This surfaces template errors on startup rather than on the first request, and warms the cache so the first users don't pay the parse cost.

engine := breeze.NewTemplateEngine(breeze.TemplateConfig{...})

if err := engine.Preload(); err != nil {
    log.Fatalf("template parse error: %v", err)
}

// Register routes after Preload — Preload doesn't need to know about routes
router.View("/", engine, "home", nil)

Preload is a no-op in DevMode — templates are re-parsed on every request anyway.

Middleware

Every middleware is a HandlerFunc — composable, testable, and zero-dependency on each other.

import (
    "github.com/golang-jwt/jwt/v5"
    middleware "github.com/nelthaarion/breeze/middlewares"
)

accessToken, _  := middleware.GenerateJWT(
    "secret", jwt.MapClaims{"user_id": "abc", "role": "admin"},
    15*time.Minute, nil,
)
refreshToken, _ := middleware.GenerateRefreshToken("refresh-secret",
    jwt.MapClaims{"user_id": "abc"}, 7*24*time.Hour, nil)

router.Use(middleware.JWTAuthMiddleware(middleware.JWTOptions{
    AccessSecret:       "secret",
    RefreshSecret:      "refresh-secret",
    SigningMethod:      jwt.SigningMethodHS256,
    EnableRefreshToken: true,
    RequiredRoles:      []string{"admin"},
    UserContextKey:     "user",
    ClaimsValidator: func(claims jwt.MapClaims) bool {
        return claims["active"] == true
    },
    OnUnauthorized: func(ctx *breeze.Context, err error) {
        ctx.Status(401)
        ctx.JSON(map[string]string{"error": err.Error()})
    },
}))

router.Use(middleware.CORSMiddleware(middleware.CORSOptions{
    AllowOrigins:     "https://myapp.com",
    AllowMethods:     "GET,POST,PUT,DELETE,OPTIONS",
    AllowHeaders:     "Content-Type,Authorization",
    AllowCredentials: "true",
    MaxAge:           "86400",
}))
// OPTIONS preflight is handled automatically → 204 No Content

router.Use(middleware.NewRateLimiter(middleware.RateLimiterOptions{
    Requests: 100,
    Per:      time.Minute,
    Message:  "Slow down — rate limit exceeded",
}))

// Different limits per route
router.Handle(breeze.POST, "/login", loginHandler,
    middleware.NewRateLimiter(middleware.RateLimiterOptions{
        Requests: 5,
        Per:      time.Minute,
    }),
)
// Returns 429 Too Many Requests when exceeded

// Priority: br (Brotli) → gzip → deflate → none
router.Use(middleware.CompressionMiddleware())
// Sets Content-Encoding response header automatically

router.Use(middleware.DefaultSecurityMiddleware())

// Or fully custom
router.Use(middleware.SecurityMiddleware(middleware.SecurityOptions{
    ContentSecurityPolicy:     "default-src 'self'",
    XFrameOptions:             "DENY",
    XContentTypeOptions:       "nosniff",
    StrictTransportSecurity:   "max-age=63072000; includeSubDomains; preload",
    ReferrerPolicy:            "no-referrer",
    XXSSProtection:            "1; mode=block",
}))

router.Use(middleware.ScalarMiddleware(router, middleware.ScalarOptions{
    Title:    "My API",
    Version:  "1.0.0",
    JSONPath: "/Scalar.json",
    UIPath:   "/Scalar",
}))

router.Handle(breeze.POST, "/users", createUser,
    middleware.DocPOST("/users", Scalar.RouteDoc{
        Title: "Create user",
        Tags:  []string{"Users"},
        Input: []Scalar.InputGroup{
            {Type: Scalar.InputBody, Fields: CreateUserRequest{}, Required: true},
        },
        Output:       UserResponse{},
        OutputStatus: 201,
    }),
)
// Visit /Scalar → live Scalar UI

app := breeze.New(router, pool)
hub := app.WebSocket("/ws", &breeze.WSHandlerFunc{
    Connect: func(conn *breeze.WSConn) {
        conn.SendText("welcome")
    },
    Message: func(conn *breeze.WSConn, opcode byte, payload []byte) {
        hub.BroadcastText(string(payload))
    },
    Close: func(conn *breeze.WSConn, code uint16, reason string) {
        hub.BroadcastText("a user left")
    },
})

Logger middleware

Logs method, path, status, and elapsed time for every request. Output goes to stdout in RFC3339 format.

router.Use(middleware.LoggingMiddleware())
// Output: [Breeze][2026-06-23T12:00:00Z] GET /users -> 200 (1.2ms)

Panic Recovery middleware

Wraps the entire handler chain in a defer/recover. On panic: logs the value + full stack trace, sets 500, calls ctx.Abort(). Your server never crashes from a handler bug.

router.Use(middleware.RecoveryMiddleware())
// Register first so it wraps everything else

CORS middleware

Sets Access-Control-* headers and handles OPTIONS preflight automatically.

router.Use(middleware.CORSMiddleware(middleware.CORSOptions{
    AllowOrigins:     "*",
    AllowMethods:     "GET,POST,PUT,DELETE",
    AllowHeaders:     "Content-Type,Authorization",
    ExposeHeaders:    "X-Request-Id",
    AllowCredentials: "true",
    MaxAge:           "86400",
}))

Helmet middleware

Sets security-hardening HTTP headers. Use the opinionated defaults or configure individually.

router.Use(middleware.DefaultSecurityMiddleware())

router.Use(middleware.SecurityMiddleware(middleware.SecurityOptions{
    ContentSecurityPolicy:   "default-src 'self'; img-src *",
    XFrameOptions:           "SAMEORIGIN",
    StrictTransportSecurity: "max-age=31536000",
}))

JWT Auth middleware

Full JWT authentication with optional refresh token rotation, RBAC, and custom claims validation.

token, _   := middleware.GenerateJWT("secret", jwt.MapClaims{
    "user_id": "u-123", "role": "admin",
}, 15*time.Minute, nil)

refresh, _ := middleware.GenerateRefreshToken("refresh-secret",
    jwt.MapClaims{"user_id": "u-123"}, 7*24*time.Hour, nil)

router.Use(middleware.JWTAuthMiddleware(middleware.JWTOptions{
    AccessSecret:       "secret",
    RefreshSecret:      "refresh-secret",
    EnableRefreshToken: true,
    RequiredRoles:      []string{"admin", "editor"},
    UserContextKey:     "user",
}))

Custom Token Extraction

TokenLookup: func(ctx *breeze.Context) (string, string, error) {
    access  := ctx.Req.Header["x-access-token"]
    refresh := ctx.Req.Header["x-refresh-token"]
    if access == "" {
        return "", "", fmt.Errorf("token missing")
    }
    return access, refresh, nil
},

Rate Limiter middleware

In-memory token counter per remote IP. Resets after each Per window. Returns 429 Too Many Requests.

router.Use(middleware.NewRateLimiter(middleware.RateLimiterOptions{
    Requests: 100,
    Per:      time.Minute,
}))

router.Handle(breeze.POST, "/login", loginHandler,
    middleware.NewRateLimiter(middleware.RateLimiterOptions{
        Requests: 5,
        Per:      time.Minute,
        Message:  "Too many login attempts",
    }),
)

ETag Cache middleware

Computes an MD5 ETag from the response body. On matching If-None-Match, returns 304 Not Modified.

cache := middleware.NewETagCache()
router.Use(cache.ETagMiddleware())

Compression middleware

Negotiates the best encoding from the client's Accept-Encoding header. Priority: Brotli → Gzip → Deflate → none.

router.Use(middleware.CompressionMiddleware())
// Sets Content-Encoding: br / gzip / deflate automatically

Scalar / OpenAPI 3.1 new

Annotate routes at registration time using Go structs. No YAML, no code generation, no build step.

type CreateUserRequest struct {
    Name  string `json:"name"  description:"Full name"    example:"Alice"`
    Email string `json:"email" description:"Email address" example:"alice@example.com"`
}

router.Use(middleware.ScalarMiddleware(router, middleware.ScalarOptions{
    Title:    "Users API",
    Version:  "2.0.0",
    JSONPath: "/Scalar.json",
    UIPath:   "/Scalar",
}))

router.Handle(breeze.POST, "/users", createUser,
    middleware.DocPOST("/users", Scalar.RouteDoc{
        Title:        "Create user",
        Tags:         []string{"Users"},
        Input:        []Scalar.InputGroup{{Type: Scalar.InputBody, Fields: CreateUserRequest{}, Required: true}},
        Output:       UserResponse{},
        OutputStatus: 201,
    }),
)

WebSocket built-in

Breeze implements RFC 6455 WebSocket directly inside the gnet event loop — no goroutine-per-connection, no third-party WS library. After the HTTP upgrade handshake, the connection is promoted to WebSocket mode and all subsequent traffic bypasses the HTTP parser entirely.

type ChatHandler struct { hub *breeze.WSHub }

func (h *ChatHandler) OnConnect(conn *breeze.WSConn) {
    h.hub.BroadcastExcept(breeze.WsOpText, []byte("a user joined"), conn)
}
func (h *ChatHandler) OnMessage(conn *breeze.WSConn, opcode byte, payload []byte) {
    if opcode == breeze.WsOpText {
        h.hub.BroadcastText(fmt.Sprintf("[%s]: %s", conn.RemoteAddr(), payload))
    }
}
func (h *ChatHandler) OnClose(conn *breeze.WSConn, code uint16, reason string) {
    h.hub.BroadcastText("a user left")
}

func main() {
    router := breeze.NewRouter()
    app    := breeze.New(router, breeze.NewWorkerPool(runtime.NumCPU()))

    chat := &ChatHandler{}
    chat.hub = app.WebSocket("/ws", chat)

    app.Run(3000, true)
}

Handler Interface

type WSHandler interface {
    OnConnect(conn *WSConn)
    OnMessage(conn *WSConn, opcode byte, payload []byte)
    OnClose(conn *WSConn, code uint16, reason string)
}

// Inline shorthand — nil fields are no-ops
app.WebSocket("/ws/echo", &breeze.WSHandlerFunc{
    Connect: func(conn *breeze.WSConn) { conn.SendText("ready") },
    Message: func(conn *breeze.WSConn, opcode byte, payload []byte) {
        conn.Send(opcode, payload)
    },
})

WSConn

conn.SendText("hello")
conn.SendBinary([]byte{0x01, 0x02})
conn.Send(breeze.WsOpText, []byte("raw"))
conn.Close(1000, "bye")
addr := conn.RemoteAddr()

WSHub

hub := app.Hub()

hub.BroadcastText("server restarting in 10s")
hub.BroadcastBinary(data)
hub.Broadcast(breeze.WsOpText, []byte("raw"))
hub.BroadcastExcept(breeze.WsOpText, []byte(msg), senderConn)
n := hub.Count() // int64 — atomic read

// Multiple routes share the same hub
hub1 := app.WebSocket("/ws/chat",   chatHandler)
hub2 := app.WebSocket("/ws/events", eventsHandler)
// hub1 == hub2 == app.Hub()

Close Codes

gRPC Code Generation new

Breeze's CLI generates gRPC server and client scaffolding directly from a plain Go interface — no .proto file, no naming convention on your methods. Point it at any interface declared in a *_grpc.go file, annotate each method with a grpc_type comment, and run one command.

Call Type Annotations

Breeze doesn't infer streaming behaviour from method signatures or naming — it reads an explicit grpc_type comment directly above the method. This keeps generation predictable even as your interface grows.

Generating a Service

Define your service as a regular Go interface in a file ending in _grpc.go. Annotate each method with its call type:

// user_grpc.go
package services

// grpc_type: Unary
type UserService interface {
    GetUser(ctx context.Context, req *GetUserRequest) (*UserResponse, error)

    // grpc_type: ServerSideStreaming
    WatchUser(ctx context.Context, req *GetUserRequest, stream UserService_WatchUserServer) error

    // grpc_type: ClientSideStreaming
    BatchCreateUsers(stream UserService_BatchCreateUsersServer) error

    // grpc_type: Bidirectional
    SyncUsers(stream UserService_SyncUsersServer) error
}

Then run the generator against the interface name:

breeze generate grpc UserService

# overwrite previously generated files for this interface
breeze generate grpc UserService --force

Generated Files

Generation is driven by generate_grpc.go (detection and parsing), with output split across a small set of purpose-built files so hand-written code and generated code never collide:

Full Example

A minimal unary service, generated and mounted alongside your normal HTTP routes:

// user_grpc.go
package services

// grpc_type: Unary
type UserService interface {
    GetUser(ctx context.Context, req *GetUserRequest) (*UserResponse, error)
}

breeze generate grpc UserService

Mount the generated adapter the same way you'd wire up any other service:

package main

import (
    "runtime"

    "github.com/nelthaarion/breeze"
    "myapp/services"
)

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

    userSvc := services.NewUserServiceServer(&services.UserServiceImpl{})
    userSvc.Register(router) // generated adapter wires gRPC handlers in

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

Developer Dashboard new

A built-in, production-grade observability surface for every Breeze app — one mount call, zero external dependencies.

The dashboard is shipped as a native Breeze module under github.com/nelthaarion/breeze/dashboard. It mounts a single-page application at /dashboard that gives you live insight into traffic, routes, database queries, caches, queues, scheduler jobs, logs, runtime metrics, and per-request traces — without leaving your process, and without wiring up a second observability stack.

It is engineered to be zero-overhead when disabled. If you never call dash.Mount(), the dashboard contributes no goroutines, no routes, no allocations, and no GC pressure to your hot path. Once enabled, instrumentation uses lock-free atomics and per-event-loop ring buffers so the act of measuring never becomes the bottleneck.

What's inside

Setup & Authentication

Mounting the dashboard is a single call. The constructor takes the host *breeze.Router and a Config struct; Mount() registers the /dashboard route tree. Everything else is automatic — instrumentation hooks are wired into the router, the worker pool, and the WebSocket engine as soon as the dashboard is mounted.

package main

import (
    "os"
    "runtime"

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

func main() {
    router := breeze.NewRouter()
    router.Use(middleware.RecoveryMiddleware())
    router.Use(middleware.LoggingMiddleware())

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

    // ── Mount the developer dashboard ────────────────────────────────
    dash := dashboard.New(router, dashboard.Config{
        Username: "admin",
        Password: os.Getenv("DASH_PASSWORD"),   // never hard-code
        Path:     "/dashboard",                  // default; shown for clarity
        Enabled:  true,                          // omit or false to disable
        MaskSecrets: []string{"Authorization", "Cookie", "X-API-Key"},
    })
    dash.Mount()   // registers GET /dashboard and /dashboard/*

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

Config fields

Authentication model

The dashboard is protected by HTTP Basic Auth over the same TLS (or plain HTTP) connection as your app. Credentials are compared in constant time using crypto/subtle to mitigate timing attacks. On a failed challenge the dashboard responds with 401 WWW-Authenticate: Basic realm="breeze-dashboard" — browsers will then prompt the user natively.

For multi-tenant deployments or stricter access control, mount the dashboard behind an additional middleware: router.Use(middleware.JWTAuthMiddleware(secret)) before calling dash.Mount(). JWT and Basic Auth compose cleanly because they live in different layers of the request pipeline.

Real-time Overview

The landing panel of the dashboard. It gives you a one-glance answer to "is my service healthy right now?" by combining five high-signal metrics, each updated on a one-second cadence via a single multiplexed WebSocket.

Charts are rendered client-side using a tiny inlined SVG library — no charting framework is shipped, which keeps the single-file payload under 80 KB gzipped. Each series can be toggled, pinned to a custom range, or exported as CSV via the toolbar.

Routes Explorer

A live table of every route registered on the host *breeze.Router, joined with per-route runtime statistics. The route table itself comes from Router.RoutesInfo() — the same read-only view the framework exposes to external packages — so what you see in the dashboard is always byte-for-byte identical with what the router will actually match.

Click any row to drill into a per-route detail view: the middleware chain (in execution order), the handler source location if available, the recent request samples, and a latency distribution histogram. Filtering by method or by a free-text pattern match is supported from the toolbar.

Tip

Sort by p99 descending to instantly find the slowest endpoints in your service — this is usually more actionable than overall p99 because it isolates the few routes that drag the aggregate up.

API Explorer

A built-in alternative to Postman or Scalar UI. Pick any route from the Routes Explorer, fill in path params, query string, headers and a JSON body, and click Send. The dashboard issues the request through the same gnet event loop your real traffic uses, so what you measure is what your users get.

Every sent request can be exported as a ready-to-run code snippet in six languages. Use the language tabs above the response panel.

curl -X POST https://api.example.com/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@lovelace.dev"}'

req, _ := http.NewRequest("POST", "https://api.example.com/users",
    strings.NewReader(`{"name":"Ada","email":"ada@lovelace.dev"}`))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)

await fetch("https://api.example.com/users", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Ada", email: "ada@lovelace.dev" }),
});

import requests
requests.post(
    "https://api.example.com/users",
    headers={"Authorization": f"Bearer {token}"},
    json={"name": "Ada", "email": "ada@lovelace.dev"},
)

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", token);
var resp = await http.PostAsJsonAsync(
    "https://api.example.com/users",
    new { name = "Ada", email = "ada@lovelace.dev" });

$ch = curl_init("https://api.example.com/users");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $token",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "name" => "Ada", "email" => "ada@lovelace.dev",
    ]),
]);
curl_exec($ch);

Responses are pretty-printed, syntax-highlighted, and timed. The status, latency and response size are surfaced in the toolbar so you can compare against the route's historical p95 in one glance.

Live Requests Feed

A real-time, tail-style feed of every request handled by the framework. Push happens over a dedicated WebSocket channel — the dashboard multiplexes all of its live views (Overview, Live Requests, Logs, Timeline) over a single socket to keep connection overhead predictable.

Each entry shows the method, path, status, latency, and the originating client IP. Click an entry to expand the full request/response envelope: headers (with secrets masked — see Setup & Authentication), request body, response body, and a deep-link into the Developer Timeline for that request.

Database Browser

A read-only, paginated table inspector for the database registered via Config.DB. Use it to verify schema state, look up a row by primary key, or sanity-check reference data during development — without reaching for a separate SQL client.

Capabilities

• List all tables and views exposed by the *sql.DB driver
• Inspect column names, types, nullability and primary-key flags
• Paginated row view (50 rows/page, configurable) with column sorting
• Free-text WHERE clause builder for ad-hoc filtering
• CSV export of the current result set, capped at 10,000 rows

Production safety

The browser is disabled by default in production builds. Enable it explicitly via Config.EnableDBBrowser, and consider pointing it at a read-replica instead of your primary. The dashboard will refuse to mount the Database Browser if Config.DB is nil, so a misconfiguration fails closed rather than silently serving an empty page.

ORM Query Monitor

When a Breeze ORM adapter is registered with the dashboard, every SQL statement it issues is captured with its wall-clock duration, the calling goroutine, and — when source information is available — the file and line that triggered it. The result is a per-query timeline that makes slow queries and N+1 patterns obvious without a separate APM agent.

Each finding links back to the Developer Timeline entry that produced it, so you can see the exact request, the exact handler, and the exact line of code that triggered the offending query — closing the loop from symptom to root cause in a single click.

// Registering the ORM adapter wires query capture into the dashboard.
// Replace with your actual adapter (sqlx, gorm, ent, …).
dash.RegisterORM(breezeorm.NewAdapter(db, breezeorm.Config{
    SlowThreshold:     200 * time.Millisecond,
    NPlusOneThreshold: 5,
    CaptureExplain:    true,
}))

Cache, Queue & Scheduler Monitors

Three side-by-side panels summarise the stateful subsystems that often fail silently: caches, queues, and schedulers. Each monitor pulls from a small adapter interface — implement it once per backend (Redis, in-memory, Asynq, River, cron, …) and the dashboard handles the rest.

Cache panel

• Hit / miss / error ratio per cache, with a 60-second rolling sparkline
• Current key count, total bytes, and eviction rate
• Top-10 keys by access frequency — useful for spotting hot keys

Queue panel

• Depth and throughput per queue, with consumer-lag trend
• Dead-letter count and oldest unacked message age
• Per-worker goroutine state (idle / busy / crashed)

Scheduler panel

• Job name, cron expression, next run, last run, last status
• Last-run duration vs. the job's interval — flag jobs that overlap themselves
• Manual "Run now" trigger for one-off execution during debugging

Logs

A unified log viewer with five tabs, each backed by an independent ring buffer so opening one tab does not evict entries from another. Logs are streamed live over the same multiplexed WebSocket as the rest of the dashboard, with backpressure handled by dropping the oldest entries rather than blocking the application.

Every tab supports case-insensitive free-text filtering, level filtering (where applicable), and a "follow" toggle that auto-scrolls to the newest entry. Long lines are truncated with a click-to-expand affordance so the table stays scannable.

Health Checks & Runtime Metrics

Health checks

Each HealthCheck registered via Config.HealthChecks is polled on a configurable interval (default 15 s). The result is rendered as a coloured chip — green (pass), yellow (slow > 1 s), red (fail) — alongside the last latency, last error message, and a 60-sample sparkline of recent latencies.

dash := dashboard.New(router, dashboard.Config{
    // …
    HealthChecks: []dashboard.HealthCheck{
        {Name: "postgres", Check: func(ctx context.Context) error {
            return db.PingContext(ctx)
        }},
        {Name: "redis", Check: func(ctx context.Context) error {
            return rdb.Ping(ctx).Err()
        }},
        {Name: "downstream:billing", Check: func(ctx context.Context) error {
            return billingClient.Health(ctx)
        }},
    },
    HealthInterval: 15 * time.Second,
})

Go runtime metrics

A dedicated panel surfaces the runtime statistics that matter most for production Go services. All numbers are sampled in-process via runtime/metrics and runtime/pprof — no agent, no sidecar, no OpenTelemetry SDK required.

CPU and memory profiles are captured on demand — click the Capture profile button, wait 5 seconds, and the flame graph renders inline. Profiles never touch disk; they are decoded entirely in the browser.

Developer Timeline

The flagship debugging view. Each handled request is captured as a hierarchical timeline of spans — one per middleware, one per DB query, one per cache call, one per downstream HTTP call. The result is a flame-style chart that shows where the request spent its time, with every leaf expandable to the underlying event.

Span types captured

Anatomy of a timeline entry

Each entry expands to show:

• Start offset — milliseconds since request arrival
• Duration — wall time, with a bar proportional to the slowest sibling
• Args — query text, cache key, outbound URL, etc. (truncated, click to expand)
• Result — rows affected, cache hit/miss, HTTP status, error if any
• Source — file:line of the call site, when debug info is enabled

Click any span to filter the timeline to siblings of the same type — instantly answer questions like "show me every DB query this request made, in order" without scrolling past middleware noise.

Workflow tip

When a user reports a slow request, grab the request ID from your access logs, paste it into the timeline filter, and you'll see the exact span breakdown for that single request — no need to reproduce, no need to re-deploy with extra logging.

File Uploads

files, fields, err := ctx.ParseMultipart(10 << 20) // 10 MB max
if err != nil { ctx.Status(400); ctx.WriteString(err.Error()); return }

uf := files["avatar"][0]
fmt.Println(uf.Filename, uf.ContentType, uf.Size)

saved, err := ctx.SaveUploadedFile("avatar", "./uploads/avatar.jpg", 5<<20)
if err != nil { ctx.Status(400); ctx.WriteString(err.Error()); return }
ctx.JSON(map[string]string{"saved": saved})

Static Files

// Serve ./public/* at /assets/*
router.ServeStatic("/assets", "./public")

// Auto-serve ./public/index.html at GET / (no explicit route needed)
// Directory traversal is sanitized with filepath.Clean

Worker Pool

Off-loads handler execution from the gnet event loop so slow handlers don't block all connections on a reactor.

pool := breeze.NewWorkerPool(runtime.NumCPU())
pool := breeze.NewWorkerPool(32)

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
pool.Shutdown(ctx)

// Pass nil to skip the pool and use raw goroutines
app := breeze.New(router, nil)