README
¶
Flamego is a modular Go framework for building composable systems, and equips the most powerful routing syntax among all web frameworks within the Go ecosystem.
Installation
go get github.com/flamego/flamego
Getting started
package main
import "github.com/flamego/flamego"
func main() {
f := flamego.Classic()
f.Get("/", func() string {
return "Hello, Flamego!"
})
f.Run()
}
Features
- The most powerful routing syntax among all web frameworks within the Go ecosystem.
- Limitless routes nesting and grouping.
- Inject middleware at wherever you want.
- Integrate with any existing Go web application non-intrusively.
- Dependency injection via function signature to write testable and maintainable code.
Middleware
- Logger - Log requests and response status code
- Recovery - Automatic recovery from panics
- Static - Serve static files
- Renderer - Render content
- template - Go template rendering
- session - User session management
- recaptcha - Google reCAPTCHA verification
- csrf - Generate and validate CSRF tokens
- cors - Cross-Origin Resource Sharing
- binding - Request data binding and validation
- gzip - Gzip compression to responses
- cache - Cache management
- brotli - Brotli compression to responses
- auth - Basic and bearer authentication
- i18n - Internationalization and localization
- captcha - Captcha service
- hcaptcha - hCaptcha verification
- sse - Server-Sent Events
Getting help
- New to Flamego? Check out the starter guide!
- Have any questions? Answers may be found in our FAQs.
- Please file an issue or start a discussion if you want to reach out.
- Follow our Twitter to stay up to the latest news.
- Our brand kit is also available on GitHub!
Local development
Install "go-mockgen" and "goimports" to re-generate mocks:
go install github.com/derision-test/go-mockgen/cmd/go-mockgen@latest
go install golang.org/x/tools/cmd/goimports@latest
go generate ./...
License
This project is under the MIT License. See the LICENSE file for the full license text.
Documentation
¶
Overview ¶
Package flamego is a fantastic modular Go web framework with a slim core but limitless extensibility.
Index ¶
- func SetEnv(e EnvType)
- type BeforeFunc
- type BeforeHandler
- type ComboRoute
- func (r *ComboRoute) Connect(handlers ...Handler) *ComboRoute
- func (r *ComboRoute) Delete(handlers ...Handler) *ComboRoute
- func (r *ComboRoute) Get(handlers ...Handler) *ComboRoute
- func (r *ComboRoute) Head(handlers ...Handler) *ComboRoute
- func (r *ComboRoute) Name(name string)
- func (r *ComboRoute) Options(handlers ...Handler) *ComboRoute
- func (r *ComboRoute) Patch(handlers ...Handler) *ComboRoute
- func (r *ComboRoute) Post(handlers ...Handler) *ComboRoute
- func (r *ComboRoute) Put(handlers ...Handler) *ComboRoute
- func (r *ComboRoute) Trace(handlers ...Handler) *ComboRoute
- type Context
- type ContextInvoker
- type EnvType
- type Flame
- func (f *Flame) Action(h Handler)
- func (f *Flame) Before(h BeforeHandler)
- func (f *Flame) Handlers(handlers ...Handler)
- func (f *Flame) ReturnHandler(handler TypedReturnHandler)
- func (f *Flame) Run(args ...interface{})
- func (f *Flame) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (f *Flame) Stop()
- func (f *Flame) Use(handlers ...Handler)
- type Handler
- type LoggerInvoker
- type Params
- type RecoveryOptions
- type Render
- type RenderOptions
- type Request
- type RequestBody
- type ResponseWriter
- type ReturnHandler
- type Route
- type Router
- type StaticOptions
- type TypedReturnHandler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type BeforeFunc ¶
type BeforeFunc func(ResponseWriter)
BeforeFunc is a function that is called before the ResponseWriter is written.
type BeforeHandler ¶
type BeforeHandler func(rw http.ResponseWriter, req *http.Request) bool
BeforeHandler is a handler executes at beginning of every request. Flame instance stops further process when it returns true.
type ComboRoute ¶
type ComboRoute struct {
// contains filtered or unexported fields
}
ComboRoute is a wrapper of the router for adding handlers of different HTTP methods to the same route.
func (*ComboRoute) Connect ¶
func (r *ComboRoute) Connect(handlers ...Handler) *ComboRoute
Connect adds handlers of the CONNECT method to the route.
func (*ComboRoute) Delete ¶
func (r *ComboRoute) Delete(handlers ...Handler) *ComboRoute
Delete adds handlers of the DELETE method to the route.
func (*ComboRoute) Get ¶
func (r *ComboRoute) Get(handlers ...Handler) *ComboRoute
Get adds handlers of the GET method to the route.
func (*ComboRoute) Head ¶
func (r *ComboRoute) Head(handlers ...Handler) *ComboRoute
Head adds handlers of the HEAD method to the route.
func (*ComboRoute) Options ¶
func (r *ComboRoute) Options(handlers ...Handler) *ComboRoute
Options adds handlers of the OPTIONS method to the route.
func (*ComboRoute) Patch ¶
func (r *ComboRoute) Patch(handlers ...Handler) *ComboRoute
Patch adds handlers of the PATCH method to the route.
func (*ComboRoute) Post ¶
func (r *ComboRoute) Post(handlers ...Handler) *ComboRoute
Post adds handlers of the POST method to the route.
func (*ComboRoute) Put ¶
func (r *ComboRoute) Put(handlers ...Handler) *ComboRoute
Put adds handlers of the PUT method to the route.
func (*ComboRoute) Trace ¶
func (r *ComboRoute) Trace(handlers ...Handler) *ComboRoute
Trace adds handlers of the TRACE method to the route.
type Context ¶
type Context interface {
inject.Injector
// ResponseWriter returns the ResponseWriter in current context.
ResponseWriter() ResponseWriter
// Request returns the Request in current context.
Request() *Request
// URLPath builds the "path" portion of URL with given pairs of values. To
// include the optional segment, pass `"withOptional", "true"`.
//
// This is a transparent wrapper of Router.URLPath.
URLPath(name string, pairs ...string) string
// Next runs the next handler in the context chain.
Next()
// RemoteAddr extracts and returns the remote IP address from following attempts
// in sequence:
// - "X-Real-IP" request header
// - "X-Forwarded-For" request header
// - http.Request.RemoteAddr field
RemoteAddr() string
// Redirect sends a redirection to the response to the given location. If the
// `status` is not given, the http.StatusFound is used.
Redirect(location string, status ...int)
// Params returns all bind parameters.
Params() Params
// Param returns value of the given bind parameter.
Param(name string) string
// ParamInt returns value of the given bind parameter parsed as int.
ParamInt(name string) int
// ParamInt64 returns value of the given bind parameter parsed as int64.
ParamInt64(name string) int64
// Query returns value of the given URL parameter. The `defaultVal` (when set)
// or zero value is returned when the given parameter is absent.
Query(name string, defaultVal ...string) string
// QueryTrim trims spaces and returns value of the given URL parameter. The
// `defaultVal` (when set) or zero value is returned when the given parameter is
// absent.
QueryTrim(name string, defaultVal ...string) string
// QueryStrings returns a list of strings of the given URL parameter. The
// `defaultVal` (when set) or zero value is returned when the given parameter is
// absent.
QueryStrings(name string, defaultVal ...[]string) []string
// QueryUnescape returns unescaped query result of the given URL parameter. The
// `defaultVal` (when set) or zero value is returned when the given parameter is
// absent.
QueryUnescape(name string, defaultVal ...string) string
// QueryBool returns value of the given URL parameter parsed as bool. The
// `defaultVal` (when set) or zero value is returned when the given parameter is
// absent.
QueryBool(name string, defaultVal ...bool) bool
// QueryInt returns value of the given URL parameter parsed as int. The
// `defaultVal` (when set) or zero value is returned when the given parameter is
// absent.
QueryInt(name string, defaultVal ...int) int
// QueryInt64 returns value of the given URL parameter parsed as int64. The
// `defaultVal` (when set) or zero value is returned when the given parameter is
// absent.
QueryInt64(name string, defaultVal ...int64) int64
// QueryFloat64 returns value of the given URL parameter parsed as float64. The
// `defaultVal` (when set) or zero value is returned when the given parameter is
// absent.
QueryFloat64(name string, defaultVal ...float64) float64
// SetCookie escapes the cookie value and sets it to the current response.
SetCookie(cookie http.Cookie)
// Cookie returns the named cookie in the request or empty if not found. If
// multiple cookies match the given name, only one cookie will be returned. The
// returned value is unescaped using `url.QueryUnescape`, original value is
// returned instead if unable to unescape.
Cookie(name string) string
}
Context is the runtime context of the coming request, and provide handy methods to enhance developer experience.
type ContextInvoker ¶
type ContextInvoker func(ctx Context)
ContextInvoker is an inject.FastInvoker implementation of `func(Context)`.
type Flame ¶
Flame is the top-level web application instance, which manages global states of injected services and middleware.
func Classic ¶
func Classic() *Flame
Classic creates and returns a classic Flame instance with default middleware: `flamego.Logger`, `flamego.Recovery` and `flamego.Static`.
func New ¶
func New() *Flame
New creates and returns a bare bones Flame instance with default logger writing to os.Stdout. Use this function if you want to have full control over middleware that are used.
func NewWithLogger ¶
NewWithLogger creates and returns a bare bones Flame instance. Use this function if you want to have full control over log destination and middleware that are used.
func (*Flame) Action ¶
Action sets the final handler that will be called after all handlers have been invoked.
func (*Flame) Before ¶
func (f *Flame) Before(h BeforeHandler)
Before allows for a handler to be called before matching any route. Multiple calls to this method will queue up handlers, and handlers will be called in the FIFO manner.
func (*Flame) Handlers ¶
Handlers sets the entire middleware stack with the given Handlers. This will clear any current middleware handlers, and panics if any of the handlers is not a callable function.
func (*Flame) ReturnHandler ¶ added in v1.12.0
func (f *Flame) ReturnHandler(handler TypedReturnHandler)
ReturnHandler registers a handler for route handler return values.
The handler must accept Context as its first argument. Its remaining arguments are matched against route handler return values by exact type first, then by assignability in registration order. For example, registering `func(Context, int, string)` handles route handlers that return `(int, string)`.
Registering a handler for a return signature that is already handled replaces the previous handler, which can be used to override the built-in handlers for shapes such as `(string)` or `(int, string)`. If a route handler returns a signature that no registered handler matches, Flamego panics.
type Handler ¶
type Handler interface{}
Handler is any callable function or a value that implements http.Handler. Flamego attempts to inject services into the Handler's argument list and panics if any argument could not be fulfilled via dependency injection. Values implementing http.Handler are invoked via their ServeHTTP method.
func Logger ¶
func Logger() Handler
Logger returns a middleware handler that logs the request as it goes in and the response as it goes out.
func Recovery ¶
func Recovery(opts ...RecoveryOptions) Handler
Recovery returns a middleware handler that recovers from any panics and writes a 500 status code to the response if there was one. While in development mode (EnvTypeDev), Recovery will also output the panic as HTML, or as plain text when the PlainText option is enabled.
func Renderer ¶
func Renderer(opts ...RenderOptions) Handler
Renderer returns a middleware handler that injects flamego.Render into the request context, which is used for rendering content to the ResponseWriter.
func Static ¶
func Static(opts ...StaticOptions) Handler
Static returns a middleware handler that serves static files in the given directory.
type LoggerInvoker ¶
LoggerInvoker is an inject.FastInvoker implementation of `func(ctx Context, log *log.Logger)`.
type Params ¶
Params is a set of bind parameters with their values that are extracted from the request path.
type RecoveryOptions ¶ added in v1.13.0
type RecoveryOptions struct {
// PlainText indicates whether to respond with plain text instead of HTML when
// recovering from a panic in development mode.
PlainText bool
}
RecoveryOptions contains options for the flamego.Recovery middleware.
type Render ¶
type Render interface {
// JSON encodes given value in JSON format with given status code to the
// ResponseWriter.
JSON(status int, v interface{})
// XML encodes given value in XML format with given status code to the
// ResponseWriter.
XML(status int, v interface{})
// Binary writes binary data with given status code to the ResponseWriter.
Binary(status int, v []byte)
// PlainText writes string with given status code to the ResponseWriter.
PlainText(status int, s string)
}
Render is a thin wrapper to render content to the ResponseWriter.
type RenderOptions ¶
type RenderOptions struct {
// Charset specifies the value of the "charset" to be responded with the
// "Content-Type" header. Default is "utf-8".
Charset string
// JSONIndent specifies the indent value when encoding content in JSON format.
// Default is no indentation.
JSONIndent string
// XMLIndent specifies the indent value when encoding content in XML format.
// Default is no indentation.
XMLIndent string
}
RenderOptions contains options for the flamego.Renderer middleware.
type Request ¶
Request is a wrapper of http.Request with handy methods.
func (*Request) Body ¶
func (r *Request) Body() *RequestBody
Body returns a RequestBody for the request.
type RequestBody ¶
type RequestBody struct {
// contains filtered or unexported fields
}
RequestBody is a wrapper of http.Request.Body with handy methods.
func (*RequestBody) Bytes ¶
func (r *RequestBody) Bytes() ([]byte, error)
Bytes reads and returns the content of request body in bytes.
func (*RequestBody) ReadCloser ¶
func (r *RequestBody) ReadCloser() io.ReadCloser
ReadCloser returns a ReadCloser of request body.
func (*RequestBody) String ¶
func (r *RequestBody) String() (string, error)
String reads and returns content of request body in string.
type ResponseWriter ¶
type ResponseWriter interface {
http.ResponseWriter
http.Flusher
http.Pusher
// Status returns the status code of the response or 0 if the response has not
// been written.
Status() int
// Written returns whether the ResponseWriter has been written.
Written() bool
// Size returns the written size of the response body.
Size() int
// Before allows for a function to be called before the ResponseWriter has been
// written to. This is useful for setting headers or any other operations that
// must happen before a response has been written. Multiple calls to this method
// will stack up functions, and functions will be called in the FILO manner.
Before(BeforeFunc)
}
ResponseWriter is a wrapper of http.ResponseWriter that provides extra information about the response. It is recommended that middleware handlers use this construct to wrap a ResponseWriter if the functionality calls for it.
func NewResponseWriter ¶
func NewResponseWriter(method string, w http.ResponseWriter) ResponseWriter
NewResponseWriter returns a wrapper of http.ResponseWriter.
type ReturnHandler ¶
ReturnHandler is a service that is called when a route handler returns something. The ReturnHandler is responsible for writing to the ResponseWriter based on the values that are passed into this function.
type Route ¶
type Route struct {
// contains filtered or unexported fields
}
Route is a wrapper of the route leaves and its router.
func (*Route) Headers ¶ added in v1.5.0
Headers uses given key-value pairs as the list of matching criteria for request headers, where key is the header name and value is a regex. Once set, the route will only be matched if all header matches are successful in addition to the request path.
For example:
f.Get("/", ...).Headers(
"User-Agent", "Chrome", // Loose match
"Host", "^flamego\.dev$", // Exact match
"Cache-Control", "", // As long as "Cache-Control" is not empty
)
Subsequent calls to Headers() replace previously set matches.
func (*Route) Match ¶ added in v1.11.0
Match adds an arbitrary predicate as an additional matching criterion for the route. The predicate is evaluated only after the request path (and any Headers matchers) match. If it returns false, the request falls through to the next candidate route just like a failed Headers match — it does not halt the routing process.
Multiple calls to Match accumulate and are combined with AND: every predicate must return true for the route to match. When combined with Headers, both must pass. The predicate does not affect the matching priority of the route, nor does it participate in URLPath construction.
For example:
f.Get("/admin", h).Match(func(r *http.Request) bool {
return strings.HasPrefix(r.RemoteAddr, "10.")
})
f.Get("/", h).
Headers("Accept", "application/json").
Match(func(r *http.Request) bool { return r.TLS != nil })
Panics if fn is nil.
type Router ¶
type Router interface {
// AutoHead sets a boolean value which determines whether to add HEAD method
// automatically when GET method is added. Only routes that are added after call
// of this method will be affected, existing routes remain unchanged.
AutoHead(v bool)
// HandlerWrapper sets handlerWrapper for the router. It is used to wrap Handler
// and inject logic, and is especially useful for wrapping the Handler to
// inject.FastInvoker.
HandlerWrapper(f func(Handler) Handler)
// Route adds the new route path and its handlers to the router tree.
Route(method, routePath string, handlers []Handler) *Route
// Methods adds the new route path and its handlers for the given set of HTTP
// methods.
//
// Example:
// f.Methods("/", method.Get, handlers...)
// f.Methods("/", method.Get|method.Post, handlers...)
// f.Methods("/", method.All, handlers...)
Methods(routePath string, methods method.Set, handlers ...Handler) *Route
// Combo returns a ComboRoute for adding handlers of different HTTP methods to
// the same route.
Combo(routePath string, handlers ...Handler) *ComboRoute
// Group pushes a new group with the given route path and its handlers, it then
// pops the group when leaves the scope of `fn`.
Group(routePath string, fn func(), handlers ...Handler)
// Get is a shortcut for `r.Route(http.MethodGet, routePath, handlers)`.
Get(routePath string, handlers ...Handler) *Route
// Patch is a shortcut for `r.Route(http.MethodPatch, routePath, handlers)`.
Patch(routePath string, handlers ...Handler) *Route
// Post is a shortcut for `r.Route(http.MethodPost, routePath, handlers)`.
Post(routePath string, handlers ...Handler) *Route
// Put is a shortcut for `r.Route(http.MethodPut, routePath, handlers)`.
Put(routePath string, handlers ...Handler) *Route
// Delete is a shortcut for `r.Route(http.MethodDelete, routePath, handlers)`.
Delete(routePath string, handlers ...Handler) *Route
// Options is a shortcut for `r.Route(http.MethodOptions, routePath, handlers)`.
Options(routePath string, handlers ...Handler) *Route
// Head is a shortcut for `r.Route(http.MethodHead, routePath, handlers)`.
Head(routePath string, handlers ...Handler) *Route
// Connect is a shortcut for `r.Route(http.MethodConnect, routePath, handlers)`.
Connect(routePath string, handlers ...Handler) *Route
// Trace is a shortcut for `r.Route(http.MethodTrace, routePath, handlers)`.
Trace(routePath string, handlers ...Handler) *Route
// Any is a shortcut for `r.Route("*", routePath, handlers)`.
Any(routePath string, handlers ...Handler) *Route
// Routes is a shortcut of adding route with same list of handlers for different
// HTTP methods.
//
// Example:
// f.Routes("/", http.MethodGet, http.MethodPost, handlers...)
// f.Routes("/", "GET,POST", handlers...)
//
// Deprecated: Use Methods with the type-safe method.Set values instead, e.g.,
// f.Methods("/", method.Get|method.Post, handlers...).
Routes(routePath, methods string, handlers ...Handler) *Route
// NotFound configures a http.HandlerFunc to be called when no matching route is
// found. When it is not set, http.NotFound is used. Be sure to set
// http.StatusNotFound as the response status code in your last handler.
NotFound(handlers ...Handler)
// URLPath builds the "path" portion of URL with given pairs of values. To
// include the optional segment, pass `"withOptional", "true"`.
URLPath(name string, pairs ...string) string
// ServeHTTP implements the method of http.Handler.
ServeHTTP(w http.ResponseWriter, req *http.Request)
}
Router is the router for adding routes and their handlers.
type StaticOptions ¶
type StaticOptions struct {
// Directory is the local directory to be used to serve static file. This value
// is ignored when FileSystem is set. Default is "public".
Directory string
// FileSystem is the interface for supporting any implementation of the
// http.FileSystem.
FileSystem http.FileSystem
// Prefix is the optional prefix used to serve the static directory content.
Prefix string
// Index specifies which file to attempt to serve as the directory index.
// Default is "index.html".
Index string
// Expires is used to set the "Expires" response header for every static file
// that is served. Default is not set.
Expires func() string
// SetETag indicates whether to compute and set "ETag" response header for every
// static file that is served. File name, size and modification time are used to
// compute the value.
SetETag bool
// EnableLogging indicates whether to print "[Static]" log messages whenever a
// static file is served.
EnableLogging bool
// CacheControl is used to set the "Cache-Control" response header for every
// static file that is served. Default is not set.
CacheControl func() string
}
StaticOptions contains options for the flamego.Static middleware.
type TypedReturnHandler ¶ added in v1.12.0
type TypedReturnHandler any
TypedReturnHandler is a function that handles route handler return values.
It must accept Context as its first argument and must not return values. Its remaining arguments are matched against route handler return values by exact type first, then by assignability in registration order.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package inject provides utilities for mapping and injecting dependencies in various ways.
|
Package inject provides utilities for mapping and injecting dependencies in various ways. |
|
internal
|
|
|
Package method provides type-safe HTTP method sets for route registration.
|
Package method provides type-safe HTTP method sets for route registration. |