v5

Documentation

Index

• Constants
• Variables
• func NewAPIHandler(p charmstore.APIHandlerParams) (charmstore.HTTPCloseHandler, error)
• func ParseSearchParams(req *http.Request) (charmstore.SearchParams, error)
• func RouterHandlers(h *ReqHandler) *router.Handlers
• func StatsEnabled(req *http.Request) bool
• type Authorization
• type EntityHandlerFunc
• type Handler
  • func New(params charmstore.APIHandlerParams) (*Handler, error)
  • func (h *Handler) Close()
  • func (h *Handler) NewReqHandler(req *http.Request) (*ReqHandler, error)
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type ReqHandler
  • func (h *ReqHandler) AuthIdHandler(f ResolvedIdHandler) ResolvedIdHandler
  • func (h *ReqHandler) Authenticate(req *http.Request) (Authorization, error)
  • func (h *ReqHandler) AuthorizeEntity(id *router.ResolvedURL, req *http.Request) error
  • func (h *ReqHandler) AuthorizeEntityForOp(id *router.ResolvedURL, req *http.Request, op string) error
  • func (h *ReqHandler) Close()
  • func (h *ReqHandler) EntityHandler(f EntityHandlerFunc, fields ...string) router.BulkIncludeHandler
  • 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
• type SetAuthCookie
• type StoreWithChannel
  • func (s *StoreWithChannel) FindBaseEntity(url *charm.URL, fields map[string]int) (*mongodoc.BaseEntity, error)
  • func (s *StoreWithChannel) FindBestEntity(url *charm.URL, fields map[string]int) (*mongodoc.Entity, error)

Constants

const (
	// OpReadWithNoTerms is the operation of reading an entity
	// where either the entity has no associated terms and conditions
	// or we don't need to agree to them to access the entity.
	OpReadWithNoTerms = "read-no-terms"

	// OpReadWithTerms is the operation of reading an entity
	// where terms must be agreed to before contents
	// are provided.
	OpReadWithTerms = "read-with-terms"

	// OpWrite indicates an operation that changes something in the charmstore.
	OpWrite = "write"
)

These operations represent categories of operation by the user on the charm store. All the operations should be mutually distinct.

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 (
	PromulgatorsGroup = "charmers"
)

Variables

var (
	RequiredEntityFields = charmstore.FieldSelector(
		"baseurl",
		"user",
		"name",
		"revision",
		"series",
		"promulgated-revision",
		"promulgated-url",
		"published",
	)
	RequiredBaseEntityFields = charmstore.FieldSelector(
		"user",
		"name",
		"channelacls",
		"channelentities",
		"promulgated",
	)
)

var PermCacheExpiry = time.Minute

PermCacheExpiry holds the maximum length of time that permissions and group membership information will be cached for.

Functions

func NewAPIHandler

func NewAPIHandler(p charmstore.APIHandlerParams) (charmstore.HTTPCloseHandler, error)

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 Authorization

type Authorization struct {
	Admin    bool
	User     *idmclient.User
	Username string
}

Authorization contains authorization information extracted from an HTTP request. The zero value for a authorization contains no privileges.

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(params charmstore.APIHandlerParams) (*Handler, error)

func (*Handler) Close

func (h *Handler) Close()

Close closes the Handler.

func (*Handler) NewReqHandler

func (h *Handler) NewReqHandler(req *http.Request) (*ReqHandler, error)

NewReqHandler returns an instance of a *ReqHandler suitable for handling the given 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, associated with the channel specified
	// in the request.
	Store *StoreWithChannel

	// 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) Authenticate

func (h *ReqHandler) Authenticate(req *http.Request) (Authorization, error)

Authenticate is a convenience method that calls authorize to check that that the given request is authenticated for some user.

func (*ReqHandler) AuthorizeEntity

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

AuthorizeEntity is a convenience method that calls authorize to check that the given request can access the entity with the given id to perform all of the given operations. The operation will be chosen based on the request method (OpReadNonArchive for non-mutating HTTP methods; OpWrite for others).

If the request fails because authorization is denied, a macaroon is minted that will provide access when discharged, and returned as a discharge-required error.

This method implements router.Context.AuthorizeEntity.

func (*ReqHandler) AuthorizeEntityForOp

func (h *ReqHandler) AuthorizeEntityForOp(id *router.ResolvedURL, req *http.Request, op string) error

AuthorizeEntityForOp is a convenience method that calls authorize to check that that the given request is authorized to perform the given operation on the entity with the given id.

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) 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.

type SetAuthCookie

type SetAuthCookie struct {
	// Macaroons holds a slice of macaroons.
	Macaroons macaroon.Slice
}

SetAuthCookie holds the parameters used to make a set-auth-cookie request to the charm store. It duplicates the type in charmrepo.v2-unstable/csclient/params because we don't want to make that use macaroon.v2-unstable yet. TODO use charmrepo.v2-unstable/csclient/params for SetAuthCookie.

type StoreWithChannel

type StoreWithChannel struct {
	*charmstore.Store
	Channel params.Channel
}

StoreWithChannel associates a Store with a channel that will be used to resolve any channel-ambiguous requests.

func (*StoreWithChannel) FindBaseEntity

func (s *StoreWithChannel) FindBaseEntity(url *charm.URL, fields map[string]int) (*mongodoc.BaseEntity, error)

func (*StoreWithChannel) FindBestEntity

func (s *StoreWithChannel) FindBestEntity(url *charm.URL, fields map[string]int) (*mongodoc.Entity, error)