juju: github.com/juju/juju/apiserver/facade Index | Files | Directories

package facade

import "github.com/juju/juju/apiserver/facade"


Package Files

interface.go registry.go

type Authorizer Uses

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) (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 Uses

type Context interface {

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

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

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

Context exposes useful capabilities to a Facade.

type Description Uses

type Description struct {
    Name     string
    Versions []int

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

type Details Uses

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 Uses

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 Uses

type Factory func(Context) (Facade, error)

Factory is a callback used to create a Facade.

type Hub Uses

type Hub interface {
    Publish(topic string, data interface{}) (<-chan struct{}, error)

Hub represents the central hub that the API server has.

type ModelPresence Uses

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 Uses

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 Uses

type Registry struct {
    // contains filtered or unexported fields

Registry describes the API facades exposed by some API server.

func (*Registry) Discard Uses

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 Uses

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 Uses

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 Uses

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

List returns a slice describing each of the registered Facades.

func (*Registry) ListDetails Uses

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

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

func (*Registry) Register Uses

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.

func (*Registry) RegisterStandard Uses

func (f *Registry) RegisterStandard(name string, version int, newFunc interface{}) error

RegisterStandard is the more convenient way of registering facades. newFunc should have one of the following signatures:

func (facade.Context) (*Type, error)
func (*state.State, facade.Resources, facade.Authorizer) (*Type, error)

type Resource Uses

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 Uses

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.


mocksPackage mocks is a generated GoMock package.

Package facade imports 13 packages (graph) and is imported by 1152 packages. Updated 2020-07-16. Refresh now. Tools for package owners.