rex

package module
v1.10.12 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 11, 2024 License: MIT Imports: 26 Imported by: 1

README

REX

GoDoc GoReport MIT

REX is a lightweight, high-performance, and middleware-extensible web framework in Go. Used by esm.sh CDN.

Installing

go get -u github.com/ije/rex

Example

package main

import (
  "log"

  "github.com/ije/rex"
)

func main() {
  // use middlewares
  rex.Use(
    rex.Logger(log.Default()),
    rex.Cors(rex.CorsAllowAll()),
    rex.Compress(),
  )

  // GET / => Post list in HTML
  rex.GET("/", func(ctx *rex.Context) interface{} {
    return rex.Render(
      rex.Tpl("html", "<h1>My Blog</h1><ul>{{range .}}<li>{{.Title}}</li>{{end}}</ul>"),
      posts.GetAll(),
    )
  })

  // GET /posts/foo-bar => Post in JSON if exists
  rex.GET("/posts/:slug", func(ctx *rex.Context) interface{} {
    post, ok := posts.Get(ctx.Path.Params.Get("slug"))
    if !ok {
      return &rex.Error{404, "post not found"}
    }
    return post
  })

  // POST /posts {"title": "Hello World"} => Created Post in JSON
  rex.POST("/posts", func(ctx *rex.Context) interface{} {
    post := Newpost(ctx.Form.Value("title"))
    posts.Create(post)
    return post
  })

  // DELETE /posts/foo-bar => "true" if deleted
  rex.DELETE("/posts/:slug", func(ctx *rex.Context) interface{} {
    ok := posts.Delete(ctx.Path.Params.Get("slug"))
    return ok
  })

  // Starts the server
  <-rex.Start(80)

  // Starts the server with TLS (powered by Let's Encrypt)
  <-rex.StartWithAutoTLS(443)
}

More examples check examples.

Middleware

In REX, a middleware is a function that receives a *rex.Context and returns a interface{}. If the returned value is not nil, the middleware will return the value to the client, or continue to execute the next middleware.

rex.Use(func(ctx *rex.Context) interface{} {
  // return a html response
  return rex.HTML("<h1>hello world</h1>")

  // return nil to continue next handler
  return nil
})

Router

REX uses httprouter as the router, so you can use the same syntax as httprouter to define routes.

// static route
rex.GET("/", func(ctx *rex.Context) interface{} {})
// dynamic route
rex.GET("/posts/:slug", func(ctx *rex.Context) interface{} {})
// match all
rex.GET("/posts/*path", func(ctx *rex.Context) interface{} {})

you can access the path params via ctx.Path.Params:

rex.GET("/posts/:slug", func(ctx *rex.Context) interface{} {
  return fmt.Sprintf("slug is %s", ctx.Path.Params.Get("slug"))
})

Documentation

Overview

Package rex provides a simple & light-weight REST server in golang

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddRoute added in v1.10.1

func AddRoute(method string, pattern string, handle Handle)

func DELETE added in v1.9.0

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

DELETE returns a Handle to handle DELETE requests

func GET added in v1.9.0

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

GET returns a Handle to handle GET requests

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

HEAD returns a Handle to handle HEAD requests

func PATCH added in v1.9.0

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

PATCH returns a Handle to handle PATCH requests

func POST added in v1.9.0

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

POST returns a Handle to handle POST requests

func PUT added in v1.9.0

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

PUT returns a Handle to handle PUT requests

func Serve

func Serve(config ServerConfig) chan error

Serve serves a rex server.

func Start added in v0.9.0

func Start(port uint16) chan error

Start starts a REX server.

func StartWithAutoTLS added in v1.9.1

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

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

func StartWithTLS added in v1.9.1

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

StartWithTLS starts a REX server with TLS.

func Use added in v0.9.0

func Use(middlewares ...Handle)

Use appends middlewares to current APIS middleware stack.

Types

type ACLUser added in v0.8.1

type ACLUser interface {
	Permissions() []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 CORS

type CORS 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 Logger
}

CORS is a configuration container to setup the CORS middleware.

func CorsAllowAll added in v1.8.1

func CorsAllowAll() CORS

CorsAllowAll create a new Cors handler with permissive configuration allowing all origins with all standard methods with any header and credentials.

type Context

type Context struct {
	W     http.ResponseWriter
	R     *http.Request
	Path  *Path
	Form  *Form
	Store *Store
	// contains filtered or unexported fields
}

A Context to handle http requests.

func (*Context) ACLUser added in v0.6.0

func (ctx *Context) ACLUser() ACLUser

ACLUser returns the acl user

func (*Context) BasicAuthUser added in v0.5.0

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 cookie by name.

func (*Context) RemoteIP

func (ctx *Context) RemoteIP() string

RemoteIP returns the remote client IP.

func (*Context) RemoveCookie

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

RemoveCookie removes the cookie.

func (*Context) RemoveCookieByName added in v0.8.0

func (ctx *Context) RemoveCookieByName(name string)

RemoveCookieByName removes the cookie by name.

func (*Context) Session

func (ctx *Context) Session() *SessionStub

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

func (*Context) SetCompressionWriter added in v1.10.10

func (ctx *Context) SetCompressionWriter()

SetCompressionWriter set the compression writer based on the Accept-Encoding header

func (*Context) SetCookie

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

SetCookie sets a cookie.

type Error added in v1.0.0

type Error struct {
	Status  int    `json:"status"`
	Message string `json:"message"`
}

Error defines an error with status.

type Form added in v0.11.0

type Form struct {
	R *http.Request
}

A Form to handle request form data.

func (*Form) File added in v0.11.0

