webgo

package module
v2.5.0+incompatible Latest Latest
Warning

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

 Go to latest Published: Jul 3, 2019 License: MIT Imports: 14 Imported by: 0

README

gocover.run

WebGo v2.4.0

WebGo is a minimalistic web framework for Go. It gives you the following features.

  1. Multiplexer
  2. Chaining handlers
  3. Middleware
  4. Webgo context
  5. Helper functions
  6. HTTPS ready
  7. Graceful shutdown
  8. Logging interface

WebGo's route handlers have the same signature as the standard libraries' HTTP handler. i.e. http.HandlerFunc

Multiplexer

WebGo multiplexer lets you define URIs with or without parameters. Following are the ways you can define a URI for a route.

  1. api/users - no URI parameters
  2. api/users/:userID - named URI parameter; the value would be available in the key userID
  3. api/:wildcard* - wildcard URIs; every router confirming to /api/path/to/anything would be matched by this route, and the path would be available inside the named URI parameter wildcard

If there are multiple routes which have matching path patterns, the first one defined in the list of routes takes precedence and is executed.

Chaining

Chaining lets you handle a route with multiple handlers, and are executed in sequence. All handlers in the chain are http.HandlerFuncs.


 routes := []*webgo.Route{
	{
		// A label for the API/URI
		Name: "OPTIONS",
		// request type
		Method:                  http.MethodOptions,
		Pattern:                 "/:w*",
		FallThroughPostResponse: true,
		TrailingSlash:           true,
		// route handler
		Handlers: []http.HandlerFunc{CorsOptions("*"), handler},
	},
 }
router := webgo.NewRouter(*webgo.Config, routes)
Middleware

WebGo middleware signature is func(http.ResponseWriter, *http.Request, http.HandlerFunc). Its router exposes a method Use to add a middleware to the app. e.g.

func accessLog(rw http.ResponseWriter, req *http.Request, next http.HandlerFunc) {
	start := time.Now()
	next(rw, req)
	end := time.Now()
	log := end.Format("2006-01-02 15:04:05 -0700 MST") + " " + req.Method + " " + req.URL.String() + " " + end.Sub(start).String()
	fmt.Println(log)
}

router := webgo.NewRouter(*webgo.Config, []*Route)
router.Use(accessLog)

You can add as many middleware as you want, middleware execution order is in the same order as they were added. Execution of the middlware is stopped if you do not call next().

Context

Any app specific context can be set inside the router, and is available inside every request handler via HTTP request context. The Webgo Context (injected into HTTP request context) also provides the route configuration itself as well as the URI parameters.

router := webgo.NewRouter(*webgo.Config, []*Route)
router.AppContext = map[string]interface{}{
	"dbHandler": <db handler>
}

func API1(rw http.ResponseWriter, req *http.Request) {
	wctx := webgo.Context(req)
	wctx.Params // URI paramters, a map of string of string, where the keys are the named URI parameters
	wctx.Route // is the route configuration itself for which the handler matched
	wctx.AppContext // is the app context configured in `router.AppContext`
}
Helper functions

WebGo has certain helper functions for which the responses are wrapped in a struct according to error or successful response. All success responses are wrapped in the struct

type dOutput struct {
	Data   interface{} `json:"data"`
	Status int         `json:"status"`
}

JSON output looks like

{
	"data": <any data>,
	"status: <HTTP response status code, integer>
}

All the error responses are wrapped in the struct

type errOutput struct {
	Errors interface{} `json:"errors"`
	Status int         `json:"status"`
}

JSON output for error response looks like

{
	"errors": <any data>,
	"status": <HTTP response status code, integer>
}

