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 

func H(h SimpleHandler) Handler

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

Source Files

View all Source files

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.