facade

Documentation

Index

• type Authorizer
• type Context
• type Description
• type Facade
• type Factory
• 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) Register(name string, version int, factory Factory, facadeType reflect.Type, ...) error
• type Resource
• type Resources

Types

type Authorizer

type Authorizer interface {

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

	// AuthModelManager returns whether the authenticated entity is
	// a machine running the environment manager job. 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.
	AuthModelManager() bool

	// AuthMachineAgent returns true if the entity is a machine
	// agent. Doesn't need to be on this interface, should be a
	// utility func if anything.
	AuthMachineAgent() bool

	// AuthUnitAgent returns true if the entity is a unit agent.
	// Doesn't need to be on this interface, should be a utility
	// func if anything.
	AuthUnitAgent() bool

	// AuthOwner returns true if tag == .GetAuthTag(). Doesn't need
	// to be on this interface, should be a utility fun if anything.
	AuthOwner(tag names.Tag) bool

	// AuthClient returns true if the entity is an external user.
	// Doesn't need to be on this interface, should be a utility
	// func if anything.
	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) (bool, error)

	// UserHasPermission reports whether the given access is allowed for the given
	// target by the given user.
	UserHasPermission(user names.UserTag, operation permission.Access, target names.Tag) (bool, 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 {

	// Abort will be closed with the client connection. Any long-
	// running methods should pay attention to Abort, and terminate
	// with a sensible (non-nil) error when requested.
	Abort() <-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 common.ErrPerm for any targets for which the client is
	// not *known* to have a responsibility or requirement.
	Auth() Authorizer

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

	// 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
}

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 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 Factory

type Factory func(Context) (Facade, error)

Factory is a callback used to create a Facade.

type Registry

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

Registry describes Facades the facades exposed by some API server.

It's only actually used as a global -- `apiserver/common.Facades` -- but if we were smarter we could just create a Registry directly and pass it into the apiserver.

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

func (f *Registry) Register(name string, version int, factory Factory, facadeType reflect.Type, feature string) 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 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.