Documentation
¶
Overview ¶
Package remoterelations defines workers which manage the operation of cross model relations.
- `Worker`: Top level worker. Watches remote applications/proxies and creates a worker for each.
- `remoteApplicationWorker`: Manages operations for a consumer or offer proxy. Consumes and publishes relation data and status changes.
- `remoteRelationsWorker`: Runs on the consuming model to manage relations to the offer.
- `relationUnitsWorker`: Runs on the consuming model to receive and publish changes to each relation unit data bag.
The consuming side pushes relation updates from the consumer application to the model containing the offer. It also polls the offered application to record relation changes from the offer into the consuming model.
Index ¶
- Constants
- func Manifold(config ManifoldConfig) dependency.Manifold
- type ApplicationService
- type Config
- type CrossModelRelationService
- type CrossModelService
- type GetCrossModelServicesFunc
- type LocalConsumerWorkerConfig
- type ManifoldConfig
- type NewConsumerUnitRelationsWorkerFunc
- type NewLocalConsumerWorkerFunc
- type NewOffererRelationsWorkerFunc
- type NewOffererUnitRelationsWorkerFunc
- type NewRemoteRelationClientGetterFunc
- type NewWorkerFunc
- type OffererApplicationWorker
- type RelationService
- type RemoteModelRelationsClient
- type RemoteRelationClientGetter
- type RemovalService
- type ReportableWorker
- type StatusService
- type Worker
Constants ¶
const ( // ErrPermissionRevokedWhilstDying identifies when permission is revoked // whilst the relation is in a dying state. This is a terminal error and // requires the worker to be restarted to recover. ErrPermissionRevokedWhilstDying = internalerrors.ConstError("relation permission revoked whilst dying") )
const ( // RemoteApplicationOffererDeadErr is returned when the remote application // offerer is no longer required because it has been removed. This prevents // the worker from being restarted. RemoteApplicationOffererDeadErr = errors.ConstError("remote application offerer is dead and no longer required") )
Variables ¶
This section is empty.
Functions ¶
func Manifold ¶
func Manifold(config ManifoldConfig) dependency.Manifold
Manifold packages a Worker for use in a dependency.Engine.
Types ¶
type ApplicationService ¶
type ApplicationService interface {
// GetApplicationUUIDByName returns an application UUID by application name. It
// returns an error if the application can not be found by the name.
//
// Returns [applicationerrors.ApplicationNameNotValid] if the name is not valid,
// and [applicationerrors.ApplicationNotFound] if the application is not found.
GetApplicationUUIDByName(ctx context.Context, name string) (application.UUID, error)
}
ApplicationService is an interface that defines the methods for managing applications directly on the local model database.
type Config ¶
type Config struct {
ModelUUID model.UUID
CrossModelService CrossModelService
RemoteRelationClientGetter RemoteRelationClientGetter
NewLocalConsumerWorker NewLocalConsumerWorkerFunc
NewConsumerUnitRelationsWorker NewConsumerUnitRelationsWorkerFunc
NewOffererUnitRelationsWorker NewOffererUnitRelationsWorkerFunc
NewOffererRelationsWorker NewOffererRelationsWorkerFunc
Clock clock.Clock
Logger logger.Logger
}
Config defines the operation of a Worker.
type CrossModelRelationService ¶
type CrossModelRelationService interface {
// WatchRemoteApplicationOfferers watches the changes to remote
// application consumers and notifies the worker of any changes.
WatchRemoteApplicationOfferers(ctx context.Context) (watcher.NotifyWatcher, error)
// WatchDyingModel returns a watcher that emits when the model transitions
// to a dying state. This is used to notify the offering model that the
// consuming model is going away.
WatchDyingModel(ctx context.Context) (watcher.NotifyWatcher, error)
// GetRemoteApplicationOfferers returns the current state of all remote
// application consumers in the local model.
GetRemoteApplicationOfferers(context.Context) ([]crossmodelrelation.RemoteApplicationOfferer, error)
// UpdateRemoteSecretRevision records the specified revision for the secret
// which has been consumed from a different model.
UpdateRemoteSecretRevision(ctx context.Context, uri *secrets.URI, latestRevision int, applicationUUID application.UUID) error
// SaveMacaroonForRelation saves the given macaroon for the specified remote
// application.
SaveMacaroonForRelation(context.Context, corerelation.UUID, *macaroon.Macaroon) error
// EnsureUnitsExist ensures that the specified units exist in the local
// model, creating any that are missing.
EnsureUnitsExist(ctx context.Context, appUUID application.UUID, units []unit.Name) error
}
CrossModelRelationService is an interface that defines the methods for managing cross-model relations directly on the local model database.
type CrossModelService ¶
type CrossModelService interface {
ApplicationService
CrossModelRelationService
RelationService
RemovalService
StatusService
}
CrossModelService is an interface that groups together the local relation service and the cross-model relation service.
func GetCrossModelService ¶
func GetCrossModelService(getter dependency.Getter, domainServicesName string) (CrossModelService, error)
GetCrossModelService returns the cross-model relation services from the dependency engine.
type GetCrossModelServicesFunc ¶
type GetCrossModelServicesFunc func(getter dependency.Getter, domainServicesName string) (CrossModelService, error)
GetCrossModelServicesFunc defines the function signature for getting cross-model services.
type LocalConsumerWorkerConfig ¶
type LocalConsumerWorkerConfig struct {
CrossModelService CrossModelService
RemoteRelationClientGetter RemoteRelationClientGetter
OfferUUID string
ApplicationName string
ApplicationUUID application.UUID
ConsumerModelUUID model.UUID
OffererModelUUID string
ConsumeVersion int
Macaroon *macaroon.Macaroon
NewConsumerUnitRelationsWorker NewConsumerUnitRelationsWorkerFunc
NewOffererUnitRelationsWorker NewOffererUnitRelationsWorkerFunc
NewOffererRelationsWorker NewOffererRelationsWorkerFunc
Clock clock.Clock
Logger logger.Logger
}
LocalConsumerWorkerConfig defines the configuration for a local consumer worker.
func (LocalConsumerWorkerConfig) Validate ¶
func (c LocalConsumerWorkerConfig) Validate() error
Validate ensures that the config is valid.
type ManifoldConfig ¶
type ManifoldConfig struct {
ModelUUID model.UUID
APIRemoteRelationCallerName string
DomainServicesName string
NewRemoteRelationClientGetter NewRemoteRelationClientGetterFunc
GetCrossModelServices GetCrossModelServicesFunc
NewWorker NewWorkerFunc
NewLocalConsumerWorker NewLocalConsumerWorkerFunc
NewConsumerUnitRelationsWorker NewConsumerUnitRelationsWorkerFunc
NewOffererUnitRelationsWorker NewOffererUnitRelationsWorkerFunc
NewOffererRelationsWorker NewOffererRelationsWorkerFunc
Logger logger.Logger
Clock clock.Clock
}
ManifoldConfig defines the names of the manifolds on which a Worker manifold will depend.
func (ManifoldConfig) Validate ¶
func (config ManifoldConfig) Validate() error
Validate is called by start to check for bad configuration.
type NewConsumerUnitRelationsWorkerFunc ¶
type NewConsumerUnitRelationsWorkerFunc func(consumerunitrelations.Config) (consumerunitrelations.ReportableWorker, error)
NewConsumerUnitRelationsWorkerFunc defines the function signature for creating a new local unit relations worker.
type NewLocalConsumerWorkerFunc ¶
type NewLocalConsumerWorkerFunc func(LocalConsumerWorkerConfig) (ReportableWorker, error)
NewLocalConsumerWorkerFunc defines the function signature for creating a new local consumer worker.
type NewOffererRelationsWorkerFunc ¶
type NewOffererRelationsWorkerFunc func(offererrelations.Config) (offererrelations.ReportableWorker, error)
NewOffererRelationsWorkerFunc defines the function signature for creating a new remote relations worker.
type NewOffererUnitRelationsWorkerFunc ¶
type NewOffererUnitRelationsWorkerFunc func(offererunitrelations.Config) (offererunitrelations.ReportableWorker, error)
NewOffererUnitRelationsWorkerFunc defines the function signature for creating a new remote unit relations worker.
type NewRemoteRelationClientGetterFunc ¶
type NewRemoteRelationClientGetterFunc func(apiremoterelationcaller.APIRemoteCallerGetter) RemoteRelationClientGetter
NewRemoteRelationClientGetterFunc defines the function signature for creating a new RemoteRelationClient.
type NewWorkerFunc ¶
type NewWorkerFunc func(Config) (ReportableWorker, error)
NewWorkerFunc defines the function signature for creating a new Worker.
type OffererApplicationWorker ¶
type OffererApplicationWorker interface {
// ConsumeVersion returns the consume version for the remote application
// worker.
ConsumeVersion() int
// PublishModelDying notifies the worker that the model is dying, so it can
// perform any necessary cleanup.
PublishModelDying(ctx context.Context) error
}
OffererApplicationWorker is an interface that defines the methods that a remote application worker must implement to be managed by the Worker.
type RelationService ¶
type RelationService interface {
// WatchRelationsLifeSuspendedStatusForApplication watches the changes to the
// life suspended status of the specified application and notifies
// the worker of any changes.
WatchRelationsLifeSuspendedStatusForApplication(context.Context, application.UUID) (watcher.StringsWatcher, error)
// GetRelationDetails returns RelationDetails for the given relationID.
GetRelationDetails(context.Context, corerelation.UUID) (relation.RelationDetails, error)
// WatchRelationUnits returns a watcher for changes to the units
// in the given relation in the local model.
WatchRelationUnits(context.Context, corerelation.UUID, application.UUID) (watcher.NotifyWatcher, error)
// GetRelationUnits returns the current state of the relation units.
GetRelationUnits(context.Context, corerelation.UUID, application.UUID) (relation.RelationUnitChange, error)
// GetRelationUnitUUID returns the relation unit UUID for the given unit for
// the given relation.
GetRelationUnitUUID(
ctx context.Context,
relationUUID corerelation.UUID,
unitName unit.Name,
) (corerelation.UnitUUID, error)
// SetRelationRemoteApplicationAndUnitSettings will set the application and
// unit settings for a remote relation. If the unit has not yet entered
// scope, it will force the unit to enter scope. All settings will be
// replaced with the provided settings.
// This will ensure that the application, relation and units exist and that
// they are alive.
SetRelationRemoteApplicationAndUnitSettings(
ctx context.Context,
applicationUUID application.UUID,
relationUUID corerelation.UUID,
applicationSettings map[string]string,
unitSettings map[unit.Name]map[string]string,
) error
// SetRemoteRelationSuspendedState sets the suspended state of the specified
// remote relation in the local model.
SetRemoteRelationSuspendedState(ctx context.Context, relationUUID corerelation.UUID, suspended bool, reason string) error
}
RelationService is an interface that defines the methods for managing relations directly on the local model database.
type RemoteModelRelationsClient ¶
type RemoteModelRelationsClient interface {
// RegisterRemoteRelations sets up the remote model to participate
// in the specified relations.
RegisterRemoteRelations(_ context.Context, relations ...params.RegisterConsumingRelationArg) ([]params.RegisterConsumingRelationResult, error)
// PublishRelationChange publishes relation changes to the
// model hosting the remote application involved in the relation.
PublishRelationChange(context.Context, params.RemoteRelationChangeEvent) error
// WatchRelationChanges returns a watcher that notifies of changes
// to the units in the remote model for the relation with the
// given remote token.
WatchRelationChanges(_ context.Context, relationToken string, macs macaroon.Slice) (apiwatcher.RemoteRelationWatcher, error)
// WatchRelationSuspendedStatus starts a RelationStatusWatcher for watching the
// relations of each specified application in the remote model.
WatchRelationSuspendedStatus(_ context.Context, arg params.RemoteEntityArg) (watcher.RelationStatusWatcher, error)
// WatchOfferStatus starts an OfferStatusWatcher for watching the status
// of the specified offer in the remote model.
WatchOfferStatus(_ context.Context, arg params.OfferArg) (watcher.OfferStatusWatcher, error)
// WatchConsumedSecretsChanges starts a watcher for any changes to secrets
// consumed by the specified application.
WatchConsumedSecretsChanges(ctx context.Context, applicationToken, relationToken string, mac *macaroon.Macaroon) (watcher.SecretsRevisionWatcher, error)
}
RemoteModelRelationsClient instances publish local relation changes to the model hosting the remote application involved in the relation, and also watches for remote relation changes which are then pushed to the local model.
type RemoteRelationClientGetter ¶
type RemoteRelationClientGetter interface {
// GetRemoteRelationClient returns a RemoteModelRelationsClient for the
// given model UUID.
GetRemoteRelationClient(ctx context.Context, modelUUID string) (RemoteModelRelationsClient, error)
}
RemoteRelationClientGetter defines the interface for a remote relation facade.
func NewRemoteRelationClientGetter ¶
func NewRemoteRelationClientGetter(getter apiremoterelationcaller.APIRemoteCallerGetter) RemoteRelationClientGetter
NewRemoteRelationClientGetter creates a new RemoteRelationClientGetter using the provided APIRemoteCallerGetter.
type RemovalService ¶
type RemovalService interface {
// RemoveRelationWithRemoteOfferer sets the relation with the given relation UUID
// from the local model to dying.
RemoveRelationWithRemoteOfferer(
ctx context.Context, relUUID corerelation.UUID, force bool, wait time.Duration,
) (removal.UUID, error)
// RemoveRemoteApplicationOffererByApplicationUUID sets the remote
// application offerer with the given application UUID from the local model
// to dying.
RemoveRemoteApplicationOffererByApplicationUUID(
ctx context.Context, appUUID application.UUID, force bool, duration time.Duration) (removal.UUID, error)
// LeaveScope updates the relation to indicate that the unit represented by
// the input relation unit UUID is not in the implied relation scope.
LeaveScope(ctx context.Context, relationUnitUUID corerelation.UnitUUID) error
}
RemovalService is an interface that defines the methods for removing relations directly on the local model database.
type ReportableWorker ¶
ReportableWorker is an interface that allows a worker to be reported on by the engine.
func NewLocalConsumerWorker ¶
func NewLocalConsumerWorker(config LocalConsumerWorkerConfig) (ReportableWorker, error)
NewLocalConsumerWorker creates a new local consumer worker.
func NewWorker ¶
func NewWorker(config Config) (ReportableWorker, error)
New returns a Worker backed by config, or an error.
type StatusService ¶
type StatusService interface {
// SetRemoteApplicationOffererStatusByApplicationUUID uses the immutable
// application identity so a stale worker cannot apply a status update to a
// replacement application that reused the same name.
SetRemoteApplicationOffererStatusByApplicationUUID(ctx context.Context, appUUID application.UUID, sts status.StatusInfo) error
}
StatusService is the subset of the domain status service used by the remote relation consumer worker to update remote application offerer status.