webgo

package module
v6.7.1 Latest Latest
Warning

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

 Go to latest Published: Apr 21, 2024 License: MIT Imports: 18 Imported by: 4

README

webgo gopher

coverage

WebGo v6.7.0

WebGo is a minimalistic router for Go to build web applications (server side) with no 3rd party dependencies. WebGo will always be Go standard library compliant; with the HTTP handlers having the same signature as http.HandlerFunc.

Contents
  1. Router
  2. Handler chaining
  3. Middleware
  4. Error handling
  5. Helper functions
  6. HTTPS ready
  7. Graceful shutdown
  8. Logging
  9. Server-Sent Events
  10. Usage

Router

Webgo has a simplistic, linear path matching router and supports defining URIs with the following patterns

  1. /api/users - URI with no dynamic values
  2. /api/users/:userID
    • URI with a named parameter, userID
    • If TrailingSlash is set to true, it will accept the URI ending with a '/', refer to sample
  3. /api/users/:misc*
    • Named URI parameter misc, with a wildcard suffix '*'
    • This matches everything after /api/users. e.g. /api/users/a/b/c/d

When there are multiple handlers matching the same URI, only the first occurring handler will handle the request. Refer to the sample to see how routes are configured. You can access named parameters of the URI using the Context function.

Note: webgo Context is not available inside the special handlers (not found & method not implemented)

func helloWorld(w http.ResponseWriter, r *http.Request) {
	// WebGo context
	wctx := webgo.Context(r)
	// URI paramaters, map[string]string
	params := wctx.Params()
	// route, the webgo.Route which is executing this request
	route := wctx.Route
	webgo.R200(
		w,
		fmt.Sprintf(
			"Route name: '%s', params: '%s'",
			route.Name,
			params,
		),
	)
}

Handler chaining

Handler chaining lets you execute multiple handlers for a given route. Execution of a chain can be configured to run even after a handler has written a response to the HTTP request, if you set FallThroughPostResponse to true (refer sample).

Middleware

WebGo middlware lets you wrap all the routes with a middleware unlike handler chaining. The router exposes a method Use && UseOnSpecialHandlers to add a Middleware to the router.

NotFound && NotImplemented are considered Special handlers. webgo.Context(r) within special handlers will return nil.

Any number of middleware can be added to the router, the order of execution of middleware would be LIFO (Last In First Out). i.e. in case of the following code

func main() {
	router.Use(accesslog.AccessLog, cors.CORS(nil))
	router.Use(<more middleware>)
}

CorsWrap would be executed first, followed by AccessLog.

Error handling

Webgo context has 2 methods to set & get erro within a request context. It enables Webgo to implement a single middleware where you can handle error returned within an HTTP handler. set error, get error.

Helper functions

WebGo provides a few helper functions. When using Send or SendResponse (other Rxxx responder functions), the response is wrapped in WebGo's response struct and is serialized as JSON.

{
  "data": "<any valid JSON payload>",
  "status": "<HTTP status code, of type integer>"
}

When using SendError, the response is wrapped in WebGo's error response struct and is serialzied as JSON.

{
  "errors": "<any valid JSON payload>",
  "status": "<HTTP status code, of type integer>"
}

HTTPS ready

HTTPS server can be started easily, by providing the key & cert file. 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, routes()...)
router.StartHTTPS()

Starting both HTTP & HTTPS server

cfg := &webgo.Config{
	Port: "80",
	HTTPSPort: "443",
	CertFile: "/path/to/certfile",
	KeyFile: "/path/to/keyfile",
}

router := webgo.NewRouter(cfg, routes()...)
go router.StartHTTPS()
router.Start()

Graceful shutdown

Graceful shutdown lets you shutdown the server without affecting any live connections/clients connected to the server. Any new connection request after initiating a shutdown would be ignored.

Sample code to show how to use shutdown

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, routes()...)

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

		// If you have HTTPS server running, you can use the following code
		// err := router.ShutdownHTTPS()
		// if err != nil {
		// 	fmt.Println(err)
		// 	os.Exit(1)
		// } else {
		// 	fmt.Println("shutdown complete")
		// 	os.Exit(0)
		// }
	}()

	go func(){
		time.Sleep(time.Second*15)
		signal.Notify(osSig, os.Interrupt, syscall.SIGTERM)
	}()

	router.Start()
}

Logging

WebGo exposes a singleton & global scoped logger variable LOGHANDLER with which you can plug in your custom logger by implementing the Logger interface.

Configuring the default Logger

The default logger uses Go standard library's log.Logger with os.Stdout (for debug and info logs) & os.Stderr (for warning, error, fatal) as default io.Writers. You can set the io.Writer as well as disable specific types of logs using the GlobalLoggerConfig(stdout, stderr, cfgs...) function.

Server-Sent Events

MDN has a very good documentation of what SSE (Server-Sent Events) are. The sample app provided shows how to use the SSE extension of webgo.

