requiem

README

requiem

Controller-based REST API server container for Golang with Postgres support

• Uses GORM v1.21.13 for DB interaction with Postgres
• Uses Gorilla Mux v1.8.0 for routing
• Uses logmatic v0.4.0 for nice server logs
• Default port is 8080
• Default base path is /api

Documentation here: https://godoc.org/github.com/mborders/requiem

Example Usage

Without DB

s := requiem.NewServer(... controllers)
s.Start()

With DB

s := requiem.NewServer(... controllers)
s.EnableDB = true
s.Start()

Change port or base path

s := requiem.NewServer(... controllers)
s.Port = 9090
s.BasePath = "/rest"
s.Start()

HttpController example

type MyController struct {
    DB *gorm.DB
}

type Response struct {
    Message string
}

type CreateRequest struct {
    SomeValue string
}

func (c MyController) getStuff(ctx requiem.HTTPContext) {
    m := Response{Message: "Hello, world!"}
    ctx.SendJSON(res)
}

func (c MyController) createStuff(ctx requiem.HTTPContext) {
    m := ctx.Body.(*CreateRequest)
    fmt.Println("Value: %s", m.SomeValue)
    ctx.SendStatus(Http.StatusNoContent)
}

func AuthInterceptor(ctx HTTPContext) bool {
    // Example:
    //   1) Check if user is authenticated
    //   2) Return false if not
    //   3) Use ctx.SetAttribute() to pass user claim
    
    return true
}

func (c MyController) Load(router *requiem.Router) {
    c.DB = router.DB
    r := router.NewRestRouter("/stuff")
    r.Get("/", c.getStuff)
    r.Post("/", c.createStuff)
    
    // Use AuthInterceptor
    r.Get("/interceptor", func(ctx HTTPContext) {
        ctx.SendStatus(http.StatusOK)
    }, AuthInterceptor)
}

DB Connection Environment Variables (if DB is enabled)

DB_HOST
DB_PORT
DB_NAME
DB_USERNAME
DB_PASSWORD

Documentation

Index

• Variables
• func InitLogger(exitOnFatal bool)
• func ReadJSON(r io.Reader, v interface{}) interface{}
• func SendJSON(w http.ResponseWriter, v interface{})
• func SendJSONWithStatus(w http.ResponseWriter, v interface{}, s int)
• func SendStatus(w http.ResponseWriter, s int)
• type HTTPContext
  • func (ctx *HTTPContext) GetAttribute(key string) interface{}
  • func (ctx *HTTPContext) GetParam(p string) string
  • func (ctx *HTTPContext) SendJSON(v interface{})
  • func (ctx *HTTPContext) SendJSONWithStatus(v interface{}, s int)
  • func (ctx *HTTPContext) SendStatus(s int)
  • func (ctx *HTTPContext) SetAttribute(key string, attr interface{})
• type HTTPInterceptor
• type HealthcheckController
  • func (c HealthcheckController) Load(router *Router)
• type IHttpController
• type RestRouter
  • func (r *RestRouter) Delete(path string, handle func(HTTPContext), v interface{}, ...)
  • func (r *RestRouter) Get(path string, handle func(HTTPContext), interceptors ...HTTPInterceptor)
  • func (r *RestRouter) Post(path string, handle func(HTTPContext), v interface{}, ...)
  • func (r *RestRouter) Put(path string, handle func(HTTPContext), v interface{}, ...)
• type Router
  • func (r *Router) NewRestRouter(path string) *RestRouter
• type Server
  • func NewServer(controllers ...IHttpController) *Server
  • func (s *Server) AutoMigrate(models ...interface{})
  • func (s *Server) Start()
  • func (s *Server) UseHealthcheck()
  • func (s *Server) UseInMemoryDB(debugMode bool)
  • func (s *Server) UsePostgresDB(debugMode bool)

Variables

var Logger *logmatic.Logger

Logger provides application-wide logging

Functions

func InitLogger

func InitLogger(exitOnFatal bool)

InitLogger initializes the application-wide logger

func ReadJSON

func ReadJSON(r io.Reader, v interface{}) interface{}

ReadJSON decodes the provided stream into the given interface.

func SendJSON

