nova

README

nova is a mux for http while we don't claim to be the best or fastest we provide a lot of tools and features that enable you to be highly productive and help build up your api quickly and efficiently.

*Note nova's exported API interface will continue to change in unpredictable, backwards-incompatible ways until we tag a v1.0.0 release.

Start using it

1. Download and install

$ go get github.com/MordFustang21/nova

1. Import it into your code

import "github.com/MordFustang21/nova"

Basic Usage

http://localhost:8080/hello

package main

import (
	"log"
	"net/http"
	
	"github.com/MordFustang21/nova"
	)

func main() {
	s := nova.New()
	
	s.Get("/hello", func(request *nova.Request) error {
	    return request.Send("world")
	})
	
	if err := http.ListenAndServe(":8080", s); err != nil {
    		log.Fatal(err)
	}
}

Route Group

This will create a route with a base path than you can append other paths onto.

This example creates two routes "/v1/hello" and "/v2/world" so you can keep backwards compatible changes

package main

import (
	"log"
	"net/http"
	
	"github.com/MordFustang21/nova"
	)

func worldRequest(request *nova.Request) error {
	return request.Send("world")
}

func main() {
	s := nova.New()
	
	v1Group := s.Group("/v1")
	v2Group := s.Group("/v2")
	
	v1Group.Get("/hello", worldRequest)
	v2Group.Get("/world", worldRequest)
	
	if err := http.ListenAndServe(":8080", s); err != nil {
		log.Fatal(err)
	}
}

Retrieving parameters

http://localhost:8080/hello/world

package main

import (
	"log"
	"net/http"
	
	"github.com/MordFustang21/nova"
	)

func main() {
	s := nova.New()
	
	s.Get("/hello/:text", func(request *nova.Request) error {
		t := request.RouteParam("text")
	    return request.Send(t)
	})
	
	if err := http.ListenAndServe(":8080", s); err != nil {
    		log.Fatal(err)
	}
}

Returning Errors

http://localhost:8080/hello

package main

import (
	"log"
	"net/http"
	
	"github.com/MordFustang21/nova"
	)

func main() {
	s := nova.New()
	
	s.Post("/hello", func(request *nova.Request) error {
		r := struct {
		 World string
		}{}
		
		// ReadJSON will attempt to unmarshall the json from the request body into the given struct
		err := request.ReadJSON(&r)
		if err != nil {
		    return request.Error(http.StatusBadRequest, "couldn't parse request", err.Error())
		}
		
		// JSON will marshall the given object and marshall into into the response body
		return request.JSON(http.StatusOK, r)
	})
	
	if err := http.ListenAndServe(":8080", s); err != nil {
    		log.Fatal(err)
	}
	
}

Documentation

Overview

Package nova is an HTTP request multiplexer. It matches the URL of each incoming request against a list of registered patterns and calls the handler for the pattern that most closely matches the URL. As well as providing some nice logging and response features.

Index

• type ErrorFunc
• type JSONError
• type JSONErrors
• type Middleware
• type Node
• type Request
  • func NewRequest(w http.ResponseWriter, r *http.Request) *Request
  • func (r *Request) Error(statusCode int, msg string, userErr error) error
  • func (r *Request) GetMethod() string
  • func (r *Request) Header() http.Header
  • func (r *Request) JSON(code int, obj interface{}) error
  • func (r *Request) QueryParam(key string) string
  • func (r *Request) ReadJSON(i interface{}) error
  • func (r *Request) RouteParam(key string) string
  • func (r *Request) Send(data interface{}) error
  • func (r *Request) StatusCode(c int)
  • func (r *Request) Write(code int, data interface{}) error
  • func (r *Request) WriteHeader(c int)
• type RequestFunc
• type Route
• type RouteGroup
  • func (r *RouteGroup) All(route string, routeFunc RequestFunc)
  • func (r *RouteGroup) Delete(route string, routeFunc RequestFunc)
  • func (r *RouteGroup) Get(route string, routeFunc RequestFunc)
  • func (r *RouteGroup) Post(route string, routeFunc RequestFunc)
  • func (r *RouteGroup) Put(route string, routeFunc RequestFunc)
  • func (r *RouteGroup) Restricted(method, route string, routeFunc RequestFunc)
