router

Documentation

Index

• Constants
• Variables
• func Parse(path string) (Router, Router, error)
• func Split(path string) ([]string, error)
• type Container
• type Executor
• type Inspector
• type Middleware
• type RouteKind
• type Router
• type RoutingChain

Constants

const (
	// FullMatchTarget is a match for full regular expression. All regexp router without expression
	// will use the expression.
	FullMatchTarget = ".*"
	// TailMatchTarget is a match expression for tail only.
	TailMatchTarget = "*"
)

Variables

var ConflictInspectors = errors.Conflict.Build("Nirvana:Router:ConflictInspectors",
	"can't merge two routers that all have inspector")

ConflictInspectors can build errors for failure of merging routers. If attempts to merge two router and they all have inspector, an error should be returned. A merged router can't have two inspectors.

var EmptyRouterTarget = errors.UnprocessableEntity.Build("Nirvana:Router:EmptyRouterTarget",
	"router ${kind} has no target")

EmptyRouterTarget means a router node has an invalid empty target.

var InvalidParentRouter = errors.UnprocessableEntity.Build("Nirvana:Router:InvalidParentRouter",
	"router ${type} has no method to add children")

InvalidParentRouter means router node has no method to add child routers.

var InvalidPath = errors.UnprocessableEntity.Build("Nirvana:Router:InvalidPath",
	"invalid path")

InvalidPath means router path is invalid.

var InvalidPathKey = errors.UnprocessableEntity.Build("Nirvana:Router:InvalidPathKey",
	"key ${key} should be last element in the path")

InvalidPathKey means path key must be the last element.

var InvalidRegexp = errors.UnprocessableEntity.Build("Nirvana:Router:InvalidRegexp",
	"regexp ${regexp} does not have normative format")

InvalidRegexp means regexp is not notmative.

var NoCommonPrefix = errors.UnprocessableEntity.Build("Nirvana:Router:NoCommonPrefix",
	"there is no common prefix for the two routers")

NoCommonPrefix means two routers have no common prefix.

var NoExecutor = errors.NotFound.Build("Nirvana:Router:NoExecutor",
	"no executor to pack middlewares")

NoExecutor means can't pack middlewares for nil executor.

var NoInspector = errors.NotFound.Build("Nirvana:Router:NoInspector",
	"no inspector to generate executor")

NoInspector means there is no inspector in router.

var RouterNotFound = errors.NotFound.Build("Nirvana:Router:RouterNotFound",
	"can't find router")

RouterNotFound means there no router matches path.

var UnknownRouterType = errors.UnprocessableEntity.Build("Nirvana:Router:UnknownRouterType",
	"router ${kind} has unknown type ${type}")

UnknownRouterType means a node type is unprocessable.

var UnknownSegment = errors.UnprocessableEntity.Build("Nirvana:Router:UnknownSegment",
	"unknown segment ${value}")

UnknownSegment means can't recognize segment.

var UnmatchedPathBrace = errors.UnprocessableEntity.Build("Nirvana:Router:UnmatchedPathBrace",
	"unmatched braces")

UnmatchedPathBrace means path has unmatched brace.

var UnmatchedRouterKey = errors.UnprocessableEntity.Build("Nirvana:Router:UnmatchedRouterKey",
	"router key ${keyA} is not matched with ${keyB}")

UnmatchedRouterKey means a router's key is not matched with another.

var UnmatchedRouterRegexp = errors.UnprocessableEntity.Build("Nirvana:Router:UnmatchedRouterRegexp",
	"router regexp ${regexpA} is not matched with ${regexpA}")

UnmatchedRouterRegexp means a router's regexp is not matched with another.

var UnmatchedSegmentKeys = errors.UnprocessableEntity.Build("Nirvana:Router:UnmatchedSegmentKeys",
	"segment ${value} has unmatched keys")

UnmatchedSegmentKeys means segment has unmatched keys.

Functions

func Parse

func Parse(path string) (Router, Router, error)

Parse parses a path to a router tree. It returns the root router and the leaf router. you can add middlewares and executor to the routers. A valid path should like:

/segments/{segment}/resources/{resource}
/segments/{segment:[a-z]{1,2}}.log/paths/{path:*}

func Split

func Split(path string) ([]string, error)

Split splits string segments and regexp segments.

For instance:

/segments/{segment:[a-z]{1,2}}.log/paths/{path:*}

TO:

/segments/ {segment:[a-z]{1,2}} .log/paths/ {path:*}

Types

type Container

type Container interface {
	// Set sets key-value into the container.
	Set(key, value string)
	// Get gets a value by key from the container.
	Get(key string) (string, bool)
}

Container is a key-value container. It saves key-values from path.

type Executor

type Executor interface {
	// Execute executes with context.
	Execute(context.Context) error
}

Executor executs with a context.

type Inspector

type Inspector interface {
	// Inspect finds a valid executor to execute target context.
	// It returns an error if it can't find a valid executor.
	Inspect(context.Context) (Executor, error)
}

Inspector can select an executor to execute.

type Middleware

type Middleware func(context.Context, RoutingChain) error

Middleware describes the form of middlewares. If you want to carry on, call RoutingChain.Continue() and pass the context.

type RouteKind

type RouteKind string

RouteKind is kind of routers.

const (
	// String means the router has a fixed string.
	String RouteKind = "String"
	// Regexp means the router has a regular expression.
	Regexp RouteKind = "Regexp"
	// Path means the router matches the rest. Path router only can
	// be placed at the leaf node.
	Path RouteKind = "Path"
)

type Router

type Router interface {
	// Target returns the matching target of the node.
	// It can be a fixed string or a regular expression.
	Target() string
	// Kind returns the kind of the router node.
	Kind() RouteKind
	// Match find an executor matched by path.
	// The context contains information to inspect executor.
	// The container can save key-value pair from the path.
	// If the router is the leaf node to match the path, it will return
	// the first executor which Inspect() returns true.
	Match(ctx context.Context, c Container, path string) (Executor, error)
	// AddMiddleware adds middleware to the router node.
	// If the router matches a path, all middlewares in the router
	// will be executed by the returned executor.
	AddMiddleware(ms ...Middleware)
	// Middlewares returns all middlewares of the router.
	// Don't modify the returned values.
	Middlewares() []Middleware
	// SetInspector sets inspector to the router node.
	SetInspector(inspector Inspector)
	// Inspector gets inspector from the router node.
	// Don't modify the returned values.
	Inspector() Inspector
	// Merge merges r to the current router. The type of r should be same
	// as the current one or it panics.
	//
	// For instance:
	//  Router A: /namespaces/ -> {namespace}
	//  Router B: /nameless/ -> {other}
	// Result:
	//  /name -> spaces/ -> {namespace}
	//       |-> less/ -> {other}
	Merge(r Router) (Router, error)
}

Router describes the interface of a router node.

type RoutingChain

type RoutingChain interface {
	// Continue continues to execute the next middleware or executor.
	Continue(context.Context) error
}

RoutingChain contains the call chain of middlewares and executor.