facade

package
v0.0.0-...-e2523e8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 28, 2024 License: AGPL-3.0 Imports: 21 Imported by: 224

Documentation

Index

Constants

View Source 
const (
	// ErrorHTTPClientPurposeInvalid is an error that describes a problem where
	// a [HTTPClientPurpose] is not understood.
	ErrorHTTPClientPurposeInvalid = errors.ConstError("http client purpose is invalid")

	// ErrorHTTPClientForPurposeNotFound is an error that describes a problem
	// where a http client cannot be found for a [HTTPClientPurpose].
	ErrorHTTPClientForPurposeNotFound = errors.ConstError("http client for purpose not found")
)

Variables

This section is empty.

Functions

This section is empty.

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(ctx context.Context, operation permission.Access, target names.Tag) error

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

Authorizer represents the authenticated entity using the API server.

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.
	// This is a full multi-model factory, so we can downcast to facades
	// that are specific to a single model.
	Factory MultiModelFactory
	// 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 DomainServices 

type DomainServices interface {
	// DomainServices returns the services factory for the current model.
	DomainServices() services.DomainServices
}

DomainServices defines an interface for accessing all the services.

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)

	// MustRegisterForMultiModel adds a single named facade for a model at a
	// given version to the registry. This allows the facade to be registered
	// with a factory that takes a MultiModelContext instead of a Context.
	// MultiModelFactory 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.
	MustRegisterForMultiModel(string, int, MultiModelFactory, reflect.Type)
}

FacadeRegistry describes the API facades exposed by some API server.

type Factory 

type Factory func(stdCtx context.Context, modelCtx ModelContext) (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 Hub 

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

Hub represents the central hub that the API server has.

type LeadershipModelContext 

type LeadershipModelContext interface {
	// LeadershipClaimer returns a leadership.Claimer for this
	// context's model.
	LeadershipClaimer() (leadership.Claimer, error)

	// LeadershipRevoker returns a leadership.Revoker for this
	// context's model.
	LeadershipRevoker() (leadership.Revoker, error)

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

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

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

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

LeadershipModelContext

type LegacyStateExporter 

type LegacyStateExporter interface {
	// Export generates an abstract representation of a model.
	Export(map[string]string, objectstore.ObjectStore) (description.Model, error)
	// ExportPartial produces a partial export based based on the input
	// config.
	ExportPartial(state.ExportConfig, objectstore.ObjectStore) (description.Model, error)
}

LegacyStateExporter describes interface on state required to export a model. Deprecated: This is being replaced with the ModelExporter.

type Logger 

type Logger interface {
	// Logger returns the apiserver logger instance.
	Logger() corelogger.Logger
}

Logger defines an interface for getting the apiserver logger instance.

type ModelContext 

type ModelContext 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.
	LeadershipModelContext
	ModelMigrationFactory
	DomainServices
	ObjectStoreFactory
	Logger

	// 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.
	// Deprecated: Resources are deprecated. Use WatcherRegistry instead.
	Resources() Resources

	// WatcherRegistry returns the watcher registry for this context. The
	// watchers are per-connection, and are cleaned up when the connection
	// is closed.
	WatcherRegistry() WatcherRegistry

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

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

	// ControllerUUID returns the controller's unique identifier.
	ControllerUUID() string

	// ModelUUID returns the model's unique identifier. All facade requests
	// are in the scope of a model. There are some exceptions to the rule, but
	// they are exceptions that prove the rule.
	ModelUUID() model.UUID

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

	// HTTPClient returns an HTTP client to use for the given purpose. The
	// following errors can be expected:
	// - [ErrorHTTPClientPurposeInvalid] when the requested purpose is not
	// understood by the context.
	// - [ErrorHTTPClientForPurposeNotFound] when no http client can be found
	// for the requested [HTTPClientPurpose].
	HTTPClient(corehttp.Purpose) (HTTPClient, error)

	// MachineTag returns the current machine tag.
	MachineTag() names.Tag

	// DataDir returns the data directory.
	DataDir() string

	// LogDir returns the log directory.
	LogDir() string
}

ModelContext exposes useful capabilities to a Facade for a given model.

type ModelExporter 

type ModelExporter interface {
	// ExportModel exports the current model into a description model. This
	// can be serialized into yaml and then imported.
	ExportModel(context.Context, map[string]string, objectstore.ObjectStore) (description.Model, error)
	// ExportModelPartial exports the current model into a partial description
	// model. This can be serialized into yaml and then imported.
	ExportModelPartial(context.Context, state.ExportConfig, objectstore.ObjectStore) (description.Model, error)
}

ModelExporter defines a interface for exporting models.

type ModelImporter 

type ModelImporter interface {
	// ImportModel takes a serialized description model (yaml bytes) and returns
	// a state model and state state.
	ImportModel(ctx context.Context, bytes []byte) (*state.Model, *state.State, error)
}

ModelImporter defines an interface for importing models.

type ModelMigrationFactory 

type ModelMigrationFactory interface {
	// ModelExporter returns a model exporter for the current model.
	ModelExporter(model.UUID, LegacyStateExporter) ModelExporter

	// ModelImporter returns a model importer.
	ModelImporter() ModelImporter
}

ModelMigrationFactory defines an interface for getting a model migrator.

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 MultiModelContext 

type MultiModelContext interface {
	ModelContext

	// DomainServicesForModel returns the services factory for a given model
	// uuid.
	DomainServicesForModel(model.UUID) services.DomainServices

	// ObjectStoreForModel returns the object store for a given model uuid.
	ObjectStoreForModel(ctx context.Context, modelUUID string) (objectstore.ObjectStore, error)
}

MultiModelContext is a context that can operate on multiple models at once.

type MultiModelFactory 

type MultiModelFactory func(stdCtx context.Context, modelCtx MultiModelContext) (Facade, error)

MultiModelFactory is a callback used to create a Facade.

type ObjectStoreFactory 

type ObjectStoreFactory interface {
	// ObjectStore returns the object store for the current model.
	ObjectStore() objectstore.ObjectStore

	// ControllerObjectStore returns the object store for the controller.
	ControllerObjectStore() objectstore.ObjectStore
}

ObjectStoreFactory defines an interface for accessing the object store.

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) (MultiModelFactory, 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) MustRegisterForMultiModel 

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

