relation

Documentation

Overview

Package relation implements persistent local storage of a unit's relation state, and translation of relation changes into hooks that need to be run.

Index

• func NewCreatedRelationResolver(stateTracker RelationStateTracker, logger Logger) resolver.Resolver
• func NewRelationResolver(stateTracker RelationStateTracker, subordinateDestroyer SubordinateDestroyer, ...) resolver.Resolver
• type Application
• type LeadershipContextFunc
• type Logger
• type Relation
• type RelationStateTracker
  • func NewRelationStateTracker(cfg RelationStateTrackerConfig) (RelationStateTracker, error)
• type RelationStateTrackerConfig
• type RelationUnit
• type RelationUnitShim
  • func (r *RelationUnitShim) Relation() Relation
• type Relationer
  • func NewRelationer(ru RelationUnit, stateMgr StateManager, unitGetter UnitGetter, logger Logger) Relationer
• type State
  • func NewState(relationId int) *State
  • func (s *State) UnmarshalYAML(unmarshal func(interface{}) error) error
  • func (s *State) UpdateStateForHook(hi hook.Info, logger Logger)
  • func (s *State) Validate(hi hook.Info) (err error)
  • func (s *State) YamlString() (string, error)
• type StateManager
  • func NewStateManager(rw UnitStateReadWriter, logger Logger) (StateManager, error)
• type StateTrackerState
• type SubordinateDestroyer
• type Unit
• type UnitGetter
• type UnitStateReadWriter

Functions

func NewCreatedRelationResolver

func NewCreatedRelationResolver(stateTracker RelationStateTracker, logger Logger) resolver.Resolver

NewCreatedRelationResolver returns a resolver that handles relation-created hooks and is wired to the provided RelationStateTracker instance.

func NewRelationResolver

func NewRelationResolver(stateTracker RelationStateTracker, subordinateDestroyer SubordinateDestroyer, logger Logger) resolver.Resolver

NewRelationResolver returns a resolver that handles all relation-related hooks (except relation-created) and is wired to the provided RelationStateTracker instance.

Types

type Application

type Application interface {
	Life() life.Value
}

Application encapsulates the methods from state.Application required by a relationStateTracker.

type LeadershipContextFunc

type LeadershipContextFunc func(accessor context.LeadershipSettingsAccessor, tracker leadership.Tracker, unitName string) context.LeadershipContext

LeadershipContextFunc is a function that returns a leadership context.

type Logger

type Logger interface {
	Errorf(string, ...interface{})
	Warningf(string, ...interface{})
	Infof(string, ...interface{})
	Debugf(string, ...interface{})
	Tracef(string, ...interface{})
	IsTraceEnabled() bool
}

Logger represents the logging methods used in this package.

type Relation

type Relation interface {
	// Endpoint returns the endpoint of the relation for the application the
	// uniter's managed unit belongs to.
	Endpoint() (*uniter.Endpoint, error)

	// Id returns the integer internal relation key. This is exposed
	// because the unit agent needs to expose a value derived from this
	// (as JUJU_RELATION_ID) to allow relation hooks to differentiate
	// between relations with different applications.
	Id() int

	// Life returns the relation's current life state.
	Life() life.Value

	// OtherApplication returns the name of the application on the other
	// end of the relation (from this unit's perspective).
	OtherApplication() string

	// Refresh refreshes the contents of the relation from the underlying
	// state. It returns an error that satisfies errors.IsNotFound if the
	// relation has been removed.
	Refresh() error

	// SetStatus updates the status of the relation.
	SetStatus(relation.Status) error

	// String returns the relation as a string.
	String() string

	// Suspended returns the relation's current suspended status.
	Suspended() bool

	// Tag returns the relation tag.
	Tag() names.RelationTag

	// Unit returns a uniter.RelationUnit for the supplied unit.
	Unit(names.UnitTag) (RelationUnit, error)

	// UpdateSuspended updates the in memory value of the
	// relation's suspended attribute.
	UpdateSuspended(bool)
}

Relation encapsulates the methods from state.Relation required by a relationStateTracker.

type RelationStateTracker

