lars

package module
v4.0.1+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 31, 2017 License: MIT Imports: 20 Imported by: 0

README

LARS

Project status Build Status Coverage Status Go Report Card GoDoc License Gitter

LARS is a fast radix-tree based, zero allocation, HTTP router for Go. view examples. If looking for a more pure Go solution, be sure to check out pure which is essentially a pure version of lars

Why Another HTTP Router?

Have you ever been painted into a corner by a framework, ya me too! and I've noticed that allot of routers out there, IMHO, are adding so much functionality that they are turning into Web Frameworks, (which is fine, frameworks are important) however, not at the expense of flexibility and configurability. So with no further ado, introducing LARS an HTTP router that can be your launching pad in creating a framework for your needs. How? Context is an interface see example here, where you can add as little or much as you want or need and most importantly...under your control.

Key & Unique Features

  • Context is an interface - this allows passing of framework/globals/application specific variables. example
  • Smart Route Logic - helpful logic to help prevent adding bad routes, keeping your url's consistent. i.e. /user/:id and /user/:user_id - the second one will fail to add letting you know that :user_id should be :id
  • Uber simple middleware + handlers - middleware and handlers actually have the exact same definition!
  • Custom Handlers - can register custom handlers for making other middleware + handler patterns usable with this router; the best part about this is can register one for your custom context and not have to do type casting everywhere see here
  • Diverse handler support - Full support for standard/native http Handler + HandlerFunc + some others see here
    • When Parsing a form call Context's ParseForm amd ParseMulipartForm functions and the URL params will be added into the Form object, just like query parameters are, so no extra work
  • Fast & Efficient - lars uses a custom version of httprouter so incredibly fast and efficient.

Installation

go get -u github.com/go-playground/lars

Usage

Below is a simple example, for a full example see here

package main

import (
	"fmt"
	"net/http"

	"github.com/go-playground/lars"
	mw "github.com/go-playground/lars/_examples/middleware/logging-recovery"
)

func main() {
	l := lars.New()
	// LoggingAndRecovery is just an example copy paste and modify to your needs
	l.Use(mw.LoggingAndRecovery)

	l.Get("/", HelloWorld)

	http.ListenAndServe(":3007", l.Serve())
}

// HelloWorld ...
func HelloWorld(c lars.Context) {
	c.Response().Write([]byte("Hello World"))

	// this will also work, Response() complies with http.ResponseWriter interface
	fmt.Fprint(c.Response(), "Hello World")
}

URL Params

l := l.New()

// the matching param will be stored in the Context's params with name "id"
l.Get("/user/:id", UserHandler)

// serve css, js etc.. c.Param(lars.WildcardParam) will return the remaining path if 
// you need to use it in a custom handler...
l.Get("/static/*", http.StripPrefix("/static/", http.FileServer(http.Dir("static")))) 

...

Note: Since this router has only explicit matches, you can not register static routes and parameters for the same path segment. For example you can not register the patterns /user/new and /user/:user for the same request method at the same time. The routing of different request methods is independent from each other. I was initially against this, and this router allowed it in a previous version, however it nearly cost me in a big app where the dynamic param value say :type actually could have matched another static route and that's just too dangerous, so it is no longer allowed.

Groups


l.Use(LoggingAndRecovery)
...
l.Post("/users/add", ...)

// creates a group for user + inherits all middleware registered using l.Use()
user := l.Group("/user/:userid")
user.Get("", ...)
user.Post("", ...)
user.Delete("/delete", ...)

contactInfo := user.Group("/contact-info/:ciid")
contactinfo.Delete("/delete", ...)

// creates a group for others + inherits all middleware registered using l.Use() + adds 
// OtherHandler to middleware
others := l.GroupWithMore("/others", OtherHandler)

// creates a group for admin WITH NO MIDDLEWARE... more can be added using admin.Use()
admin := l.GroupWithNone("/admin")
admin.Use(SomeAdminSecurityMiddleware)
...

Custom Context + Avoid Type Casting / Custom Handlers

...
// MyContext is a custom context
type MyContext struct {
	*lars.Ctx  // a little dash of Duck Typing....
}

// CustomContextFunction is a function that is specific to your applications needs that you added
func (mc *MyContext) CustomContextFunction() {
	// do something
}

// newContext is the function that creates your custom context +
// contains lars's default context
func newContext(l *lars.LARS) lars.Context {
	return &MyContext{
		Ctx:        lars.NewContext(l),
	}
}

// casts custom context and calls you custom handler so you don;t have to type cast lars.Context everywhere
func castCustomContext(c lars.Context, handler lars.Handler) {
	// could do it in all one statement, but in long form for readability
	h := handler.(func(*MyContext))
	ctx := c.(*MyContext)

	h(ctx)
}