func (form *Form) File(key string) (multipart.File, *multipart.FileHeader, error)

File returns the first file for the provided form key.

func (*Form) Float added in v0.11.1

func (form *Form) Float(key string) (float64, error)

Float returns the form value as float

func (*Form) Has added in v1.6.0

func (form *Form) Has(key string) bool

Has checks the value for the key whether exists.

func (*Form) Int added in v0.11.1

func (form *Form) Int(key string) (int64, error)

Int returns the form value as integer

func (*Form) Require added in v0.11.0

func (form *Form) Require(key string) string

Require requires a value

func (*Form) RequireFloat added in v0.11.0

func (form *Form) RequireFloat(key string) float64

RequireFloat requires a value as float

func (*Form) RequireInt added in v0.11.0

func (form *Form) RequireInt(key string) int64

RequireInt requires a value as int

func (*Form) Value added in v0.11.0

func (form *Form) Value(key string) string

Value returns the first value for the named component of the POST, PATCH, or PUT request body, or returns the first value for the named component of the request url query.

type Handle added in v0.8.0

type Handle func(ctx *Context) interface{}

Handle defines the API handle

func ACL added in v0.5.1

func ACL(permission string) Handle

ACL returns a ACL middleware.

func ACLAuth added in v0.5.8

func ACLAuth(auth func(ctx *Context) ACLUser) Handle

ACLAuth returns a ACL authentication middleware.

func AccessLogger added in v0.13.2

func AccessLogger(logger Logger) Handle

AccessLogger returns a AccessLogger middleware to sets the access logger.

func BasicAuth added in v0.4.0

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

BasicAuth returns a Basic HTTP Authorization middleware.

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 Chain added in v1.10.3

func Chain(handles ...Handle) Handle

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

func Compression added in v1.8.0

func Compression() Handle

Compression is REX middleware to enable compress by content type and client `Accept-Encoding`

func Cors added in v0.13.2

func Cors(c CORS) Handle

Cors returns a Cors middleware to handle CORS.

func ErrorLogger added in v0.13.2

func ErrorLogger(logger Logger) Handle

ErrorLogger returns a ErrorLogger middleware to sets the error logger.

func Header(key string, value string) Handle

Header is REX middleware to set http header

func Session added in v0.5.1

func Session(opts SessionOptions) Handle

func Static added in v0.5.0

func Static(root, fallback string) Handle

Static returns a Static middleware handler.

type Logger added in v0.5.0

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

A Logger interface contains the Printf method.

type Param added in v1.10.1

type Param struct {
	Key   string
	Value string
}

Param is a single URL parameter, consisting of a key and a value.

type Params added in v1.10.0

type Params []Param

Params is a Param-slice, as returned by the router. The slice is ordered, the first URL parameter is also the first slice value. It is therefore safe to read values by the index.

func (Params) Get added in v1.10.0

func (ps Params) Get(name string) string

Get returns the value of the first Param which key matches the given name. If no matching Param is found, an empty string is returned.

type Path added in v1.2.0

type Path struct {
	Params Params
	// contains filtered or unexported fields
}

A Form to handle request path.

func (*Path) String added in v1.2.0

func (path *Path) String() string

String returns the path as string

type Response added in v1.10.3

type Response interface{}

Response defines the response interface.

func Content added in v1.0.0

func Content(name string, mtime time.Time, r io.ReadSeeker) Response

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

func Err added in v1.3.0

func Err(status int, v ...string) Response

Err returns an error with status.

func FS added in v1.0.1

func FS(root string, fallback string) Response

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

func File added in v1.0.0

func File(name string) Response

File replies to the request using the file content.

func HTML added in v1.0.0

func HTML(html string) Response

HTML replies to the request with a html content.

func Redirect added in v1.0.0

func Redirect(url string, status int) Response

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

func Render added in v1.0.0

func Render(t Template, data interface{}) Response

Render renders the template with the given data.

func Status added in v1.1.1

func Status(status int, payload interface{}) Response

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

type Router added in v1.10.1

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

Router is a http.Handler with middlewares and routes.

func (*Router) AddRoute added in v1.10.1

func (a *Router) AddRoute(method string, pattern string, handle Handle)

AddRoute adds a route.

func (*Router) ServeHTTP added in v1.10.1

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

ServeHTTP implements the http Handler.

func (*Router) Use added in v1.10.1

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

Use appends middlewares to current APIS middleware stack.

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.IdHandler
	Pool      session.Pool
}

type SessionStub added in v1.9.2

type SessionStub struct {
	session.Session
}

SessionStub is a stub for 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) SID added in v1.9.2

func (s *SessionStub) SID() string

SID returns the sid

func (*SessionStub) Set added in v1.9.2

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

Set sets a session value

type Store added in v1.1.0

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

A Store to store values.

func (*Store) Get added in v1.1.0

func (s *Store) Get(key string) (interface{}, bool)

Get returns the value stored in the store for a key, or nil if no value is present.

func (*Store) Set added in v1.1.0

func (s *Store) Set(key string, value interface{})

Set sets the value for a key.

type TLSConfig added in v0.9.0

type TLSConfig struct {
	Port         uint16        `json:"port"`
	CertFile     string        `json:"certFile"`
	KeyFile      string        `json:"keyFile"`
	AutoTLS      AutoTLSConfig `json:"autotls"`
	AutoRedirect bool          `json:"autoRedirect"`
}

TLSConfig contains options to support https.

type Template added in v0.5.8

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

Template is an interface for template.

func Tpl added in v1.4.0

func Tpl(ttype string, text string) Template

Directories

Path Synopsis
examples

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL