echo

package module
v0.0.13 Latest Latest
Warning

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

Go to latest
Published: May 19, 2015 License: MIT Imports: 15 Imported by: 0

README

Echo GoDoc Build Status Coverage Status

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

Features

  • Fast 🚀 HTTP router which smartly prioritize routes.
  • Extensible middleware/handler, supports:
    • Middleware
      • echo.MiddlewareFunc
      • func(echo.HandlerFunc) echo.HandlerFunc
      • echo.HandlerFunc
      • func(*echo.Context) *echo.HTTPError
      • func(http.Handler) http.Handler
      • http.Handler
      • http.HandlerFunc
      • func(http.ResponseWriter, *http.Request)
    • Handler
      • echo.HandlerFunc
      • func(*echo.Context) *echo.HTTPError
      • http.Handler
      • http.HandlerFunc
      • func(http.ResponseWriter, *http.Request)
  • 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

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

##Examples

###Hello, World!

package main

import (
	"net/http"

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

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

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

	// Middleware
	e.Use(mw.Logger())
	e.Use(mw.Recover())

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

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

###CRUD

package main

import (
	"net/http"
	"strconv"

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

type (
	user struct {
		ID   int
		Name string
	}
)

var (
	users = map[int]*user{}
	seq   = 1
)

//----------
// Handlers
//----------

func createUser(c *echo.Context) *echo.HTTPError {
	u := &user{
		ID: seq,
	}
	if he := c.Bind(u); he != nil {
		return he
	}
	users[u.ID] = u
	seq++
	return c.JSON(http.StatusCreated, u)
}

func getUser(c *echo.Context) *echo.HTTPError {
	id, _ := strconv.Atoi(c.Param("id"))
	return c.JSON(http.StatusOK, users[id])
}

func updateUser(c *echo.Context) *echo.HTTPError {
	u := new(user)
	if he := c.Bind(u); he != nil {
		return he
	}
	id, _ := strconv.Atoi(c.Param("id"))
	users[id].Name = u.Name
	return c.JSON(http.StatusOK, users[id])
}

func deleteUser(c *echo.Context) *echo.HTTPError {
	id, _ := strconv.Atoi(c.Param("id"))
	delete(users, id)
	return c.NoContent(http.StatusNoContent)
}

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

	// Middleware
	e.Use(mw.Logger())
	e.Use(mw.Recover())

	// Routes
	e.Post("/users", createUser)
	e.Get("/users/:id", getUser)
	e.Patch("/users/:id", updateUser)
	e.Delete("/users/:id", deleteUser)

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

###Website

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{}) *echo.HTTPError {
	if err := t.templates.ExecuteTemplate(w, name, data); err != nil {
		return &echo.HTTPError{Error: err}
	}
	return nil
}

//----------
// Handlers
//----------

func welcome(c *echo.Context) *echo.HTTPError {
	return c.Render(http.StatusOK, "welcome", "Joe")
}

func createUser(c *echo.Context) *echo.HTTPError {
	u := new(user)
	if err := c.Bind(u); err != nil {
		return err
	}
	users[u.ID] = *u
	return c.JSON(http.StatusCreated, u)
}

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

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

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

	// Middleware
	e.Use(mw.Logger())
	e.Use(mw.Recover())

	//------------------------
	// 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) *echo.HTTPError {
		return c.JSON(http.StatusOK, s.Data())
	})

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

	// Serve favicon
	e.Favicon("public/favicon.ico")

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

	//--------
	// 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/views/welcome.html")),
	}
	e.Renderer(t)
	e.Get("/welcome", welcome)

	//-------
	// Group
	//-------

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

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

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

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

###Middleware

package main