It provides the following helper functions.

  1. SendHeader(w http.ResponseWriter, rCode int) - Send only an HTTP response header with the required response code.
  2. Send(w http.ResponseWriter, contentType string, data interface{}, rCode int) - Send any response
  3. SendResponse(w http.ResponseWriter, data interface{}, rCode int) - Send response wrapped in WebGo's default response struct
  4. SendError(w http.ResponseWriter, data interface{}, rCode int) - Send an error wrapped in WebGo's default error response struct
  5. Render(w http.ResponseWriter, data interface{}, rCode int, tpl *template.Template) - Render renders a Go template, with the requierd data & response code.
  6. Render404(w http.ResponseWriter, tpl *template.Template) - Renders a static 404 message
  7. R200(w http.ResponseWriter, data interface{}) - Responds with the provided data, with HTTP 200 status code
  8. R201(w http.ResponseWriter, data interface{}) - Same as R200, but status code 201
  9. R204(w http.ResponseWriter) - Sends a reponse header with status code 201 and no response body.
  10. R302(w http.ResponseWriter, data interface{}) - Same as R200, but with status code 302
  11. R400(w http.ResponseWriter, data interface{}) - Same as R200, but with status code 400 and response wrapped in error struct
  12. R403(w http.ResponseWriter, data interface{}) - Same as R400, but with status code 403
  13. R404(w http.ResponseWriter, data interface{}) - Same as R400, but with status code 404
  14. R406(w http.ResponseWriter, data interface{}) - Same as R400, but with status code 406
  15. R451(w http.ResponseWriter, data interface{}) - Same as R400, but with status code 451
  16. R500(w http.ResponseWriter, data interface{}) - Same as R400, but with status code 500
HTTPS ready

HTTPS server can be started easily, just by providing the key & cert file required. You can also have both HTTP & HTTPS servers running side by side.

Start HTTPS server

cfg := webgo.Config{
	Port: "80",
	HTTPSPort: "443",
	CertFile: "/path/to/certfile",
	KeyFile: "/path/to/keyfile",
}
router := webgo.NewRouter(&cfg, []*Route)
router.StartHTTPS()

Starting both HTTP & HTTPS server

router := webgo.NewRouter(*webgo.Config, []*Route)
go router.StartHTTPS()
router.Start()
Graceful shutdown

Graceful shutdown lets you shutdown your server without affecting any live connections/clients connected to your server.

func main() {
	osSig := make(chan os.Signal, 5)

	cfg := webgo.Config{
		Host:            "",
		Port:            "8080",
		ReadTimeout:     15 * time.Second,
		WriteTimeout:    60 * time.Second,
		ShutdownTimeout: 15 * time.Second,
	}
	router := webgo.NewRouter(&cfg, getRoutes())

	go func() {
		<-osSig
		// Initiate HTTP server shutdown
		err := router.Shutdown()
		if err != nil {
			fmt.Println(err)
			os.Exit(1)
		} else {
			fmt.Println("shutdown complete")
			os.Exit(0)
		}

		// err := router.ShutdownHTTPS()
		// if err != nil {
		// 	fmt.Println(err)
		// 	os.Exit(1)
		// } else {
		// 	fmt.Println("shutdown complete")
		// 	os.Exit(0)
		// }
	}()

	signal.Notify(osSig, os.Interrupt, syscall.SIGTERM)

	router.Start()

	for {
		// Prevent main thread from exiting, and wait for shutdown to complete
		time.Sleep(time.Second * 1)
	}
}
Logging interface

Webgo has a singleton, global variable LOGHANDLER of type Logger. Logger is an interface which has the following methods:

type Logger interface {
	Debug(data ...interface{})
	Info(data ...interface{})
	Warn(data ...interface{})
	Error(data ...interface{})
	Fatal(data ...interface{})
}

The singleton variable is initialized in the package's init() function. The default logger which is initialized in Webgo has uses Go's standard log library.

A custom logger which implements the same interface can be assigned to the singleton to use your own logger.


package main

import (
	"github.com/bnkamalesh/webgo"
)

func main() {
	webgo.LOGHANDLER = customLogger
}

Full sample

package main

import (
	"net/http"
	"time"

	"github.com/bnkamalesh/webgo/middleware"

	"github.com/bnkamalesh/webgo"
)

func helloWorld(w http.ResponseWriter, r *http.Request) {
	wctx := webgo.Context(r)
	webgo.R200(
		w,
		wctx.Params, // URI parameters
	)
}

