Router & handlers#

breeze.NewRouter() builds a *Router: exact-path routing via per-method buckets, dynamic :params, and wildcard segments, with O(1) lookup for the common case.

router := breeze.NewRouter()

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

Registering routes#

// In-memory, returns immediately → inline (fastest path).
router.Handle(breeze.GET, "/users/:id", getUser)

// Touches a database, disk, or network → the worker pool.
router.HandleBlocking(breeze.POST, "/orders", createOrder)

Choosing wrong doesn't crash anything — it just means a blocking call made inline stalls every other connection pinned to that event loop, or an in-memory handler pays a pool hop it didn't need. See Performance Model for why inline execution is the default assumption.

Patterns#

• Exact segments — /users, /health
• Dynamic params — /users/:id, read with ctx.Param("id")
• Wildcards — a trailing *filepath-style segment, used by SetStaticDir and the video package's mount

Route lookup is indexed per HTTP method into buckets at registration time (indexRoute), so matching a request never scans routes registered for a different method.

Handler signature#

Every handler and every middleware share one type:

type HandlerFunc func(ctx *breeze.Context) error

A middleware runs before the handler, calls ctx.Next() to continue, and returns an error — there is exactly one function type to learn. See Middleware Reference for the built-ins and the order they must install in.

router.Use and per-route middleware#

router.Use(middleware.RecoveryMiddleware()) // global, prepended to every chain

router.Handle(breeze.GET, "/admin", adminHandler, requireAdmin) // per-route, trailing args

Use prepends to every route's chain, including routes registered before the Use call — the chain is rebuilt, so installation order in the file does not have to match registration order. Per-route middleware runs after all global middleware. The whole chain is composed once, at registration time, not per request — a route with no :params costs zero allocations to dispatch.

Static files#

router.SetStaticDir("./public")

Serves files from the given directory under a wildcard route. For anything that needs byte-range support — video, large downloads with seeking — use the dedicated Video Streaming package instead; a plain static handler answers Range requests incorrectly by silently ignoring them.

Introspection#

router.RoutesInfo()  // []RouteInfo — every registered route
router.Routes()      // []*route — the internal route objects

breeze routes (the CLI command) reads the same information without booting the application. The dashboard's Routes Explorer page and the scalar OpenAPI generator both read from the same registration data, so a route documented once is consistent everywhere it appears.