routes

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Jun 25, 2019 License: Apache-2.0 Imports: 16 Imported by: 22

Documentation

Index

Constants

View Source
const (

	// TagRequiredQueryArg is the tag used to document required query args.
	TagRequiredQueryArg = "required:allof:queryarg"
	// TagOptionalQueryArg is the tag used to document optional query args.
	TagOptionalQueryArg = "optional:allof:queryarg"
)
View Source
const (
	ErrUnsupportedContentType = constError("bad content type")
	ErrMultipleContentTypes   = constError("multiple content types")
	ErrMissingContentType     = constError("missing content type")
	TagRequiredContentType    = "required:contenttype"
)
View Source
const (
	ErrMethodNotAllowed = constError("Method is not allowed.")
)

Variables

View Source
var (
	// AwsAccountIdsOptionalQueryArg allows to get the DB ids for AWS Accounts
	// in the URL parameters with routes.RequiredQueryArgs. These IDs will be a
	// slice of Uint stored in the routes.Arguments map with itself for key.
	// AwsAccountIdsOptionalQueryArg is optional and will not panic if no query
	// argument is found.
	AwsAccountIdsOptionalQueryArg = QueryArg{
		Name:        "account-ids",
		Type:        QueryArgIntSlice{},
		Description: "Comma separated DB IDs for many AWS account.",
		Optional:    true,
	}

	// AwsAccountIdQueryArg allows to get the DB id for an AWS Account in the URL Parameters
	// with routes.RequiredQueryArgs. This AWS Account ID will be an Uint stored
	// in the routes.Arguments map with itself for key.
	AwsAccountIdQueryArg = QueryArg{
		Name:        "account-id",
		Type:        QueryArgInt{},
		Description: "The DB ID for an AWS account.",
	}

	// AwsAccountsOptionalQueryArg allows to get the AWS Accounts in the URL
	// Parameters with routes.RequiredQueryArgs. This AWS Accounts will be a
	// slice of String stored in the routes.Arguments map with itself for key.
	// AwsAccountsOptionalQueryArg is optional and will not panic if no query
	// argument is found.
	AwsAccountsOptionalQueryArg = QueryArg{
		Name:        "accounts",
		Type:        QueryArgStringSlice{},
		Description: "Comma separated AWS account IDs.",
		Optional:    true,
	}

	// AwsAccountQueryArg allows to get the AWS Account in the URL Parameters
	// with routes.RequiredQueryArgs. This AWS Account will be a String stored
	// in the routes.Arguments map with itself for key.
	AwsAccountQueryArg = QueryArg{
		Name:        "account",
		Type:        QueryArgString{},
		Description: "AWS account ID.",
	}

	// BillPositoryQueryArg allows to get the bill repository ID in the URL Parameters
	// with routes.RequiredQueryArgs. This bill repository ID will be an int stored
	// in the routes.Arguments map with itself for key.
	BillPositoryQueryArg = QueryArg{
		Name:        "br",
		Type:        QueryArgInt{},
		Description: "The ID for a bill repository.",
	}

	// DateQueryArg allows to get the iso8601 date in the URL
	// Parameters with routes.QueryArgs. This date will be a
	// time.Time stored in the routes.Arguments map with itself for key.
	DateQueryArg = QueryArg{
		Name:        "date",
		Type:        QueryArgDate{},
		Description: "Date with year, month and day. Format is ISO8601",
		Optional:    false,
	}

	// DateBeginQueryArg allows to get the iso8601 begin date in the URL
	// Parameters with routes.QueryArgs. This date will be a
	// time.Time stored in the routes.Arguments map with itself for key.
	DateBeginQueryArg = QueryArg{
		Name:        "begin",
		Type:        QueryArgDate{},
		Description: "Begining of date interval. Format is ISO8601",
		Optional:    false,
	}

	// DateEndQueryArg allows to get the iso8601 begin date in the URL
	// Parameters with routes.QueryArgs. This date will be a
	// time.Time stored in the routes.Arguments map with itself for key.
	DateEndQueryArg = QueryArg{
		Name:        "end",
		Type:        QueryArgDate{},
		Description: "End of date interval. Format is ISO8601",
		Optional:    false,
	}

	// ReportTypeQueryArg allows to get the report type in the URL
	// Parameters with routes.QueryArgs. This type will be a
	// string stored in the routes.Arguments map with itself for key.
	ReportTypeQueryArg = QueryArg{
		Name:        "report-type",
		Type:        QueryArgString{},
		Description: "The report type",
		Optional:    false,
	}

	// FileNameQueryArg allows to a file name in the URL
	// Parameters with routes.QueryArgs. This type will be a
	// string stored in the routes.Arguments map with itself for key.
	FileNameQueryArg = QueryArg{
		Name:        "file-name",
		Type:        QueryArgString{},
		Description: "The file type",
		Optional:    false,
	}

	// ShareIdQueryArg allows to get the DB id for an Shared access in the URL Parameters
	// with routes.QueryArgs. This Shared ID will be an Uint stored
	// in the routes.Arguments map with itself for key.
	ShareIdQueryArg = QueryArg{
		Name:        "share-id",
		Type:        QueryArgInt{},
		Description: "The DB ID of the sharing",
	}
)
View Source
var RegisteredHandlers = make([]RegisteredHandler, 0, 0x40)

