echo

README

Echo

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

Features

• Fast 🚀 router which smartly resolves conflicting routes
• 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)
• 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 (
	"io"
	"net/http"

	"html/template"

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

type (
	// Template provides HTML template rendering
	Template struct {
		templates *template.Template
	}

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

var (
	users map[string]user
)

// Render HTML
func (t *Template) Render(w io.Writer, name string, data interface{}) error {
	return t.templates.ExecuteTemplate(w, name, data)
}

func welcome(c *echo.Context) {
	c.Render("welcome", "Joe")
}

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)

	//***************//
	//   Templates   //
	//***************//
	t := &Template{
		// Cached templates
		templates: template.Must(template.ParseFiles("public/tpl/welcome.tpl")),
	}
	e.Renderer(t)
	e.Get("/welcome", welcome)

	//***********//
	//   Group   //
	//***********//
	// Group with parent middleware
	a := e.Group("/admin")
	a.Use(func(c *echo.Context) {
		// Security middleware
	})
	a.Get("", func(c *echo.Context) {
		c.String(http.StatusOK, "Welcome admin!")
	})

	// Group with no parent middleware
	g := e.Group("/files", func(c *echo.Context) {
		// Security middleware
	})
	g.Get("", func(c *echo.Context) {
		c.String(http.StatusOK, "Your files!")
	})

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

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

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

License

MIT

Documentation

Index

• Constants
• Variables
• func NewRouter(e *Echo) (r *router)
• type BindFunc
• type Context
  • func (c *Context) Bind(v interface{}) error
  • func (c *Context) Get(key string) interface{}
  • func (c *Context) HTML(code int, html string) (err error)
  • func (c *Context) JSON(code int, v interface{}) error
  • func (c *Context) P(i uint8) string
  • func (c *Context) Param(name string) (value string)
  • func (c *Context) Redirect(code int, url string)
  • func (c *Context) Render(name string, data interface{}) error
  • func (c *Context) Set(key string, val interface{})
  • func (c *Context) String(code int, s string) (err error)
• type Echo
  • func New() (e *Echo)
  • func (e *Echo) Binder(b BindFunc)
  • 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, m ...Middleware) *Echo
  • func (e *Echo) Head(path string, h Handler)
  • func (e *Echo) Index(file string)
  • func (e *Echo) MaxParam(n uint8)
  • 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) Renderer(r Renderer)
  • func (e *Echo) Run(addr string)
  • func (e *Echo) RunServer(server *http.Server)
  • func (e *Echo) RunTLS(addr, certFile, keyFile string)
  • func (e *Echo) RunTLSServer(server *http.Server, certFile, keyFile string)
  • func (e *Echo) ServeFile(path, file string)
  • func (e *Echo) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (e *Echo) Static(path, root string)
  • 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
• type Renderer

Constants

const (
	CONNECT = "CONNECT"
	DELETE  = "DELETE"
	GET     = "GET"
	HEAD    = "HEAD"
	OPTIONS = "OPTIONS"
	PATCH   = "PATCH"
	POST    = "POST"
	PUT     = "PUT"
	TRACE   = "TRACE"

	MIMEJSON          = "application/json"
	MIMEText          = "text/plain"
	MIMEHTML          = "text/html"
	MIMEForm          = "application/x-www-form-urlencoded"
	MIMEMultipartForm = "multipart/form-data"

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

Variables

var (

	// Errors
	ErrUnsupportedMediaType = errors.New("echo: unsupported media type")
	ErrNoRenderer           = errors.New("echo: renderer not registered")
)

Functions

func NewRouter

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

Types

type BindFunc

type BindFunc func(r *http.Request, v interface{}) error

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.

func (*Context) Bind

func (c *Context) Bind(v interface{}) error

Bind binds the request body into specified type v. Default binder does it based on Content-Type header.

func (*Context) Get

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

Get retrieves data from the context.

func (*Context) HTML

func (c *Context) HTML(code int, html string) (err error)

HTML sends a text/html response with status code.

func (*Context) JSON

func (c *Context) JSON(code int, v interface{}) 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(name string) (value string)

Param returns path parameter by name.

func (*Context) Redirect

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

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

func (*Context) Render

func (c *Context) Render(name string, data interface{}) error

Render invokes the registered HTML template renderer and sends a text/html response.

func (*Context) Set

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

Set saves data in the context.

func (*Context) String

func (c *Context) String(code int, s string) (err error)

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 an Echo instance.

func (*Echo) Binder

func (e *Echo) Binder(b BindFunc)

Binder registers a custom binder. It's invoked by Context.Bind API.

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, m ...Middleware) *Echo

Group creates a new sub router with prefix and inherits all properties from the parent. Passing middleware overrides parent middleware.

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) MaxParam

func (e *Echo) MaxParam(n uint8)

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

func (*Echo) NotFoundHandler

func (e *Echo) NotFoundHandler(h Handler)

NotFoundHandler registers 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) Renderer

func (e *Echo) Renderer(r Renderer)

Renderer registers an HTML template renderer. It's invoked by Context.Render API.

func (*Echo) Run

func (e *Echo) Run(addr string)

Run a server

func (*Echo) RunServer

func (e *Echo) RunServer(server *http.Server)

RunServer runs a custom server

func (*Echo) RunTLS

func (e *Echo) RunTLS(addr, certFile, keyFile string)

RunTLS a server

func (*Echo) RunTLSServer

func (e *Echo) RunTLSServer(server *http.Server, certFile, keyFile string)

RunTLSServer runs a custom server with TLS configuration

func (*Echo) ServeFile

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

ServeFile serves a file.

func (*Echo) ServeHTTP

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

func (*Echo) Static

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

Static serves static files.

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

type Renderer

type Renderer interface {
	Render(w io.Writer, name string, data interface{}) error
}

Renderer is the interface that wraps the Render method.

Render renders the HTML template with given name and specified data. It writes the output to w.