func getRoutes() []*webgo.Route {
	return []*webgo.Route{
		&webgo.Route{
			Name:     "helloworld",                   // A label for the API/URI, this is not used anywhere.
			Method:   http.MethodGet,                 // request type
			Pattern:  "/",                            // Pattern for the route
			Handlers: []http.HandlerFunc{helloWorld}, // route handler
		},
		&webgo.Route{
			Name:     "helloworld",                                     // A label for the API/URI, this is not used anywhere.
			Method:   http.MethodGet,                                   // request type
			Pattern:  "/api/:param",                                    // Pattern for the route
			Handlers: []http.HandlerFunc{middleware.Cors(), helloWorld}, // route handler
		},
	}
}

func main() {
	cfg := webgo.Config{
		Host:         "",
		Port:         "8080",
		ReadTimeout:  15 * time.Second,
		WriteTimeout: 60 * time.Second,
	}
	router := webgo.NewRouter(&cfg, getRoutes())
	router.Use(middleware.AccessLog)
	router.Start()
}
Testing

URI parameters, route matching, HTTP server, HTTPS server, graceful shutdown and context fetching are tested in the tests provided.

$ cd $GOPATH/src/github.com/bnkamalesh/webgo
$ go test

Documentation

Overview

Package webgo is a lightweight framework for building web apps. It has a multiplexer, middleware plugging mechanism & context management of its own. The primary goal of webgo is to get out of the developer's way as much as possible. i.e. it does not enforce you to build your app in any particular pattern, instead just helps you get all the trivial things done faster and easier.

e.g. 1. Getting named URI parameters. 2. Multiplexer for regex matching of URI and such. 3. Inject special app level configurations or any such objects to the request context as required.

Index

Constants

View Source 
const (
	// HeaderContentType is the key for mentioning the response header content type
	HeaderContentType = "Content-Type"
	// JSONContentType is the MIME type when the response is JSON
	JSONContentType = "application/json"
	// HTMLContentType is the MIME type when the response is HTML
	HTMLContentType = "text/html; charset=UTF-8"

	// ErrInternalServer to send when there's an internal server error
	ErrInternalServer = "Internal server error."
)

Variables

View Source 
var (
	// ErrInvalidPort is the error returned when the port number provided in the config file is invalid
	ErrInvalidPort = errors.New("Port number not provided or is invalid (should be between 0 - 65535)")
)

Functions

func R200 

func R200(w http.ResponseWriter, data interface{})

R200 - Successful/OK response

func R201 

func R201(w http.ResponseWriter, data interface{})

R201 - New item created

func R204 

func R204(w http.ResponseWriter)

R204 - empty, no content

func R302 

func R302(w http.ResponseWriter, data interface{})

R302 - Temporary redirect

func R400 

func R400(w http.ResponseWriter, data interface{})

R400 - Invalid request, any incorrect/erraneous value in the request body

func R403 

func R403(w http.ResponseWriter, data interface{})

R403 - Unauthorized access

func R404 

func R404(w http.ResponseWriter, data interface{})

R404 - Resource not found

func R406 

func R406(w http.ResponseWriter, data interface{})

R406 - Unacceptable header. For any error related to values set in header

func R451 

func R451(w http.ResponseWriter, data interface{})

R451 - Resource taken down because of a legal request

func R500 

func R500(w http.ResponseWriter, data interface{})

R500 - Internal server error

func Render 

func Render(w http.ResponseWriter, data interface{}, rCode int, tpl *template.Template)

Render is used for rendering templates (HTML)

func Render404 

func Render404(w http.ResponseWriter, tpl *template.Template)

Render404 - used to render a 404 page

func Send 

func Send(w http.ResponseWriter, contentType string, data interface{}, rCode int)

Send sends a completely custom response without wrapping in the `{data: <data>, status: <int>` struct

func SendError 

func SendError(w http.ResponseWriter, data interface{}, rCode int)

SendError is used to respond to any request with an error

func SendHeader 

func SendHeader(w http.ResponseWriter, rCode int)

SendHeader is used to send only a response header, i.e no response body

func SendResponse 

func SendResponse(w http.ResponseWriter, data interface{}, rCode int)

SendResponse is used to respond to any request (JSON response) based on the code, data etc.

Types

type Config 

