v5

Documentation

Index

• Constants
• Variables
• func NewAPIHandler(pool *charmstore.Pool, config charmstore.ServerParams, rootPath string) charmstore.HTTPCloseHandler
• func ParseSearchParams(req *http.Request) (charmstore.SearchParams, error)
• func RouterHandlers(h *ReqHandler) *router.Handlers
• func StatsEnabled(req *http.Request) bool
• type EntityHandlerFunc
• type Handler
  • func New(pool *charmstore.Pool, config charmstore.ServerParams, rootPath string) *Handler
  • func (h *Handler) Close()
  • func (h *Handler) NewReqHandler() (*ReqHandler, error)
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type ReqHandler
  • func (h *ReqHandler) AuthIdHandler(f ResolvedIdHandler) ResolvedIdHandler
  • func (h *ReqHandler) AuthorizeEntity(id *router.ResolvedURL, req *http.Request) error
  • func (h *ReqHandler) AuthorizeEntityAndTerms(req *http.Request, entityIds []*router.ResolvedURL) (authorization, error)
  • func (h *ReqHandler) CheckRequest(req *http.Request, entityIds []*router.ResolvedURL, operation string) (authorization, error)
  • func (h *ReqHandler) Close()
  • func (h *ReqHandler) EntityHandler(f EntityHandlerFunc, fields ...string) router.BulkIncludeHandler
  • func (h *ReqHandler) GroupsForUser(username string) ([]string, error)
  • func (h *ReqHandler) Reset()
  • func (h *ReqHandler) ResolveURL(url *charm.URL) (*router.ResolvedURL, error)
  • func (h *ReqHandler) ResolveURLs(urls []*charm.URL) ([]*router.ResolvedURL, error)
  • func (h *ReqHandler) ResolvedIdHandler(f ResolvedIdHandler, cacheFields ...string) router.IdHandler
  • func (h *ReqHandler) Search(sp charmstore.SearchParams, req *http.Request) (interface{}, error)
  • func (h *ReqHandler) SendEntityArchive(id *router.ResolvedURL, w http.ResponseWriter, req *http.Request, ...)
  • func (h *ReqHandler) ServeBlobFile(w http.ResponseWriter, req *http.Request, id *router.ResolvedURL, ...) error
  • func (h *ReqHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (h *ReqHandler) WillIncludeMetadata(includes []string)
• type ResolvedIdHandler

Constants

const (
	PromulgatorsGroup = "charmers"

	// OpAccessCharmWithTerms indicates an operation of accessing the archive of
	// a charm that requires agreement to certain terms and conditions.
	OpAccessCharmWithTerms = "op-get-with-terms"

	// OpOther indicates all other operations.
	// This operation should not be added as part of a macaroon caveat.
	OpOther = "op-other"
)

const ArchiveCachePublicMaxAge = 1 * time.Hour

ArchiveCachePublicMaxAge specifies the cache expiry duration for items returned from the archive where the id represents the id of a public entity.

const DefaultIcon = defaultIcon

DefaultIcon holds the default charm icon SVG content.

const (
	DelegatableMacaroonExpiry = time.Minute
)

const UsernameAttr = "username"

Variables

var (
	RequiredEntityFields = charmstore.FieldSelector(
		"baseurl",
		"user",
		"name",
		"revision",
		"series",
		"promulgated-revision",
		"development",
		"promulgated-url",
	)
	RequiredBaseEntityFields = charmstore.FieldSelector(
		"user",
		"name",
		"acls",
		"public",
		"developmentacls",
		"promulgated",
	)
)

Functions

func NewAPIHandler

func NewAPIHandler(pool *charmstore.Pool, config charmstore.ServerParams, rootPath string) charmstore.HTTPCloseHandler

NewAPIHandler returns a new Handler as an http Handler. It is defined for the convenience of callers that require a charmstore.NewAPIHandlerFunc.

func ParseSearchParams

func ParseSearchParams(req *http.Request) (charmstore.SearchParams, error)

ParseSearchParms extracts the search paramaters from the request

func RouterHandlers

func RouterHandlers(h *ReqHandler) *router.Handlers

RouterHandlers returns router handlers that will route requests to the given ReqHandler. This is provided so that different API versions can override selected parts of the handlers to serve their own API while still using ReqHandler to serve the majority of the API.

func StatsEnabled

func StatsEnabled(req *http.Request) bool

StatsEnabled reports whether statistics should be gathered for the given HTTP request.

Types

type EntityHandlerFunc

type EntityHandlerFunc func(entity *mongodoc.Entity, id *router.ResolvedURL, path string, flags url.Values, req *http.Request) (interface{}, error)

type Handler

type Handler struct {
	// Pool holds the store pool that the handler was created
	// with.
	Pool *charmstore.Pool
	// contains filtered or unexported fields
}

func New

func New(pool *charmstore.Pool, config charmstore.ServerParams, rootPath string) *Handler

func (*Handler) Close

func (h *Handler) Close()

Close closes the Handler.

func (*Handler) NewReqHandler

func (h *Handler) NewReqHandler() (*ReqHandler, error)

NewReqHandler returns an instance of a *ReqHandler suitable for handling an HTTP request. After use, the ReqHandler.Close method should be called to close it.

If no handlers are available, it returns an error with a charmstore.ErrTooManySessions cause.

func (*Handler) ServeHTTP

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

ServeHTTP implements http.Handler by first retrieving a request-specific instance of ReqHandler and calling ServeHTTP on that.

type ReqHandler

type ReqHandler struct {
	// Router holds the router that the ReqHandler will use
	// to route HTTP requests. This is usually set by
	// Handler.NewReqHandler to the result of RouterHandlers.
	Router *router.Router

	// Handler holds the Handler that the ReqHandler
	// is derived from.
	Handler *Handler

	// Store holds the charmstore Store instance
	// for the request.
	Store *charmstore.Store

	// cache holds the per-request entity cache.
	Cache *entitycache.Cache
	// contains filtered or unexported fields
}

ReqHandler holds the context for a single HTTP request. It uses an independent mgo session from the handler used by other requests.

func (*ReqHandler) AuthIdHandler

func (h *ReqHandler) AuthIdHandler(f ResolvedIdHandler) ResolvedIdHandler

AuthIdHandler returns a ResolvedIdHandler that uses h.Router.Context.AuthorizeEntity to check that the client is authorized to perform the HTTP request method before invoking f.

Note that it only accesses h.Router.Context when the returned handler is called.

func (*ReqHandler) AuthorizeEntity

func (h *ReqHandler) AuthorizeEntity(id *router.ResolvedURL, req *http.Request) error

AuthorizeEntity checks that the given HTTP request can access the entity with the given id.

func (*ReqHandler) AuthorizeEntityAndTerms

func (h *ReqHandler) AuthorizeEntityAndTerms(req *http.Request, entityIds []*router.ResolvedURL) (authorization, error)

AuthorizeEntityAndTerms is similar to the authorize method, but in addition it also checks if the entity meta data specifies and terms and conditions that the user needs to agree to. If so, it will require the user to agree to those terms and conditions by adding a third party caveat addressed to the terms service requiring the user to have agreements to specified terms.

func (*ReqHandler) CheckRequest

func (h *ReqHandler) CheckRequest(req *http.Request, entityIds []*router.ResolvedURL, operation string) (authorization, error)

CheckRequest checks for any authorization tokens in the request and returns any found as an authorization. If no suitable credentials are found, or an error occurs, then a zero valued authorization is returned. It also checks any first party caveats. If the entityId is provided, it will be used to check any "is-entity" first party caveat. In addition it adds a checker that checks if operation specified by the operation parameters is allowed.

func (*ReqHandler) Close

func (h *ReqHandler) Close()

Close closes the ReqHandler. This should always be called when the ReqHandler is done with.

func (*ReqHandler) EntityHandler

func (h *ReqHandler) EntityHandler(f EntityHandlerFunc, fields ...string) router.BulkIncludeHandler

EntityHandler returns a Handler that calls f with a *mongodoc.Entity that contains at least the given fields. It allows only GET requests.

func (*ReqHandler) GroupsForUser

func (h *ReqHandler) GroupsForUser(username string) ([]string, error)

Groups for user fetches the list of groups to which the user belongs.

func (*ReqHandler) Reset

func (h *ReqHandler) Reset()

Reset resets the request-specific fields of the ReqHandler so that it's suitable for putting back into a pool for reuse.

func (*ReqHandler) ResolveURL

func (h *ReqHandler) ResolveURL(url *charm.URL) (*router.ResolvedURL, error)

ResolveURL implements router.Context.ResolveURL.

func (*ReqHandler) ResolveURLs

func (h *ReqHandler) ResolveURLs(urls []*charm.URL) ([]*router.ResolvedURL, error)

ResolveURL implements router.Context.ResolveURLs.

func (*ReqHandler) ResolvedIdHandler

func (h *ReqHandler) ResolvedIdHandler(f ResolvedIdHandler, cacheFields ...string) router.IdHandler

ResolvedIdHandler returns an id handler that uses h.Router.Context.ResolveURL to resolves any entity ids before calling f with the resolved id.

Any specified fields will be added to the fields required by the cache, so they will be pre-fetched by ResolveURL.

Note that it only accesses h.Router.Context when the returned handler is called.

func (*ReqHandler) Search

func (h *ReqHandler) Search(sp charmstore.SearchParams, req *http.Request) (interface{}, error)

Search performs the search specified by SearchParams. If sp specifies that additional metadata needs to be added to the results, then it is added.

func (*ReqHandler) SendEntityArchive

func (h *ReqHandler) SendEntityArchive(id *router.ResolvedURL, w http.ResponseWriter, req *http.Request, blob *charmstore.Blob)

SendEntityArchive writes the given blob, which has been retrieved from the given id, as a response to the given request.

func (*ReqHandler) ServeBlobFile

func (h *ReqHandler) ServeBlobFile(w http.ResponseWriter, req *http.Request, id *router.ResolvedURL, blob *charmstore.Blob) error

ServeBlobFile serves a file from the given blob. The path of the file is taken from req.URL.Path. The blob should be associated with the entity with the given id.

func (*ReqHandler) ServeHTTP

func (h *ReqHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP implements http.Handler by calling h.Router.ServeHTTP.

func (*ReqHandler) WillIncludeMetadata

func (h *ReqHandler) WillIncludeMetadata(includes []string)

WillIncludeMetadata implements router.Context.WillIncludeMetadata.

type ResolvedIdHandler

type ResolvedIdHandler func(id *router.ResolvedURL, w http.ResponseWriter, req *http.Request) error

ResolvedIdHandler represents a HTTP handler that is invoked on a resolved entity id.