facade

Documentation

Index

• type Authorizer
• type Context
• type Description
• type Details
• type Facade
• type FacadeRegistry
• type Factory
• type HTTPClient
• type HTTPClientPurpose
• type Hub
• type LeadershipContext
• type ModelPresence
• type Presence
• type Registry
  • func (f *Registry) Discard(name string, version int)
  • func (f *Registry) GetFactory(name string, version int) (Factory, error)
  • func (f *Registry) GetType(name string, version int) (reflect.Type, error)
  • func (f *Registry) List() []Description
  • func (f *Registry) ListDetails() []Details
  • func (f *Registry) MustRegister(name string, version int, factory Factory, facadeType reflect.Type)
  • func (f *Registry) Register(name string, version int, factory Factory, facadeType reflect.Type) error
• type RequestRecorder
• type Resource
• type Resources

Types

type Authorizer

type Authorizer interface {

	// GetAuthTag returns the entity's tag.
	GetAuthTag() names.Tag

	// AuthController returns whether the authenticated entity is
	// a machine acting as a controller. Can't be removed from this
	// interface without introducing a dependency on something else
	// to look up that property: it's not inherent in the result of
	// GetAuthTag, as the other methods all are.
	AuthController() bool

	// AuthMachineAgent returns true if the entity is a machine agent.
	AuthMachineAgent() bool

	// AuthApplicationAgent returns true if the entity is an application operator.
	AuthApplicationAgent() bool

	// AuthModelAgent returns true if the entity is a model operator.
	AuthModelAgent() bool

	// AuthUnitAgent returns true if the entity is a unit agent.
	AuthUnitAgent() bool

	// AuthOwner returns true if tag == .GetAuthTag().
	AuthOwner(tag names.Tag) bool

	// AuthClient returns true if the entity is an external user.
	AuthClient() bool

	// HasPermission reports whether the given access is allowed for the given
	// target by the authenticated entity.
	HasPermission(operation permission.Access, target names.Tag) error

	// EntityHasPermission reports whether the given access is allowed for the given
	// target by the given entity.
	EntityHasPermission(entity names.Tag, operation permission.Access, target names.Tag) error

	// ConnectedModel returns the UUID of the model to which the API
	// connection was made.
	ConnectedModel() string
}

Authorizer represents the authenticated entity using the API server.

type Context

type Context interface {
	// TODO (stickupkid): This shouldn't be embedded, instead this should be
	// in the form of `context.Leadership() Leadership`, which returns the
	// contents of the LeadershipContext.
	// Context should have a single responsibility, and that's access to other
	// types/objects.
	LeadershipContext

	// Cancel channel represents an indication from the API server that
	// all interruptable calls should stop. The channel is only ever
	// closed, and never sents values.
	Cancel() <-chan struct{}

	// Auth represents information about the connected client. You
	// should always be checking individual requests against Auth:
	// both state changes *and* data retrieval should be blocked
	// with apiservererrors.ErrPerm for any targets for which the client is
	// not *known* to have a responsibility or requirement.
	Auth() Authorizer

	// Dispose disposes the context and any resources related to
	// the API server facade object. Normally the context will not
	// be disposed until the API connection is closed. This is OK
	// except when contexts are dynamically generated, such as in
	// the case of watchers. When a facade context is no longer
	// needed, e.g. when a watcher is closed, then the context may
	// be disposed by calling this method.
	Dispose()

	// Resources exposes per-connection capabilities. By adding a
	// resource, you make it accessible by (returned) id to all
	// other facades used by this connection. It's mostly used to
	// pass watcher ids over to watcher-specific facades, but that
	// seems to be an antipattern: it breaks the separate-facades-
	// by-role advice, and makes it inconvenient to track a given
	// worker's watcher activity alongside its other communications.
	//
	// It's also used to hold some config strings used by various
	// consumers, because it's convenient; and the Pinger that
	// reports client presence in state, because every Resource gets
	// Stop()ped on conn close. Not all of these uses are
	// necessarily a great idea.
	Resources() Resources

	// State returns, /sigh, a *State. As yet, there is no way
	// around this; in the not-too-distant future, we hope, its
	// capabilities will migrate towards access via Resources.
	State() *state.State

	// StatePool returns the state pool used by the apiserver to minimise the
	// creation of the expensive *State instances.
	StatePool() *state.StatePool

	// MultiwatcherFactory returns the factory to create multiwatchers.
	MultiwatcherFactory() multiwatcher.Factory

	// Controller returns the in-memory representation of the models
	// in the database.
	Controller() *cache.Controller

	// CachedModel returns the in-memory representation of the specified
	// model. This call will wait for the model to appear in the cache.
	// The method optimistically expects the model to exist in the cache
	// or appear very soon. If the model doesn't appear, the database is
	// checked. A NotFound error is returned if the model no longer exists
	// in the database, or a Timeout error is returned if the model didn't
	// appear, but should have.
	CachedModel(uuid string) (*cache.Model, error)

	// Presence returns an instance that is able to be asked for
	// the current model presence.
	Presence() Presence

	// Hub returns the central hub that the API server holds.
	// At least at this stage, facades only need to publish events.
	Hub() Hub

	// ID returns a string that should almost always be "", unless
	// this is a watcher facade, in which case it exists in lieu of
	// actual arguments in the Next() call, and is used as a key
	// into Resources to get the watcher in play. This is not really
	// a good idea; see Resources.
	ID() string

	// RequestRecorder defines a metrics collector for outbound requests.
	RequestRecorder() RequestRecorder

	// HTTPClient returns an HTTP client to use for the given purpose.
	HTTPClient(purpose HTTPClientPurpose) HTTPClient

	// ControllerDB returns a TrackedDB reference for the controller database.
	ControllerDB() (coredatabase.TrackedDB, error)
}

