echo

README

Echo

Echo is a fast HTTP router (zero memory allocation) + micro web framework in Go.

Features

• Zippy router.
• Extensible middleware/handler, supports:
  • Middleware
    • func(*echo.Context)
    • func(echo.HandlerFunc) echo.HandlerFunc
    • func(http.Handler) http.Handler
    • http.Handler
    • http.HandlerFunc
    • func(http.ResponseWriter, *http.Request)
  • Handler
    • func(*echo.Context)
    • http.Handler
    • http.HandlerFunc
    • func(http.ResponseWriter, *http.Request)
• Sub/Group routing
• Handy encoding/decoding functions.
• Serve static files, including index.

Installation

go get github.com/labstack/echo

Usage

labstack/echo/example

package main

import (
	"net/http"

	"github.com/labstack/echo"
	mw "github.com/labstack/echo/middleware"
	"github.com/rs/cors"
	"github.com/thoas/stats"
)

type user struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

var users map[string]user

func init() {
	users = map[string]user{
		"1": user{
			ID:   "1",
			Name: "Wreck-It Ralph",
		},
	}
}

func createUser(c *echo.Context) {
	u := new(user)
	if err := c.Bind(u); err == nil {
		users[u.ID] = *u
		if err := c.JSON(http.StatusCreated, u); err == nil {
			// Do something!
		}
		return
	}
	http.Error(c.Response, http.StatusText(http.StatusBadRequest), http.StatusBadRequest)
}

func getUsers(c *echo.Context) {
	c.JSON(http.StatusOK, users)
}

func getUser(c *echo.Context) {
	c.JSON(http.StatusOK, users[c.P(0)])
}

func main() {
	e := echo.New()

	//*************************//
	//   Built-in middleware   //
	//*************************//
	e.Use(mw.Logger)

	//****************************//
	//   Third-party middleware   //
	//****************************//
	// https://github.com/rs/cors
	e.Use(cors.Default().Handler)

	// https://github.com/thoas/stats
	s := stats.New()
	e.Use(s.Handler)
	// Route
	e.Get("/stats", func(c *echo.Context) {
		c.JSON(200, s.Data())
	})

	// Serve index file
	e.Index("public/index.html")

	// Serve static files
	e.Static("/js", "public/js")

	//************//
	//   Routes   //
	//************//
	e.Post("/users", createUser)
	e.Get("/users", getUsers)
	e.Get("/users/:id", getUser)

	//****************//
	//   Sub router   //
	//****************//
	// Sub - inherits parent middleware
	sub := e.Sub("/sub")
	sub.Use(func(c *echo.Context) { // Middleware
	})
	sub.Get("/home", func(c *echo.Context) {
		c.String(200, "Sub route /sub/welcome")
	})

	// Group - doesn't inherit parent middleware
	grp := e.Group("/group")
	grp.Use(func(c *echo.Context) { // Middleware
	})
	grp.Get("/home", func(c *echo.Context) {
		c.String(200, "Group route /group/welcome")
	})

	// Start server
	e.Run(":8080")
}

Benchmark

