goweb

README

Goweb

Light weight web framework based on net/http.

Includes

• routing
• middleware
• logging
• auto TLS (https)
• easy CORS

Goweb aims to

1. rely only on the standard library as much as possible
2. be flexible
3. perform well

Usage

See examples.

package main

import (
	"github.com/twharmon/goweb"
)

func main() {
    app := goweb.New()
    app.GET("/hello/{name}", hello)
    app.Run(":8080")
}

func hello(c *goweb.Context) goweb.Responder {
    return c.JSON(goweb.Map{
        "hello": c.Param("name"),
    })
}

Documentation

For full documentation see pkg.go.dev.

Benchmarks

BenchmarkGinPlaintext        	 	       780 ns/op	    1040 B/op	       9 allocs/op
BenchmarkEchoPlaintext       	 	       817 ns/op	    1024 B/op	      10 allocs/op
BenchmarkGowebPlaintext      	  	      1241 ns/op	    1456 B/op	      16 allocs/op
BenchmarkGorillaPlaintext    	  	      1916 ns/op	    2032 B/op	      19 allocs/op
BenchmarkMartiniPlaintext    	   	     14448 ns/op	    1779 B/op	      36 allocs/op

BenchmarkGowebJSON           	   	     60042 ns/op	   50798 B/op	      15 allocs/op
BenchmarkGorillaJSON         	   	     61086 ns/op	   51330 B/op	      18 allocs/op
BenchmarkEchoJSON            	   	     61115 ns/op	   50280 B/op	      10 allocs/op
BenchmarkGinJSON             	   	     68322 ns/op	  100116 B/op	      10 allocs/op
BenchmarkMartiniJSON         	   	     96365 ns/op	  144335 B/op	      38 allocs/op

BenchmarkGinPathParams       	  	      2464 ns/op	    1952 B/op	      27 allocs/op
BenchmarkEchoPathParams      	  	      2600 ns/op	    1968 B/op	      27 allocs/op
BenchmarkGowebPathParams     	  	      3591 ns/op	    2673 B/op	      35 allocs/op
BenchmarkGorillaPathParams   	  	      4220 ns/op	    3265 B/op	      36 allocs/op
BenchmarkMartiniPathParams   	   	     15211 ns/op	    2657 B/op	      45 allocs/op

Contribute

Create a pull request to contribute to Goweb.

Documentation

Index

• func DirCache(dir string) autocert.Cache
• type Context
  • func (c *Context) BadRequest() *Context
  • func (c *Context) Conflict() *Context
  • func (c *Context) Created() *Context
  • func (c *Context) Empty() *EmptyResponse
  • func (c *Context) Forbidden() *Context
  • func (c *Context) Get(key string) interface{}
  • func (c *Context) InternalServerError() *Context
  • func (c *Context) JSON(value interface{}) *JSONResponse
  • func (c *Context) LogAlert(messages ...interface{})
  • func (c *Context) LogCritical(messages ...interface{})
  • func (c *Context) LogDebug(messages ...interface{})
  • func (c *Context) LogEmergency(messages ...interface{})
  • func (c *Context) LogError(messages ...interface{})
  • func (c *Context) LogInfo(messages ...interface{})
  • func (c *Context) LogNotice(messages ...interface{})
  • func (c *Context) LogWarning(messages ...interface{})
  • func (c *Context) NotFound() *Context
  • func (c *Context) Param(name string) string
  • func (c *Context) ParseJSON(target interface{}) error
  • func (c *Context) Query(name string) string
  • func (c *Context) Redirect(url string, code int) *RedirectResponse
  • func (c *Context) Set(key string, value interface{})
  • func (c *Context) SetCookie(cookie *http.Cookie)
  • func (c *Context) Status(status int) *Context
  • func (c *Context) Text(text string) *TextResponse
  • func (c *Context) Unauthorized() *Context
  • func (c *Context) UnprocessableEntity() *Context
• type CorsConfig
• type EmptyResponse
  • func (r *EmptyResponse) Respond()
• type Engine
  • func New() *Engine
  • func (e *Engine) AutoCors(config *CorsConfig)
  • func (e *Engine) DELETE(path string, handler Handler)
  • func (e *Engine) GET(path string, handler Handler)
  • func (e *Engine) HEAD(path string, handler Handler)
  • func (e *Engine) Middleware(middleware ...Handler) *Middleware
  • func (e *Engine) NotFound(handler Handler)
  • func (e *Engine) PATCH(path string, handler Handler)
  • func (e *Engine) POST(path string, handler Handler)
  • func (e *Engine) PUT(path string, handler Handler)
  • func (e *Engine) RegisterLogger(logger Logger)
  • func (e *Engine) Run(port string) error
  • func (e *Engine) RunTLS(config *TLSConfig) error
  • func (e *Engine) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (e *Engine) Shutdown() error
• type Handler
• type JSONResponse
  • func (r *JSONResponse) Respond()
• type LogLevel
  • func (l LogLevel) String() string