Usage

A fully functional sample is provided here.

Benchmark
  1. the-benchmarker
  2. go-web-framework-benchmark
Contributing

Refer here to find out details about making a contribution

Credits

Thanks to all the contributors

The gopher

The gopher used here was created using Gopherize.me. WebGo stays out of developers' way, so sitback and enjoy a cup of coffee.

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 (
	// LogCfgDisableDebug is used to disable debug logs
	LogCfgDisableDebug = logCfg("disable-debug")
	// LogCfgDisableInfo is used to disable info logs
	LogCfgDisableInfo = logCfg("disable-info")
	// LogCfgDisableWarn is used to disable warning logs
	LogCfgDisableWarn = logCfg("disable-warn")
	// LogCfgDisableError is used to disable error logs
	LogCfgDisableError = logCfg("disable-err")
	// LogCfgDisableFatal is used to disable fatal logs
	LogCfgDisableFatal = logCfg("disable-fatal")
)
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 GetError 

func GetError(r *http.Request) error

GetError is a helper function to get the error from webgo context

func GlobalLoggerConfig 

func GlobalLoggerConfig(stdout io.Writer, stderr io.Writer, cfgs ...logCfg)

GlobalLoggerConfig is used to configure the global/default logger of webgo IMPORTANT: This is not concurrent safe

func OriginalResponseWriter 

func OriginalResponseWriter(rw http.ResponseWriter) http.ResponseWriter

OriginalResponseWriter returns the Go response writer stored within the webgo custom response writer

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 ResponseStatus 

func ResponseStatus(rw http.ResponseWriter) int

ResponseStatus returns the response status code. It works only if the http.ResponseWriter is not wrapped in another response writer before calling ResponseStatus

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.

func SetError 

func SetError(r *http.Request, err error)

SetError is a helper function to set the error in webgo context

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
	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 ContextPayload 

type ContextPayload struct {
	Route     *Route
	Err       error
	URIParams map[string]string
}

ContextPayload is the WebgoContext. A new instance of ContextPayload is injected inside every request's context object

func Context 

func Context(r *http.Request) *ContextPayload

Context returns the ContextPayload injected inside the HTTP request context

func (*ContextPayload) Error 

func (cp *ContextPayload) Error() error

Error returns the error set within the context

func (*ContextPayload) Params 

func (cp *ContextPayload) Params() map[string]string

Params returns the URI parameters of the respective route

func (*ContextPayload) SetError 

func (cp *ContextPayload) SetError(err error)

SetError sets the err within the context

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{})
}

Logger defines all the logging methods to be implemented 

var LOGHANDLER Logger

LOGHANDLER is a global variable which webgo uses to log messages

type Middleware 

type Middleware func(http.ResponseWriter, *http.Request, http.HandlerFunc)

Middleware is the signature of WebGo's middleware

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. IMPORTANT: It does not 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 RouteGroup 

type RouteGroup struct {

	// PathPrefix is the URI prefix for all routes in this group
	PathPrefix string
	// contains filtered or unexported fields
}

func NewRouteGroup 

func NewRouteGroup(pathPrefix string, skipRouterMiddleware bool, rr ...Route) *RouteGroup

func (*RouteGroup) Add 

func (rg *RouteGroup) Add(rr ...Route)

func (*RouteGroup) Routes 

func (rg *RouteGroup) Routes() []*Route

func (*RouteGroup) Use 

func (rg *RouteGroup) Use(mm ...Middleware)

type Router 

type Router struct {

	// NotFound is the generic handler for 404 resource not found response
	NotFound http.HandlerFunc

	// NotImplemented is the generic handler for 501 method not implemented
	NotImplemented http.HandlerFunc
	// 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) Add 

func (rtr *Router) Add(routes ...*Route)

Add is a convenience method used to add a new route to an already initialized router Important: `.Use` should be used only after all routes are added

func (*Router) ServeHTTP 

func (rtr *Router) ServeHTTP(rw http.ResponseWriter, r *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(mm ...Middleware)

Use adds a middleware layer

func (*Router) UseOnSpecialHandlers 

func (rtr *Router) UseOnSpecialHandlers(mm ...Middleware)

UseOnSpecialHandlers adds middleware to the 2 special handlers of webgo

Source Files

View all Source files

Directories

Path Synopsis
extensions
sse
Package sse implements Server-Sent Events(SSE) This extension is compliant with any net/http implementation, and is not limited to WebGo.
 Package sse implements Server-Sent Events(SSE) This extension is compliant with any net/http implementation, and is not limited to WebGo.
middleware
accesslog
Package accesslogs provides a simple straight forward access log middleware.
 Package accesslogs provides a simple straight forward access log middleware.
cors
Package cors sets the appropriate CORS(https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) response headers, and lets you customize.
 Package cors sets the appropriate CORS(https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) response headers, and lets you customize.

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.