RegisteredHandlers is the list of all route handlers that were registered. Modules providing route handlers are expected to run Register in order to populate that list, and the main package is expected to use this list to populate its HTTP server.

Functions

func GetRequestBody

func GetRequestBody(a Arguments, ptr interface{}) error

func MustRequestBody

func MustRequestBody(a Arguments, ptr interface{})

Types

type Arguments

type Arguments map[interface{}]interface{}

Arguments is a map used by decorators to supply the route handler (or later decorators) with additional values.

type BackendId

type BackendId struct {
	BackendId string
}

BackendId is a decorator which adds a backend ID to incoming requests. It adds it to the response in the `X-Backend-ID` HTTP header. It is useful in correlating requests with logs.

func (BackendId) Decorate

func (d BackendId) Decorate(h Handler) Handler

type Cors

type Cors struct {
	AllowOrigin      []string
	AllowHeaders     []string
	AllowCredentials bool
}

Cors is a decorator which adds support for CORS to the handler. The Headers, Origin and Credentials are configured with the structure, while the Methods are determined from the handler.

func (Cors) Decorate

func (c Cors) Decorate(h Handler) Handler

type Decorator

type Decorator interface {
	Decorate(Handler) Handler
}

Decorator is an interface for any type that can decorate an IntermediateHandler.

type Documentation

type Documentation HandlerDocumentationBody

Documentation decorates a handler to document it. Summary, Description and Tags will be set on the documentation if not zero.

func (Documentation) Decorate

func (d Documentation) Decorate(h Handler) Handler

type ErrorBody

type ErrorBody struct{}

ErrorBody is a decorator for an HTTP handler. If that handler returns an error, it will wrap it in a structure so that it can correctly be returned to the user as JSON.

func (ErrorBody) Decorate

func (d ErrorBody) Decorate(h Handler) Handler

type Handler

type Handler struct {
	Func          HandlerFunc
	Documentation HandlerDocumentation
	// contains filtered or unexported fields
}

func DocumentationHandler

func DocumentationHandler() Handler

DocumentationHandler returns a Handler which responds to http.MehodGet requests with a JSON representation of all registered routes.

func H

H builds a Handler from a SimpleHandler. The produced handler has an empty documentation.

func (Handler) Register

func (h Handler) Register(pattern string) Handler

func (Handler) ServeHTTP

func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

BUG(zanchi-r): We do not support content type negociation Only a single type without quality factor should be specified in the Accept header Example : "Accept: text/csv" If an unsupported type is specified an empty body will be returned