Based on [julienschmidt/go-http-routing-benchmark] (https://github.com/vishr/go-http-routing-benchmark), April 1, 2015

GitHub API

Echo: 42728 ns/op, 0 B/op, 0 allocs/op

BenchmarkAce_GithubAll	   	   20000	     65328 ns/op	   13792 B/op	     167 allocs/op
BenchmarkBear_GithubAll	   	   10000	    241852 ns/op	   79952 B/op	     943 allocs/op
BenchmarkBeego_GithubAll	    3000	    458234 ns/op	  146272 B/op	    2092 allocs/op
BenchmarkBone_GithubAll	    	1000	   1923508 ns/op	  648016 B/op	    8119 allocs/op
BenchmarkDenco_GithubAll	   20000	     81294 ns/op	   20224 B/op	     167 allocs/op
BenchmarkEcho_GithubAll	   	   30000	     42728 ns/op	       0 B/op	       0 allocs/op
BenchmarkGin_GithubAll	   	   20000	     69373 ns/op	   13792 B/op	     167 allocs/op
BenchmarkGocraftWeb_GithubAll  10000	    370978 ns/op	  133280 B/op	    1889 allocs/op
BenchmarkGoji_GithubAll	    	3000	    542766 ns/op	   56113 B/op	     334 allocs/op
BenchmarkGoJsonRest_GithubAll	5000	    452551 ns/op	  135995 B/op	    2940 allocs/op
BenchmarkGoRestful_GithubAll	 200	   9500204 ns/op	  707604 B/op	    7558 allocs/op
BenchmarkGorillaMux_GithubAll	 200	   6770545 ns/op	  153137 B/op	    1791 allocs/op
BenchmarkHttpRouter_GithubAll  30000	     56097 ns/op	   13792 B/op	     167 allocs/op
BenchmarkHttpTreeMux_GithubAll 10000	    143175 ns/op	   56112 B/op	     334 allocs/op
BenchmarkKocha_GithubAll	   10000	    147959 ns/op	   23304 B/op	     843 allocs/op
BenchmarkMacaron_GithubAll	    2000	    724650 ns/op	  224960 B/op	    2315 allocs/op
BenchmarkMartini_GithubAll	     100	  10926021 ns/op	  237953 B/op	    2686 allocs/op
BenchmarkPat_GithubAll	     	 300	   4525114 ns/op	 1504101 B/op	   32222 allocs/op
BenchmarkRevel_GithubAll	    2000	   1172963 ns/op	  345553 B/op	    5918 allocs/op
BenchmarkRivet_GithubAll	   10000	    249104 ns/op	   84272 B/op	    1079 allocs/op
BenchmarkTango_GithubAll	     300	   4012826 ns/op	 1368581 B/op	   29157 allocs/op
BenchmarkTigerTonic_GithubAll	2000	    975450 ns/op	  241088 B/op	    6052 allocs/op
BenchmarkTraffic_GithubAll	     200	   7540377 ns/op	 2664762 B/op	   22390 allocs/op
BenchmarkVulcan_GithubAll	    5000	    307241 ns/op	   19894 B/op	     609 allocs/op
BenchmarkZeus_GithubAll	        2000	    752907 ns/op	  300688 B/op	    2648 allocs/op

Documentation

Index

• Constants
• Variables
• func NewRouter(e *Echo) (r *router)
• type Context
  • func (c *Context) Bind(i interface{}) (err error)
  • func (c *Context) Get(key string) interface{}
  • func (c *Context) JSON(n int, i interface{}) (err error)
  • func (c *Context) P(i uint8) string
  • func (c *Context) Param(n string) string
  • func (c *Context) Redirect(n int, url string)
  • func (c *Context) Set(key string, val interface{})
  • func (c *Context) String(n int, s string)
• type Echo
  • func New() (e *Echo)
  • func (e *Echo) Connect(path string, h Handler)
  • func (e *Echo) Delete(path string, h Handler)
  • func (e *Echo) Get(path string, h Handler)
  • func (e *Echo) Group(pfx string) *Echo
  • func (e *Echo) Head(path string, h Handler)
  • func (e *Echo) Index(file string)
  • func (e *Echo) InternalServerErrorHandler(h Handler)
  • func (e *Echo) MaxParam(n uint8)
  • func (e *Echo) MethodNotAllowedHandler(h Handler)
  • func (e *Echo) NotFoundHandler(h Handler)
  • func (e *Echo) Options(path string, h Handler)
  • func (e *Echo) Patch(path string, h Handler)
  • func (e *Echo) Post(path string, h Handler)
  • func (e *Echo) Put(path string, h Handler)
  • func (e *Echo) Run(addr string)
  • func (e *Echo) ServeFile(path, file string)
  • func (e *Echo) ServeHTTP(rw http.ResponseWriter, r *http.Request)
  • func (e *Echo) Static(path, root string)
  • func (e *Echo) Sub(pfx string) *Echo
  • func (e *Echo) Trace(path string, h Handler)
  • func (e *Echo) Use(m ...Middleware)
• type Handler
• type HandlerFunc
  • func (h HandlerFunc) ServeHTTP(http.ResponseWriter, *http.Request)
• type Middleware
• type MiddlewareFunc
• type Params
  • func (ps Params) Get(n string) (v string)

Constants

const (
	MethodCONNECT = "CONNECT"
	MethodDELETE  = "DELETE"
	MethodGET     = "GET"
	MethodHEAD    = "HEAD"
	MethodOPTIONS = "OPTIONS"
	MethodPATCH   = "PATCH"
	MethodPOST    = "POST"
	MethodPUT     = "PUT"
	MethodTRACE   = "TRACE"

	MIMEJSON = "application/json"
	MIMEText = "text/plain"

	HeaderAccept             = "Accept"
	HeaderContentDisposition = "Content-Disposition"
	HeaderContentLength      = "Content-Length"
	HeaderContentType        = "Content-Type"
)

Variables

var (

	// Errors
	ErrUnsupportedContentType = errors.New("echo: unsupported content type")
	ErrBindJSON               = errors.New("echo: bind json error")
	ErrRenderJSON             = errors.New("echo: render json error")
)

Functions

func NewRouter

func NewRouter(e *Echo) (r *router)

Types

type Context

type Context struct {
	Request  *http.Request
	Response *response
	// contains filtered or unexported fields
}

Context represents context for the current request. It holds request and response references, path parameters, data and registered handler for the route.

func (*Context) Bind

func (c *Context) Bind(i interface{}) (err error)

Bind decodes the payload into provided type based on Content-Type header.

func (*Context) Get

func (c *Context) Get(key string) interface{}

Get retrieves data from the context.

func (*Context) JSON

func (c *Context) JSON(n int, i interface{}) (err error)

JSON sends an application/json response with status code.

func (*Context) P

func (c *Context) P(i uint8) string

P returns path parameter by index.

func (*Context) Param

func (c *Context) Param(n string) string

Param returns path parameter by name.

func (*Context) Redirect

func (c *Context) Redirect(n int, url string)

Redirect redirects the request using http.Redirect with status code.

func (*Context) Set

func (c *Context) Set(key string, val interface{})

Set saves data in the context.

func (*Context) String

func (c *Context) String(n int, s string)

String sends a text/plain response with status code.

type Echo

type Echo struct {
	Router *router
	// contains filtered or unexported fields
}

func New

func New() (e *Echo)

New creates a echo instance.

func (*Echo) Connect

func (e *Echo) Connect(path string, h Handler)

Connect adds a CONNECT route > handler to the router.

func (*Echo) Delete

func (e *Echo) Delete(path string, h Handler)

Delete adds a DELETE route > handler to the router.

func (*Echo) Get

func (e *Echo) Get(path string, h Handler)

Get adds a GET route > handler to the router.

func (*Echo) Group

func (e *Echo) Group(pfx string) *Echo

Group is simmilar to Sub but excludes inheriting middleware from the parent router.

func (*Echo) Head

func (e *Echo) Head(path string, h Handler)

Head adds a HEAD route > handler to the router.

func (*Echo) Index

func (e *Echo) Index(file string)

Index serves index file.

func (*Echo) InternalServerErrorHandler

func (e *Echo) InternalServerErrorHandler(h Handler)

InternalServerErrorHandler sets a custom InternalServerError handler.

func (*Echo) MaxParam

func (e *Echo) MaxParam(n uint8)

MaxParam sets the maximum allowed path parameters. Default is 5, good enough for many users.

func (*Echo) MethodNotAllowedHandler

func (e *Echo) MethodNotAllowedHandler(h Handler)

MethodNotAllowedHandler sets a custom MethodNotAllowed handler.

func (*Echo) NotFoundHandler

func (e *Echo) NotFoundHandler(h Handler)

NotFoundHandler sets a custom NotFound handler.

func (*Echo) Options

func (e *Echo) Options(path string, h Handler)

Options adds an OPTIONS route > handler to the router.

func (*Echo) Patch

func (e *Echo) Patch(path string, h Handler)

Patch adds a PATCH route > handler to the router.

func (*Echo) Post

func (e *Echo) Post(path string, h Handler)

Post adds a POST route > handler to the router.

func (*Echo) Put

func (e *Echo) Put(path string, h Handler)

Put adds a PUT route > handler to the router.

func (*Echo) Run

func (e *Echo) Run(addr string)

func (*Echo) ServeFile

func (e *Echo) ServeFile(path, file string)

ServeFile serves a file.

func (*Echo) ServeHTTP

func (e *Echo) ServeHTTP(rw http.ResponseWriter, r *http.Request)

func (*Echo) Static

func (e *Echo) Static(path, root string)

Static serves static files.

func (*Echo) Sub

func (e *Echo) Sub(pfx string) *Echo

Sub creates a new sub router. It inherits all properties from the parent router, including middleware.

func (*Echo) Trace

func (e *Echo) Trace(path string, h Handler)

Trace adds a TRACE route > handler to the router.

func (*Echo) Use

func (e *Echo) Use(m ...Middleware)

Use adds handler to the middleware chain.

type Handler

type Handler interface{}

type HandlerFunc

type HandlerFunc func(*Context)

func (HandlerFunc) ServeHTTP

func (h HandlerFunc) ServeHTTP(http.ResponseWriter, *http.Request)

NOP

type Middleware

type Middleware interface{}

type MiddlewareFunc

type MiddlewareFunc func(HandlerFunc) HandlerFunc

type Params

type Params []param

func (Params) Get

func (ps Params) Get(n string) (v string)

Get returns path parameter by name.