goweb

README

Goweb

Light weight web framework based on net/http.

Includes

• routing
• middleware
• logging
• easy CORS (experimental)

Goweb aims to

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

Usage

See examples.

Basic usage

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"),
    })
}

Easily extendable

See serving files, template rendering, and tls for examples.

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

• 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) Resource(resourceName string, resource Resource)
  • func (e *Engine) Run(port string) 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)
  • func (m *Middleware) Resource(resourceName string, resource Resource)
• type RedirectResponse
  • func (r *RedirectResponse) Respond()
• type Resource
• type Responder
• type TextResponse
  • func (r *TextResponse) Respond()

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

func (e *Engine) Resource(resourceName string, resource Resource)

Resource creates multiple REST handlers from given interface.

func (*Engine) Run

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

Run starts a server on the given port.

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.

func (*Middleware) Resource

func (m *Middleware) Resource(resourceName string, resource Resource)

Resource creates multiple REST handlers from given interface.

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 Resource

type Resource interface {
	Index(c *Context) Responder
	Get(c *Context) Responder
	Put(c *Context) Responder
	Delete(c *Context) Responder
	Post(c *Context) Responder
	Identifier() string
}

Resource handles Index, Get, Put, Delete, and Post requests.

type Responder

type Responder interface {
	Respond()
}

Responder is the Responder interface that responds to HTTP requests.

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.