govalin

README

govalin

A simple way of creating efficient HTTP APIs in golang using conventions over configuration.

Installation

To install govalin run:

go get -u github.com/pkkummermo/govalin

Motivation

I love how fast and efficient go is. What I don't like, is how it doesn't create an easy way of creating HTTP APIs. Govalin focuses on pleasing those who want to create APIs without too much hassle, with a lean simple API.

Inspired by simple libraries and frameworks such as Javalin, I wanted to see if we could port the simplicity to golang.

Documentation

Index

• type AfterFunc
• type App
  • func New() *App
  • func (server *App) After(path string, afterFunc AfterFunc)
  • func (server *App) Before(path string, beforeFunc BeforeFunc)
  • func (server *App) Delete(path string, handler HandlerFunc) *App
  • func (server *App) Get(path string, handler HandlerFunc) *App
  • func (server *App) Head(path string, handler HandlerFunc) *App
  • func (server *App) Options(path string, handler HandlerFunc) *App
  • func (server *App) Patch(path string, handler HandlerFunc) *App
  • func (server *App) Post(path string, handler HandlerFunc) *App
  • func (server *App) Put(path string, handler HandlerFunc) *App
  • func (server *App) Route(path string, scopeFunc func()) *App
  • func (server *App) Shutdown() error
  • func (server *App) Start(port ...uint16) error
• type BeforeFunc
• type Call
  • func (call *Call) BodyAs(obj any) error
  • func (call *Call) Error(err error)
  • func (call *Call) FormParam(key string) string
  • func (call *Call) FormParamOrDefault(key string, def string) string
  • func (call *Call) HTML(text string)
  • func (call *Call) Header(key string, value ...string) string
  • func (call *Call) HeaderOrDefault(key string, def string) string
  • func (call *Call) JSON(obj interface{})
  • func (call *Call) PathParam(key string) string
  • func (call *Call) PathParams() map[string]string
  • func (call *Call) QueryParam(key string) string
  • func (call *Call) QueryParamOrDefault(key string, def string) string
  • func (call *Call) Status(statusCode int)
  • func (call *Call) Text(text string)
• type HandlerFunc

Types

type AfterFunc

type AfterFunc func(call *Call)

type App

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

func New

func New() *App

New creates a new Govalin App instance.

func (*App) After

func (server *App) After(path string, afterFunc AfterFunc)

Add an after handler to given path

Add an after handler that will run after any endpoint handler which matches the same request.

func (*App) Before

func (server *App) Before(path string, beforeFunc BeforeFunc)

Add a before handler to given path

Add a before handler that will run before any endpoint handler which matches the same request. If the before handler returns false, the request will be short circuited.

func (*App) Delete

func (server *App) Delete(path string, handler HandlerFunc) *App

Add a DELETE handler

Add a DELETE handler based on where you are in a hierarchy composed from other method handlers or route handlers.

func (*App) Get

func (server *App) Get(path string, handler HandlerFunc) *App

Add a GET handler

Add a GET handler based on where you are in a hierarchy composed from other method handlers or route handlers.

func (*App) Head

func (server *App) Head(path string, handler HandlerFunc) *App

Add a HEAD handler

Add a HEAD handler based on where you are in a hierarchy composed from other method handlers or route handlers.

func (*App) Options

func (server *App) Options(path string, handler HandlerFunc) *App

Add a OPTIONS handler

Add a OPTIONS handler based on where you are in a hierarchy composed from other method handlers or route handlers.

func (*App) Patch

func (server *App) Patch(path string, handler HandlerFunc) *App

Add a PATCH handler

Add a PATCH handler based on where you are in a hierarchy composed from other method handlers or route handlers.

func (*App) Post

func (server *App) Post(path string, handler HandlerFunc) *App

Add a POST handler

Add a POST handler based on where you are in a hierarchy composed from other method handlers or route handlers.

func (*App) Put

func (server *App) Put(path string, handler HandlerFunc) *App

Add a PUT handler

Add a PUT handler based on where you are in a hierarchy composed from other method handlers or route handlers.

func (*App) Route

func (server *App) Route(path string, scopeFunc func()) *App

Add a route to the given path

Add a route which provides a scoped route function for which you can add methods or even more routes into. This allows for hierarchical building of routes and methods.

func (*App) Shutdown

func (server *App) Shutdown() error

Shutdown the govalin server

Start a graceful shutdown of the govalin instance.

func (*App) Start

func (server *App) Start(port ...uint16) error

Start the server

Start the server based on given configuration.

type BeforeFunc

type BeforeFunc func(call *Call) bool

type Call

type Call struct {
	Raw raw
	// contains filtered or unexported fields
}

func (*Call) BodyAs

func (call *Call) BodyAs(obj any) error

Get body as given struct

BodyAs takes a pointer as input and tries to deserialize the body into the object expecting the body to be JSON. Returns an error on failed unmarshalling or non-pointer.

func (*Call) Error

func (call *Call) Error(err error)

Handle an error

Write a response based on given error. If the error is recognized as a govalin error the error is handled specific according to the error.

func (*Call) FormParam

func (call *Call) FormParam(key string) string

Get the value of given form param key

Parses the body as a www-form-urlencoded body. If the content type is not correct a warning is given and an empty string is returned.

func (*Call) FormParamOrDefault

func (call *Call) FormParamOrDefault(key string, def string) string

Get form param value by key, if empty, use default

Get a form param value based on given key from the request, or use the given default value if the value is an empty string.

func (*Call) HTML

func (call *Call) HTML(text string)

Send text as HTML to response

HTML will set the content-type of the response as text/html and write it to the response. If no other status has been given the response, it will write a 200 OK to the response.

func (*Call) Header

func (call *Call) Header(key string, value ...string) string

Get or set header by given key and value

Get a header value based on given header key from the request or set header value on the response by providing a value.

func (*Call) HeaderOrDefault

func (call *Call) HeaderOrDefault(key string, def string) string

Get header value by key, if empty, use default

Get a header value based on given header key from the request, or use the given default value if the value is an empty string.

func (*Call) JSON

func (call *Call) JSON(obj interface{})

Send obj as JSON to response

JSON will set the content-type of the response as application/json and serializes the given object as JSON, and writes it to the response. If no other status has been given the response, it will write a 200 OK to the response.

func (*Call) PathParam

func (call *Call) PathParam(key string) string

Get path param based on key.

func (*Call) PathParams

func (call *Call) PathParams() map[string]string

Get all path params as a map

Returns a map populated with the values based on the configuration of the path URL as a map[string]string.

func (*Call) QueryParam

func (call *Call) QueryParam(key string) string

Get query param for given key

Returns the query param value as string.

func (*Call) QueryParamOrDefault

func (call *Call) QueryParamOrDefault(key string, def string) string

Get query param by key, if empty, use default

Returns the query param value as string or use the given default value if the value is an empty string.

func (*Call) Status

func (call *Call) Status(statusCode int)

Set HTTP status that will be used on JSON/Text/HTML calls

If the status has already been set, a warning will be printed. The status will not be written to the response until a JSON/Text/HTML-call is made.

func (*Call) Text

func (call *Call) Text(text string)

Send text as pure text to response

Text will set the content-type of the response as text/plain and write it to the response. If no other status has been given the response, it will write a 200 OK to the response.

type HandlerFunc

type HandlerFunc func(call *Call)