neo

package module
v0.0.0-...-447c481 Latest Latest
Warning

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

 Go to latest Published: Mar 3, 2025 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package routing provides high performance and powerful HTTP routing capabilities.

Example 
package main

import (
	"log"
	"net/http"

	"github.com/caeret/neo"
	"github.com/caeret/neo/access"
	"github.com/caeret/neo/content"
	"github.com/caeret/neo/fault"
	"github.com/caeret/neo/file"
	"github.com/caeret/neo/slash"
)

func main() {
	router := neo.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 *neo.Context) error {
		return c.Write("user list")
	})
	api.Post("/users", func(c *neo.Context) error {
		return c.Write("create a new user")
	})
	api.Put(`/users/<id:\d+>`, func(c *neo.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)
}

Index

Examples

Constants

View Source 
const (
	MIMEApplicationJSON                  = "application/json"
	MIMEApplicationJSONCharsetUTF8       = MIMEApplicationJSON + "; " + charsetUTF8
	MIMEApplicationJavaScript            = "application/javascript"
	MIMEApplicationJavaScriptCharsetUTF8 = MIMEApplicationJavaScript + "; " + charsetUTF8
	MIMEApplicationXML                   = "application/xml"
	MIMEApplicationXMLCharsetUTF8        = MIMEApplicationXML + "; " + charsetUTF8
	MIMETextXML                          = "text/xml"
	MIMETextXMLCharsetUTF8               = MIMETextXML + "; " + charsetUTF8
	MIMEApplicationForm                  = "application/x-www-form-urlencoded"
	MIMEApplicationProtobuf              = "application/protobuf"
	MIMEApplicationMsgpack               = "application/msgpack"
	MIMETextHTML                         = "text/html"
	MIMETextHTMLCharsetUTF8              = MIMETextHTML + "; " + charsetUTF8
	MIMETextPlain                        = "text/plain"
	MIMETextPlainCharsetUTF8             = MIMETextPlain + "; " + charsetUTF8
	MIMEMultipartForm                    = "multipart/form-data"
	MIMEOctetStream                      = "application/octet-stream"
)

MIME types

View Source 
const (
	HeaderAccept         = "Accept"
	HeaderAcceptEncoding = "Accept-Encoding"
	// HeaderAllow is the name of the "Allow" header field used to list the set of methods
	// advertised as supported by the target resource. Returning an Allow header is mandatory
	// for status 405 (method not found) and useful for the OPTIONS method in responses.
	// See RFC 7231: https://datatracker.ietf.org/doc/html/rfc7231#section-7.4.1
	HeaderAllow               = "Allow"
	HeaderAuthorization       = "Authorization"
	HeaderContentDisposition  = "Content-Disposition"
	HeaderContentEncoding     = "Content-Encoding"
	HeaderContentLength       = "Content-Length"
	HeaderContentType         = "Content-Type"
	HeaderCookie              = "Cookie"
	HeaderSetCookie           = "Set-Cookie"
	HeaderIfModifiedSince     = "If-Modified-Since"
	HeaderLastModified        = "Last-Modified"
	HeaderLocation            = "Location"
	HeaderRetryAfter          = "Retry-After"
	HeaderUpgrade             = "Upgrade"
	HeaderVary                = "Vary"
	HeaderWWWAuthenticate     = "WWW-Authenticate"
	HeaderXForwardedFor       = "X-Forwarded-For"
	HeaderXForwardedProto     = "X-Forwarded-Proto"
	HeaderXForwardedProtocol  = "X-Forwarded-Protocol"
	HeaderXForwardedSsl       = "X-Forwarded-Ssl"
	HeaderXUrlScheme          = "X-Url-Scheme"
	HeaderXHTTPMethodOverride = "X-HTTP-Method-Override"
	HeaderXRealIP             = "X-Real-Ip"
	HeaderXRequestID          = "X-Request-Id"
	HeaderXCorrelationID      = "X-Correlation-Id"
	HeaderXRequestedWith      = "X-Requested-With"
	HeaderServer              = "Server"
	HeaderOrigin              = "Origin"
	HeaderCacheControl        = "Cache-Control"
	HeaderConnection          = "Connection"

	// Access control
	HeaderAccessControlRequestMethod    = "Access-Control-Request-Method"
	HeaderAccessControlRequestHeaders   = "Access-Control-Request-Headers"
	HeaderAccessControlAllowOrigin      = "Access-Control-Allow-Origin"
	HeaderAccessControlAllowMethods     = "Access-Control-Allow-Methods"
	HeaderAccessControlAllowHeaders     = "Access-Control-Allow-Headers"
	HeaderAccessControlAllowCredentials = "Access-Control-Allow-Credentials"
	HeaderAccessControlExposeHeaders    = "Access-Control-Expose-Headers"
	HeaderAccessControlMaxAge           = "Access-Control-Max-Age"

	// Security
	HeaderStrictTransportSecurity         = "Strict-Transport-Security"
	HeaderXContentTypeOptions             = "X-Content-Type-Options"
	HeaderXXSSProtection                  = "X-XSS-Protection"
	HeaderXFrameOptions                   = "X-Frame-Options"
	HeaderContentSecurityPolicy           = "Content-Security-Policy"
	HeaderContentSecurityPolicyReportOnly = "Content-Security-Policy-Report-Only"
	HeaderXCSRFToken                      = "X-CSRF-Token"
	HeaderReferrerPolicy                  = "Referrer-Policy"
)

Headers

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 GracefulShutdown 

func GracefulShutdown(hs *http.Server, timeout time.Duration, logFunc func(format string, args ...interface{}))

GracefulShutdown shuts down the given HTTP server gracefully when receiving an os.Interrupt or syscall.SIGTERM signal. It will wait for the specified timeout to stop hanging HTTP handlers.

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(*Context) error

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

func Read 

func Read[T any](c *Context) (T, error)

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 {
	Request  *http.Request       // the current request
	Response 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) Context 

func (c *Context) Context() context.Context

Context returns the request context.

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

func (c *Context) Next() 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) Params 

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

Params returns the named parameter values that are found in the URL path matching the current route. If the named parameter cannot be found, an empty string will be returned.

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

func (c *Context) RealIP() string

RealIP returns the real client ip.

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

func (c *Context) WriteWithStatus(data interface{}, statusCode int) error

WriteWithStatus sends the HTTP status code and writes the given data of arbitrary type to the response. See Write() for details on how data is written to response.

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{}) 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 mat.Handler.

func HTTPHandlerFunc 

func HTTPHandlerFunc(h http.HandlerFunc) Handler

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

type IPExtractor 

type IPExtractor func(*http.Request) string

IPExtractor is a function to extract IP addr from http.Request. Set appropriate one to Echo#IPExtractor. See https://echo.labstack.com/guide/ip-address for more details.

func ExtractIPDirect 

func ExtractIPDirect() IPExtractor

ExtractIPDirect extracts IP address using actual IP address. Use this if your server faces to internet directory (i.e.: uses no proxy).

func ExtractIPFromRealIPHeader 

func ExtractIPFromRealIPHeader(options ...TrustOption) IPExtractor

ExtractIPFromRealIPHeader extracts IP address using x-real-ip header. Use this if you put proxy which uses this header.

func ExtractIPFromXFFHeader 

func ExtractIPFromXFFHeader(options ...TrustOption) IPExtractor

ExtractIPFromXFFHeader extracts IP address using x-forwarded-for header. Use this if you put proxy which uses this header. This returns nearest untrustable IP. If all IPs are trustable, returns furthest one (i.e.: XFF[0]).

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

func (r *Route) Handler() string

Handler returns the last handler name that this route is associated with.

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 mat.Methods.

func (*RouteGroup) CatchAll 

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

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

func (rg *RouteGroup) Provide(fn func(*RouteGroup)) *RouteGroup

Provide adds routes to the group by provided func

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.

func (*RouteGroup) With 

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

With creates a RouteGroup with an empty route path prefix and handlers. The new group will combine the existing path prefix with the new one. The new group will inherit the handlers registered with the current group and provided handlers.

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

	IPExtractor IPExtractor
	// 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) 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) FindAllowedMethods 

func (r *Router) FindAllowedMethods(path string) map[string]bool

func (*Router) NotFound 

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

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 TrustOption 

type TrustOption func(*ipChecker)

TrustOption is config for which IP address to trust

func TrustIPRange 

func TrustIPRange(ipRange *net.IPNet) TrustOption

TrustIPRange add trustable IP ranges using CIDR notation.

func TrustLinkLocal 

func TrustLinkLocal(v bool) TrustOption

TrustLinkLocal configures if you trust link-local address (default: true).

func TrustLoopback 

func TrustLoopback(v bool) TrustOption

TrustLoopback configures if you trust loopback address (default: true).

func TrustPrivateNet 

func TrustPrivateNet(v bool) TrustOption

TrustPrivateNet configures if you trust private network address (default: true).

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

Source Files

View all Source files

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 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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.