import (
	"net/http"

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

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

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

	// Debug mode
	e.Debug(true)

	//------------
	// Middleware
	//------------

	// Logger
	e.Use(mw.Logger())

	// Recover
	e.Use(mw.Recover())

	// Basic auth
	e.Use(mw.BasicAuth(func(u, p string) bool {
		if u == "joe" && p == "secret" {
			return true
		}
		return false
	}))

	//-------
	// Slash
	//-------

	e.Use(mw.StripTrailingSlash())

	// or

	//	e.Use(mw.RedirectToSlash())

	// Gzip
	e.Use(mw.Gzip())

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

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

##Guide

Contribute

Use issues for everything

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

Credits

License

MIT

Documentation

Index

Constants

View Source
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"

	ApplicationJSON     = "application/json"
	ApplicationProtobuf = "application/protobuf"
	ApplicationMsgpack  = "application/msgpack"
	TextPlain           = "text/plain"
	TextHTML            = "text/html"
	ApplicationForm     = "application/x-www-form-urlencoded"
	MultipartForm       = "multipart/form-data"

	Accept             = "Accept"
	AcceptEncoding     = "Accept-Encoding"
	ContentDisposition = "Content-Disposition"
	ContentEncoding    = "Content-Encoding"
	ContentLength      = "Content-Length"
	ContentType        = "Content-Type"
	Authorization      = "Authorization"
)

Variables

View Source
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 added in v0.0.9

type BindFunc func(*http.Request, interface{}) *HTTPError

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 objects, path parameters, data and registered handler.

func NewContext added in v0.0.13

func NewContext(req *http.Request, res *Response, e *Echo) *Context

func (*Context) Bind

func (c *Context) Bind(i interface{}) *HTTPError

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

func (*Context) Error added in v0.0.10

func (c *Context) Error(he *HTTPError)

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 added in v0.0.5

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

HTML sends a text/html response with status code.

func (*Context) JSON

func (c *Context) JSON(code int, i interface{}) *HTTPError

JSON sends an application/json response with status code.

func (*Context) NoContent added in v0.0.10

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

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

func (*Context) P

func (c *Context) P(i uint8) (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 added in v0.0.5

func (c *Context) Render(code int, name string, data interface{}) *HTTPError

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) *HTTPError

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 added in v0.0.9

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) Debug added in v0.0.13

func (e *Echo) Debug(on bool)

Debug runs the application in debug mode.

func (*Echo) Delete

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

Delete adds a DELETE route > handler to the router.

func (*Echo) Favicon added in v0.0.13

func (e *Echo) Favicon(file string)

Favicon serves the default favicon - GET /favicon.ico.

func (*Echo) Get

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

Get adds a GET route > handler to the router.

func (*Echo) Group added in v0.0.4

func (e *Echo) Group(pfx string, m ...Middleware) *Echo

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

func (*Echo) HTTPErrorHandler added in v0.0.10

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 number of path parameters allowed for the application. Default value is 5, good enough for many use cases.

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 added in v0.0.7

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 added in v0.0.5

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

RunServer runs a custom server.

func (*Echo) RunTLS added in v0.0.5

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

RunTLS runs a server with TLS configuration.

func (*Echo) RunTLSServer added in v0.0.5

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 added in v0.0.11

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

URI generates a URI from handler.

func (*Echo) URL added in v0.0.11

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

URL is an alias for URI

func (*Echo) Use

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

Use adds handler to the middleware chain.

type HTTPError added in v0.0.12

type HTTPError struct {
	Code    int
	Message string
	Error   error
}

type HTTPErrorHandler added in v0.0.10

type HTTPErrorHandler func(*HTTPError, *Context)

HTTPErrorHandler is a centralized HTTP error handler.

type Handler

type Handler interface{}

type HandlerFunc

type HandlerFunc func(*Context) *HTTPError

type Middleware

type Middleware interface{}

type MiddlewareFunc

type MiddlewareFunc func(HandlerFunc) HandlerFunc

type Renderer added in v0.0.7

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

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.

type Response added in v0.0.13

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

func (*Response) CloseNotify added in v0.0.13

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

CloseNotify wraps response writer's CloseNotify function.

func (*Response) Flush added in v0.0.13

func (r *Response) Flush()

Flush wraps response writer's Flush function.

func (*Response) Header added in v0.0.13

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

func (*Response) Hijack added in v0.0.13

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

Hijack wraps response writer's Hijack function.

func (*Response) Size added in v0.0.13

func (r *Response) Size() int64

func (*Response) Status added in v0.0.13

func (r *Response) Status() int

func (*Response) Write added in v0.0.13

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

func (*Response) WriteHeader added in v0.0.13

func (r *Response) WriteHeader(code int)

Directories

Path Synopsis
examples

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL