rex

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 using Let's Encrypt certificates
  <-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 {
  t := time.Now()
  defer func() {
    // Log the request
    log.Printf("%s %s %s", ctx.Method(), ctx.Pathname(), time.Since(t))
  }()

  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.html matches the path /index.html for any host and method.
• GET /static/ matches a GET request whose path begins with /static/.
• example.com/ matches any request to the host example.com.
• example.com/{$} matches requests with host example.com and path /.
• /b/{bucket}/o/{objectname...} matches paths whose first segment is b and whose third segment is o. The name bucket denotes the second segment and objectname denotes 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

• 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 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
  • func CorsAll() CorsOptions
• type Error
  • func (e *Error) Error() string
• 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
  • func New() *Mux
  • func (a *Mux) AddRoute(pattern string, handle Handle)
  • func (a *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (a *Mux) Use(middlewares ...Handle)
• type ServerConfig
• type SessionOptions
• type SessionStub
  • func (s *SessionStub) Delete(key string)
  • func (s *SessionStub) Flush()
  • func (s *SessionStub) Get(key string) []byte
  • func (s *SessionStub) Has(key string) bool
  • func (s *SessionStub) SID() string
  • func (s *SessionStub) Set(key string, value []byte)
• type TLSConfig
• type Template
  • func Tpl(text string) Template

Functions

func AddRoute

func AddRoute(pattern string, handle Handle)

AddRoute adds a route.

func Content

func Content(name string, mtime time.Time, r io.Reader) any

Content replies to the request using the content in the provided Reader.

func DELETE

func DELETE(pattern string, handles ...Handle)

DELETE returns a Handle to handle DELETE requests

func Err

func Err(code int, v ...string) any

Err returns an error with code and message.

func FS

func FS(root string, fallback string) any

FS replies to the request with the contents of the file system rooted at root.

func File

func File(name string) any

File replies to the request using the file content.

func GET

func GET(pattern string, handles ...Handle)

GET returns a Handle to handle GET requests

func HEAD

func HEAD(pattern string, handles ...Handle)

HEAD returns a Handle to handle HEAD requests

func HTML

func HTML(html string) any

HTML replies to the request with a html content.

func Invalid

func Invalid(code int, v ...string) any

Invalid returns an invalid error with code and message.

func Next

func Next() any

Next executes the next middleware in the chain.

func NoContent

func NoContent() any

NoContent replies to the request with no content.

func PATCH

func PATCH(pattern string, handles ...Handle)

PATCH returns a Handle to handle PATCH requests

func POST

func POST(pattern string, handles ...Handle)

POST returns a Handle to handle POST requests

func PUT

func PUT(pattern string, handles ...Handle)

PUT returns a Handle to handle PUT requests

func Redirect

func Redirect(url string, status int) any

Redirect replies to the request with a redirect to url, which may be a path relative to the request path.

func Render

func Render(t Template, data any) any

Render renders the template with the given data.

func Serve

func Serve(config ServerConfig) chan error

Serve serves a REX server.

func Start

func Start(port uint16) chan error

Start starts a REX server.

func StartWithAutoTLS

func StartWithAutoTLS(port uint16, hosts ...string) chan error

StartWithAutoTLS starts a REX server with autocert powered by Let's Encrypto SSL

func StartWithTLS

func StartWithTLS(port uint16, certFile string, keyFile string) chan error

StartWithTLS starts a REX server with TLS.

func Status

func Status(code int, content any) any

Status replies to the request using the payload in the status.

func Use

func Use(middlewares ...Handle)

Use appends middlewares to current APIS middleware stack.

Types

type AclUser

type AclUser interface {
	Perms() []string
}

A AclUser interface contains the Permissions method that returns the permission IDs

type AutoTLSConfig

type AutoTLSConfig struct {
	AcceptTOS bool
	Hosts     []string
	CacheDir  string
	Cache     autocert.Cache
}

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) AclUser

func (ctx *Context) AclUser() AclUser

AclUser returns the ACL user

func (*Context) BasicAuthUser

func (ctx *Context) BasicAuthUser() string

BasicAuthUser returns the BasicAuth username

func (*Context) Cookie

func (ctx *Context) Cookie(name string) (cookie *http.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

func (ctx *Context) DeleteCookie(cookie http.Cookie)

DeleteCookie sets a cookie to the response with an expiration time in the past.

func (*Context) DeleteCookieByName

func (ctx *Context) DeleteCookieByName(name string)

DeleteCookieByName sets a cookie to the response with an expiration time in the past.

func (*Context) FormFile

func (ctx *Context) FormFile(key string) (multipart.File, *multipart.FileHeader, error)

FormFile returns the first file for the provided form key. FormFile calls [Request.ParseMultipartForm] and [Request.ParseForm] if necessary.

func (*Context) FormValue

func (ctx *Context) FormValue(key string) string

FormValue returns the first value for the named component of the query. The precedence order:

1. application/x-www-form-urlencoded form body (POST, PUT, PATCH only)
2. query parameters (always)
3. 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) Method

func (ctx *Context) Method() string

Method returns the request method.

func (*Context) Next

func (ctx *Context) Next() any

Next executes the next middleware in the chain.

func (*Context) PathValue

func (ctx *Context) PathValue(key string) string

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) Pathname