• type Logger
• type Map
• type Middleware
  • func (m *Middleware) DELETE(path string, handler Handler)
  • func (m *Middleware) GET(path string, handler Handler)
  • func (m *Middleware) HEAD(path string, handler Handler)
  • func (m *Middleware) Middleware(middleware ...Handler) *Middleware
  • func (m *Middleware) PATCH(path string, handler Handler)
  • func (m *Middleware) POST(path string, handler Handler)
  • func (m *Middleware) PUT(path string, handler Handler)
• type RedirectResponse
  • func (r *RedirectResponse) Respond()
• type Responder
• type TLSConfig
• type TextResponse
  • func (r *TextResponse) Respond()

Functions

func DirCache

func DirCache(dir string) autocert.Cache

DirCache creates a cache for Let's Encrypt certificates.

Types

type Context

type Context struct {
	ResponseWriter http.ResponseWriter
	Request        *http.Request
	// contains filtered or unexported fields
}

Context provides helper methods to read the request, get and set values in a data store, and send a response to the client. A new Context is constructed for each request, and is dropped when the response is sent.

func (*Context) BadRequest

func (c *Context) BadRequest() *Context

BadRequest sets the response status to 400.

func (*Context) Conflict

func (c *Context) Conflict() *Context

Conflict sets the response status to 409.

func (*Context) Created

func (c *Context) Created() *Context

Created sets the response status to 201.

func (*Context) Empty

func (c *Context) Empty() *EmptyResponse

Empty returns a EmptyResponse.

func (*Context) Forbidden

func (c *Context) Forbidden() *Context

Forbidden sets the response status to 403.

func (*Context) Get

func (c *Context) Get(key string) interface{}

Get gets a value from the Context data store.

func (*Context) InternalServerError

func (c *Context) InternalServerError() *Context

InternalServerError sets the response status to 500.

func (*Context) JSON

func (c *Context) JSON(value interface{}) *JSONResponse

JSON returns a JSONResponse.

func (*Context) LogAlert

func (c *Context) LogAlert(messages ...interface{})

LogAlert logs the given messages for the logger where ShouldLog(LogLevelAlert) method returns true.

func (*Context) LogCritical

func (c *Context) LogCritical(messages ...interface{})

LogCritical logs the given messages for the logger where ShouldLog(LogLevelCritical) method returns true.

func (*Context) LogDebug

func (c *Context) LogDebug(messages ...interface{})

LogDebug logs the given messages for the logger where ShouldLog(LogLevelDebug) method returns true.

func (*Context) LogEmergency

func (c *Context) LogEmergency(messages ...interface{})

LogEmergency logs the given messages for the logger where ShouldLog(LogLevelEmergency) method returns true.

func (*Context) LogError

func (c *Context) LogError(messages ...interface{})

LogError logs the given messages for the logger where ShouldLog(LogLevelError) method returns true.

func (*Context) LogInfo

func (c *Context) LogInfo(messages ...interface{})

LogInfo logs the given messages for the logger where ShouldLog(LogLevelInfo) method returns true.

func (*Context) LogNotice

func (c *Context) LogNotice(messages ...interface{})

LogNotice logs the given messages for the logger where ShouldLog(LogLevelNotice) method returns true.

func (*Context) LogWarning

func (c *Context) LogWarning(messages ...interface{})

LogWarning logs the given messages for the logger where ShouldLog(LogLevelWarning) method returns true.

func (*Context) NotFound

func (c *Context) NotFound() *Context

NotFound sets the response status to 404.

func (*Context) Param

func (c *Context) Param(name string) string

Param gets a path parameter by the given name. An Empty string is returned if a parameter by the given name doesn't exist.

func (*Context) ParseJSON

func (c *Context) ParseJSON(target interface{}) error

ParseJSON parses the request body into the given target.

func (*Context) Query

func (c *Context) Query(name string) string

Query gets a query value by the given name. An empty string is returned if a value by the given name doesn't exist.

func (*Context) Redirect

func (c *Context) Redirect(url string, code int) *RedirectResponse

Redirect redirects the request.

func (*Context) Set

func (c *Context) Set(key string, value interface{})

Set sets a value in the Context data store.

func (*Context) SetCookie

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

SetCookie adds a Set-Cookie header to response.

func (*Context) Status

func (c *Context) Status(status int) *Context

Status sets the response status.

func (*Context) Text

func (c *Context) Text(text string) *TextResponse

Text returns a TextResponse.

func (*Context) Unauthorized

func (c *Context) Unauthorized() *Context

Unauthorized sets the response status to 401.

func (*Context) UnprocessableEntity

func (c *Context) UnprocessableEntity() *Context

UnprocessableEntity sets the response status to 422.

type CorsConfig

type CorsConfig struct {
	Origin  string
	Headers []string
	MaxAge  time.Duration
}

CorsConfig holds CORS information.

type EmptyResponse

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

EmptyResponse implements Responder interface.

func (*EmptyResponse) Respond

func (r *EmptyResponse) Respond()

