router

README

router

router is a lightweight micro-framework for building Go HTTP services.

It is a modified fork of https://github.com/saurabh0719/jett

Key Features :

• Build REST APIs quickly with minimal abstraction!

• Add middleware at any level - Root, Subrouter or in a specific route!

• Built-in development server with support for graceful shutdown and shutdown functions.

• Highly flexible & easily customisable with middleware.

• Helpful response renderers for HTML, JSON, XML and Plain Text.

• Clean and simple code. Jett's core is less than 300 LOC.

• Extremely lightweight. Built on top of net/http & HttpRouter.

package main

import (
	"fmt"
	"net/http"
	"gitlab.com/golang-utils/web/lib/router"
	"gitlab.com/golang-utils/web/lib/router/middleware"
)

func main() {

	r := router.New()

	r.Use(middleware.RequestID, middleware.Logger)

	r.GET("/", Home)
	
	r.Run(":8000")
}

func Home(w http.ResponseWriter, req *http.Request) {
	router.JSON(w, "Hello World", 200)
}

Install -

$ go get gitlab.com/golang-utils/web/lib/router

Credits

Author and maintainer of Jett - Saurabh Pujari

Documentation

Overview

router is a lightweight micro-framework for building Go HTTP services.

router is a modified fork of Jett from Saurabh Pujari, see github.com/saurabh0719/jett

router builds a layer on top of HttpRouter to enable subrouting and flexible addition of middleware at any level - root, subrouter or a specific route!

Built for Go 1.23 & above.

Example :

package main

import (
	"fmt"
	"net/http"
	"gitlab.com/golang-utils/web/router"
	"gitlab.com/golang-utils/web/router/middleware"
)

func main() {

	r := router.New()

	r.Use(middleware.RequestID, middleware.Logger)

	r.GET("/", Home)

	r.Run(":8000")
}

func Home(w http.ResponseWriter, req *http.Request) {
	router.JSON(w, "Hello World", 200)
}

router strives to be simple and easy to use with minimal abstractions. The core framework is less than 300 loc but is designed to be extendable with middleware. Comes packaged with a development server equipped for graceful shutdown and a few essential middleware.

It is based on Jett by Saurabh Pujari, see https://github.com/saurabh0719/jett#readme for further details.

LICENSE

BSD 3-Clause License. Copyright (c) 2022, Saurabh Pujari. (c) 2024, Marc René Arns All rights reserved.

Index

• func HTML(w http.ResponseWriter, data interface{}, htmlFiles ...string)
• func JSON(w http.ResponseWriter, data interface{}, status int)
• func QueryParams(req *http.Request) map[string][]string
• func Text(w http.ResponseWriter, data string, status int)
• func URLParams(req *http.Request) map[string]string
• func XML(w http.ResponseWriter, data interface{}, status int)
• type Router
  • func New() *Router
  • func (r *Router) Any(path string, handlerFn http.HandlerFunc, ...)
  • func (r *Router) DELETE(path string, handlerFn http.HandlerFunc, ...)
  • func (r *Router) GET(path string, handlerFn http.HandlerFunc, ...)
  • func (r *Router) HEAD(path string, handlerFn http.HandlerFunc, ...)
  • func (r *Router) Handle(method, path string, handler http.Handler, ...)
  • func (r *Router) Handler() http.Handler
  • func (r *Router) Middleware() []func(http.Handler) http.Handler
  • func (r *Router) NotFound(handlerFn http.HandlerFunc)
  • func (r *Router) OPTIONS(path string, handlerFn http.HandlerFunc, ...)
  • func (r *Router) PATCH(path string, handlerFn http.HandlerFunc, ...)
  • func (r *Router) POST(path string, handlerFn http.HandlerFunc, ...)
  • func (r *Router) PUT(path string, handlerFn http.HandlerFunc, ...)
  • func (r *Router) PathPrefix() string
  • func (r *Router) Run(address string, onShutdownFns ...func())
  • func (r *Router) RunTLS(address, certFile, keyFile string, onShutdownFns ...func())
  • func (r *Router) RunTLSWithContext(ctx context.Context, address, certFile, keyFile string, ...)
  • func (r *Router) RunWithContext(ctx context.Context, address string, onShutdownFns ...func())
  • func (r *Router) ServeEmbededFiles(embedFS embed.FS, dir path.Relative)
  • func (r *Router) ServeFSFiles(fsys fs.ReadOnly, dir path.Absolute)
  • func (r *Router) ServeFiles(path string, root http.FileSystem)
  • func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (r *Router) Subrouter(path string) *Router
  • func (r *Router) Use(middleware ...func(http.Handler) http.Handler)

Functions

func HTML

func HTML(w http.ResponseWriter, data interface{}, htmlFiles ...string)

HTML template renderer - Sets the Content-Type header to text/html. Can render nested html files. Files need to ne sent in order of parent -> children

func JSON

func JSON(w http.ResponseWriter, data interface{}, status int)

JSON renderer. Sets the status code and the Content-Type header to application/json

func QueryParams

func QueryParams(req *http.Request) map[string][]string

Helper function to extract query params as a map[string][]string

Eg - /?one=true,false&two=true