func main() {
	l := lars.New()
	l.RegisterContext(newContext) // all gets cached in pools for you
	l.RegisterCustomHandler(func(*MyContext) {}, castCustomContext)
	l.Use(Logger)

	l.Get("/", Home)

	http.ListenAndServe(":3007", l.Serve())
}

// Home ...notice the receiver is *MyContext, castCustomContext handled the type casting for us
// quite the time saver if you ask me.
func Home(c *MyContext) {
	c.CustomContextFunction()
	...
}

Decoding Body

For full example see here. currently JSON, XML, FORM + Multipart Form's are support out of the box.

	// first argument denotes yes or no I would like URL query parameter fields
	// to be included. i.e. 'id' in route '/user/:id' should it be included.
	// run, then change to false and you'll see user.ID is not populated.
	if err := c.Decode(true, maxBytes, &user); err != nil {
		log.Println(err)
	}

Misc

...
// can register multiple handlers, the last is considered the last in the chain and others 
// considered middleware, but just for this route and not added to middleware like l.Use() does.
l.Get(/"home", AdditionalHandler, HomeHandler)

// set custom 404 ( not Found ) handler
l.Register404(404Handler)

// Redirect to or from ending slash if route not found, default is true
l.SetRedirectTrailingSlash(true)

// Handle 405 ( Method Not allowed ), default is false
l.SetHandle405MethodNotAllowed(false)

// automatically handle OPTION requests; manually configured
// OPTION handlers take precedence. default true
l.SetAutomaticallyHandleOPTIONS(set bool)

// register custom context
l.RegisterContext(ContextFunc)

// Register custom handler type, see https://github.com/go-playground/lars/blob/master/util.go#L62
// for example handler creation
l.RegisterCustomHandler(interface{}, CustomHandlerFunc)

// NativeChainHandler is used as a helper to create your own custom handlers, or use custom handlers 
// that already exist an example usage can be found here 
// https://github.com/go-playground/lars/blob/master/util.go#L86, below is an example using nosurf CSRF middleware

l.Use(nosurf.NewPure(lars.NativeChainHandler))


// Context has 2 methods of which you should be aware of ParseForm and ParseMulipartForm, they just call the 
// default http functions but provide one more additional feature, they copy the URL params to the request 
// Forms variables, just like Query parameters would have been.
// The functions are for convenience and are totally optional.

Special Note

I don't know if it was an oversight or just an assumption about how middleware would be used with Go 1.7's new context integration into the *http.Request but there are a few quirks. As you know lars handles multiple handler types, including the native handler, this functionality is possible because of the way lar handles the middleware; lars does not chain the middleware in the normal way, but rather calles each in sequence; because of this all you have to do is call c.Next() or it has already been wrapped to do so for you transparently. OK getting back to the point, if you are not using lars.Context to set the context information you will have to set the request object so that the information gets back to the calling package. eg.

// because 'r' is a copy of a pointer to allow the information to get
// back to the caller, need to set the value of 'r' as below with '*r'
func(w http.ResponseWriter, r *http.Request) {
	*r = *r.WithContext(context.WithValue(r.Context(), 0, "testval1"))
}

this is not an issue specific to lars, but a quirk of the way context is tied to the http.Request object.

Middleware

There are some pre-defined middlewares within the middleware folder; NOTE: that the middleware inside will comply with the following rule(s):

  • Are completely reusable by the community without modification

Other middleware will be listed under the _examples/middleware/... folder for a quick copy/paste modify. as an example a logging or recovery middleware are very application dependent and therefore will be listed under the _examples/middleware/...

Benchmarks

Run on MacBook Pro (15-inch, 2017) 3.1 GHz Intel Core i7 16GB DDR3 using Go version go1.9.2 darwin/amd64

NOTICE: lars uses a custom version of httprouter, benchmarks can be found here

go test -bench=. -benchmem=true
#GithubAPI Routes: 203
   LARS: 49032 Bytes

#GPlusAPI Routes: 13
   LARS: 3640 Bytes

#ParseAPI Routes: 26
   LARS: 6632 Bytes

#Static Routes: 157
   LARS: 30120 Bytes