type RelationStateTracker interface {
	// PrepareHook returns the name of the supplied relation hook, or an error
	// if the hook is unknown or invalid given current state.
	PrepareHook(hook.Info) (string, error)

	// CommitHook persists the state change encoded in the supplied relation
	// hook, or returns an error if the hook is unknown or invalid given
	// current relation state.
	CommitHook(hook.Info) error

	// SynchronizeScopes ensures that the locally tracked relation scopes
	// reflect the contents of the remote state snapshot by entering or
	// exiting scopes as required.
	SynchronizeScopes(remotestate.Snapshot) error

	// IsKnown returns true if the relation ID is known by the tracker.
	IsKnown(int) bool

	// IsImplicit returns true if the endpoint for a relation ID is implicit.
	IsImplicit(int) (bool, error)

	// IsPeerRelation returns true if the endpoint for a relation ID has a
	// Peer role.
	IsPeerRelation(int) (bool, error)

	// HasContainerScope returns true if the specified relation ID has a
	// container scope.
	HasContainerScope(int) (bool, error)

	// RelationCreated returns true if a relation created hook has been
	// fired for the specified relation ID.
	RelationCreated(int) bool

	// RemoteApplication returns the remote application name associated
	// with the specified relation ID.
	RemoteApplication(int) string

	// State returns a State instance for accessing the local state
	// for a relation ID.
	State(int) (*State, error)

	// StateFound returns a true if there is a state for the given in
	// in the state manager.
	StateFound(int) bool

	// GetInfo returns information about current relation state.
	GetInfo() map[int]*context.RelationInfo

	// Name returns the name of the relation with the supplied id, or an error
	// if the relation is unknown.
	Name(id int) (string, error)

	// LocalUnitName returns the name for the local unit.
	LocalUnitName() string

	// LocalUnitAndApplicationLife returns the life values for the local
	// unit and application.
	LocalUnitAndApplicationLife() (life.Value, life.Value, error)

	// Report provides information for the engine report.
	Report() map[string]interface{}
}

func NewRelationStateTracker

func NewRelationStateTracker(cfg RelationStateTrackerConfig) (RelationStateTracker, error)

NewRelationStateTracker returns a new RelationStateTracker instance.

type RelationStateTrackerConfig

type RelationStateTrackerConfig struct {
	State                *uniter.State
	Unit                 *uniter.Unit
	Tracker              leadership.Tracker
	CharmDir             string
	NewLeadershipContext LeadershipContextFunc
	Abort                <-chan struct{}
	Logger               Logger
}

RelationStateTrackerConfig contains configuration values for creating a new RelationStateTracker instance.

type RelationUnit

type RelationUnit interface {
	// ApplicationSettings returns a Settings which allows access to this
	// unit's application settings within the relation. This can only be
	// used from the leader unit.
	ApplicationSettings() (*uniter.Settings, error)

	// Endpoint returns the endpoint of the relation for the application the
	// uniter's managed unit belongs to.
	Endpoint() uniter.Endpoint

	// EnterScope ensures that the unit has entered its scope in the relation.
	// When the unit has already entered its relation scope, EnterScope will
	// report success but make no changes to state.
	EnterScope() error

	// LeaveScope signals that the unit has left its scope in the relation.
	// After the unit has left its relation scope, it is no longer a member
	// of the relation.
	LeaveScope() error

	// Relation returns the relation associated with the unit.
	Relation() Relation

	// ReadSettings returns a map holding the settings of the unit with the
	// supplied name within this relation.
	ReadSettings(name string) (params.Settings, error)

	// Settings returns a Settings which allows access to the unit's settings
	// within the relation.
	Settings() (*uniter.Settings, error)

	// UpdateRelationSettings is used to record any changes to settings for
	// this unit and application. It is only valid to update application
	// settings if this unit is the leader.
	UpdateRelationSettings(unit, application params.Settings) error
}

RelationUnit encapsulates the methods from state.RelationUnit required by a relationer.

type RelationUnitShim

type RelationUnitShim struct {
	*uniter.RelationUnit
}

func (*RelationUnitShim) Relation

func (r *RelationUnitShim) Relation() Relation

type Relationer

type Relationer interface {
	// CommitHook persists the fact of the supplied hook's completion.
	CommitHook(hi hook.Info) error

	// ContextInfo returns a representation of the relationer's current state.
	ContextInfo() *context.RelationInfo

	// IsDying returns whether the relation is dying.
	IsDying() bool

	// IsImplicit returns whether the local relation endpoint is implicit.
	IsImplicit() bool

	// Join initializes local state and causes the unit to enter its relation
	// scope, allowing its counterpart units to detect its presence and settings
	// changes.
	Join() error

	// PrepareHook checks that the relation is in a state such that it makes
	// sense to execute the supplied hook, and ensures that the relation context
	// contains the latest relation state as communicated in the hook.Info.
	PrepareHook(hi hook.Info) (string, error)

	// RelationUnit returns the relation unit associated with this relationer instance.
	RelationUnit() RelationUnit

	// SetDying informs the relationer that the unit is departing the relation,
	// and that the only hooks it should send henceforth are -departed hooks,
	// until the relation is empty, followed by a -broken hook.
	SetDying() error
}

Relationer encapsulates the methods from relationer required by a stateTracker.

func NewRelationer

func NewRelationer(ru RelationUnit, stateMgr StateManager, unitGetter UnitGetter, logger Logger) Relationer

NewRelationer creates a new relationer. The unit will not join the relation until explicitly requested.

type State

