routers

Documentation

Overview

Package routers provides the router interface and the implementation of different routing policies.

Index

• Variables
• func Register(k *Kind)
• type Header
• type Headers
  • func (hs Headers) Match(headers http.Header, matchAll bool) bool
  • func (hs Headers) Validate() error
• type Host
• type Kind
• type MethodType
• type Params
• type Path
  • func (p *Path) AllowIP(ip string) bool
  • func (p *Path) GetBackend() string
  • func (p *Path) GetClientMaxBodySize() int64
  • func (p *Path) GetExactPath() string
  • func (p *Path) GetPathPrefix() string
  • func (p *Path) GetPathRegexp() string
  • func (p *Path) Init(parentIPFilter *ipfilter.IPFilter)
  • func (p *Path) Match(context *RouteContext) bool
  • func (p *Path) Validate() error
• type Paths
• type Queries
  • func (qs Queries) Match(query url.Values, matchAll bool) bool
  • func (qs Queries) Validate() error
• type Query
• type Route
• type RouteContext
  • func NewContext(req *httpprot.Request) *RouteContext
  • func (ctx *RouteContext) GetCaptures() map[string]string
  • func (ctx *RouteContext) GetHeader() http.Header
  • func (ctx *RouteContext) GetHost() string
  • func (ctx *RouteContext) GetQueries() url.Values
• type Router
  • func Create(kind string, rules Rules) Router
• type Rule
  • func (rule *Rule) AllowIP(ip string) bool
  • func (rule *Rule) Init()
  • func (rule *Rule) MatchHost(ctx *RouteContext) bool
• type Rules
  • func (rules Rules) Init()

Variables

var (
	// MALL represents the methodType that can match all methods.
	MALL = mCONNECT | mDELETE | mGET | mHEAD |
		mOPTIONS | mPATCH | mPOST | mPUT | mTRACE

	// Methods represents the mapping of http method and methodType.
	Methods = map[string]MethodType{
		http.MethodGet:     mGET,
		http.MethodHead:    mHEAD,
		http.MethodPost:    mPOST,
		http.MethodPut:     mPUT,
		http.MethodPatch:   mPATCH,
		http.MethodDelete:  mDELETE,
		http.MethodConnect: mCONNECT,
		http.MethodOptions: mOPTIONS,
		http.MethodTrace:   mTRACE,
	}
)

Functions

func Register

func Register(k *Kind)

Register registers a router kind.

Types

type Header

type Header struct {
	Key    string   `json:"key" jsonschema:"required"`
	Values []string `json:"values,omitempty" jsonschema:"uniqueItems=true"`
	Regexp string   `json:"regexp,omitempty" jsonschema:"format=regexp"`
	// contains filtered or unexported fields
}

Header is the third level entry of router. A header entry is always under a specific path entry, that is to mean the headers entry will only be checked after a path entry matched. However, the headers entry has a higher priority than the path entry itself.

type Headers

type Headers []*Header

Headers represents the set of headers.

func (Headers) Match

func (hs Headers) Match(headers http.Header, matchAll bool) bool

Match is the matching function of Headers.

func (Headers) Validate

func (hs Headers) Validate() error

Validate validates Headers.

type Host

type Host struct {
	IsRegexp bool   `json:"isRegexp,omitempty"`
	Value    string `json:"value" jsonschema:"required"`
	// contains filtered or unexported fields
}

Host defines the host match rule.

type Kind

type Kind struct {
	// Name is the name of the router kind.
	Name string

	// Description is the description of the router.
	Description string

	// CreateInstance creates a new router instance of the kind.
	CreateInstance func(rules Rules) Router
}

Kind contains the meta data and functions of a router kind.

type MethodType

type MethodType uint

MethodType represents the bit-operated representation of the http method.

type Params

type Params struct {
	Keys, Values []string
}

Params are used to store the variables in the search path and their corresponding values.

type Path

type Path struct {
	IPFilterSpec      *ipfilter.Spec `json:"ipFilter,omitempty"`
	Path              string         `json:"path,omitempty" jsonschema:"pattern=^/"`
	PathPrefix        string         `json:"pathPrefix,omitempty" jsonschema:"pattern=^/"`
	PathRegexp        string         `json:"pathRegexp,omitempty" jsonschema:"format=regexp"`
	RewriteTarget     string         `json:"rewriteTarget,omitempty"`
	Methods           []string       `json:"methods,omitempty" jsonschema:"uniqueItems=true,format=httpmethod-array"`
	Backend           string         `json:"backend" jsonschema:"required"`
	ClientMaxBodySize int64          `json:"clientMaxBodySize,omitempty"`
	Headers           Headers        `json:"headers,omitempty"`
	Queries           Queries        `json:"queries,omitempty"`
	MatchAllHeader    bool           `json:"matchAllHeader,omitempty"`
	MatchAllQuery     bool           `json:"matchAllQuery,omitempty"`
	// contains filtered or unexported fields
}

Path is second level entry of router.

func (*Path) AllowIP

func (p *Path) AllowIP(ip string) bool

AllowIP return if rule ipFilter allows the incoming ip.

func (*Path) GetBackend

func (p *Path) GetBackend() string

GetBackend is used to get the backend corresponding to the route.

func (*Path) GetClientMaxBodySize

func (p *Path) GetClientMaxBodySize() int64

GetClientMaxBodySize is used to get the clientMaxBodySize corresponding to the route.

func (*Path) GetExactPath

func (p *Path) GetExactPath() string

GetExactPath returns the exact path of the route.

func (*Path) GetPathPrefix

func (p *Path) GetPathPrefix() string

GetPathPrefix returns the path prefix of the route.

func (*Path) GetPathRegexp

func (p *Path) GetPathRegexp() string

GetPathRegexp returns the path regexp of the route.

func (*Path) Init

func (p *Path) Init(parentIPFilter *ipfilter.IPFilter)

Init is the initialization portal for Path

func (*Path) Match

func (p *Path) Match(context *RouteContext) bool

Match is the matching function of path.

func (*Path) Validate

func (p *Path) Validate() error

Validate validates Path.

type Paths

type Paths []*Path

Paths represents the set of paths.

type Queries

type Queries []*Query

Queries represents the set of queries.

func (Queries) Match

func (qs Queries) Match(query url.Values, matchAll bool) bool

Match is the matching function of Queries.

func (Queries) Validate

func (qs Queries) Validate() error

Validate validates Queries.

type Query

type Query struct {
	Key    string   `json:"key" jsonschema:"required"`
	Values []string `json:"values,omitempty" jsonschema:"uniqueItems=true"`
	Regexp string   `json:"regexp,omitempty" jsonschema:"format=regexp"`
	// contains filtered or unexported fields
}

Query is the third level entry.

type Route

type Route interface {
	protocols.Route

	// Rewrite for path rewriting.
	Rewrite(context *RouteContext)
	// GetBackend is used to get the backend corresponding to the route.
	GetBackend() string
	// GetClientMaxBodySize is used to get the clientMaxBodySize corresponding to the route.
	GetClientMaxBodySize() int64

	// GetExactPath is used to get the exact path corresponding to the route.
	GetExactPath() string
	// GetPathPrefix is used to get the path prefix corresponding to the route.
	GetPathPrefix() string
	// GetPathRegexp is used to get the path regexp corresponding to the route.
	GetPathRegexp() string
}

Route is the corresponding route interface for different routing policies.

type RouteContext

type RouteContext struct {
	// Request is httpprot.Request.
	Request *httpprot.Request
	// Path represents the path of the request.
	Path string
	// Method represents the MethodType corresponding to the http method.
	Method MethodType

	// Params are used to store the variables in the search path and their corresponding values.
	Params Params

	// Cacheable means whether the route can be cached or not.
	Cacheable bool
	// Route represents the results of this search
	Route                                                     Route
	HeaderMismatch, MethodMismatch, QueryMismatch, IPMismatch bool
	// contains filtered or unexported fields
}

RouteContext is the context container in the route search

func NewContext

func NewContext(req *httpprot.Request) *RouteContext

NewContext creates a context instance.

func (*RouteContext) GetCaptures

func (ctx *RouteContext) GetCaptures() map[string]string

GetCaptures is used to get and cache path parameter mappings.

func (*RouteContext) GetHeader

func (ctx *RouteContext) GetHeader() http.Header

GetHeader is used to get request http header.

func (*RouteContext) GetHost

func (ctx *RouteContext) GetHost() string

GetHost is used to get and cache host.

func (*RouteContext) GetQueries

func (ctx *RouteContext) GetQueries() url.Values

GetQueries is used to get and cache query params.

type Router

type Router interface {
	// Search performs a route search and populates the context with search-related information.
	Search(context *RouteContext)
}

Router is the interface for route search.

func Create

func Create(kind string, rules Rules) Router

Create creates a router instance of kind.

type Rule

type Rule struct {
	// NOTICE: If the field is a pointer, it must have `omitempty` in tag `json`
	// when it has `omitempty` in tag `jsonschema`.
	// Otherwise it will output null value, which is invalid in json schema (the type is object).
	// the original reason is the jsonscheme(genjs) has not support multiple types.
	// Reference: https://github.com/alecthomas/jsonschema/issues/30
	// In the future if we have the scenario where we need marshal the field, but omitempty
	// in the schema, we are suppose to support multiple types on our own.
	IPFilterSpec *ipfilter.Spec `json:"ipFilter,omitempty"`
	Host         string         `json:"host,omitempty"`
	HostRegexp   string         `json:"hostRegexp,omitempty" jsonschema:"format=regexp"`
	Hosts        []Host         `json:"hosts,omitempty"`
	Paths        Paths          `json:"paths,omitempty"`
	// contains filtered or unexported fields
}

Rule is first level entry of router.

func (*Rule) AllowIP

func (rule *Rule) AllowIP(ip string) bool

AllowIP return if rule ipFilter allows the incoming ip.

func (*Rule) Init

func (rule *Rule) Init()

Init is the initialization portal for Rule.

func (*Rule) MatchHost

func (rule *Rule) MatchHost(ctx *RouteContext) bool

MatchHost matches the host of the request to the rule.

type Rules

type Rules []*Rule

Rules represents the set of rules.

func (Rules) Init

func (rules Rules) Init()

Init is the initialization portal for Rules.