goos: darwin
goarch: amd64
pkg: github.com/joeybloggs/go-http-routing-benchmark
BenchmarkLARS_Param        	20000000	        51.6 ns/op	       0 B/op	       0 allocs/op
BenchmarkLARS_Param5       	20000000	        85.7 ns/op	       0 B/op	       0 allocs/op
BenchmarkLARS_Param20      	10000000	       215 ns/op	       0 B/op	       0 allocs/op
BenchmarkLARS_ParamWrite   	20000000	        94.3 ns/op	       0 B/op	       0 allocs/op
BenchmarkLARS_GithubStatic 	20000000	        68.7 ns/op	       0 B/op	       0 allocs/op
BenchmarkLARS_GithubParam  	20000000	       103 ns/op	       0 B/op	       0 allocs/op
BenchmarkLARS_GithubAll    	  100000	     21066 ns/op	       0 B/op	       0 allocs/op
BenchmarkLARS_GPlusStatic  	30000000	        53.1 ns/op	       0 B/op	       0 allocs/op
BenchmarkLARS_GPlusParam   	20000000	        70.3 ns/op	       0 B/op	       0 allocs/op
BenchmarkLARS_GPlus2Params 	20000000	        84.4 ns/op	       0 B/op	       0 allocs/op
BenchmarkLARS_GPlusAll     	 2000000	       894 ns/op	       0 B/op	       0 allocs/op
BenchmarkLARS_ParseStatic  	20000000	        53.5 ns/op	       0 B/op	       0 allocs/op
BenchmarkLARS_ParseParam   	20000000	        60.4 ns/op	       0 B/op	       0 allocs/op
BenchmarkLARS_Parse2Params 	20000000	        68.7 ns/op	       0 B/op	       0 allocs/op
BenchmarkLARS_ParseAll     	 1000000	      1602 ns/op	       0 B/op	       0 allocs/op
BenchmarkLARS_StaticAll    	  100000	     13777 ns/op	       0 B/op	       0 allocs/op

Package Versioning

I'm jumping on the vendoring bandwagon, you should vendor this package as I will not be creating different version with gopkg.in like allot of my other libraries.

Why? because my time is spread pretty thin maintaining all of the libraries I have + LIFE, it is so freeing not to worry about it and will help me keep pouring out bigger and better things for you the community.

This package is inspired by the following

Licenses

  • MIT License (MIT), Copyright (c) 2015 Dean Karn
  • BSD License, Copyright (c) 2013 Julien Schmidt. All rights reserved.

Documentation

Overview

Package lars - Library Access/Retrieval System, is a fast radix-tree based, zero allocation, HTTP router for Go.

Usage

Below is a simple example, for a full example see here https://github.com/go-playground/lars/blob/master/_examples/all-in-one/main.go 

package main

import (
	"net/http"

	"github.com/go-playground/lars"
	mw "github.com/go-playground/lars/_examples/middleware/logging-recovery"
)

func main() {

	l := lars.New()
	l.Use(mw.LoggingAndRecovery) // LoggingAndRecovery is just an example copy
				     // paste and modify to your needs
	l.Get("/", HelloWorld)

	http.ListenAndServe(":3007", l.Serve())
}

// HelloWorld ...
func HelloWorld(c lars.Context) {
	c.Response().Write([]byte("Hello World"))

	// this will also work, Response() complies with http.ResponseWriter interface
	fmt.Fprint(c.Response(), "Hello World")
}

URL Params

example param usage 

l := l.New()
l.Get("/user/:id", UserHandler)

// serve css, js etc.. c.Param(lars.WildcardParam) will return the
// remaining path if you need to use it in a custom handler...
l.Get("/static/*", http.FileServer(http.Dir("static/")))

NOTE: Since this router has only explicit matches, you can not register static routes
and parameters for the same path segment. For example you can not register the patterns
/user/new and /user/:user for the same request method at the same time. The routing of
different request methods is independent from each other. I was initially against this,
and this router allowed it in a previous version, however it nearly cost me in a big
app where the dynamic param value say :type actually could have matched another static
route and that's just too dangerous, so it is no longer allowed.

Groups

example group definitions 

...
l.Use(LoggingAndRecovery)
...
l.Post("/users/add", ...)

// creates a group for user + inherits all middleware registered using l.Use()
user := l.Group("/user/:userid")
user.Get("", ...)
user.Post("", ...)
user.Delete("/delete", ...)

contactInfo := user.Group("/contact-info/:ciid")
contactinfo.Delete("/delete", ...)

// creates a group for others + inherits all middleware registered using l.Use() +
// adds OtherHandler to middleware
others := l.GroupWithMore("/others", OtherHandler)

// creates a group for admin WITH NO MIDDLEWARE... more can be added using admin.Use()
admin := l.GroupWithNone("/admin")
admin.Use(SomeAdminSecurityMiddleware)
...

Custom Context - Avoid Type Casting - Custom Handlers

example context + custom handlers 

...
// MyContext is a custom context
type MyContext struct {
	*lars.Ctx  // a little dash of Duck Typing....
}

