routing

package module
Version: v2.2.2+incompatible Latest Latest
Warning

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

Go to latest
Published: Apr 3, 2019 License: MIT Imports: 15 Imported by: 10

README

ozzo-routing

GoDoc Build Status Coverage Status Go Report

You may consider using golang-restful-starter-kit to jumpstart your new RESTful applications with ozzo-routing.

Description

ozzo-routing is a Go package that provides high performance and powerful HTTP routing capabilities for Web applications. It has the following features:

  • middleware pipeline architecture, similar to that of the Express framework.
  • extremely fast request routing with zero dynamic memory allocation (the performance is comparable to that of httprouter and gin, see the performance comparison below)
  • modular code organization through route grouping
  • flexible URL path matching, supporting URL parameters and regular expressions
  • URL creation according to the predefined routes
  • compatible with http.Handler and http.HandlerFunc
  • ready-to-use handlers sufficient for building RESTful APIs

If you are using fasthttp, you may use a similar routing package fasthttp-routing which is adapted from ozzo-routing.

Requirements

Go 1.7 or above.

Installation

Run the following command to install the package:

go get github.com/ltick/tick-routing

You may also get specified release of the package by:

go get gopkg.in/go-ozzo/ozzo-routing.v1

Getting Started

For a complete RESTful application boilerplate based on ozzo-routing, please refer to the golang-restful-starter-kit. Below we describe how to create a simple REST API using ozzo-routing.

Create a server.go file with the following content:

package main

import (
	"log"
	"net/http"
	"github.com/ltick/tick-routing"
	"github.com/ltick/tick-routing/access"
	"github.com/ltick/tick-routing/slash"
	"github.com/ltick/tick-routing/content"
	"github.com/ltick/tick-routing/fault"
	"github.com/ltick/tick-routing/file"
)

func main() {
	router := routing.New()

	router.Use(
		// all these handlers are shared by every route
		access.Logger(log.Printf),
		slash.Remover(http.StatusMovedPermanently),
		fault.Recovery(log.Printf),
	)

	// serve RESTful APIs
	api := router.Group("/api")
	api.Use(
		// these handlers are shared by the routes in the api group only
		content.TypeNegotiator(content.JSON, content.XML),
	)
	api.Get("/users", func(c *routing.Context) error {
		return c.Write("user list")
	})
	api.Post("/users", func(c *routing.Context) error {
		return c.Write("create a new user")
	})
	api.Put(`/users/<id:\d+>`, func(c *routing.Context) error {
		return c.Write("update user " + c.Param("id"))
	})

	// serve index file
	router.Get("/", file.Content("ui/index.html"))
	// serve files under the "ui" subdirectory
	router.Get("/*", file.Server(file.PathMap{
		"/": "/ui/",
	}))

	http.Handle("/", router)
	http.ListenAndServe(":8080", nil)
}

Create an HTML file ui/index.html with any content.

Now run the following command to start the Web server:

go run server.go

You should be able to access URLs such as http://localhost:8080, http://localhost:8080/api/users.

Routes

ozzo-routing works by building a routing table in a router and then dispatching HTTP requests to the matching handlers found in the routing table. An intuitive illustration of a routing table is as follows:

Routes Handlers
GET /users m1, m2, h1, ...
POST /users m1, m2, h2, ...
PUT /users/<id> m1, m2, h3, ...
DELETE /users/<id> m1, m2, h4, ...

For an incoming request GET /users, the first route would match and the handlers m1, m2, and h1 would be executed. If the request is PUT /users/123, the third route would match and the corresponding handlers would be executed. Note that the token <id> can match any number of non-slash characters and the matching part can be accessed as a path parameter value in the handlers.

If an incoming request matches multiple routes in the table, the route added first to the table will take precedence. All other matching routes will be ignored.

The actual implementation of the routing table uses a variant of the radix tree data structure, which makes the routing process as fast as working with a hash table, thanks to the inspiration from httprouter.

To add a new route and its handlers to the routing table, call the To method like the following:

router := routing.New()
router.To("GET", "/users", m1, m2, h1)
router.To("POST", "/users", m1, m2, h2)

