husky

README

Husky

Microservice framework written in Go.

Example

func main() {
    h := husky.New()

    // index handler
    h.GET("/", func(c husky.Context) error {
        return c.JSON(200, "Hello World!")
    })

    h.Start()
}

Config

Husky provides the ability to configure your service from a central config file. Copy .env.example to .env into the source of your service. You can place any environment variables into this file. The .env is loaded into a Config struct which can be read from anywhere in the service.

Routes

Add Routes

// Add GET route
h.GET('/endpoint', handler)

// Add POST route
h.POST('/endpoint', handler)

// Add PATCH route
h.PATCH('/endpoint', handler)

// Add PUT route
h.PUT('/endpoint', handler)

// Add DELETE route
h.DELETE('/endpoint', handler)

Middleware

Included Middleware

Husky includes a couple of middleware (more to come) handlers which can be used right out of the box.

JWT Middleware

// the JWT middleware gets the key/secret from the config which is set in .env
h.GET("/endpoint", handler, middleware.JWT)

CORS Middleware

h.GET("/endpoint", handler, middleware.CORSConfig{
  AllowedOrigins: "http://domain.com",  // default "*"
  AllowedMethods: "GET,POST,PUT,PATCH", // default "*"
  AllowedHeaders: "application/json",   // default "*"
  ExposedHeaders: "*",                  // default "*"
})

Custom Middleware

Husky allows you to define your own custom middleware that can be used throughout your service.

To create custom middleware:

// Define middleware handler
middleware := func(c husky.Context, handler husky.Handler) husky.Handler {
    // code here
    return handler
}

// Add middleware to route
h.GET('/path', handler, middleware)

How to Implement Middleware

Middleware

Adds a middleware handler to be executed after route is found but before the handler is executed.

h.Middleware(middleware1)
h.Middleware(middleware2)
-- or --
h.Middleware(middleware1, middleware2)

Before

Adds a middleware function to be executed before the route handler is executed.

h.Before(middleware1)
h.Before(middleware2)
-- or --
h.Before(middleware1, middleware2)

After

Adds a middleware function to be executed after the route handler is executed.

h.After(middleware1)
h.After(middleware2)
-- or --
h.After(middleware1, middleware2)

Route Groups

// Create Route Group
g := h.Group('/prefix')
g.GET('/endpoint', handler) // GET /prefix/endpoint
g.POST('/endpoint', handler) // POST /prefix/endpoint

Middleware

Groups can have defined middleware. These middleware handlers will be executed for every route within the group:

g := h.Group('/prefix', middlewareHandler1, middlewareHandler1)

Groups can have middleware handlers that are executed for every route within the group:

g := h.Group('/prefix')
g.Middleware(middlwareHandler1)
g.Middleware(middlwareHandler2)

If you need middleware to be executed on specific routes you can add middleware to the route definition:

g := h.Group('/prefix')
g.GET('/endpoint', handler, middleware)

Development

Husky uses golang's dep for dependency management. Make sure dep is installed on your local development machine.

To pull in the required dependencies, run the following command: dep ensure.

Documentation

Index

• func NotFoundHandler(ctx *CTX) (err error)
• type CTX
  • func (ctx *CTX) AddParams(params map[string]string)
  • func (ctx *CTX) Code(code int) (err error)
  • func (ctx *CTX) GetHeader(header string) string
  • func (ctx *CTX) GetParam(i string) string
  • func (ctx *CTX) GetParams() map[string]string
  • func (ctx *CTX) HTTPError(code int, message string) (err error)
  • func (ctx *CTX) HasParam(param string) bool
  • func (ctx *CTX) JSON(code int, i interface{}) (err error)
  • func (ctx *CTX) Redirect(code int, uri string) (err error)
  • func (ctx *CTX) SetHeader(k string, v string)
  • func (ctx *CTX) String(code int, s string) (err error)
• type Configuration
  • func (configuration *Configuration) Load() map[string]string
• type Group
  • func (g *Group) DELETE(endpoint string, handler Handler, middleware ...MiddlewareHandler)
  • func (g *Group) GET(endpoint string, handler Handler, middleware ...MiddlewareHandler)
  • func (g *Group) Middleware(m MiddlewareHandler)
  • func (g *Group) PATCH(endpoint string, handler Handler, middleware ...MiddlewareHandler)
  • func (g *Group) POST(endpoint string, handler Handler, middleware ...MiddlewareHandler)
  • func (g *Group) PUT(endpoint string, handler Handler, middleware ...MiddlewareHandler)