// CustomContextFunction is a function that is specific to your applications
// needs that you added
func (mc *MyContext) CustomContextFunction() {
	// do something
}

// newContext is the function that creates your custom context +
// contains lars's default context
func newContext(l *lars.LARS) lars.Context {
	return &MyContext{
		Ctx:        lars.NewContext(l),
	}
}

// casts custom context and calls you custom handler so you don't have to
// type cast lars.Context everywhere
func castCustomContext(c lars.Context, handler lars.Handler) {

	// could do it in all one statement, but in long form for readability
	h := handler.(func(*MyContext))
	ctx := c.(*MyContext)

	h(ctx)
}

func main() {

	l := lars.New()
	l.RegisterContext(newContext) // all gets cached in pools for you
	l.RegisterCustomHandler(func(*MyContext) {}, castCustomContext)
	l.Use(Logger)

	l.Get("/", Home)

	http.ListenAndServe(":3007", l.Serve())
}

// Home ...notice the receiver is *MyContext, castCustomContext handled the
// type casting for us; quite the time saver if you ask me.
func Home(c *MyContext) {

	c.CustomContextFunction()
	...
}

Decoding Body

For full example see https://github.com/go-playground/lars/blob/master/_examples/decode/main.go currently JSON, XML, FORM + Multipart Form's are support out of the box. 

// first argument denotes yes or no I would like URL query parameter fields
// to be included. i.e. 'id' in route '/user/:id' should it be included.
// run, then change to false and you'll see user.ID is not populated.
if err := c.Decode(true, maxBytes, &user); err != nil {
	log.Println(err)
}

Misc

misc examples and noteworthy features 

...
// can register multiple handlers, the last is considered the last in the chain and
// others considered middleware, but just for this route and not added to middleware
// like l.Use() does.
l.Get(/"home", AdditionalHandler, HomeHandler)

// set custom 404 ( not Found ) handler
l.Register404(404Handler)

// Redirect to or from ending slash if route not found, default is true
l.SetRedirectTrailingSlash(true)

// Handle 405 ( Method Not allowed ), default is false
l.SetHandle405MethodNotAllowed(false)

// automatically handle OPTION requests; manually configured
// OPTION handlers take precedence. default true
l.SetAutomaticallyHandleOPTIONS(set bool)

// register custom context
l.RegisterContext(ContextFunc)

// Register custom handler type, see util.go
// https://github.com/go-playground/lars/blob/master/util.go#L62 for example handler
// creation
l.RegisterCustomHandler(interface{}, CustomHandlerFunc)

// NativeChainHandler is used as a helper to create your own custom handlers, or use
// custom handlers that already exist an example usage can be found here
// https://github.com/go-playground/lars/blob/master/util.go#L86, below is an example
// using nosurf CSRF middleware
l.Use(nosurf.NewPure(lars.NativeChainHandler))

// Context has 2 methods of which you should be aware of ParseForm and
// ParseMulipartForm, they just call the default http functions but provide one more
// additional feature, they copy the URL params to the request Forms variables, just
// like Query parameters would have been. The functions are for convenience and are
// totally optional.

Index

Constants

View Source 
const (
	// CONNECT HTTP method
	CONNECT = http.MethodConnect
	// DELETE HTTP method
	DELETE = http.MethodDelete
	// GET HTTP method
	GET = http.MethodGet
	// HEAD HTTP method
	HEAD = http.MethodHead
	// OPTIONS HTTP method
	OPTIONS = http.MethodOptions
	// PATCH HTTP method
	PATCH = http.MethodPatch
	// POST HTTP method
	POST = http.MethodPost
	// PUT HTTP method
	PUT = http.MethodPut
	// TRACE HTTP method
	TRACE = http.MethodTrace

	ApplicationJSON                  = "application/json"
	ApplicationJSONCharsetUTF8       = ApplicationJSON + "; " + CharsetUTF8
	ApplicationJavaScript            = "application/javascript"
	ApplicationJavaScriptCharsetUTF8 = ApplicationJavaScript + "; " + CharsetUTF8
	ApplicationXML                   = "application/xml"
	ApplicationXMLCharsetUTF8        = ApplicationXML + "; " + CharsetUTF8
	ApplicationForm                  = "application/x-www-form-urlencoded"
	ApplicationProtobuf              = "application/protobuf"
	ApplicationMsgpack               = "application/msgpack"
	TextHTML                         = "text/html"
	TextHTMLCharsetUTF8              = TextHTML + "; " + CharsetUTF8
	TextPlain                        = "text/plain"
	TextPlainCharsetUTF8             = TextPlain + "; " + CharsetUTF8
	MultipartForm                    = "multipart/form-data"
	OctetStream                      = "application/octet-stream"

	CharsetUTF8 = "charset=utf-8"

	AcceptedLanguage   = "Accept-Language"
	AcceptEncoding     = "Accept-Encoding"
	Authorization      = "Authorization"
	ContentDisposition = "Content-Disposition"
	ContentEncoding    = "Content-Encoding"
	ContentLength      = "Content-Length"
	ContentType        = "Content-Type"
	Location           = "Location"
	Upgrade            = "Upgrade"
	Vary               = "Vary"
	WWWAuthenticate    = "WWW-Authenticate"
	XForwardedFor      = "X-Forwarded-For"
	XRealIP            = "X-Real-Ip"
	Allow              = "Allow"
	Origin             = "Origin"

	Gzip = "gzip"

	WildcardParam = "*wildcard"
)