func (ctx *Context) Pathname() string

Pathname returns the request pathname.

func (*Context) PostFormValue

func (ctx *Context) PostFormValue(key string) string

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

func (ctx *Context) Query() url.Values

Query returns the request query values.

func (*Context) RawQuery

func (ctx *Context) RawQuery() string

RawQuery returns the request raw query string.

func (*Context) RemoteIP

func (ctx *Context) RemoteIP() string

RemoteIP returns the remote client IP.

func (*Context) Session

func (ctx *Context) Session() *SessionStub

Session returns the session if it is undefined then create a new one.

func (*Context) SetCookie

func (ctx *Context) SetCookie(cookie http.Cookie)

SetCookie sets a cookie to the response.

func (*Context) SetHeader

func (ctx *Context) SetHeader(key, value string)

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.

func (*Context) UserAgent

func (ctx *Context) UserAgent() string

UserAgent returns the request User-Agent.

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 Error

type Error struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

Error defines an error with code and message.

func (*Error) Error

func (e *Error) Error() string

type Handle

type Handle func(ctx *Context) any

Handle defines the API handle

func AccessLogger

func AccessLogger(logger ILogger) Handle

AccessLogger returns a logger middleware to sets the access logger.

func AclAuth

func AclAuth(auth func(ctx *Context) AclUser) Handle

AclAuth returns a ACL authorization middleware.

func BasicAuth

func BasicAuth(auth func(name string, secret string) (ok bool, err error)) Handle

BasicAuth returns a basic HTTP authorization middleware.

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 Chain

func Chain(middlewares ...Handle) Handle

Chain returns a middleware handler that executes handlers in a chain.

func Compress

func Compress() Handle

Compress returns a rex middleware to enable http compression.

func Cors

func Cors(c CorsOptions) Handle

Cors returns a CORS middleware to handle CORS.

func Header

func Header(key string, value string) Handle

Header is rex middleware to set http header for the current request.

func Logger

func Logger(logger ILogger) Handle

Logger returns a logger middleware to sets the error logger for the context.

func Optional

func Optional(handle Handle, condition bool) Handle

Optional returns a middleware handler that executes the given handler only if the condition is true.

func Perm

func Perm(perms ...string) Handle

Perm returns a ACL middleware that sets the permission for the current request.

func Session

func Session(opts SessionOptions) Handle

Session returns a session middleware to configure the session manager.

func Static

func Static(root, fallback string) Handle

Static returns a static file server middleware.

type ILogger

type ILogger interface {
	Printf(format string, v ...any)
}

A ILogger interface contains the Printf method.

type Mux

type Mux struct {
	// contains filtered or unexported fields
}

Mux is a http.Handler with middlewares and routes.

func New

func New() *Mux

New returns a new Mux.

func (*Mux) AddRoute

func (a *Mux) AddRoute(pattern string, handle Handle)

AddRoute adds a route.

func (*Mux) ServeHTTP

func (a *Mux) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements the http Handler.

func (*Mux) Use

func (a *Mux) Use(middlewares ...Handle)

Use appends middlewares to current APIS middleware stack.

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

type SessionStub struct {
	session.Session
}

SessionStub is a stub for a session

func (*SessionStub) Delete

func (s *SessionStub) Delete(key string)

Delete removes a session value

func (*SessionStub) Flush

func (s *SessionStub) Flush()

Flush flushes all session values

func (*SessionStub) Get

func (s *SessionStub) Get(key string) []byte

Get returns a session value

func (*SessionStub) Has

func (s *SessionStub) Has(key string) bool

Has checks a value exists

func (*SessionStub) SID

func (s *SessionStub) SID() string

SID returns the sid

func (*SessionStub) Set

func (s *SessionStub) Set(key string, value []byte)

Set sets a session value

type TLSConfig

type TLSConfig struct {
	Port         uint16
	CertFile     string
	KeyFile      string
	AutoTLS      AutoTLSConfig
	AutoRedirect bool
}

TLSConfig contains options to support https.

type Template

type Template interface {
	Name() string
	Execute(wr io.Writer, data any) error
}

Template is an interface for template.

func Tpl

func Tpl(text string) Template