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.
- Router
- Handler chaining
- Middleware
- Error handling
- Helper functions
- HTTPS ready
- Graceful shutdown
- Logging
- Server-Sent Events
- Usage
Webgo has a simplistic, linear path matching router and supports defining URIs with the following patterns
/api/users
- URI with no dynamic values/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
- URI with a named parameter,
/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
- Named URI parameter
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 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).
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.
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.
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 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 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()
}
WebGo exposes a singleton & global scoped logger variable LOGHANDLER with which you can plug in your custom logger by implementing the Logger interface.
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.
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.
A fully functional sample is provided here.
Refer here to find out details about making a contribution
Thanks to all the contributors
The gopher used here was created using Gopherize.me. WebGo stays out of developers' way, so sitback and enjoy a cup of coffee.