You can also use shortcut methods, such as Get, Post, Put, etc., which are named after the HTTP method names:

router.Get("/users", m1, m2, h1)
router.Post("/users", m1, m2, h2)

If you have multiple routes with the same URL path but different HTTP methods, like the above example, you can chain them together as follows,

router.Get("/users", m1, m2, h1).Post(m1, m2, h2)

If you want to use the same set of handlers to handle the same URL path but different HTTP methods, you can take the following shortcut:

router.To("GET,POST", "/users", m1, m2, h)

A route may contain parameter tokens which are in the format of <name:pattern>, where name stands for the parameter name, and pattern is a regular expression which the parameter value should match. A token <name> is equivalent to <name:[^/]*>, i.e., it matches any number of non-slash characters. At the end of a route, an asterisk character can be used to match any number of arbitrary characters. Below are some examples:

  • /users/<username>: matches /users/admin
  • /users/accnt-<id:\d+>: matches /users/accnt-123, but not /users/accnt-admin
  • /users/<username>/*: matches /users/admin/profile/address

When a URL path matches a route, the matching parameters on the URL path can be accessed via Context.Param():

router := routing.New()

router.Get("/users/<username>", func (c *routing.Context) error {
	fmt.Fprintf(c.Response, "Name: %v", c.Param("username"))
	return nil
})
Route Groups

Route group is a way of grouping together the routes which have the same route prefix. The routes in a group also share the same handlers that are registered with the group via its Use method. For example,

router := routing.New()
api := router.Group("/api")
api.Use(m1, m2)
api.Get("/users", h1).Post(h2)
api.Put("/users/<id>", h3).Delete(h4)

The above /api route group establishes the following routing table:

Routes Handlers
GET /api/users m1, m2, h1, ...
POST /api/users m1, m2, h2, ...
PUT /api/users/<id> m1, m2, h3, ...
DELETE /api/users/<id> m1, m2, h4, ...

As you can see, all these routes have the same route prefix /api and the handlers m1 and m2. In other similar routing frameworks, the handlers registered with a route group are also called middlewares.

Route groups can be nested. That is, a route group can create a child group by calling the Group() method. The router serves as the top level route group. A child group inherits the handlers registered with its parent group. For example,

router := routing.New()
router.Use(m1)

api := router.Group("/api")
api.Use(m2)

users := api.Group("/users")
users.Use(m3)
users.Put("/<id>", h1)

Because the router serves as the parent of the api group which is the parent of the users group, the PUT /api/users/<id> route is associated with the handlers m1, m2, m3, and h1.

Router

Router manages the routing table and dispatches incoming requests to appropriate handlers. A router instance is created by calling the routing.New() method.

Because Router implements the http.Handler interface, it can be readily used to serve subtrees on existing Go servers. For example,

router := routing.New()
http.Handle("/", router)
http.ListenAndServe(":8080", nil)
Handlers

A handler is a function with the signature func(*routing.Context) error. A handler is executed by the router if the incoming request URL path matches the route that the handler is associated with. Through the routing.Context parameter, you can access the request information in handlers.

A route may be associated with multiple handlers. These handlers will be executed in the order that they are registered to the route. The execution sequence can be terminated in the middle using one of the following two methods:

  • A handler returns an error: the router will skip the rest of the handlers and handle the returned error.
  • A handler calls Context.Abort(): the router will simply skip the rest of the handlers. There is no error to be handled.

A handler can call Context.Next() to explicitly execute the rest of the unexecuted handlers and take actions after they finish execution. For example, a response compression handler may start the output buffer, call Context.Next(), and then compress and send the output to response.

Context

For each incoming request, a routing.Context object is populated with the request information and passed through the handlers that need to handle the request. Handlers can get the request information via Context.Request and send a response back via Context.Response. The Context.Param() method allows handlers to access the URL path parameters that match the current route.

Using Context.Get() and Context.Set(), handlers can share data between each other. For example, an authentication handler can store the authenticated user identity by calling Context.Set(), and other handlers can retrieve back the identity information by calling Context.Get().

Reading Request Data

Context provides a few shortcut methods to read query parameters. The Context.Query() method returns the named URL query parameter value; the Context.PostForm() method returns the named parameter value in the POST or PUT body parameters; and the Context.Form() method returns the value from either POST/PUT or URL query parameters.

The Context.Read() method supports reading data from the request body and populating it into an object. The method will check the Content-Type HTTP header and parse the body data as the corresponding format. For example, if Content-Type is application/json, the request body will be parsed as JSON data. The public fields in the object being populated will receive the parsed data if the data contains the same named fields. For example,

func foo(c *routing.Context) error {
    data := &struct{
        A string
        B bool
    }{}

    // assume the body data is: {"A":"abc", "B":true}
    // data will be populated as: {A: "abc", B: true}
    if err := c.Read(&data); err != nil {
        return err
    }
}

By default, Context supports reading data that are in JSON, XML, form, and multipart-form data. You may modify routing.DataReaders to add support for other data formats.

Note that when the data is read as form data, you may use struct tag named form to customize the name of the corresponding field in the form data. The form data reader also supports populating data into embedded objects which are either named or anonymous.

Writing Response Data

The Context.Write() method can be used to write data of arbitrary type to the response. By default, if the data being written is neither a string nor a byte array, the method will will call fmt.Fprint() to write the data into the response.

You can call Context.SetWriter() to replace the default data writer with a customized one. For example, the content.TypeNegotiator will negotiate the content response type and set the data writer with an appropriate one.

Error Handling

A handler may return an error indicating some erroneous condition. Sometimes, a handler or the code it calls may cause a panic. Both should be handled properly to ensure best user experience. It is recommended that you use the fault.Recover handler or a similar error handler to handle these errors.

If an error is not handled by any handler, the router will handle it by calling its handleError() method which simply sets an appropriate HTTP status code and writes the error message to the response.

When an incoming request has no matching route, the router will call the handlers registered via the Router.NotFound() method. All the handlers registered via Router.Use() will also be called in advance. By default, the following two handlers are registered with Router.NotFound():

  • routing.MethodNotAllowedHandler: a handler that sends an Allow HTTP header indicating the allowed HTTP methods for a requested URL
  • routing.NotFoundHandler: a handler triggering 404 HTTP error

Serving Static Files

Static files can be served with the help of file.Server and file.Content handlers. The former serves files under the specified directories, while the latter serves the content of a single file. For example,

import (
	"github.com/ltick/tick-routing"
	"github.com/ltick/tick-routing/file"
)

router := routing.NewRouter()

// serve index file
router.Get("/", file.Content("ui/index.html"))
// serve files under the "ui" subdirectory
router.Get("/*", file.Server(file.PathMap{
	"/": "/ui/",
}))

Handlers

ozzo-routing comes with a few commonly used handlers in its subpackages:

Handler name Description
access.Logger records an entry for every incoming request
auth.Basic provides authentication via HTTP Basic
auth.Bearer provides authentication via HTTP Bearer
auth.Query provides authentication via token-based query parameter
auth.JWT provides JWT-based authentication
content.TypeNegotiator supports content negotiation by response types
content.LanguageNegotiator supports content negotiation by accepted languages
cors.Handler implements the CORS (Cross Origin Resource Sharing) specification from the W3C
fault.Recovery recovers from panics and handles errors returned by handlers
fault.PanicHandler recovers from panics happened in the handlers
fault.ErrorHandler handles errors returned by handlers by writing them in an appropriate format to the response
file.Server serves the files under the specified folder as response content
file.Content serves the content of the specified file as the response
slash.Remover removes the trailing slashes from the request URL and redirects to the proper URL

The following code shows how these handlers may be used:

import (
	"log"
	"net/http"
	"github.com/ltick/tick-routing"
	"github.com/ltick/tick-routing/access"
	"github.com/ltick/tick-routing/slash"
	"github.com/ltick/tick-routing/fault"
)

router := routing.New()

router.Use(
	access.Logger(log.Printf),
	slash.Remover(http.StatusMovedPermanently),
	fault.Recovery(log.Printf),
)

...
Third-party Handlers

The following third-party handlers are specifically designed for ozzo-routing:

Handler name Description
jwt.JWT supports JWT Authorization

ozzo-routing also provides adapters to support using third-party http.HandlerFunc or http.Handler handlers. For example,

router := routing.New()

// using http.HandlerFunc
router.Use(routing.HTTPHandlerFunc(http.NotFound))

// using http.Handler
router.Use(routing.HTTPHandler(http.NotFoundHandler))

3rd-Party Extensions and Code Examples

Benchmarks

Last updated on Jan 6, 2017

Ozzo-routing is very fast, thanks to the radix tree data structure and the usage of sync.Pool (the idea was originally from HttpRouter and Gin). The following table (by running go-http-routing-benchmark) shows how ozzo-routing compares with Gin, HttpRouter, and Martini in performance.

BenchmarkOzzo_GithubAll                    50000             37989 ns/op               0 B/op          0 allocs/op
BenchmarkEcho_GithubAll                    20000             91003 ns/op            6496 B/op        203 allocs/op
BenchmarkGin_GithubAll                     50000             26717 ns/op               0 B/op          0 allocs/op
BenchmarkHttpRouter_GithubAll              50000             36052 ns/op           13792 B/op        167 allocs/op
BenchmarkMartini_GithubAll                   300           4162283 ns/op          228216 B/op       2483 allocs/op

BenchmarkOzzo_GPlusAll                   1000000              1732 ns/op               0 B/op          0 allocs/op
BenchmarkEcho_GPlusAll                    300000              4523 ns/op             416 B/op         13 allocs/op
BenchmarkGin_GPlusAll                    1000000              1171 ns/op               0 B/op          0 allocs/op
BenchmarkHttpRouter_GPlusAll             1000000              1533 ns/op             640 B/op         11 allocs/op
BenchmarkMartini_GPlusAll                  20000             75634 ns/op           14448 B/op        165 allocs/op

BenchmarkOzzo_ParseAll                    500000              3318 ns/op               0 B/op          0 allocs/op
BenchmarkEcho_ParseAll                    200000              7336 ns/op             832 B/op         26 allocs/op
BenchmarkGin_ParseAll                    1000000              2075 ns/op               0 B/op          0 allocs/op
BenchmarkHttpRouter_ParseAll             1000000              2034 ns/op             640 B/op         16 allocs/op
BenchmarkMartini_ParseAll                  10000            122002 ns/op           25600 B/op        276 allocs/op

Credits

ozzo-routing has referenced many popular routing frameworks, including Express, Martini, httprouter, and gin.

Documentation

Overview

Package routing provides high performance and powerful HTTP routing capabilities.

Example
router := routing.New(context.Background())

router.AppendStartupHandler(
	// all these handlers are shared by every route
	access.Logger(log.Printf),
	slash.Remover(http.StatusMovedPermanently),
	fault.Recovery(log.Printf),
)

// serve RESTful APIs
api := router.Group("/api", nil, nil)
api.AppendStartupHandler(
	// these handlers are shared by the routes in the api group only
	content.TypeNegotiator(content.JSON, content.XML),
)
api.Get("/users", func(c *routing.Context) error {
	return c.Write("user list")
})
api.Post("/users", func(c *routing.Context) error {
	return c.Write("create a new user")
})
api.Put(`/users/<id:\d+>`, func(c *routing.Context) error {
	return c.Write("update user " + c.Param("id"))
})

// serve index file
router.Get("/", file.Content("ui/index.html"))
// serve files under the "ui" subdirectory
router.Get("/*", file.Server(file.PathMap{
	"/": "/ui/",
}))

http.Handle("/", router)
http.ListenAndServe(":8080", nil)
Output:

Index

Examples

Constants

View Source
const (
	MIME_JSON           = "application/json"
	MIME_XML            = "application/xml"
	MIME_XML2           = "text/xml"
	MIME_HTML           = "text/html"
	MIME_FORM           = "application/x-www-form-urlencoded"
	MIME_MULTIPART_FORM = "multipart/form-data"
)

MIME types used when doing request data reading and response data writing.

Variables

View Source
var Methods = []string{
	"CONNECT",
	"DELETE",
	"GET",
	"HEAD",
	"OPTIONS",
	"PATCH",
	"POST",
	"PUT",
	"TRACE",
}

Methods lists all supported HTTP methods by Router.

Functions

func MethodNotAllowedHandler

func MethodNotAllowedHandler(c *Context) error

MethodNotAllowedHandler handles the situation when a request has matching route without matching HTTP method. In this case, the handler will respond with an Allow HTTP header listing the allowed HTTP methods. Otherwise, the handler will do nothing and let the next handler (usually a NotFoundHandler) to handle the problem.

func NotFoundHandler

func NotFoundHandler(c *Context) error

NotFoundHandler returns a 404 HTTP error indicating a request has no matching route.

func ReadFormData

func ReadFormData(form map[string][]string, data interface{}) error

ReadFormData populates the data variable with the data from the given form values.

Types

type Context

type Context struct {
	context.Context
	Wrote bool

	Request        *http.Request       // the current request
	ResponseWriter http.ResponseWriter // the response writer
	// contains filtered or unexported fields
}

Context represents the contextual data and environment while processing an incoming HTTP request.

func NewContext

func NewContext(res http.ResponseWriter, req *http.Request, handlers ...Handler) *Context

NewContext creates a new Context object with the given response, request, and the handlers. This method is primarily provided for writing unit tests for handlers.

func (*Context) Abort

func (c *Context) Abort()

Abort skips the rest of the handlers associated with the current route. Abort is normally used when a handler handles the request normally and wants to skip the rest of the handlers. If a handler wants to indicate an error condition, it should simply return the error without calling Abort.

func (*Context) Form

func (c *Context) Form(key string, defaultValue ...string) string

Form returns the first value for the named component of the query. Form reads the value from POST and PUT body parameters as well as URL query parameters. The form takes precedence over the latter. If key is not present, it returns the specified default value or an empty string.

func (*Context) Get

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

Get returns the named data item previously registered with the context by calling Set. If the named data item cannot be found, nil will be returned.

func (*Context) GetClientIP

func (c *Context) GetClientIP() string

func (*Context) GetClientRealIP

func (c *Context) GetClientRealIP() string

func (*Context) GetClientRemoteIP

func (c *Context) GetClientRemoteIP() string

func (*Context) Next

func (c *Context) Next() (err error)

Next calls the rest of the handlers associated with the current route. If any of these handlers returns an error, Next will return the error and skip the following handlers. Next is normally used when a handler needs to do some postprocessing after the rest of the handlers are executed.

func (*Context) Param

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

Param returns the named parameter value that is found in the URL path matching the current route. If the named parameter cannot be found, an empty string will be returned.

func (*Context) ParamMap

func (c *Context) ParamMap() map[string]string

func (*Context) Params

func (c *Context) Params() []string

func (*Context) PostForm

func (c *Context) PostForm(key string, defaultValue ...string) string

PostForm returns the first value for the named component from POST and PUT body parameters. If key is not present, it returns the specified default value or an empty string.

func (*Context) Query

func (c *Context) Query(name string, defaultValue ...string) string

Query returns the first value for the named component of the URL query parameters. If key is not present, it returns the specified default value or an empty string.

func (*Context) Read

func (c *Context) Read(data interface{}) error

Read populates the given struct variable with the data from the current request. If the request is NOT a GET request, it will check the "Content-Type" header and find a matching reader from DataReaders to read the request data. If there is no match or if the request is a GET request, it will use DefaultFormDataReader to read the request data.

func (*Context) Router

func (c *Context) Router() *Router

Router returns the Router that is handling the incoming HTTP request.

func (*Context) Set

func (c *Context) Set(name string, value interface{})

Set stores the named data item in the context so that it can be retrieved later.

func (*Context) SetDataWriter

func (c *Context) SetDataWriter(writer DataWriter)

SetDataWriter sets the data writer that will be used by Write().

func (*Context) SetParam

func (c *Context) SetParam(name, value string)

SetParam sets the named parameter value. This method is primarily provided for writing unit tests.

func (*Context) URL

func (c *Context) URL(route string, pairs ...interface{}) string

URL creates a URL using the named route and the parameter values. The parameters should be given in the sequence of name1, value1, name2, value2, and so on. If a parameter in the route is not provided a value, the parameter token will remain in the resulting URL. Parameter values will be properly URL encoded. The method returns an empty string if the URL creation fails.

func (*Context) Write

func (c *Context) Write(data interface{}) error

Write writes the given data of arbitrary type to the response. The method calls the data writer set via SetDataWriter() to do the actual writing. By default, the DefaultDataWriter will be used.

func (*Context) WriteHeader

func (c *Context) WriteHeader(status int)

type DataReader

type DataReader interface {
	// Read reads from the given HTTP request and populate the specified data.
	Read(*http.Request, interface{}) error
}

DataReader is used by Context.Read() to read data from an HTTP request.

var (
	// DataReaders lists all supported content types and the corresponding data readers.
	// Context.Read() will choose a matching reader from this list according to the "Content-Type"
	// header from the current request.
	// You may modify this variable to add new supported content types.
	DataReaders = map[string]DataReader{
		MIME_FORM:           &FormDataReader{},
		MIME_MULTIPART_FORM: &FormDataReader{},
		MIME_JSON:           &JSONDataReader{},
		MIME_XML:            &XMLDataReader{},
		MIME_XML2:           &XMLDataReader{},
	}
	// DefaultFormDataReader is the reader used when there is no matching reader in DataReaders
	// or if the current request is a GET request.
	DefaultFormDataReader DataReader = &FormDataReader{}
)

type DataWriter

type DataWriter interface {
	// SetHeader sets necessary response headers.
	SetHeader(http.ResponseWriter)
	// Write writes the given data into the response.
	Write(http.ResponseWriter, interface{}) (int, error)
}

DataWriter is used by Context.Write() to write arbitrary data into an HTTP response.

var DefaultDataWriter DataWriter = &dataWriter{}

DefaultDataWriter writes the given data in an HTTP response. If the data is neither string nor byte array, it will use fmt.Fprint() to write it into the response.

type FormDataReader

type FormDataReader struct{}

FormDataReader reads the query parameters and request body as form data.

func (*FormDataReader) Read

func (r *FormDataReader) Read(req *http.Request, data interface{}) error

type HTTPError

type HTTPError interface {
	error
	// StatusCode returns the HTTP status code of the error
	StatusCode() int
}

HTTPError represents an HTTP error with HTTP status code and error message

func NewHTTPError

func NewHTTPError(status int, message ...string) HTTPError

NewHTTPError creates a new HttpError instance. If the error message is not given, http.StatusText() will be called to generate the message based on the status code.

type Handler

type Handler func(*Context) error

Handler is the function for handling HTTP requests.

func HTTPHandler

func HTTPHandler(h http.Handler) Handler

HTTPHandler adapts a http.Handler into a routing.Handler.

func HTTPHandlerFunc

func HTTPHandlerFunc(h http.HandlerFunc) Handler

HTTPHandlerFunc adapts a http.HandlerFunc into a routing.Handler.

type JSONDataReader

type JSONDataReader struct{}

JSONDataReader reads the request body as JSON-formatted data.

func (*JSONDataReader) Read

func (r *JSONDataReader) Read(req *http.Request, data interface{}) error

type Route

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

Route represents a URL path pattern that can be used to match requested URLs.

func (*Route) Connect

func (r *Route) Connect(handlers ...Handler) *Route

Connect adds the route to the router using the CONNECT HTTP method.

func (*Route) Delete

func (r *Route) Delete(handlers ...Handler) *Route

Delete adds the route to the router using the DELETE HTTP method.

func (*Route) Get

func (r *Route) Get(handlers ...Handler) *Route

Get adds the route to the router using the GET HTTP method.

func (*Route) Head

func (r *Route) Head(handlers ...Handler) *Route

Head adds the route to the router using the HEAD HTTP method.

func (*Route) Method

func (r *Route) Method() string

Method returns the HTTP method that this route is associated with.

func (*Route) Name

func (r *Route) Name(name string) *Route

Name sets the name of the route. This method will update the registration of the route in the router as well.

func (*Route) Options

func (r *Route) Options(handlers ...Handler) *Route

Options adds the route to the router using the OPTIONS HTTP method.

func (*Route) Patch

func (r *Route) Patch(handlers ...Handler) *Route

Patch adds the route to the router using the PATCH HTTP method.

func (*Route) Path

func (r *Route) Path() string

Path returns the request path that this route should match.

func (*Route) Post

func (r *Route) Post(handlers ...Handler) *Route

Post adds the route to the router using the POST HTTP method.

func (*Route) Put

func (r *Route) Put(handlers ...Handler) *Route

Put adds the route to the router using the PUT HTTP method.

func (*Route) String

func (r *Route) String() string

String returns the string representation of the route.

func (*Route) Tag

func (r *Route) Tag(value interface{}) *Route

Tag associates some custom data with the route.

func (*Route) Tags

func (r *Route) Tags() []interface{}

Tags returns all custom data associated with the route.

func (*Route) To

func (r *Route) To(methods string, handlers ...Handler) *Route

To adds the route to the router with the given HTTP methods and handlers. Multiple HTTP methods should be separated by commas (without any surrounding spaces).

func (*Route) Trace

func (r *Route) Trace(handlers ...Handler) *Route

Trace adds the route to the router using the TRACE HTTP method.

func (*Route) URL

func (r *Route) URL(pairs ...interface{}) (s string)

URL creates a URL using the current route and the given parameters. The parameters should be given in the sequence of name1, value1, name2, value2, and so on. If a parameter in the route is not provided a value, the parameter token will remain in the resulting URL. The method will perform URL encoding for all given parameter values.

type RouteGroup

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

RouteGroup represents a group of routes that share the same path prefix.

func (*RouteGroup) Any

func (rg *RouteGroup) Any(path string, handlers ...Handler) *Route

Any adds a route with the given route, handlers, and the HTTP methods as listed in routing.Methods.

func (*RouteGroup) AppendAnteriorHandler

func (rg *RouteGroup) AppendAnteriorHandler(handlers ...Handler)

func (*RouteGroup) AppendPosteriorHandler

func (rg *RouteGroup) AppendPosteriorHandler(handlers ...Handler)

func (*RouteGroup) AppendShutdownHandler

func (rg *RouteGroup) AppendShutdownHandler(handlers ...Handler)

func (*RouteGroup) AppendStartupHandler

func (rg *RouteGroup) AppendStartupHandler(handlers ...Handler)

Startup registers one or multiple handlers to the current route group. These handlers will be shared by all routes belong to this group and its subgroups.

func (*RouteGroup) Connect

func (rg *RouteGroup) Connect(path string, handlers ...Handler) *Route

Connect adds a CONNECT route to the router with the given route path and handlers.

func (*RouteGroup) Delete

func (rg *RouteGroup) Delete(path string, handlers ...Handler) *Route

Delete adds a DELETE route to the router with the given route path and handlers.

func (*RouteGroup) Get

func (rg *RouteGroup) Get(path string, handlers ...Handler) *Route

Get adds a GET route to the router with the given route path and handlers.

func (*RouteGroup) GetAnteriorHandlers

func (rg *RouteGroup) GetAnteriorHandlers() []Handler

func (*RouteGroup) GetPosteriorHandlers

func (rg *RouteGroup) GetPosteriorHandlers() []Handler

func (*RouteGroup) GetShutdownHandlers

func (rg *RouteGroup) GetShutdownHandlers() []Handler

func (*RouteGroup) GetStartupHandlers

func (rg *RouteGroup) GetStartupHandlers() []Handler

func (*RouteGroup) Group

func (rg *RouteGroup) Group(prefix string, handlers ...Handler) *RouteGroup

Group creates a RouteGroup with the given route path prefix and handlers. The new group will combine the existing path prefix with the new one. If no handler is provided, the new group will inherit the handlers registered with the current group.

func (*RouteGroup) Head

func (rg *RouteGroup) Head(path string, handlers ...Handler) *Route

Head adds a HEAD route to the router with the given route path and handlers.

func (*RouteGroup) Options

func (rg *RouteGroup) Options(path string, handlers ...Handler) *Route

Options adds an OPTIONS route to the router with the given route path and handlers.

func (*RouteGroup) Patch

func (rg *RouteGroup) Patch(path string, handlers ...Handler) *Route

Patch adds a PATCH route to the router with the given route path and handlers.

func (*RouteGroup) Post

func (rg *RouteGroup) Post(path string, handlers ...Handler) *Route

Post adds a POST route to the router with the given route path and handlers.

func (*RouteGroup) Put

func (rg *RouteGroup) Put(path string, handlers ...Handler) *Route

Put adds a PUT route to the router with the given route path and handlers.

func (*RouteGroup) To

func (rg *RouteGroup) To(methods, path string, handlers ...Handler) *Route

To adds a route to the router with the given HTTP methods, route path, and handlers. Multiple HTTP methods should be separated by commas (without any surrounding spaces).

func (*RouteGroup) Trace

func (rg *RouteGroup) Trace(path string, handlers ...Handler) *Route

Trace adds a TRACE route to the router with the given route path and handlers.

func (*RouteGroup) Use

func (rg *RouteGroup) Use(handlers ...Handler)

Use registers one or multiple handlers to the current route group. These handlers will be shared by all routes belong to this group and its subgroups.

type Router

type Router struct {
	RouteGroup
	IgnoreTrailingSlash bool // whether to ignore trailing slashes in the end of the request URL
	UseEscapedPath      bool // whether to use encoded URL instead of decoded URL to match routes
	// contains filtered or unexported fields
}

Router manages routes and dispatches HTTP requests to the handlers of the matching routes.

func New

func New() *Router

New creates a new Router object.

func (*Router) AppendAnteriorHandler

func (r *Router) AppendAnteriorHandler(handlers ...Handler) *Router

func (*Router) AppendPosteriorHandler

func (r *Router) AppendPosteriorHandler(handlers ...Handler) *Router

func (*Router) AppendShutdownHandler

func (r *Router) AppendShutdownHandler(handlers ...Handler) *Router

Shutdown appends the specified handlers to the router and shares them with all routes.

func (*Router) AppendStartupHandler

func (r *Router) AppendStartupHandler(handlers ...Handler) *Router

Startup prepends the specified handlers to the router and shares them with all routes.

func (*Router) Find

func (r *Router) Find(method, path string) (handlers []Handler, params map[string]string)

Find determines the handlers and parameters to use for a specified method and path.

func (*Router) NotFound

func (r *Router) NotFound(handlers ...Handler) *Router

NotFound specifies the handlers that should be invoked when the router cannot find any route matching a request. Note that the handlers registered via Use will be invoked first in this case.

func (*Router) Route

func (r *Router) Route(name string) *Route

Route returns the named route. Nil is returned if the named route cannot be found.

func (*Router) Routes

func (r *Router) Routes() []*Route

Routes returns all routes managed by the router.

func (*Router) ServeHTTP

func (r *Router) ServeHTTP(res http.ResponseWriter, req *http.Request)

ServeHTTP handles the HTTP request. It is required by http.Handler

func (*Router) Use

func (r *Router) Use(handlers ...Handler)

Use appends the specified handlers to the router and shares them with all routes.

type XMLDataReader

type XMLDataReader struct{}

XMLDataReader reads the request body as XML-formatted data.

func (*XMLDataReader) Read

func (r *XMLDataReader) Read(req *http.Request, data interface{}) error

Directories

Path Synopsis
Package access provides an access logging handler for the ozzo routing package.
Package access provides an access logging handler for the ozzo routing package.
Package auth provides a set of user authentication handlers for the ozzo routing package.
Package auth provides a set of user authentication handlers for the ozzo routing package.
Package content provides content negotiation handlers for the ozzo routing package.
Package content provides content negotiation handlers for the ozzo routing package.
Package cors provides a handler for handling CORS.
Package cors provides a handler for handling CORS.
Package fault provides a panic and error handler for the ozzo routing package.
Package fault provides a panic and error handler for the ozzo routing package.
Package file provides handlers that serve static files for the ozzo routing package.
Package file provides handlers that serve static files for the ozzo routing package.
Package access provides an access logging handler for the ozzo routing package.
Package access provides an access logging handler for the ozzo routing package.
Package slash provides a trailing slash remover handler for the ozzo routing package.
Package slash provides a trailing slash remover handler for the ozzo routing package.

Jump to

Keyboard shortcuts

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