HTTP Constant Terms and Variables

Variables

View Source 
var NativeChainHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

	c := GetContext(w)
	b := c.BaseContext()

	b.request = r

	if b.index+1 < len(b.handlers) {
		c.Next()
	}
})

NativeChainHandler is used in native handler chain middleware example using nosurf crsf middleware nosurf.NewPure(lars.NativeChainHandler)

Functions

This section is empty.

Types

type Context 

type Context interface {
	context.Context
	Request() *http.Request
	Response() *Response
	WebSocket() *websocket.Conn
	Param(name string) string
	QueryParams() url.Values
	ParseForm() error
	ParseMultipartForm(maxMemory int64) error
	Set(key interface{}, value interface{})
	Get(key interface{}) (value interface{}, exists bool)
	Context() context.Context
	WithContext(context.Context)
	WithCancel() context.CancelFunc
	WithDeadline(time.Time) context.CancelFunc
	WithTimeout(time.Duration) context.CancelFunc
	WithValue(key interface{}, val interface{})
	Next()
	RequestStart(w http.ResponseWriter, r *http.Request)
	RequestEnd()
	ClientIP() (clientIP string)
	AcceptedLanguages(lowercase bool) []string
	HandlerName() string
	Stream(step func(w io.Writer) bool)
	JSON(int, interface{}) error
	JSONBytes(int, []byte) error
	JSONP(int, interface{}, string) error
	XML(int, interface{}) error
	XMLBytes(int, []byte) error
	Text(int, string) error
	TextBytes(int, []byte) error
	Attachment(r io.Reader, filename string) (err error)
	Inline(r io.Reader, filename string) (err error)
	Decode(includeFormQueryParams bool, maxMemory int64, v interface{}) (err error)
	BaseContext() *Ctx
}

Context is the context interface type

func GetContext 

func GetContext(w http.ResponseWriter) Context

GetContext is a helper method for retrieving the Context object from the ResponseWriter when using native go hanlders. NOTE: this will panic if fed an http.ResponseWriter not provided by lars's chaining.

type ContextFunc 

type ContextFunc func(l *LARS) Context

ContextFunc is the function to run when creating a new context

type Ctx 

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

Ctx encapsulates the http request, response context

func NewContext 

func NewContext(l *LARS) *Ctx

NewContext returns a new default lars Context object.

func (*Ctx) AcceptedLanguages 

func (c *Ctx) AcceptedLanguages(lowercase bool) []string

AcceptedLanguages returns an array of accepted languages denoted by the Accept-Language header sent by the browser NOTE: some stupid browsers send in locales lowercase when all the rest send it properly

func (*Ctx) Attachment 

func (c *Ctx) Attachment(r io.Reader, filename string) (err error)

Attachment is a helper method for returning an attachement file to be downloaded, if you with to open inline see function

func (*Ctx) BaseContext 

func (c *Ctx) BaseContext() *Ctx

BaseContext returns the underlying context object LARS uses internally. used when overriding the context object

func (*Ctx) ClientIP 

func (c *Ctx) ClientIP() (clientIP string)

ClientIP implements a best effort algorithm to return the real client IP, it parses X-Real-IP and X-Forwarded-For in order to work properly with reverse-proxies such us: nginx or haproxy.

func (*Ctx) Context 

func (c *Ctx) Context() context.Context

Context returns the request's context. To change the context, use WithContext.

The returned context is always non-nil.

func (*Ctx) Deadline 

func (c *Ctx) Deadline() (deadline time.Time, ok bool)

Deadline calls the underlying context.Deadline()

func (*Ctx) Decode 

func (c *Ctx) Decode(includeFormQueryParams bool, maxMemory int64, v interface{}) (err error)

Decode takes the request and attempts to discover it's content type via the http headers and then decode the request body into the provided struct. Example if header was "application/json" would decode using json.NewDecoder(io.LimitReader(c.request.Body, maxMemory)).Decode(v).

func (*Ctx) Done 

func (c *Ctx) Done() <-chan struct{}

Done calls the underlying context.Done()

func (*Ctx) Err 

func (c *Ctx) Err() error

Err calls the underlying context.Err()

func (*Ctx) Get 

func (c *Ctx) Get(key interface{}) (value interface{}, exists bool)

Get returns the value for the given key and is a shortcut for context.Value(...) ... but it also returns if the value was found or not.

func (*Ctx) HandlerName 

func (c *Ctx) HandlerName() string

HandlerName returns the current Contexts final handler's name

func (*Ctx) Inline 

func (c *Ctx) Inline(r io.Reader, filename string) (err error)

Inline is a helper method for returning a file inline to be rendered/opened by the browser

func (*Ctx) JSON 

func (c *Ctx) JSON(code int, i interface{}) (err error)

JSON marshals provided interface + returns JSON + status code

func (*Ctx) JSONBytes 

func (c *Ctx) JSONBytes(code int, b []byte) (err error)

JSONBytes returns provided JSON response with status code

func (*Ctx) JSONP 

func (c *Ctx) JSONP(code int, i interface{}, callback string) (err error)

JSONP sends a JSONP response with status code and uses `callback` to construct the JSONP payload.

func (*Ctx) Next 

func (c *Ctx) Next()

Next should be used only inside middleware. It executes the pending handlers in the chain inside the calling handler. See example in github.

func (*Ctx) Param 

func (c *Ctx) Param(name string) string

Param returns the value of the first Param which key matches the given name. If no matching Param is found, an empty string is returned.

func (*Ctx) ParseForm 

func (c *Ctx) ParseForm() error

ParseForm calls the underlying http.Request ParseForm but also adds the URL params to the request Form as if they were defined as query params i.e. ?id=13&ok=true but does not add the params to the http.Request.URL.RawQuery for SEO purposes

func (*Ctx) ParseMultipartForm 

func (c *Ctx) ParseMultipartForm(maxMemory int64) error

ParseMultipartForm calls the underlying http.Request ParseMultipartForm but also adds the URL params to the request Form as if they were defined as query params i.e. ?id=13&ok=true but does not add the params to the http.Request.URL.RawQuery for SEO purposes

func (*Ctx) QueryParams 

func (c *Ctx) QueryParams() url.Values

QueryParams returns the http.Request.URL.Query() values this function is not for convenience, but rather performance URL.Query() reparses the RawQuery every time it's called, but this function will cache the initial parsing so it doesn't have to reparse; which is useful if when accessing these Params from multiple middleware.

func (*Ctx) Request 

func (c *Ctx) Request() *http.Request

Request returns context assotiated *http.Request.

func (*Ctx) RequestEnd 

func (c *Ctx) RequestEnd()

RequestEnd fires after request completes and just before the *Ctx object gets put back into the pool. Used to close DB connections and such on a custom context

func (*Ctx) RequestStart 

func (c *Ctx) RequestStart(w http.ResponseWriter, r *http.Request)

RequestStart resets the Context to it's default request state

func (*Ctx) Response 

func (c *Ctx) Response() *Response

Response returns http.ResponseWriter.

func (*Ctx) Set 

func (c *Ctx) Set(key interface{}, value interface{})

Set is used to store a new key/value pair using the context contained on this Ctx. It is a shortcut for context.WithValue(..., ...)

func (*Ctx) Stream 

func (c *Ctx) Stream(step func(w io.Writer) bool)

Stream provides HTTP Streaming

func (*Ctx) Text 

func (c *Ctx) Text(code int, s string) error

Text returns the provided string with status code

func (*Ctx) TextBytes 

func (c *Ctx) TextBytes(code int, b []byte) (err error)

TextBytes returns the provided response with status code

func (*Ctx) Value 

func (c *Ctx) Value(key interface{}) interface{}

Value calls the underlying context.Value()

func (*Ctx) WebSocket 

func (c *Ctx) WebSocket() *websocket.Conn

WebSocket returns context's assotiated *websocket.Conn.

func (*Ctx) WithCancel 

func (c *Ctx) WithCancel() context.CancelFunc

WithCancel calls context.WithCancel and automatically updates context on the containing lars.Ctx object.

func (*Ctx) WithContext 

func (c *Ctx) WithContext(ctx context.Context)

WithContext updates the underlying request's context with to ctx The provided ctx must be non-nil.

func (*Ctx) WithDeadline 

func (c *Ctx) WithDeadline(deadline time.Time) context.CancelFunc

WithDeadline calls context.WithDeadline and automatically updates context on the containing lars.Ctx object.

func (*Ctx) WithTimeout 

func (c *Ctx) WithTimeout(timeout time.Duration) context.CancelFunc

WithTimeout calls context.WithTimeout and automatically updates context on the containing lars.Ctx object.

func (*Ctx) WithValue 

func (c *Ctx) WithValue(key interface{}, val interface{})

WithValue calls golang.org/x/net/context WithValue and automatically updates context on the containing lars.Ctx object. Can also use Set() function on Ctx object (Recommended)

func (*Ctx) XML 

func (c *Ctx) XML(code int, i interface{}) error

XML marshals provided interface + returns XML + status code

func (*Ctx) XMLBytes 

func (c *Ctx) XMLBytes(code int, b []byte) (err error)

XMLBytes returns provided XML response with status code

type CustomHandlerFunc 

type CustomHandlerFunc func(Context, Handler)

CustomHandlerFunc wraped by HandlerFunc and called where you can type cast both Context and Handler and call Handler

type Handler 

type Handler interface{}

Handler is the type used in registering handlers. NOTE: these handlers may get wrapped by the HandlerFunc type internally.

type HandlerFunc 

type HandlerFunc func(Context)

HandlerFunc is the internal handler type used for middleware and handlers

type HandlersChain 

type HandlersChain []HandlerFunc

HandlersChain is an array of HanderFunc handlers to run

type IRouteGroup 

type IRouteGroup interface {
	IRoutes
	GroupWithNone(prefix string) IRouteGroup
	GroupWithMore(prefix string, middleware ...Handler) IRouteGroup
	Group(prefix string) IRouteGroup
}

IRouteGroup interface for router group

type IRoutes 

type IRoutes interface {
	Use(...Handler)
	Any(string, ...Handler)
	Get(string, ...Handler)
	Post(string, ...Handler)
	Delete(string, ...Handler)
	Patch(string, ...Handler)
	Put(string, ...Handler)
	Options(string, ...Handler)
	Head(string, ...Handler)
	Connect(string, ...Handler)
	Trace(string, ...Handler)
	WebSocket(websocket.Upgrader, string, Handler)
}

IRoutes interface for routes

type LARS 

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

LARS is the main routing instance

func New 

func New() *LARS

New Creates and returns a new lars instance

func (*LARS) Any 

func (g *LARS) Any(path string, h ...Handler)

Any adds a route & handler to the router for all HTTP methods.

func (*LARS) BuiltInFormDecoder 

func (l *LARS) BuiltInFormDecoder() *form.Decoder

BuiltInFormDecoder returns the built in form decoder github.com/go-playground/form in order for custom type to be registered.

func (*LARS) Connect 

func (g *LARS) Connect(path string, h ...Handler)

Connect adds a CONNECT route & handler to the router.

func (*LARS) Delete 

func (g *LARS) Delete(path string, h ...Handler)

Delete adds a DELETE route & handler to the router.

func (*LARS) Get 

func (g *LARS) Get(path string, h ...Handler)

Get adds a GET route & handler to the router.

func (*LARS) Group 

func (g *LARS) Group(prefix string) IRouteGroup

Group creates a new sub router with specified prefix and retains existing middleware.

func (*LARS) GroupWithMore 

func (g *LARS) GroupWithMore(prefix string, middleware ...Handler) IRouteGroup

GroupWithMore creates a new sub router with specified prefix, retains existing middleware and adds new middleware.

func (*LARS) GroupWithNone 

func (g *LARS) GroupWithNone(prefix string) IRouteGroup

GroupWithNone creates a new sub router with specified prefix and no middleware attached.

func (*LARS) Handle 

func (g *LARS) Handle(method string, path string, h ...Handler)

Handle allows for any method to be registered with the given route & handler. Allows for non standard methods to be used like CalDavs PROPFIND and so forth.

func (*LARS) Head 

func (g *LARS) Head(path string, h ...Handler)

Head adds a HEAD route & handler to the router.

func (*LARS) Match 

func (g *LARS) Match(methods []string, path string, h ...Handler)

Match adds a route & handler to the router for multiple HTTP methods provided.

func (*LARS) Options 

func (g *LARS) Options(path string, h ...Handler)

Options adds an OPTIONS route & handler to the router.

func (*LARS) Patch 

func (g *LARS) Patch(path string, h ...Handler)

Patch adds a PATCH route & handler to the router.

func (*LARS) Post 

func (g *LARS) Post(path string, h ...Handler)

Post adds a POST route & handler to the router.

func (*LARS) Put 

func (g *LARS) Put(path string, h ...Handler)

Put adds a PUT route & handler to the router.

func (*LARS) Register404 

func (l *LARS) Register404(notFound ...Handler)

Register404 alows for overriding of the not found handler function. NOTE: this is run after not finding a route even after redirecting with the trailing slash

func (*LARS) RegisterContext 

func (l *LARS) RegisterContext(fn ContextFunc)

RegisterContext registers a custom Context function for creation and resetting of a global object passed per http request

func (*LARS) RegisterCustomHandler 

func (l *LARS) RegisterCustomHandler(customType interface{}, fn CustomHandlerFunc)

RegisterCustomHandler registers a custom handler that gets wrapped by HandlerFunc

func (*LARS) Serve 

func (l *LARS) Serve() http.Handler

Serve returns an http.Handler to be used.

func (*LARS) SetAutomaticallyHandleOPTIONS 

func (l *LARS) SetAutomaticallyHandleOPTIONS(set bool)

SetAutomaticallyHandleOPTIONS tells lars whether to automatically handle OPTION requests; manually configured OPTION handlers take precedence. default true

func (*LARS) SetHandle405MethodNotAllowed 

func (l *LARS) SetHandle405MethodNotAllowed(set bool)

SetHandle405MethodNotAllowed tells lars whether to handle the http 405 Method Not Allowed status code

func (*LARS) SetRedirectTrailingSlash 

func (l *LARS) SetRedirectTrailingSlash(set bool)

SetRedirectTrailingSlash tells lars whether to try and fix a URL by trying to find it lowercase -> with or without slash -> 404

func (*LARS) Trace 

func (g *LARS) Trace(path string, h ...Handler)

Trace adds a TRACE route & handler to the router.

func (*LARS) Use 

func (g *LARS) Use(m ...Handler)

Use adds a middleware handler to the group middleware chain.

func (*LARS) WebSocket 

func (g *LARS) WebSocket(upgrader websocket.Upgrader, path string, h Handler)

WebSocket adds a websocket route

type Param 

type Param struct {
	Key   string
	Value string
}

Param is a single URL parameter, consisting of a key and a value.

type Params 

type Params []Param

Params is a Param-slice, as returned by the router. The slice is ordered, the first URL parameter is also the first slice value. It is therefore safe to read values by the index.

type Response 

type Response struct {
	http.ResponseWriter
	// contains filtered or unexported fields
}

Response struct contains methods and to capture extra data about the http request and more efficiently reset underlying writer object... it does comply with the http.ResponseWriter interface

func (*Response) CloseNotify 

func (r *Response) CloseNotify() <-chan bool

CloseNotify wraps response writer's CloseNotify function.

func (*Response) Committed 

func (r *Response) Committed() bool

Committed returns whether the *Response header has already been written to and if has been committed to this return.

func (*Response) Flush 

func (r *Response) Flush()

Flush wraps response writer's Flush function.

func (*Response) Header 

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

Header returns the header map that will be sent by WriteHeader. Changing the header after a call to WriteHeader (or Write) has no effect unless the modified headers were declared as trailers by setting the "Trailer" header before the call to WriteHeader (see example). To suppress implicit *Response headers, set their value to nil.

func (*Response) Hijack 

func (r *Response) Hijack() (net.Conn, *bufio.ReadWriter, error)

Hijack wraps response writer's Hijack function.

func (*Response) SetWriter 

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

SetWriter sets the provided writer as the new *Response http.ResponseWriter

func (*Response) Size 

func (r *Response) Size() int64

Size returns the number of bytes written in the *Response

func (*Response) Status 

func (r *Response) Status() int

Status returns the *Response's current http status code.

func (*Response) Write 

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

Write writes the data to the connection as part of an HTTP reply. If WriteHeader has not yet been called, Write calls WriteHeader(http.StatusOK) before writing the data. If the Header does not contain a Content-Type line, Write adds a Content-Type set to the result of passing the initial 512 bytes of written data to DetectContentType.

func (*Response) WriteHeader 

func (r *Response) WriteHeader(code int)

WriteHeader sends an HTTP *Response header with 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.

func (*Response) WriteString 

func (r *Response) WriteString(s string) (n int, err error)

WriteString write string to ResponseWriter

func (*Response) Writer 

func (r *Response) Writer() http.ResponseWriter

Writer return the *Response's http.ResponseWriter object. Usually only used when creating middleware.

type RouteMap 

type RouteMap struct {
	Depth   int    `json:"depth"`
	Path    string `json:"path"`
	Method  string `json:"method"`
	Handler string `json:"handler"`
}

RouteMap contains a single routes full path and other information

Source Files

View all Source files

Directories

Path Synopsis
_examples
README
all-in-one
custom-handler
decode
groups
hello-world
middleware/logging-recovery
native
websockets

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.