router

Documentation

Overview

The router package implements an HTTP request router for charm store HTTP requests.

Index

• Variables
• func NotFoundHandler() http.Handler
• func RelativeURLPath(basePath, targPath string) (string, error)
• type BulkIncludeHandler
  • func FieldIncludeHandler(p FieldIncludeHandlerParams) BulkIncludeHandler
• type FieldGetFunc
• type FieldIncludeHandlerParams
• type FieldPutFunc
• type FieldQueryFunc
• type FieldUpdateFunc
• type FieldUpdater
  • func (u *FieldUpdater) UpdateField(fieldName string, val interface{})
• type Handlers
• type IdHandler
• type Router
  • func New(handlers *Handlers, resolveURL func(url *charm.Reference) error) *Router
  • func (r *Router) GetMetadata(id *charm.Reference, includes []string) (map[string]interface{}, error)
  • func (r *Router) Handlers() *Handlers
  • func (r *Router) PutMetadata(id *charm.Reference, data map[string]*json.RawMessage) error
  • func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type ServeMux
  • func NewServeMux() *ServeMux
  • func (mux *ServeMux) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type SingleIncludeHandler
  • func (h SingleIncludeHandler) HandleGet(hs []BulkIncludeHandler, id *charm.Reference, paths []string, flags url.Values) ([]interface{}, error)
  • func (h SingleIncludeHandler) HandlePut(hs []BulkIncludeHandler, id *charm.Reference, paths []string, ...) []error
  • func (h SingleIncludeHandler) Key() interface{}

Variables

var (
	HandleErrors = jsonhttp.HandleErrors(errToResp)
	HandleJSON   = jsonhttp.HandleJSON(errToResp)
	WriteError   = jsonhttp.WriteError(errToResp)
)

Functions

func NotFoundHandler

func NotFoundHandler() http.Handler

NotFoundHandler is like http.NotFoundHandler except it returns a JSON error response.

func RelativeURLPath

func RelativeURLPath(basePath, targPath string) (string, error)

RelativeURLPath returns a relative URL path that is lexically equivalent to targpath when interpreted by url.URL.ResolveReference. On succes, the returned path will always be relative to basePath, even if basePath and targPath share no elements. An error is returned if targPath can't be made relative to basePath (for example when either basePath or targetPath are non-absolute).

Types

type BulkIncludeHandler

type BulkIncludeHandler interface {
	// Key returns a value that will be used to group handlers
	// together in preparation for a call to HandleGet or HandlePut.
	// The key should be comparable for equality.
	// Please do not return NaN. That would be silly, OK?
	Key() interface{}

	// HandleGet returns the results of invoking all the given handlers
	// on the given charm or bundle id. Each result is held in
	// the respective element of the returned slice.
	//
	// All of the handlers' Keys will be equal to the receiving handler's
	// Key.
	//
	// Each item in paths holds the remaining metadata path
	// for the handler in the corresponding position
	// in hs after the prefix in Handlers.Meta has been stripped,
	// and flags holds all the URL query values.
	//
	// TODO(rog) document indexed errors.
	HandleGet(hs []BulkIncludeHandler, id *charm.Reference, paths []string, flags url.Values) ([]interface{}, error)

	// HandlePut invokes a PUT request on all the given handlers on
	// the given charm or bundle id. If there is an error, the
	// returned errors slice should contain one element for each element
	// in paths. The error for handler hs[i] should be returned in errors[i].
	// If there is no error, an empty slice should be returned.
	//
	// Each item in paths holds the remaining metadata path
	// for the handler in the corresponding position
	// in hs after the prefix in Handlers.Meta has been stripped,
	// and flags holds all the url query values.
	HandlePut(hs []BulkIncludeHandler, id *charm.Reference, paths []string, values []*json.RawMessage) []error
}

BulkIncludeHandler represents a metadata handler that can handle multiple metadata "include" requests in a single batch.

For simple metadata handlers that cannot be efficiently combined, see SingleIncludeHandler.

All handlers may assume that http.Request.ParseForm has been called to parse the URL form values.

func FieldIncludeHandler

func FieldIncludeHandler(p FieldIncludeHandlerParams) BulkIncludeHandler

FieldIncludeHandler returns a BulkIncludeHandler that will perform only a single database query for several requests. See FieldIncludeHandlerParams for more detail.

See in ../v4/api.go for an example of its use.

type FieldGetFunc

type FieldGetFunc func(doc interface{}, id *charm.Reference, path string, flags url.Values) (interface{}, error)

A FieldGetFunc returns some data from the given document. The document will have been returned from an earlier call to the associated QueryFunc.

type FieldIncludeHandlerParams

type FieldIncludeHandlerParams struct {
	// Key is used to group together similar FieldIncludeHandlers
	// (the same query should be generated for any given key).
	Key interface{}

	// Query is used to retrieve the document from the database for
	// GET requests. The fields passed to the query will be the
	// union of all fields found in all the handlers in the bulk
	// request.
	Query FieldQueryFunc

	// Fields specifies which fields are required by the given handler.
	Fields []string

	// Handle actually returns the data from the document retrieved
	// by Query, for GET requests.
	HandleGet FieldGetFunc

	// HandlePut generates update operations for a PUT
	// operation.
	HandlePut FieldPutFunc

	// Update is used to update the document in the database for
	// PUT requests.
	Update FieldUpdateFunc
}

