echo

README

Echo

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

Features

• Fast 🚀 HTTP router which smartly resolves conflicting routes.
• Fast router which smartly resolves conflicting routes.
• Extensible middleware/handler, supports:
  • Middleware
    • func(*echo.Context)
    • func(*echo.Context) error
    • func(echo.HandlerFunc) echo.HandlerFunc
    • func(http.Handler) http.Handler
    • http.Handler
    • http.HandlerFunc
    • func(http.ResponseWriter, *http.Request)
    • func(http.ResponseWriter, *http.Request) error
  • Handler
    • func(*echo.Context)
    • func(*echo.Context) error
    • http.Handler
    • http.HandlerFunc
    • func(http.ResponseWriter, *http.Request)
    • func(http.ResponseWriter, *http.Request) error
• Sub routing with groups.
• Handy encoding/decoding functions.
• Serve static files, including index.
• Centralized HTTP error handling.
• Use a customized function to bind request body to a Go type.
• Register a view render so you can use any HTML template engine.

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

Installation

$ go get github.com/labstack/echo

##Hello, World!

package main

import (
	"net/http"

	"github.com/labstack/echo"
	mw "github.com/labstack/echo/middleware"
)

// Handler
func hello(c *echo.Context) {
	c.String(http.StatusOK, "Hello, World!\n")
}

func main() {
	// Echo instance
	e := echo.New()

	// Middleware
	e.Use(mw.Logger)

	// Routes
	e.Get("/", hello)

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

##Examples

##Guide

Contribute

Use issues for everything

• Report problems
• Discuss before sending pull request
• Suggest new features
• Improve/fix documentation

Credits

• Vishal Rana - Author
• Nitin Rana - Consultant
• Contributors

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) Error(code int, err 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) NoContent(code int) error
  • func (c *Context) P(i int) (value string)
  • func (c *Context) Param(name string) (value string)
  • func (c *Context) Redirect(code int, url string)
  • func (c *Context) Render(code int, 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) HTTPErrorHandler(h HTTPErrorHandler)
  • 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) URI(h Handler, params ...string) string
  • func (e *Echo) URL(h Handler, params ...string) string
  • func (e *Echo) Use(m ...Middleware)
• type HTTPErrorHandler
• type Handler
• type HandlerFunc
• type Middleware
• type MiddlewareFunc
• type Renderer

Constants

const (
	// CONNECT HTTP method
	CONNECT = "CONNECT"
	// DELETE HTTP method
	DELETE = "DELETE"
	// GET HTTP method
	GET = "GET"
	// HEAD HTTP method
	HEAD = "HEAD"
	// OPTIONS HTTP method
	OPTIONS = "OPTIONS"
	// PATCH HTTP method
	PATCH = "PATCH"
	// POST HTTP method
	POST = "POST"
	// PUT HTTP method
	PUT = "PUT"
	// TRACE HTTP method
	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 (
	UnsupportedMediaType  = errors.New("echo: unsupported media type")
	RendererNotRegistered = errors.New("echo: renderer not registered")
)

Functions

func NewRouter

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

Types

type BindFunc

type BindFunc func(*http.Request, 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) Error

func (c *Context) Error(code int, err error)

Error invokes the registered HTTP error handler.

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

func (c *Context) NoContent(code int) error

NoContent sends a response with no body and a status code.

func (*Context) P

func (c *Context) P(i int) (value 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(code int, name string, data interface{}) error

Render invokes the registered HTML template renderer and sends a text/html response 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(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) HTTPErrorHandler

func (e *Echo) HTTPErrorHandler(h HTTPErrorHandler)

HTTPErrorHandler registers an HTTP error handler.

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 runs 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 runs a server with TLS configuration.

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

func (e *Echo) URI(h Handler, params ...string) string

URI generates a URI from handler.

func (*Echo) URL

func (e *Echo) URL(h Handler, params ...string) string

URL is an alias for URI

func (*Echo) Use

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

Use adds handler to the middleware chain.

type HTTPErrorHandler

type HTTPErrorHandler func(int, error, *Context)

HTTPErrorHandler is a centralized HTTP error handler.

type Handler

type Handler interface{}

type HandlerFunc

type HandlerFunc func(*Context) error

type Middleware

type Middleware interface{}

type MiddlewareFunc

type MiddlewareFunc func(HandlerFunc) HandlerFunc

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.