Respond sends a JSON response.

type Engine

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

Engine contains routing and logging information for your app.

func New

func New() *Engine

New returns a new Engine.

func (*Engine) AutoCors

func (e *Engine) AutoCors(config *CorsConfig)

AutoCors automatically set CORS related headers for incoming requests.

func (*Engine) DELETE

func (e *Engine) DELETE(path string, handler Handler)

DELETE registers a route for method DELETE.

func (*Engine) GET

func (e *Engine) GET(path string, handler Handler)

GET registers a route for method GET.

func (*Engine) HEAD

func (e *Engine) HEAD(path string, handler Handler)

HEAD registers a route for method HEAD.

func (*Engine) Middleware

func (e *Engine) Middleware(middleware ...Handler) *Middleware

Middleware returns a new middleware chain.

func (*Engine) NotFound

func (e *Engine) NotFound(handler Handler)

NotFound registers a handler to be called if no route is matched.

func (*Engine) PATCH

func (e *Engine) PATCH(path string, handler Handler)

PATCH registers a route for method PATCH.

func (*Engine) POST

func (e *Engine) POST(path string, handler Handler)

POST registers a route for method POST.

func (*Engine) PUT

func (e *Engine) PUT(path string, handler Handler)

PUT registers a route for method PUT.

func (*Engine) RegisterLogger

func (e *Engine) RegisterLogger(logger Logger)

RegisterLogger registers a logger.

func (*Engine) Run

func (e *Engine) Run(port string) error

Run starts a server on the given port.

func (*Engine) RunTLS

func (e *Engine) RunTLS(config *TLSConfig) error

RunTLS starts a server on port :443.

func (*Engine) ServeHTTP

func (e *Engine) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements the http.Handler interface.

func (*Engine) Shutdown

func (e *Engine) Shutdown() error

Shutdown shuts down the server.

type Handler

type Handler func(*Context) Responder

Handler handles HTTP requests.

type JSONResponse

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

JSONResponse implements Responder interface.

func (*JSONResponse) Respond

func (r *JSONResponse) Respond()

Respond sends a JSON response.

type LogLevel

type LogLevel int

LogLevel as defined in the RFC 5424 specification.

const (
	// LogLevelDebug as defined in the RFC 5424 specification.
	LogLevelDebug LogLevel = 1

	// LogLevelInfo as defined in the RFC 5424 specification.
	LogLevelInfo LogLevel = 2

	// LogLevelNotice as defined in the RFC 5424 specification.
	LogLevelNotice LogLevel = 3

	// LogLevelWarning as defined in the RFC 5424 specification.
	LogLevelWarning LogLevel = 4

	// LogLevelError as defined in the RFC 5424 specification.
	LogLevelError LogLevel = 5

	// LogLevelCritical as defined in the RFC 5424 specification.
	LogLevelCritical LogLevel = 6

	// LogLevelAlert as defined in the RFC 5424 specification.
	LogLevelAlert LogLevel = 7

	// LogLevelEmergency as defined in the RFC 5424 specification.
	LogLevelEmergency LogLevel = 8
)

func (LogLevel) String

func (l LogLevel) String() string

type Logger

type Logger interface {
	Log(ctx *Context, level LogLevel, messages ...interface{})
}

Logger is an interface that implements Log(level int, message interface{}).

type Map

type Map map[string]interface{}

Map is an alias for map[string]interface{}.

type Middleware

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

Middleware contains a set of Handler functions that will be applied in the same order in which they were registered.

func (*Middleware) DELETE

func (m *Middleware) DELETE(path string, handler Handler)

DELETE registers a route for method DELETE.

func (*Middleware) GET

func (m *Middleware) GET(path string, handler Handler)

GET registers a route for method GET.

func (*Middleware) HEAD

func (m *Middleware) HEAD(path string, handler Handler)

HEAD registers a route for method HEAD.

func (*Middleware) Middleware

func (m *Middleware) Middleware(middleware ...Handler) *Middleware

Middleware returns a new middleware chain.

func (*Middleware) PATCH

func (m *Middleware) PATCH(path string, handler Handler)

PATCH registers a route for method PATCH.

func (*Middleware) POST

func (m *Middleware) POST(path string, handler Handler)

POST registers a route for method POST.

func (*Middleware) PUT

func (m *Middleware) PUT(path string, handler Handler)

PUT registers a route for method PUT.

type RedirectResponse

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

RedirectResponse implements Responder interface.

func (*RedirectResponse) Respond

func (r *RedirectResponse) Respond()

Respond sends a plain text response.

type Responder

type Responder interface {
	Respond()
}

Responder is the Responder interface that responds to HTTP requests.

type TLSConfig

type TLSConfig struct {
	HostPolicy func(string) error
	AllowHTTP  bool
	Cache      autocert.Cache
}

TLSConfig contains TLS configuration information.

type TextResponse

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

TextResponse implements Responder interface.

func (*TextResponse) Respond

func (r *TextResponse) Respond()

Respond sends a plain text response.