• type Server
  • func New() *Server
  • func (sn *Server) All(route string, routeFunc RequestFunc)
  • func (sn *Server) Delete(route string, routeFunc RequestFunc)
  • func (sn *Server) EnableDebug(debug bool)
  • func (sn *Server) ErrorFunc(f ErrorFunc)
  • func (sn *Server) Get(route string, routeFunc RequestFunc)
  • func (sn *Server) Group(path string) *RouteGroup
  • func (sn *Server) Post(route string, routeFunc RequestFunc)
  • func (sn *Server) Put(route string, routeFunc RequestFunc)
  • func (sn *Server) Restricted(method, route string, routeFunc RequestFunc)
  • func (sn *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (sn *Server) Use(f func(req *Request, next func()))

Types

type ErrorFunc

type ErrorFunc func(req *Request, err error)

ErrorFunc is the callback used for errors

type JSONError

type JSONError struct {
	Code    int      `json:"code"`
	Errors  []string `json:"errors"`
	Message string   `json:"message"`
}

JSONError resembles the RESTful standard for an error response

type JSONErrors

type JSONErrors struct {
	Error JSONError `json:"error"`
}

JSONErrors holds the JSONError response

type Middleware

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

Middleware holds all middleware functions

type Node

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

Node holds a single route with accompanying children routes

type Request

type Request struct {
	*http.Request
	ResponseWriter http.ResponseWriter

	BaseUrl      string
	ResponseCode int
	// contains filtered or unexported fields
}

Request resembles an incoming request

func NewRequest

func NewRequest(w http.ResponseWriter, r *http.Request) *Request

NewRequest creates a new Request pointer for an incoming request

func (*Request) Error

func (r *Request) Error(statusCode int, msg string, userErr error) error

Error provides and easy way to send a structured error response

func (*Request) GetMethod

func (r *Request) GetMethod() string

GetMethod provides a simple way to return the request method type as a string

func (*Request) Header

func (r *Request) Header() http.Header

Header returns the header map that will be sent by WriteHeader. The Header map also is the mechanism with which Handlers can set HTTP trailers.

Changing the header map after a call to WriteHeader (or Write) has no effect unless the modified headers are trailers.

There are two ways to set Trailers. The preferred way is to predeclare in the headers which trailers you will later send by setting the "Trailer" header to the names of the trailer keys which will come later. In this case, those keys of the Header map are treated as if they were trailers. See the example. The second way, for trailer keys not known to the Handler until after the first Write, is to prefix the Header map keys with the TrailerPrefix constant value. See TrailerPrefix.

To suppress automatic response headers (such as "Date"), set their value to nil.

func (*Request) JSON

func (r *Request) JSON(code int, obj interface{}) error

JSON marshals the given interface object and writes the JSON response.

func (*Request) QueryParam

func (r *Request) QueryParam(key string) string

QueryParam checks for and returns param or "" if doesn't exist

func (*Request) ReadJSON

func (r *Request) ReadJSON(i interface{}) error

ReadJSON unmarshals request body into the struct provided

func (*Request) RouteParam

func (r *Request) RouteParam(key string) string

RouteParam checks for and returns param or "" if doesn't exist

func (*Request) Send

func (r *Request) Send(data interface{}) error

Send writes the data to the response body

func (*Request) StatusCode

func (r *Request) StatusCode(c int)

StatusCode sets the status code header

func (*Request) Write

func (r *Request) Write(code int, data interface{}) error

Write will write data to the response and set a given status code

func (*Request) WriteHeader

func (r *Request) WriteHeader(c int)

WriteHeader sends an HTTP response header with the provided status code.

If WriteHeader is not called explicitly, the first call to Write will trigger an implicit WriteHeader(http.StatusOK). Thus explicit calls to WriteHeader are mainly used to send error codes.

The provided code must be a valid HTTP 1xx-5xx status code. Only one header may be written. Go does not currently support sending user-defined 1xx informational headers, with the exception of 100-continue response header that the Server sends automatically when the Request.Body is read.

type RequestFunc

type RequestFunc func(req *Request) error

RequestFunc is the callback used in all handler func

type Route

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

Route is the construct of a single route pattern

type RouteGroup

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

RouteGroup is used to add routes prepending a base path

func (*RouteGroup) All

func (r *RouteGroup) All(route string, routeFunc RequestFunc)

All adds route for all http methods

func (*RouteGroup) Delete

func (r *RouteGroup) Delete(route string, routeFunc RequestFunc)

Delete adds only DELETE method to route

func (*RouteGroup) Get

func (r *RouteGroup) Get(route string, routeFunc RequestFunc)

Get adds only GET method to route

func (*RouteGroup) Post

func (r *RouteGroup) Post(route string, routeFunc RequestFunc)

Post adds only POST method to route

func (*RouteGroup) Put

func (r *RouteGroup) Put(route string, routeFunc RequestFunc)

Put adds only PUT method to route

func (*RouteGroup) Restricted

func (r *RouteGroup) Restricted(method, route string, routeFunc RequestFunc)

Restricted adds route that is restricted by method

type Server

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

Server represents the router and all associated data

func New

func New() *Server

New returns new supernova router

func (*Server) All

func (sn *Server) All(route string, routeFunc RequestFunc)

All adds route for all http methods

func (*Server) Delete

func (sn *Server) Delete(route string, routeFunc RequestFunc)

Delete adds only DELETE method to route

func (*Server) EnableDebug

func (sn *Server) EnableDebug(debug bool)

EnableDebug toggles output for incoming requests

func (*Server) ErrorFunc

func (sn *Server) ErrorFunc(f ErrorFunc)

ErrorFunc sets the callback for errors

func (*Server) Get

func (sn *Server) Get(route string, routeFunc RequestFunc)

Get adds only GET method to route

func (*Server) Group

func (sn *Server) Group(path string) *RouteGroup

Group creates a new sub router that appends the path prefix

func (*Server) Post

func (sn *Server) Post(route string, routeFunc RequestFunc)

Post adds only POST method to route

func (*Server) Put

func (sn *Server) Put(route string, routeFunc RequestFunc)

Put adds only PUT method to route

func (*Server) Restricted

func (sn *Server) Restricted(method, route string, routeFunc RequestFunc)

Restricted adds route that is restricted by method

func (*Server) ServeHTTP

func (sn *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

handler is the main entry point into the router

func (*Server) Use

func (sn *Server) Use(f func(req *Request, next func()))

Use adds a new function to the middleware stack