• type Handler
• type Husky
  • func New() (husky *Husky)
  • func (husky *Husky) After(middleware ...MiddlewareHandler)
  • func (husky *Husky) Before(middleware ...MiddlewareHandler)
  • func (husky *Husky) DELETE(endpoint string, handler Handler, middleware ...MiddlewareHandler)
  • func (husky *Husky) GET(endpoint string, handler Handler, middleware ...MiddlewareHandler)
  • func (husky *Husky) GetContext() *CTX
  • func (husky *Husky) Group(prefix string, middleware ...MiddlewareHandler) *Group
  • func (husky *Husky) Middlware(middleware MiddlewareHandler)
  • func (husky *Husky) NewContext(w http.ResponseWriter, r *http.Request) *CTX
  • func (husky *Husky) OPTIONS(endpoint string, handler Handler, middleware ...MiddlewareHandler)
  • func (husky *Husky) PATCH(endpoint string, handler Handler, middleware ...MiddlewareHandler)
  • func (husky *Husky) POST(endpoint string, handler Handler, middleware ...MiddlewareHandler)
  • func (husky *Husky) PUT(endpoint string, handler Handler, middleware ...MiddlewareHandler)
  • func (husky *Husky) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (husky *Husky) Start()
• type MiddlewareHandler
• type Response
  • func NewResponse(w http.ResponseWriter) (r *Response)
  • func (response *Response) Header() http.Header
  • func (response *Response) Write(b []byte) (n int, err error)
  • func (response *Response) WriteHeader(code int)
• type Route
• type Router
  • func (router *Router) Add(verb string, endpoint string, handler Handler, middleware []MiddlewareHandler)
  • func (router *Router) FindRoute(ctx *CTX) (bool, Route)
  • func (router *Router) GetRoutes(method string) map[string]Route

Functions

func NotFoundHandler

func NotFoundHandler(ctx *CTX) (err error)

NotFoundHandler default 404 handler for not found routes

Types

type CTX

type CTX struct {
	Request  *http.Request
	Response *Response
	Params   map[string]string
}

CTX (Context) struct

func (*CTX) AddParams

func (ctx *CTX) AddParams(params map[string]string)

AddParams adds parameters to context

func (*CTX) Code

func (ctx *CTX) Code(code int) (err error)

Code writes header with HTTP code

func (*CTX) GetHeader

func (ctx *CTX) GetHeader(header string) string

GetHeader returns specified header

func (*CTX) GetParam

func (ctx *CTX) GetParam(i string) string

GetParam return specified paramater

func (*CTX) GetParams

func (ctx *CTX) GetParams() map[string]string

GetParams returns all stored parameters

func (*CTX) HTTPError

func (ctx *CTX) HTTPError(code int, message string) (err error)

HTTPError returns a text/html error with requested code

func (*CTX) HasParam

func (ctx *CTX) HasParam(param string) bool

HasParam checks if param is set

func (*CTX) JSON

func (ctx *CTX) JSON(code int, i interface{}) (err error)

JSON returns response as serialized JSON

func (*CTX) Redirect

func (ctx *CTX) Redirect(code int, uri string) (err error)

Redirect returns a HTTP code

func (*CTX) SetHeader

func (ctx *CTX) SetHeader(k string, v string)

SetHeader adds header to response

func (*CTX) String

func (ctx *CTX) String(code int, s string) (err error)

type Configuration

type Configuration struct{}

Configuration handles a Husky service's configuration

func (*Configuration) Load

func (configuration *Configuration) Load() map[string]string

Load reads and returns a .env file as a map

type Group

type Group struct {
	Husky              *Husky
	MiddlewareHandlers []MiddlewareHandler
	Prefix             string
}

Group holds information about the route group

func (*Group) DELETE

func (g *Group) DELETE(endpoint string, handler Handler, middleware ...MiddlewareHandler)

DELETE adds a HTTP DELETE method to the group

func (*Group) GET

func (g *Group) GET(endpoint string, handler Handler, middleware ...MiddlewareHandler)

GET adds a HTTP Get method to the group

func (*Group) Middleware

func (g *Group) Middleware(m MiddlewareHandler)

Middleware adds a middleware handler to be executed after route is found but before the handler is executed

func (*Group) PATCH

func (g *Group) PATCH(endpoint string, handler Handler, middleware ...MiddlewareHandler)