Result - {"two" : ["true"], "one": ["true, "false"]}

func Text

func Text(w http.ResponseWriter, data string, status int)

Plain Text renderer. Sets the status code and the Content-Type header to text/plain

func URLParams

func URLParams(req *http.Request) map[string]string

Helper function to extract URL params from request Context() as a map[string]string for easy access.

func XML

func XML(w http.ResponseWriter, data interface{}, status int)

XML renderer. Sets the Content-Type header to application/xml

Types

type Router

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

Jett's Router is built on top of julienschmidt's httprouter. https://github.com/julienschmidt/httprouter

func New

func New() *Router

Create a new instance of the Jett's Router

func (*Router) Any

func (r *Router) Any(path string, handlerFn http.HandlerFunc, middleware ...func(http.Handler) http.Handler)

Assigns a HandlerFunc to the GET, HEAD, OPTIONS, POST, PUT, PATCH & DELETE method for the given path. It DOES NOT actually match any random arbitrary method.

func (*Router) DELETE

func (r *Router) DELETE(path string, handlerFn http.HandlerFunc, middleware ...func(http.Handler) http.Handler)

Assigns a HandlerFunc to the DELETE method for the given path. Route-specific middleware can be added as well.

func (*Router) GET

func (r *Router) GET(path string, handlerFn http.HandlerFunc, middleware ...func(http.Handler) http.Handler)

Assigns a HandlerFunc to the GET method for the given path. Route-specific middleware can be added as well.

func (*Router) HEAD

func (r *Router) HEAD(path string, handlerFn http.HandlerFunc, middleware ...func(http.Handler) http.Handler)

Assigns a HandlerFunc to the HEAD method for the given path. Route-specific middleware can be added as well.

func (*Router) Handle

func (r *Router) Handle(method, path string, handler http.Handler, middleware ...func(http.Handler) http.Handler)

Register the path and method to the given handler. Also applies the middleware to the Handler

func (*Router) Handler

func (r *Router) Handler() http.Handler

creates an http.Handler for the router + middleware stack

func (*Router) Middleware

func (r *Router) Middleware() []func(http.Handler) http.Handler

Middleware returns a slice ([]func(http.Handler) http.Handler) of the middleware stack for the router

func (*Router) NotFound

func (r *Router) NotFound(handlerFn http.HandlerFunc)

Assigns a HandlerFunc as http NotFound handler

func (*Router) OPTIONS

func (r *Router) OPTIONS(path string, handlerFn http.HandlerFunc, middleware ...func(http.Handler) http.Handler)

Assigns a HandlerFunc to the OPTIONS method for the given path. Route-specific middleware can be added as well.

func (*Router) PATCH

func (r *Router) PATCH(path string, handlerFn http.HandlerFunc, middleware ...func(http.Handler) http.Handler)

Assigns a HandlerFunc to the PATCH method for the given path. Route-specific middleware can be added as well.

func (*Router) POST

func (r *Router) POST(path string, handlerFn http.HandlerFunc, middleware ...func(http.Handler) http.Handler)

Assigns a HandlerFunc to the POST method for the given path. Route-specific middleware can be added as well.

func (*Router) PUT

func (r *Router) PUT(path string, handlerFn http.HandlerFunc, middleware ...func(http.Handler) http.Handler)

Assigns a HandlerFunc to the PUT method for the given path. Route-specific middleware can be added as well.

func (*Router) PathPrefix

func (r *Router) PathPrefix() string

func (*Router) Run

func (r *Router) Run(address string, onShutdownFns ...func())

development server that handles graceful shutdown. onShutdownFns -> Cleanup functions to run during shutdown

func (*Router) RunTLS

func (r *Router) RunTLS(address, certFile, keyFile string, onShutdownFns ...func())

development server that runs with TLS and handles graceful shutdown. onShutdownFns -> Cleanup functions to run during shutdown

func (*Router) RunTLSWithContext

func (r *Router) RunTLSWithContext(ctx context.Context, address, certFile, keyFile string, onShutdownFns ...func())

development server that runs with TLS and handles graceful shutdown. ctx -> coordinates shutdown with a top level context

func (*Router) RunWithContext

func (r *Router) RunWithContext(ctx context.Context, address string, onShutdownFns ...func())

development server that handles graceful shutdown. ctx -> coordinates shutdown with a top level context

func (*Router) ServeEmbededFiles

func (r *Router) ServeEmbededFiles(embedFS embed.FS, dir path.Relative)

func (*Router) ServeFSFiles

func (r *Router) ServeFSFiles(fsys fs.ReadOnly, dir path.Absolute)

func (*Router) ServeFiles

func (r *Router) ServeFiles(path string, root http.FileSystem)

Serve Static files from a directory. From github.com/julienschmidt/httprouter -> router.go :

 ServeFiles serves files from the given file system root.
 The path must end with "/*filepath", files are then served from the local
 path /defined/root/dir/*filepath.

 For example if root is "/etc" and *filepath is "passwd", the local file
 "/etc/passwd" would be served.

 Internally a http.FileServer is used, therefore http.NotFound is used instead
 of the Router's NotFound handler.

	To use the operating system's file system implementation,
 	use http.Dir:
    		router.ServeFiles("/src/*filepath", http.Dir("/var/www"))

func (*Router) ServeHTTP

func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

Implement http.Handler interface

func (*Router) Subrouter

func (r *Router) Subrouter(path string) *Router

Create a new subrouter. The subrouter automatically gets assigned the middleware from the parent router

func (*Router) Use

func (r *Router) Use(middleware ...func(http.Handler) http.Handler)

Add a middlware to the Router's middlware stack. To use built-in essential middleware,

import "github.com/saurabh0719/jett/middleware"

Read https://github.com/saurabh0719/jett#middleware for further details.