FieldIncludeHandlerParams specifies the parameters for NewFieldIncludeHandler.

type FieldPutFunc

type FieldPutFunc func(id *charm.Reference, path string, val *json.RawMessage, updater *FieldUpdater) error

FieldPutFunc sets using the given FieldUpdater corresponding to fields to be set in the metadata document for the given id. The path holds the metadata path after the initial prefix has been removed.

type FieldQueryFunc

type FieldQueryFunc func(id *charm.Reference, selector map[string]int) (interface{}, error)

A FieldQueryFunc is used to retrieve a metadata document for the given URL, selecting only those fields specified in keys of the given selector.

type FieldUpdateFunc

type FieldUpdateFunc func(id *charm.Reference, fields map[string]interface{}) error

A FieldUpdateFunc is used to update a metadata document for the given id. For each field in fields, it should set that field to its corresponding value in the metadata document.

type FieldUpdater

type FieldUpdater struct {
	// contains filtered or unexported fields
}

FieldUpdater records field changes made by a FieldUpdateFunc.

func (*FieldUpdater) UpdateField

func (u *FieldUpdater) UpdateField(fieldName string, val interface{})

UpdateField requests that the provided field is updated with the given value.

type Handlers

type Handlers struct {
	// Global holds handlers for paths not matched by Meta or Id.
	// The map key is the path; the value is the handler that will
	// be used to handle that path.
	//
	// Path matching is by matched by longest-prefix - the same as
	// http.ServeMux.
	//
	// Note that, unlike http.ServeMux, the prefix is stripped
	// from the URL path before the hander is invoked,
	// matching the behaviour of the other handlers.
	Global map[string]http.Handler

	// Id holds handlers for paths which correspond to a single
	// charm or bundle id other than the meta path. The map key
	// holds the first element of the path, which may end in a
	// trailing slash (/) to indicate that longer paths are allowed
	// too.
	Id map[string]IdHandler

	// Meta holds metadata handlers for paths under the meta
	// endpoint. The map key holds the first element of the path,
	// which may end in a trailing slash (/) to indicate that longer
	// paths are allowed too.
	Meta map[string]BulkIncludeHandler
}

Handlers specifies how HTTP requests will be routed by the router. All errors returned by the handlers will be processed by WriteError with their Cause left intact. This means that, for example, if they return an error with a Cause that is params.ErrNotFound, the HTTP status code will reflect that (assuming the error has not been absorbed by the bulk metadata logic).

type IdHandler

type IdHandler func(charmId *charm.Reference, w http.ResponseWriter, req *http.Request) error

IdHandler handles a charm store request rooted at the given id. The request path (req.URL.Path) holds the URL path after the id has been stripped off.

type Router

type Router struct {
	// contains filtered or unexported fields
}

Router represents a charm store HTTP request router.

func New

func New(handlers *Handlers, resolveURL func(url *charm.Reference) error) *Router

New returns a charm store router that will route requests to the given handlers and retrieve metadata from the given database.

The resolveURL function will be called to resolve ids in router paths - it should fill in the Series and Revision fields of its argument URL if they are not specified. The Cause of the resolveURL error will be left unchanged, as for the handlers.

func (*Router) GetMetadata

func (r *Router) GetMetadata(id *charm.Reference, includes []string) (map[string]interface{}, error)

GetMetadata retrieves metadata for the given charm or bundle id, including information as specified by the includes slice.

func (*Router) Handlers

func (r *Router) Handlers() *Handlers

Handlers returns the set of handlers that the router was created with. This should not be changed.

func (*Router) PutMetadata

func (r *Router) PutMetadata(id *charm.Reference, data map[string]*json.RawMessage) error

PutMetadata puts metadata for the given id. Each key in data holds the name of a metadata endpoint; its associated value holds the value to be written.

func (*Router) ServeHTTP

func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP implements http.Handler.ServeHTTP.

type ServeMux

type ServeMux struct {
	*http.ServeMux
}

ServeMux is like http.ServeMux but returns JSON errors when pages are not found.

func NewServeMux

func NewServeMux() *ServeMux

func (*ServeMux) ServeHTTP

func (mux *ServeMux) ServeHTTP(w http.ResponseWriter, req *http.Request)

type SingleIncludeHandler

type SingleIncludeHandler func(id *charm.Reference, path string, flags url.Values) (interface{}, error)

SingleIncludeHandler implements BulkMetaHander for a non-batching metadata retrieval function that can perform a GET only.

func (SingleIncludeHandler) HandleGet

func (h SingleIncludeHandler) HandleGet(hs []BulkIncludeHandler, id *charm.Reference, paths []string, flags url.Values) ([]interface{}, error)

HandleGet implements BulkMetadataHander.HandleGet.

func (SingleIncludeHandler) HandlePut

func (h SingleIncludeHandler) HandlePut(hs []BulkIncludeHandler, id *charm.Reference, paths []string, values []*json.RawMessage) []error

HandlePut implements BulkMetadataHander.HandlePut.

func (SingleIncludeHandler) Key

func (h SingleIncludeHandler) Key() interface{}

Key implements BulkMetadataHander.Key.