PATCH adds a HTTP PATCH method to the group

func (*Group) POST

func (g *Group) POST(endpoint string, handler Handler, middleware ...MiddlewareHandler)

POST adds a HTTP POST method to the group

func (*Group) PUT

func (g *Group) PUT(endpoint string, handler Handler, middleware ...MiddlewareHandler)

PUT adds a HTTP PUT method to the group

type Handler

type Handler func(*CTX) error

Handler basic function to router handlers

type Husky

type Husky struct {
	AfterMiddleware  []MiddlewareHandler
	BeforeMiddleware []MiddlewareHandler
	Config           Configuration
	Context          *CTX
	Middleware       []MiddlewareHandler
	Router           *Router
}

Husky struct holds router and context for framework

func New

func New() (husky *Husky)

New creates a new service

func (*Husky) After

func (husky *Husky) After(middleware ...MiddlewareHandler)

After adds a handler to be executed after the route handler Executed if route is found or not

func (*Husky) Before

func (husky *Husky) Before(middleware ...MiddlewareHandler)

Before adds a handler to be executed before the route handler Executed if route is found or not

func (*Husky) DELETE

func (husky *Husky) DELETE(endpoint string, handler Handler, middleware ...MiddlewareHandler)

DELETE adds a HTTP DELETE route to router

func (*Husky) GET

func (husky *Husky) GET(endpoint string, handler Handler, middleware ...MiddlewareHandler)

GET adds a HTTP GET route to router

func (*Husky) GetContext

func (husky *Husky) GetContext() *CTX

GetContext returns current context

func (*Husky) Group

func (husky *Husky) Group(prefix string, middleware ...MiddlewareHandler) *Group

Group creates a route group with a common prefix

func (*Husky) Middlware

func (husky *Husky) Middlware(middleware MiddlewareHandler)

Middlware adds a handler to be executed before the route handler

func (*Husky) NewContext

func (husky *Husky) NewContext(w http.ResponseWriter, r *http.Request) *CTX

NewContext creates new Context struct

func (*Husky) OPTIONS

func (husky *Husky) OPTIONS(endpoint string, handler Handler, middleware ...MiddlewareHandler)

OPTIONS adds a HTTP OPTIONS route to router

func (*Husky) PATCH

func (husky *Husky) PATCH(endpoint string, handler Handler, middleware ...MiddlewareHandler)

PATCH adds a HTTP PATCH route to router

func (*Husky) POST

func (husky *Husky) POST(endpoint string, handler Handler, middleware ...MiddlewareHandler)

POST adds a HTTP POST route to router

func (*Husky) PUT

func (husky *Husky) PUT(endpoint string, handler Handler, middleware ...MiddlewareHandler)

PUT adds a HTTP PUT route to router

func (*Husky) ServeHTTP

func (husky *Husky) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Husky) Start

func (husky *Husky) Start()

Start initates the framework to start listening for requests

type MiddlewareHandler

type MiddlewareHandler func(Handler) Handler

MiddlewareHandler defines a function to process middleware

type Response

type Response struct {
	Writer    http.ResponseWriter
	Status    int
	Size      int64
	Committed bool
}

Response standard Husky response struct

func NewResponse

func NewResponse(w http.ResponseWriter) (r *Response)

NewResponse creates new Husky Response struct

func (*Response) Header

func (response *Response) Header() http.Header

Header returns the header information

func (*Response) Write

func (response *Response) Write(b []byte) (n int, err error)

Write writs the bytes (message) to the client

func (*Response) WriteHeader

func (response *Response) WriteHeader(code int)

WriteHeader writes a header to the response writer

type Route

type Route struct {
	Handler    Handler             // main handler
	Endpoint   string              // endpoint for route
	Middleware []MiddlewareHandler // array of middleware handlers
	Verb       string              // http verb
}

Route holds all information about a defined route

type Router

type Router struct {
	Routes map[string]map[string]Route
}

Router holds all defined routes map[string]map[string] = [VERB][PATTERN] = [GET][/users]

func (*Router) Add

func (router *Router) Add(verb string, endpoint string, handler Handler, middleware []MiddlewareHandler)

Add will add a new route to the Router.Routes map

func (*Router) FindRoute

func (router *Router) FindRoute(ctx *CTX) (bool, Route)

FindRoute searches for requested route

func (*Router) GetRoutes

func (router *Router) GetRoutes(method string) map[string]Route

GetRoutes returns the routes of a specific http verb