Context exposes useful capabilities to a Facade.

type Description

type Description struct {
	Name     string
	Versions []int
}

Description describes the name and what versions of a facade have been registered.

type Details

type Details struct {
	// Name is the name of the facade.
	Name string
	// Version holds the version of the facade.
	Version int
	// Factory holds the factory function for making
	// instances of the facade.
	Factory Factory
	// Type holds the type of object that the Factory
	// will return. This can be used to find out
	// details of the facade without actually creating
	// a facade instance (see rpcreflect.ObjTypeOf).
	Type reflect.Type
}

Details holds information about a facade.

type Facade

type Facade interface{}

Facade could be anything; it will be interpreted by the apiserver machinery such that certain exported methods will be made available as facade methods to connected clients.

type FacadeRegistry

type FacadeRegistry interface {
	// MustRegister adds a single named facade at a given version to the
	// registry.
	// Factory will be called when someone wants to instantiate an object of
	// this facade, and facadeType defines the concrete type that the returned
	// object will be.
	// The Type information is used to define what methods will be exported in
	// the API, and it must exactly match the actual object returned by the
	// factory.
	MustRegister(string, int, Factory, reflect.Type)
}

FacadeRegistry describes the API facades exposed by some API server.

type Factory

type Factory func(Context) (Facade, error)

Factory is a callback used to create a Facade.

type HTTPClient

type HTTPClient interface {
	Do(*http.Request) (*http.Response, error)
}

HTTPClient represents an HTTP client, for example, an *http.Client.

type HTTPClientPurpose

type HTTPClientPurpose string

HTTPClientPurpose describes a specific purpose for an HTTP client.

const (
	CharmhubHTTPClient HTTPClientPurpose = "charmhub"
)

type Hub

type Hub interface {
	Publish(topic string, data interface{}) (func(), error)
}

Hub represents the central hub that the API server has.

type LeadershipContext

type LeadershipContext interface {

	// LeadershipClaimer returns a leadership.Claimer tied to a
	// specific model.
	LeadershipClaimer(modelUUID string) (leadership.Claimer, error)

	// LeadershipRevoker returns a leadership.Revoker tied to a
	// specific model.
	LeadershipRevoker(modelUUID string) (leadership.Revoker, error)

	// LeadershipChecker returns a leadership.Checker for this
	// context's model.
	LeadershipChecker() (leadership.Checker, error)

	// LeadershipPinner returns a leadership.Pinner for this
	// context's model.
	LeadershipPinner(modelUUID string) (leadership.Pinner, error)

	// LeadershipReader returns a leadership.Reader for this
	// context's model.
	LeadershipReader(modelUUID string) (leadership.Reader, error)

	// SingularClaimer returns a lease.Claimer for singular leases for
	// this context's model.
	SingularClaimer() (lease.Claimer, error)
}

LeadershipContext describes factory methods for objects that deliver specific lease-related capabilities

type ModelPresence

type ModelPresence interface {
	// For a given non controller agent, return the Status for that agent.
	AgentStatus(agent string) (presence.Status, error)
}

ModelPresence represents the API server connections for a model.

type Presence

type Presence interface {
	ModelPresence(modelUUID string) ModelPresence
}

Presence represents the current known state of API connections from agents to any of the API servers.

type Registry

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

Registry describes the API facades exposed by some API server.

func (*Registry) Discard

func (f *Registry) Discard(name string, version int)

Discard gets rid of a registration that has already been done. Calling discard on an entry that is not present is not considered an error.

func (*Registry) GetFactory

func (f *Registry) GetFactory(name string, version int) (Factory, error)

GetFactory returns just the Factory for a given Facade name and version. See also GetType for getting the type information instead of the creation factory.

func (*Registry) GetType

func (f *Registry) GetType(name string, version int) (reflect.Type, error)

GetType returns the type information for a given Facade name and version. This can be used for introspection purposes (to determine what methods are available, etc).

func (*Registry) List

func (f *Registry) List() []Description

List returns a slice describing each of the registered Facades.

func (*Registry) ListDetails

func (f *Registry) ListDetails() []Details

ListDetails returns information about all the facades registered in f, ordered lexically by name.

func (*Registry) MustRegister

func (f *Registry) MustRegister(name string, version int, factory Factory, facadeType reflect.Type)

MustRegister adds a single named facade at a given version to the registry and panics if it fails. See: Register.

func (*Registry) Register

func (f *Registry) Register(name string, version int, factory Factory, facadeType reflect.Type) error

Register adds a single named facade at a given version to the registry. Factory will be called when someone wants to instantiate an object of this facade, and facadeType defines the concrete type that the returned object will be. The Type information is used to define what methods will be exported in the API, and it must exactly match the actual object returned by the factory.

type RequestRecorder

type RequestRecorder interface {
	// Record an outgoing request that produced a http.Response.
	Record(method string, url *url.URL, res *http.Response, rtt time.Duration)

	// RecordError records an outgoing request that returned back an error.
	RecordError(method string, url *url.URL, err error)
}

RequestRecorder is implemented by types that can record information about successful and unsuccessful http requests.

type Resource

type Resource interface {
	Stop() error
}

Resource should almost certainly be worker.Worker: the current implementation renders the apiserver vulnerable to deadlock when shutting down. (See common.Resources.StopAll -- *that* should be a Kill() and a Wait(), so that connection cleanup can kill the resources early, along with everything else, and then just wait for all those things to finish.)

type Resources

type Resources interface {
	Register(Resource) string
	Get(string) Resource
	Stop(string) error
}

Resources allows you to store and retrieve Resource implementations.

The lack of error returns are in deference to the existing implementation, not because they're a good idea.