type Config struct {
	// Host is the host on which the server is listening
	Host string `json:"host,omitempty"`
	// Port is the port number where the server has to listen for the HTTP requests
	Port string `json:"port,omitempty"`

	// CertFile is the TLS/SSL certificate file path, required for HTTPS
	CertFile string `json:"certFile,omitempty"`
	// KeyFile is the filepath of private key of the certificate
	KeyFile string `json:"keyFile,omitempty"`
	// HTTPSPort is the port number where the server has to listen for the HTTP requests
	HTTPSPort string `json:"httpsPort,omitempty"`

	// ReadTimeout is the maximum duration for which the server would read a request
	ReadTimeout time.Duration `json:"readTimeout,omitempty"`
	// WriteTimeout is the maximum duration for which the server would try to respond
	WriteTimeout time.Duration `json:"writeTimeout,omitempty"`

	// InsecureSkipVerify is the HTTP certificate verification
	InsecureSkipVerify bool `json:"insecureSkipVerify,omitempty"`

	// ShutdownTimeout is the duration in which graceful shutdown is completed, in seconds
	ShutdownTimeout time.Duration
}

Config is used for reading app's configuration from json file

func (*Config) Load 

func (cfg *Config) Load(filepath string)

Load config file from the provided filepath and validate

func (*Config) Validate 

func (cfg *Config) Validate() error

Validate the config parsed into the Config struct

type ErrorData 

type ErrorData struct {
	ErrCode        int
	ErrDescription string
}

ErrorData used to render the error page

type Logger 

type Logger interface {
	Debug(data ...interface{})
	Info(data ...interface{})
	Warn(data ...interface{})
	Error(data ...interface{})
	Fatal(data ...interface{})
}

Service defines all the logging methods to be implemented 

var LOGHANDLER Logger

type Route 

type Route struct {
	// Name is unique identifier for the route
	Name string
	// Method is the HTTP request method/type
	Method string
	// Pattern is the URI pattern to match
	Pattern string
	// TrailingSlash if set to true, the URI will be matched with or without
	// a trailing slash. Note: It does not *do* a redirect.
	TrailingSlash bool

	// FallThroughPostResponse if enabled will execute all the handlers even if a response was already sent to the client
	FallThroughPostResponse bool

	// Handlers is a slice of http.HandlerFunc which can be middlewares or anything else. Though only 1 of them will be allowed to respond to client.
	// subsequent writes from the following handlers will be ignored
	Handlers []http.HandlerFunc
	// contains filtered or unexported fields
}

Route defines a route for each API

type Router 

type Router struct {

	// NotFound is the generic handler for 404 resource not found response
	NotFound http.HandlerFunc
	// AppContext holds all the app specific context which is to be injected into all HTTP
	// request context
	AppContext map[string]interface{}
	// contains filtered or unexported fields
}

Router is the HTTP router

func NewRouter 

func NewRouter(cfg *Config, routes []*Route) *Router

NewRouter initializes returns a new router instance with all the configurations and routes set

func (*Router) ServeHTTP 

func (rtr *Router) ServeHTTP(rw http.ResponseWriter, req *http.Request)

func (*Router) Shutdown 

func (router *Router) Shutdown() error

Shutdown gracefully shuts down HTTP server

func (*Router) ShutdownHTTPS 

func (router *Router) ShutdownHTTPS() error

ShutdownHTTPS gracefully shuts down HTTPS server

func (*Router) Start 

func (router *Router) Start()

Start starts the HTTP server with the appropriate configurations

func (*Router) StartHTTPS 

func (router *Router) StartHTTPS()

StartHTTPS starts the server with HTTPS enabled

func (*Router) Use 

func (rtr *Router) Use(f func(http.ResponseWriter, *http.Request, http.HandlerFunc))

Use adds a middleware layer

type WC 

type WC struct {
	Params     map[string]string
	Route      *Route
	AppContext map[string]interface{}
}

WC is the WebgoContext. A new instance of WC is injected inside every request's context object Note: This name will be deperecated and renamed to `WebgoContext` in the next major release

func Context 

func Context(r *http.Request) *WC

Context returns the WebgoContext injected inside the HTTP request context

Source Files

View all Source files

Directories

Path Synopsis
Package middleware defines the signature/type which can be added as a middleware to Webgo.
 Package middleware defines the signature/type which can be added as a middleware to Webgo.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.