remoterelationconsumer

package
v0.0.0-...-234537a Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: AGPL-3.0 Imports: 39 Imported by: 0

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

View Source
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")
)
View Source
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.

func (Config) Validate

func (config Config) Validate() error

Validate returns an error if config cannot drive 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

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

type ReportableWorker interface {
	worker.Worker
	worker.Reporter
}

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.

type Worker

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

Worker manages relations and associated settings where one end of the relation is a remote application.

func (*Worker) Kill

func (w *Worker) Kill()

Kill the remote relation consumer worker.

func (*Worker) Report

func (w *Worker) Report(ctx context.Context) map[string]any

Report provides information for the engine report.

func (*Worker) Wait

func (w *Worker) Wait() error

Wait for the remote relation consumer worker to finish.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址