func SendJSON(w http.ResponseWriter, v interface{})

SendJSON converts the given interface into JSON and writes to the provided stream.

func SendJSONWithStatus

func SendJSONWithStatus(w http.ResponseWriter, v interface{}, s int)

SendJSONWithStatus writes a JSON response body to the provided stream, along with the specified status code.

func SendStatus

func SendStatus(w http.ResponseWriter, s int)

SendStatus writes the given HTTP status code into the provided response stream.

Types

type HTTPContext

type HTTPContext struct {
	Response http.ResponseWriter
	Request  *http.Request
	Body     interface{}
	// contains filtered or unexported fields
}

HTTPContext provides utility functions for HTTP requests/responses

func (*HTTPContext) GetAttribute

func (ctx *HTTPContext) GetAttribute(key string) interface{}

GetAttribute returns the context-scoped value for the given key

func (*HTTPContext) GetParam

func (ctx *HTTPContext) GetParam(p string) string

GetParam obtains the given parameter key from the request parameters.

func (*HTTPContext) SendJSON

func (ctx *HTTPContext) SendJSON(v interface{})

SendJSON converts the given interface into JSON and writes to the response.

func (*HTTPContext) SendJSONWithStatus

func (ctx *HTTPContext) SendJSONWithStatus(v interface{}, s int)

SendJSONWithStatus writes a JSON response body to the response, along with the specified status code.

func (*HTTPContext) SendStatus

func (ctx *HTTPContext) SendStatus(s int)

SendStatus writes the given HTTP status code into the response.

func (*HTTPContext) SetAttribute

func (ctx *HTTPContext) SetAttribute(key string, attr interface{})

SetAttribute sets the context-scoped value for the given key

type HTTPInterceptor

type HTTPInterceptor func(ctx HTTPContext) bool

HTTPInterceptor allows for pre-processing request handlers ex. an authentication interceptor could verify a user session

type HealthcheckController

type HealthcheckController struct {
}

func (HealthcheckController) Load

func (c HealthcheckController) Load(router *Router)

type IHttpController

type IHttpController interface {
	Load(router *Router)
}

IHttpController represents a REST API that can be loaded into a router

type RestRouter

type RestRouter struct {
	DB *gorm.DB
	// contains filtered or unexported fields
}

RestRouter represents a router for a specific REST API

func (*RestRouter) Delete

func (r *RestRouter) Delete(path string, handle func(HTTPContext), v interface{}, interceptors ...HTTPInterceptor)

Delete handles DELETE HTTP requests for the given path

func (*RestRouter) Get

func (r *RestRouter) Get(path string, handle func(HTTPContext), interceptors ...HTTPInterceptor)

Get handles GET HTTP requests for the given path

func (*RestRouter) Post

func (r *RestRouter) Post(path string, handle func(HTTPContext), v interface{}, interceptors ...HTTPInterceptor)

Post handles POST HTTP requests for the given path

func (*RestRouter) Put

func (r *RestRouter) Put(path string, handle func(HTTPContext), v interface{}, interceptors ...HTTPInterceptor)

Put handles PUT HTTP requests for the given path

type Router

type Router struct {
	MuxRouter *mux.Router
	DB        *gorm.DB
}

Router maintains routing paths for a single REST API

func (*Router) NewRestRouter

func (r *Router) NewRestRouter(path string) *RestRouter

NewRestRouter initializes a new REST router on at the given path

type Server

type Server struct {
	Port        int
	BasePath    string
	ExitOnFatal bool
	// contains filtered or unexported fields
}

Server represents a REST API server container Default port is 8080 Default path is /api

func NewServer

func NewServer(controllers ...IHttpController) *Server

NewServer creates a route-based REST API server instance

func (*Server) AutoMigrate

func (s *Server) AutoMigrate(models ...interface{})

func (*Server) Start

func (s *Server) Start()

Start initializes the API and starts running on the specified port Blocks on current thread

func (*Server) UseHealthcheck

func (s *Server) UseHealthcheck()

func (*Server) UseInMemoryDB

func (s *Server) UseInMemoryDB(debugMode bool)

func (*Server) UsePostgresDB

func (s *Server) UsePostgresDB(debugMode bool)