type State struct {
	// RelationId identifies the relation.
	// Do not use omitempty, 0 is a valid id.
	RelationId int `yaml:"id"`

	// Members is a map from unit name to the last change version
	// for which a hook.Info was delivered on the output channel.
	// keys must be in the form <application name>-<unit number>
	// to match RemoteUnits in HookInfo.
	Members map[string]int64 `yaml:"members,omitempty"`

	// ApplicationMembers is a map from application name to the last change
	// version for which a hook.Info was delivered
	ApplicationMembers map[string]int64 `yaml:"application-members,omitempty"`

	// ChangedPending indicates that a "relation-changed" hook for the given
	// unit name must be the first hook.Info to be sent to the output channel.
	ChangedPending string `yaml:"changed-pending,omitempty"`
}

State describes the state of a relation.

func NewState

func NewState(relationId int) *State

NewState returns an initial State for relationId.

func (*State) UnmarshalYAML

func (s *State) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements the yaml.Unmarshaler interface.

func (*State) UpdateStateForHook

func (s *State) UpdateStateForHook(hi hook.Info, logger Logger)

UpdateStateForHook updates the current relation state with changes in hi. It must be called after the respective hook was executed successfully. UpdateStateForHook doesn't validate hi but guarantees that successive changes of the same hi are idempotent.

func (*State) Validate

func (s *State) Validate(hi hook.Info) (err error)

Validate returns an error if the supplied hook.Info does not represent a valid change to the relation state. Hooks must always be validated against the current state before they are run, to ensure that the system meets its guarantees about hook execution order.

func (*State) YamlString

func (s *State) YamlString() (string, error)

type StateManager

type StateManager interface {
	// KnownIDs returns a slice of relation ids, known to the
	// state manager.
	KnownIDs() []int

	// Relation returns a copy of the relation state for the given id.
	Relation(int) (*State, error)

	// SetRelation persists the given state, overwriting the previous
	// state for a given id or creating state at a new id.
	SetRelation(*State) error

	// RelationFound returns true if the state manager has a
	// state for the given id.
	RelationFound(id int) bool

	// RemoveRelation removes the state for the given id from the
	// manager.
	RemoveRelation(id int, unitGetter UnitGetter, knownUnits map[string]bool) error
}

StateManager encapsulates methods required to handle relation state.

func NewStateManager

func NewStateManager(rw UnitStateReadWriter, logger Logger) (StateManager, error)

NewStateManager creates a new StateManager instance.

type StateTrackerState

type StateTrackerState interface {
	// Unit returns the existing unit with the given tag.
	Unit(tag names.UnitTag) (Unit, error)

	// Relation returns the existing relation with the given tag.
	Relation(tag names.RelationTag) (Relation, error)

	// RelationById returns the existing relation with the given id.
	RelationById(int) (Relation, error)
}

StateTrackerState encapsulates the methods from state required by a relationStateTracker.

type SubordinateDestroyer

type SubordinateDestroyer interface {
	DestroyAllSubordinates() error
}

SubordinateDestroyer destroys all subordinates of a unit.

type Unit

type Unit interface {
	UnitStateReadWriter

	// Tag returns the tag for this unit.
	Tag() names.UnitTag

	// ApplicationTag returns the tag for this unit's application.
	ApplicationTag() names.ApplicationTag

	// RelationsStatus returns the tags of the relations the unit has joined
	// and entered scope, or the relation is suspended.
	RelationsStatus() ([]uniter.RelationStatus, error)

	// Watch returns a watcher for observing changes to the unit.
	Watch() (watcher.NotifyWatcher, error)

	// Destroy when called on a Alive unit, advances its lifecycle as far as
	// possible; it otherwise has no effect. In most situations, the unit's
	// life is just set to Dying; but if a principal unit that is not assigned
	// to a provisioned machine is Destroyed, it will be removed from state
	// directly.
	Destroy() error

	// Name returns the name of the unit.
	Name() string

	// Refresh updates the cached local copy of the unit's data.
	Refresh() error

	// Application returns the unit's application.
	Application() (Application, error)

	// Life returns the unit's lifecycle value.
	Life() life.Value
}

Unit encapsulates the methods from state.Unit required by a relationStateTracker.

type UnitGetter

type UnitGetter interface {
	// Unit returns the existing unit with the given tag.
	Unit(tag names.UnitTag) (Unit, error)
}

UnitGetter encapsulates methods to get unit info.

type UnitStateReadWriter

type UnitStateReadWriter interface {
	// SetState sets the state persisted by the charm running in this unit
	// and the state internal to the uniter for this unit.
	SetState(unitState params.SetUnitStateArg) error

	// State returns the state persisted by the charm running in this unit
	// and the state internal to the uniter for this unit.
	State() (params.UnitStateResult, error)
}

UnitStateReadWriter encapsulates the methods from a state.Unit required to set and get unit state.