MustRegisterForMultiModel adds a single named facade for operating and accessing multiple models at a given version to the registry and panics if it fails.

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.

func (*Registry) RegisterForMultiModel 

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

RegisterForMultiModel adds a single named facade for operating and accessing multiple models at a given version to the registry.

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 Resources deprecated 

type Resources interface {
	// Register registers the given resource. It returns a unique identifier
	// for the resource which can then be used in subsequent API requests to
	// refer to the resource.
	// Deprecated: Resources are deprecated. Use WatcherRegistry instead.
	Register(worker.Worker) string

	// Get returns the resource for the given id, or nil if there is no such
	// resource.
	// Deprecated: Resources are deprecated. Use WatcherRegistry instead.
	Get(string) worker.Worker

	// Stop stops the resource with the given id and unregisters it.
	// Deprecated: Resources are deprecated. Use WatcherRegistry instead.
	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.

Deprecated: Resources are deprecated. Use WatcherRegistry instead.

type WatcherRegistry 

type WatcherRegistry interface {
	worker.Worker

	// Get returns the watcher for the given id, or nil if there is no such
	// watcher.
	Get(string) (worker.Worker, error)
	// Register registers the given watcher. It returns a unique identifier for the
	// watcher which can then be used in subsequent API requests to refer to the
	// watcher.
	Register(worker.Worker) (string, error)

	// RegisterNamed registers the given watcher. Callers must supply a unique
	// name for the given watcher. It is an error to try to register another
	// watcher with the same name as an already registered name.
	// It is also an error to supply a name that is an integer string, since that
	// collides with the auto-naming from Register.
	RegisterNamed(string, worker.Worker) error

	// Stop stops the resource with the given id and unregisters it.
	// It returns any error from the underlying Stop call.
	// It does not return an error if the resource has already
	// been unregistered.
	Stop(id string) error

	// Count returns the number of resources currently held.
	Count() int
}

WatcherRegistry holds all the watchers for a connection. It allows the registration of watchers that will be cleaned up when a connection terminates.

Source Files

View all Source files

Directories

Path Synopsis
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.