func (Handler) With

func (h Handler) With(ds ...Decorator) Handler

type HandlerDocumentation

type HandlerDocumentation struct {
	HandlerDocumentationBody
	Components map[string]HandlerDocumentation `json:"components,omitempty"`
}

HandlerDocumentation represent a handler's documentation. It can have a tree of component subdocumentations.

type HandlerDocumentationBody

type HandlerDocumentationBody struct {
	Summary     string `json:"summary"`
	Description string `json:"description,omitempty"`
	Tags        Tags   `json:"tags,omitempty"`
}

HandlerDocumentationBody represents the values forming the body of a documentation component.

type HandlerFunc

type HandlerFunc func(http.ResponseWriter, *http.Request, Arguments) (int, interface{})

type MethodMuxer

type MethodMuxer map[string]Handler

MethodMuxer multiplexes requests based on their method. If a request arrives with a method not in the map, MethodMuxer responds with http.StatusMethodNotAllowed.

func (MethodMuxer) H

func (mm MethodMuxer) H() Handler

H builds a handler from the MethodMuxer. If the MethodMuxer has only one element, the summary of the single handler's documentation will be copied over to the MethodMuxer's.

type PanicAsError

type PanicAsError struct{}

PanicAsError decorates handlers to recover from panics: it uses the panic's payload and wraps it into an error. It also logs the panic.

func (PanicAsError) Decorate

func (d PanicAsError) Decorate(h Handler) Handler

type QueryArg

type QueryArg struct {
	Name        string
	Description string
	Type        QueryParser
	Optional    bool
}

QueryArg defines an argument by its name and its type. A description can be used for documentation purposes. The argument can be optional by changing the Optional value to true.

type QueryArgBool

type QueryArgBool struct{}

QueryArgBool denotes an int query argument. It fulfills the QueryParser interface.

func (QueryArgBool) FormatName

func (d QueryArgBool) FormatName() string

func (QueryArgBool) QueryParse

func (QueryArgBool) QueryParse(val string) (interface{}, error)

QueryParse parses an int. A nil error indicates a success. With this func, QueryArgBool fulfills QueryArgType.

type QueryArgDate

type QueryArgDate struct{}

QueryArgDate denotes a time.Time query argument. The time format is the ISO8601. It fulfills the QueryParser interface.

func (QueryArgDate) FormatName

func (d QueryArgDate) FormatName() string

func (QueryArgDate) QueryParse

func (QueryArgDate) QueryParse(val string) (interface{}, error)

QueryParse parses a time.Time in the ISO8601 format. With this func, QueryArgDate fulfills QueryArgType.

type QueryArgInt

type QueryArgInt struct{}

QueryArgInt denotes an int query argument. It fulfills the QueryParser interface.

func (QueryArgInt) FormatName

func (d QueryArgInt) FormatName() string

func (QueryArgInt) QueryParse

func (QueryArgInt) QueryParse(val string) (interface{}, error)

QueryParse parses an int. A nil error indicates a success. With this func, QueryArgInt fulfills QueryArgType.

type QueryArgIntSlice

type QueryArgIntSlice struct{}

QueryArgIntSlice denotes a []int query argument. It fulfills the QueryParser interface.

func (QueryArgIntSlice) FormatName

func (d QueryArgIntSlice) FormatName() string

func (QueryArgIntSlice) QueryParse

func (QueryArgIntSlice) QueryParse(val string) (interface{}, error)

QueryParse parses an []int. A nil error indicates a success. With this func, QueryArgIntSlice fulfills QueryArgType.

type QueryArgString

type QueryArgString struct{}

QueryArgString denotes a string query argument. It fulfills the QueryParser interface.

func (QueryArgString) FormatName

func (d QueryArgString) FormatName() string

func (QueryArgString) QueryParse

func (QueryArgString) QueryParse(val string) (interface{}, error)

