README
¶
REX
REX is a lightweight, high-performance, and middleware-extensible web framework in Go. Used by esm.sh project.
Installation
go get -u github.com/ije/rex
Usage
package main
import (
"log"
"github.com/ije/rex"
)
func main() {
// use middlewares
rex.Use(
rex.Logger(log.Default()),
rex.Cors(rex.CorsAll()),
rex.Compress(),
)
// match "GET /" route
rex.GET("/{$}", func(ctx *rex.Context) any {
return rex.Render(
rex.Tpl("<h1>My Blog</h1><ul>{{range .}}<li>{{.Title}}</li>{{end}}</ul>"),
posts.List(),
)
})
// match "GET /posts/:id" route
rex.GET("/posts/{id}", func(ctx *rex.Context) any {
post, ok := posts.Get(ctx.PathValue("id"))
if !ok {
return rex.Err(404, "post not found")
}
return post
})
// match "POST /posts" route
rex.POST("/posts", func(ctx *rex.Context) any {
return posts.Add(ctx.FormValue("title"), ctx.FormValue("author"), ctx.FormValue("content"))
})
// match "DELETE /posts/:id" route
rex.DELETE("/posts/{id}", func(ctx *rex.Context) any {
ok := posts.Delete(ctx.PathValue("id"))
return ok
})
// Starts the server
<-rex.Start(80)
// Starts the server with TLS (powered by Let's Encrypt)
<-rex.StartWithAutoTLS(443)
}
More usages please check examples/.
Middleware
In REX, a middleware is a function that receives a *rex.Context and returns a any. If the returned value is not rex.Next(), the middleware will return the value to the client, or continue to execute the next middleware.
rex.Use(func(ctx *rex.Context) any {
// return a html response
return rex.HTML("<h1>hello world</h1>")
// continue next middleware
return rex.Next()
})
Routing
REX uses ServeMux Patterns (requires Go 1.22+) to define routes.
Patterns can match the method, host and path of a request. Some examples:
/index.htmlmatches the path/index.htmlfor any host and method.GET /static/matches a GET request whose path begins with/static/.example.com/matches any request to the hostexample.com.example.com/{$}matches requests with hostexample.comand path/./b/{bucket}/o/{objectname...}matches paths whose first segment isband whose third segment iso. The namebucketdenotes the second segment andobjectnamedenotes the remainder of the path.
In general, a pattern looks like:
[METHOD ][HOST]/[PATH]
You can access the path params via the ctx.PathValue():
rex.GET("/posts/{id}", func(ctx *rex.Context) any {
return fmt.Sprintf("ID is %s", ctx.PathValue("id"))
})
Documentation
¶
Overview ¶
Package rex provides a simple & light-weight REST server in golang
Index ¶
- func AddRoute(pattern string, handle Handle)
- func Content(name string, mtime time.Time, r io.Reader) any
- func DELETE(pattern string, handles ...Handle)
- func Err(status int, v ...string) any
- func FS(root string, fallback string) any
- func File(name string) any
- func GET(pattern string, handles ...Handle)
- func HEAD(pattern string, handles ...Handle)
- func HTML(html string) any
- func Next() any
- func NoContent() any
- func PATCH(pattern string, handles ...Handle)
- func POST(pattern string, handles ...Handle)
- func PUT(pattern string, handles ...Handle)
- func Redirect(url string, status int) any
- func Render(t Template, data any) any
- func Serve(config ServerConfig) chan error
- func Start(port uint16) chan error
- func StartWithAutoTLS(port uint16, hosts ...string) chan error
- func StartWithTLS(port uint16, certFile string, keyFile string) chan error
- func Status(code int, content any) any
- func Use(middlewares ...Handle)
- type AclUser
- type AutoTLSConfig
- type Context
- func (ctx *Context) AclUser() AclUser
- func (ctx *Context) BasicAuthUser() string
- func (ctx *Context) Cookie(name string) (cookie *http.Cookie)
- func (ctx *Context) DeleteCookie(cookie http.Cookie)
- func (ctx *Context) DeleteCookieByName(name string)
- func (ctx *Context) FormFile(key string) (multipart.File, *multipart.FileHeader, error)
- func (ctx *Context) FormValue(key string) string
- func (ctx *Context) Next() any
- func (ctx *Context) ParseForm() error
- func (ctx *Context) ParseMultipartForm(maxMemory int64) error
- func (ctx *Context) PathValue(key string) string
- func (ctx *Context) Pathname() string
- func (ctx *Context) PostFormValue(key string) string
- func (ctx *Context) Query() url.Values
- func (ctx *Context) RemoteIP() string
- func (ctx *Context) Session() *SessionStub
- func (ctx *Context) SetCookie(cookie http.Cookie)
- func (ctx *Context) SetPathValue(key string, value string)
- func (ctx *Context) UserAgent() string
- type CorsOptions
- type Error
- type Handle
- func AccessLogger(logger ILogger) Handle
- func AclAuth(auth func(ctx *Context) AclUser) Handle
- func BasicAuth(auth func(name string, secret string) (ok bool, err error)) Handle
- func BasicAuthWithRealm(realm string, auth func(name string, secret string) (ok bool, err error)) Handle
- func Chain(middlewares ...Handle) Handle
- func Compress() Handle
- func Cors(c CorsOptions) Handle
- func Header(key string, value string) Handle
- func Logger(logger ILogger) Handle
- func Optional(handle Handle, condition bool) Handle
- func Perm(perms ...string) Handle
- func Session(opts SessionOptions) Handle
- func Static(root, fallback string) Handle
- type ILogger
- type Mux
- type ServerConfig
- type SessionOptions
- type SessionStub
- type TLSConfig
- type Template
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Content ¶ added in v1.0.0
Content replies to the request using the content in the provided Reader.
func FS ¶ added in v1.0.1
FS replies to the request with the contents of the file system rooted at root.
func NoContent ¶ added in v1.13.8
func NoContent() any
NoContent replies to the request with no content.
func Redirect ¶ added in v1.0.0
Redirect replies to the request with a redirect to url, which may be a path relative to the request path.
func StartWithAutoTLS ¶ added in v1.9.1
StartWithAutoTLS starts a REX server with autocert powered by Let's Encrypto SSL
func StartWithTLS ¶ added in v1.9.1
StartWithTLS starts a REX server with TLS.
Types ¶
type AclUser ¶ added in v1.12.1
type AclUser interface {
Perms() []string
}
A AclUser interface contains the Permissions method that returns the permission IDs
type AutoTLSConfig ¶ added in v0.4.0
type AutoTLSConfig struct {
AcceptTOS bool `json:"acceptTOS"`
Hosts []string `json:"hosts"`
CacheDir string `json:"cacheDir"`
Cache autocert.Cache `json:"-"`
}
AutoTLSConfig contains options to support autocert by Let's Encrypto SSL.
type Context ¶
type Context struct {
R *http.Request
W http.ResponseWriter
Header http.Header
// contains filtered or unexported fields
}
A Context to handle http requests.
func (*Context) BasicAuthUser ¶ added in v0.5.0
BasicAuthUser returns the BasicAuth username
func (*Context) DeleteCookie ¶ added in v1.14.0
DeleteCookie sets a cookie to the response with an expiration time in the past.
func (*Context) DeleteCookieByName ¶ added in v1.14.0
DeleteCookieByName sets a cookie to the response with an expiration time in the past.
func (*Context) FormFile ¶ added in v0.7.5
FormFile returns the first file for the provided form key. FormFile calls [Request.ParseMultipartForm] and [Request.ParseForm] if necessary.
func (*Context) FormValue ¶ added in v0.6.1
FormValue returns the first value for the named component of the query. The precedence order:
- application/x-www-form-urlencoded form body (POST, PUT, PATCH only)
- query parameters (always)
- multipart/form-data form body (always)
FormValue calls [Request.ParseMultipartForm] and [Request.ParseForm] if necessary and ignores any errors returned by these functions. If key is not present, FormValue returns the empty string. To access multiple values of the same key, call ParseForm and then inspect [Request.Form] directly.
func (*Context) ParseForm ¶ added in v1.12.0
ParseForm populates r.Form and r.PostForm.
For all requests, ParseForm parses the raw query from the URL and updates r.Form.
For POST, PUT, and PATCH requests, it also reads the request body, parses it as a form and puts the results into both r.PostForm and r.Form. Request body parameters take precedence over URL query string values in r.Form.
If the request Body's size has not already been limited by [MaxBytesReader], the size is capped at 10MB.
For other HTTP methods, or when the Content-Type is not application/x-www-form-urlencoded, the request Body is not read, and r.PostForm is initialized to a non-nil, empty value.
[Request.ParseMultipartForm] calls ParseForm automatically. ParseForm is idempotent.
func (*Context) ParseMultipartForm ¶
ParseMultipartForm parses a request body as multipart/form-data. The whole request body is parsed and up to a total of maxMemory bytes of its file parts are stored in memory, with the remainder stored on disk in temporary files. ParseMultipartForm calls [Request.ParseForm] if necessary. If ParseForm returns an error, ParseMultipartForm returns it but also continues parsing the request body. After one call to ParseMultipartForm, subsequent calls have no effect.
func (*Context) PathValue ¶ added in v1.12.0
PathValue returns the value for the named path wildcard in the [ServeMux] pattern that matched the request. It returns the empty string if the request was not matched against a pattern or there is no such wildcard in the pattern.
func (*Context) PostFormValue ¶ added in v1.12.0
PostFormValue returns the first value for the named component of the POST, PUT, or PATCH request body. URL query parameters are ignored. PostFormValue calls [Request.ParseMultipartForm] and [Request.ParseForm] if necessary and ignores any errors returned by these functions. If key is not present, PostFormValue returns the empty string.
func (*Context) Session ¶
func (ctx *Context) Session() *SessionStub
Session returns the session if it is undefined then create a new one.
func (*Context) SetPathValue ¶ added in v1.12.0
SetPathValue sets name to value, so that subsequent calls to r.PathValue(name) return value.
type CorsOptions ¶ added in v1.8.0
type CorsOptions struct {
// AllowedOrigins is a list of origins a cross-domain request can be executed from.
// If the special "*" value is present in the list, all origins will be allowed.
// An origin may contain a wildcard (*) to replace 0 or more characters
// (i.e.: http://*.domain.com). Usage of wildcards implies a small performance penalty.
// Only one wildcard can be used per origin.
// Default value is ["*"]
AllowedOrigins []string
// AllowOriginFunc is a custom function to validate the origin. It take the
// origin as argument and returns true if allowed or false otherwise. If
// this option is set, the content of `AllowedOrigins` is ignored.
AllowOriginFunc func(origin string) bool
// AllowOriginRequestFunc is a custom function to validate the origin. It
// takes the HTTP Request object and the origin as argument and returns true
// if allowed or false otherwise. If headers are used take the decision,
// consider using AllowOriginVaryRequestFunc instead. If this option is set,
// the content of `AllowedOrigins`, `AllowOriginFunc` are ignored.
AllowOriginRequestFunc func(r *http.Request, origin string) bool
// AllowOriginVaryRequestFunc is a custom function to validate the origin.
// It takes the HTTP Request object and the origin as argument and returns
// true if allowed or false otherwise with a list of headers used to take
// that decision if any so they can be added to the Vary header. If this
// option is set, the content of `AllowedOrigins`, `AllowOriginFunc` and
// `AllowOriginRequestFunc` are ignored.
AllowOriginVaryRequestFunc func(r *http.Request, origin string) (bool, []string)
// AllowedMethods is a list of methods the client is allowed to use with
// cross-domain requests. Default value is simple methods (HEAD, GET and POST).
AllowedMethods []string
// AllowedHeaders is list of non simple headers the client is allowed to use with
// cross-domain requests.
// If the special "*" value is present in the list, all headers will be allowed.
// Default value is [].
AllowedHeaders []string
// ExposedHeaders indicates which headers are safe to expose to the API of a CORS
// API specification
ExposedHeaders []string
// MaxAge indicates how long (in seconds) the results of a preflight request
// can be cached. Default value is 0, which stands for no
// Access-Control-Max-Age header to be sent back, resulting in browsers
// using their default value (5s by spec). If you need to force a 0 max-age,
// set `MaxAge` to a negative value (ie: -1).
MaxAge int
// AllowCredentials indicates whether the request can include user credentials like
// cookies, HTTP authentication or client side SSL certificates.
AllowCredentials bool
// AllowPrivateNetwork indicates whether to accept cross-origin requests over a
// private network.
AllowPrivateNetwork bool
// OptionsPassthrough instructs preflight to let other potential next handlers to
// process the OPTIONS method. Turn this on if your application handles OPTIONS.
OptionsPassthrough bool
// Provides a status code to use for successful OPTIONS requests.
// Default value is http.StatusNoContent (204).
OptionsSuccessStatus int
// Debugging flag adds additional output to debug server side CORS issues
Debug bool
// Adds a custom logger, implies Debug is true
Logger ILogger
}
CorsOptions is a configuration container to setup the CorsOptions middleware.
func CorsAll ¶ added in v1.12.1
func CorsAll() CorsOptions
CorsAll create a new Cors handler with permissive configuration allowing all origins with all standard methods with any header and credentials.
type Handle ¶ added in v0.8.0
Handle defines the API handle
func AccessLogger ¶ added in v0.13.2
AccessLogger returns a logger middleware to sets the access logger.
func BasicAuthWithRealm ¶ added in v0.8.0
func BasicAuthWithRealm(realm string, auth func(name string, secret string) (ok bool, err error)) Handle
BasicAuthWithRealm returns a basic HTTP authorization middleware with realm.
func Compress ¶ added in v1.12.1
func Compress() Handle
Compress returns a rex middleware to enable http compression.
func Cors ¶ added in v0.13.2
func Cors(c CorsOptions) Handle
Cors returns a CORS middleware to handle CORS.
func Logger ¶ added in v0.5.0
Logger returns a logger middleware to sets the error logger for the context.
func Optional ¶ added in v1.12.5
Optional returns a middleware handler that executes the given handler only if the condition is true.
func Perm ¶ added in v1.12.2
Perm returns a ACL middleware that sets the permission for the current request.
func Session ¶ added in v0.5.1
func Session(opts SessionOptions) Handle
Session returns a session middleware to configure the session manager.
type Mux ¶
type Mux struct {
// contains filtered or unexported fields
}
Mux is a http.Handler with middlewares and routes.
type ServerConfig ¶ added in v0.12.5
type ServerConfig struct {
Host string `json:"host"`
Port uint16 `json:"port"`
TLS TLSConfig `json:"tls"`
ReadTimeout uint32 `json:"readTimeout"`
WriteTimeout uint32 `json:"writeTimeout"`
MaxHeaderBytes uint32 `json:"maxHeaderBytes"`
}
ServerConfig contains options to run the REX server.
type SessionOptions ¶ added in v1.9.2
type SessionOptions struct {
IdHandler session.SidHandler
Pool session.Pool
}
SessionOptions contains the options for the session manager.
type SessionStub ¶ added in v1.9.2
SessionStub is a stub for a session
func (*SessionStub) Delete ¶ added in v1.9.2
func (s *SessionStub) Delete(key string)
Delete removes a session value
func (*SessionStub) Flush ¶ added in v1.9.2
func (s *SessionStub) Flush()
Flush flushes all session values
func (*SessionStub) Get ¶ added in v1.9.2
func (s *SessionStub) Get(key string) []byte
Get returns a session value
func (*SessionStub) Has ¶ added in v1.9.2
func (s *SessionStub) Has(key string) bool
Has checks a value exists
func (*SessionStub) Set ¶ added in v1.9.2
func (s *SessionStub) Set(key string, value []byte)
Set sets a session value
Source Files
Directories