README
¶
flare
a small, fasthttp-backed router with a gin-like handler, batteries not included.
module: github.com/deglebe/flare
package main
import (
"log"
"github.com/deglebe/flare"
)
func main() {
e := flare.New()
e.Use(flare.Recover())
e.GET("/health", func(c *flare.Ctx) {
c.SetBodyString("ok")
})
e.GET("/users/:id", func(c *flare.Ctx) {
c.JSON(200, map[string]string{"id": c.Param("id")})
})
log.Fatal(e.Listen(":8080"))
}
is it any good?
install
go get github.com/deglebe/flare
requires go 1.25.5+ (see go.mod). for faster json encoding/decoding using bytedance's sonic (marginal boost on small apis):
go build -tags flare_sonic
examples
from the repo root:
go run ./examples/basic # / /health /hello/:name
go run ./examples/api # token-gated json crud
go run ./examples/static # get / -> public/index.html
# basic
curl -s localhost:8080/hello/ada
# api (header required)
curl -s -H 'X-Token: secret' localhost:8080/api/users
curl -s -H 'X-Token: secret' -H 'Content-Type: application/json' \
-d '{"name":"linus"}' localhost:8080/api/users
# static
curl -s localhost:8080/
curl -s localhost:8080/health
how it works
routing
each http method owns a radix tree (:param and *catchall). trailing slashes
are strict by default: /a and /a/ are different routes.
# registered GET /users; wrong slash 404s
curl -i localhost:8080/users/ # 404
curl -i localhost:8080/users # 200
set e.RedirectTrailingSlash = true to redirect the flipped slash instead
(301 for GET, 307 otherwise):
curl -i localhost:8080/users/ # 301 Location: .../users
registration freezes on the first Handler()/Listen(). at freeze, flare:
- collapses an empty method root that has a single child (reduces hops per request by one)
- builds an exact-path table for static leaves so common paths skip walking the full tree.
the seven usual verbs use a fixed method index instead of a map. unknown methods panic at registration.
middleware and Ctx
Use and Group precompose middleware into each route's handler slice when the
route is registered, meaning that there is no per-request stack rebuild. Next,
Abort/AbortWithStatus/AbortWithStatusJSON, and Recover/RecoverWith
follow the usual pattern.
each request borrows a pooled Ctx wrapping *fasthttp.RequestCtx. routes with
a single leaf handler call it directly and skip the Next index loop.
requests and responses
helpers stay optional and off the match path:
| params/query/headers | Param, ParamInt, Query, GetHeader |
| json | JSON, BindJSON (-tags flare_sonic optional) |
| forms | Bind, BindForm |
| content negotiate | Negotiate (html vs json stub) |
| files | Static / StaticFS, File / FileAttachment |
| redirect | Redirect (301/302/307/308; other codes become 302) |
| client address | ClientIP (see below) |
Engine.Server is an embedded fasthttp.Server with conservative defaults
(4 mib body, 10 s read/write, 60 s idle). override fields before Listen.
NoRoute / NoMethod distinguish unknown paths (404) from wrong methods on a
known path (405).
client ip and proxies
by default ClientIP() returns the socket peer and ignores
X-Forwarded-For/X-Real-IP. behind nginx or similar, you must allow the proxy
hop explicitly:
_ = e.SetTrustedProxies("10.0.0.0/8", "127.0.0.1")
// optional: e.SetRemoteIPHeaders("X-Forwarded-For")
trusted peers may supply those headers; X-Forwarded-For is walked
right-to-left, skipping hops that are also trusted.
scope
flare is meant to be a minimal router kernel on top of which to build an
equally, if not more performant stack. so, flare is only match, groups,
middleware, Ctx, bind/json helpers, static files, and listen/limits, until
more is called for in core. sessions, oauth, openapi, orms, heavy validators,
and cors/rate-limit packs are intentionally left out, though a companion library
may include these features in the future.
Documentation
¶
Index ¶
- Variables
- func SetJSONCodec(marshal jsonMarshalFunc, unmarshal jsonUnmarshalFunc)
- type Accept
- type Ctx
- func (c *Ctx) Abort()
- func (c *Ctx) AbortWithStatus(code int)
- func (c *Ctx) AbortWithStatusJSON(code int, v any)
- func (c *Ctx) Bind(v any) error
- func (c *Ctx) BindForm(v any) error
- func (c *Ctx) BindJSON(v any) error
- func (c *Ctx) ClientIP() string
- func (c *Ctx) File(path string)
- func (c *Ctx) FileAttachment(path, filename string)
- func (c *Ctx) GetHeader(key string) string
- func (c *Ctx) IsAborted() bool
- func (c *Ctx) JSON(code int, v any)
- func (c *Ctx) Negotiate(code int, a Accept)
- func (c *Ctx) Next()
- func (c *Ctx) Param(key string) string
- func (c *Ctx) ParamInt(key string) (int, error)
- func (c *Ctx) Query(key string) string
- func (c *Ctx) Redirect(code int, url string)
- type Engine
- func (e *Engine) DELETE(path string, h ...Handler)
- func (e *Engine) GET(path string, h ...Handler)
- func (e *Engine) Group(prefix string, mws ...Handler) *Router
- func (e *Engine) HEAD(path string, h ...Handler)
- func (e *Engine) Handler() fasthttp.RequestHandler
- func (e *Engine) Listen(addr string) error
- func (e *Engine) NoMethod(h ...Handler)
- func (e *Engine) NoRoute(h ...Handler)
- func (e *Engine) OPTIONS(path string, h ...Handler)
- func (e *Engine) PATCH(path string, h ...Handler)
- func (e *Engine) POST(path string, h ...Handler)
- func (e *Engine) PUT(path string, h ...Handler)
- func (e *Engine) SetRemoteIPHeaders(headers ...string)
- func (e *Engine) SetTrustedProxies(proxies ...string) error
- func (e *Engine) Static(prefix, rootDir string)
- func (e *Engine) StaticFS(prefix string, fsys fs.FS)
- func (e *Engine) Use(mws ...Handler)
- type Handler
- type Router
- func (r *Router) DELETE(path string, h ...Handler)
- func (r *Router) GET(path string, h ...Handler)
- func (r *Router) Group(prefix string, mws ...Handler) *Router
- func (r *Router) HEAD(path string, h ...Handler)
- func (r *Router) PATCH(path string, h ...Handler)
- func (r *Router) POST(path string, h ...Handler)
- func (r *Router) PUT(path string, h ...Handler)
- func (r *Router) Static(prefix, rootDir string)
- func (r *Router) StaticFS(prefix string, fsys fs.FS)
- func (r *Router) Use(mws ...Handler)
Constants ¶
This section is empty.
Variables ¶
var ErrUnsupportedMediaType = errors.New("flare: unsupported media type")
returned by Bind for content-types other than json/form
Functions ¶
func SetJSONCodec ¶
func SetJSONCodec(marshal jsonMarshalFunc, unmarshal jsonUnmarshalFunc)
swaps json encode/decode (nil arg keeps current)
Types ¶
type Ctx ¶
type Ctx struct {
*fasthttp.RequestCtx
// contains filtered or unexported fields
}
pooled request context wrapping *fasthttp.RequestCtx
func (*Ctx) AbortWithStatusJSON ¶
write json, then abort
func (*Ctx) Bind ¶
decode body from content-type (json or form-urlencoded) call from handlers only, not from router hot path
func (*Ctx) BindForm ¶
fill exported string/int fields from post args (form tag, else json, else name) reflect-based, also keep off hot path
func (*Ctx) ClientIP ¶
returns client address if socket peer is listed in SetTrustedProxies, headers from SetRemoteIPHeaders are consulted w/o anything configured headers are ignored and the peer address is returned
func (*Ctx) File ¶ added in v0.1.1
File sends a local file as the response body, do not pass user-supplied paths
func (*Ctx) FileAttachment ¶ added in v0.1.1
FileAttachment sends a local file as a download named filename empty filename uses filepath.Base(path), do not pass user-supplied paths
type Engine ¶
type Engine struct {
// when true, miss that matches same method with slash flipped redirects
// (301 GET, 307 otherwise). default false keeps strict /a vs /a/
RedirectTrailingSlash bool
// fasthttp limits/timeouts; override before Listen
Server fasthttp.Server
// contains filtered or unexported fields
}
fasthttp router trailing slashes are significant by default; see RedirectTrailingSlash
func New ¶
func New() *Engine
new engine w/ conservative server defaults (4mib body, 10s r/w, 60s idle)
func (*Engine) Handler ¶
func (e *Engine) Handler() fasthttp.RequestHandler
fasthttp handler; freezes routes on first call
func (*Engine) SetRemoteIPHeaders ¶
overrides header list used when peer is trusted defaults restored with nothing passed
func (*Engine) SetTrustedProxies ¶
set cidrs/bare ips allowed to supply forwarded-client headers empty means clientip always returns sock peer
func (*Engine) Static ¶
serve from rootdir under prefix (get+head) prefix / serves the directory at the site root
type Router ¶
type Router struct {
// contains filtered or unexported fields
}
route group with shared prefix and middleware
Source Files
Directories