QueryParse parses a string. A nil error indicates a success. With this func, QueryArgString fulfills QueryArgType.

type QueryArgStringSlice

type QueryArgStringSlice struct{}

QueryArgStringSlice denotes a []string query argument. It fulfills the QueryParser interface.

func (QueryArgStringSlice) FormatName

func (d QueryArgStringSlice) FormatName() string

func (QueryArgStringSlice) QueryParse

func (QueryArgStringSlice) QueryParse(val string) (interface{}, error)

QueryParse parses a []string. Since it does not do any type conversion, it cannot fail. With this func, QueryArgStringSlice fulfills QueryArgType.

type QueryArgUint

type QueryArgUint struct{}

QueryArgUint denotes a uint query argument. It fulfills the QueryParser interface.

func (QueryArgUint) FormatName

func (d QueryArgUint) FormatName() string

func (QueryArgUint) QueryParse

func (QueryArgUint) QueryParse(val string) (interface{}, error)

QueryParse parses a uint. A nil error indicates a success. With this func, QueryArgUint fulfills QueryArgType.

type QueryArgUintSlice

type QueryArgUintSlice struct{}

QueryArgUintSlice denotes a []uint query argument. It fulfills the QueryParser interface.

func (QueryArgUintSlice) FormatName

func (d QueryArgUintSlice) FormatName() string

func (QueryArgUintSlice) QueryParse

func (QueryArgUintSlice) QueryParse(val string) (interface{}, error)

QueryParse parses an []uint. A nil error indicates a success. With this func, QueryArgUintSlice fulfills QueryArgType.

type QueryArgs

type QueryArgs []QueryArg

QueryArgs contains all the arguments to parse in the URL. QueryArgs has a method Decorate called to apply the decorators on an endpoint.

func (QueryArgs) Decorate

func (qa QueryArgs) Decorate(h Handler) Handler

Decorate is the function called to apply the decorators to an endpoint. It returns a function. This function produces a 400 error code with a json error message or calls the next IntermediateHandler. The goal of this function is to get the URL parameters to store them in the Arguments.

type QueryParser

type QueryParser interface {
	// QueryParse parses a query string argument.
	QueryParse(string) (interface{}, error)
	// FormatName returns the name of the parameter type.
	FormatName() string
}

QueryParser parses a string and returns a typed value. An error can be returned if the value could not be parsed.

type RegisteredHandler

type RegisteredHandler struct {
	Pattern string
	Handler
}

RegisteredHandler is a registered handler with the pattern it will serve.

type RequestBody

type RequestBody struct {
	Example interface{}
}

func (RequestBody) Decorate

func (rb RequestBody) Decorate(h Handler) Handler

type RequestContentType

type RequestContentType []string

RequestContentType decorates handlers and requires requests to be of a given content type. Requests with a content type not in the RequestContentType list will be rejected with a http.StatusBadRequest.

func (RequestContentType) Decorate

func (rct RequestContentType) Decorate(h Handler) Handler

type RequestId

type RequestId struct{}

RequestId is a decorator which adds a request ID to incoming requests. It stores it in the request context, sets the logger up to log it, and adds it to the response in the `X-Request-ID` HTTP header.

func (RequestId) Decorate

func (ri RequestId) Decorate(h Handler) Handler

type RouteLog

type RouteLog struct{}

RouteLog is a decorator which logs any calls to the route, with some data about the request.

func (RouteLog) Decorate

func (rl RouteLog) Decorate(h Handler) Handler

type SimpleHandler

type SimpleHandler func(*http.Request, Arguments) (int, interface{})

Handler is the type a route Handler must have.

type Tags

type Tags map[string][]string

Tags is a map of tags on a documentation.

Notes

Bugs

  • We do not support content type negociation Only a single type without quality factor should be specified in the Accept header Example : "Accept: text/csv" If an unsupported type is specified an empty body will be returned

Jump to

Keyboard shortcuts

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