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.Logger) resolver.Resolver
• func NewRelationResolver(stateTracker RelationStateTracker, subordinateDestroyer SubordinateDestroyer, ...) resolver.Resolver
• type Application
• type RelationStateTracker
  • func NewRelationStateTracker(ctx stdcontext.Context, cfg RelationStateTrackerConfig) (RelationStateTracker, error)
• type RelationStateTrackerConfig
• type Relationer
  • func NewRelationer(ru api.RelationUnit, stateMgr StateManager, unitGetter UnitGetter, ...) Relationer
• type State
  • func NewState(relationId int) *State
  • func (s *State) UnmarshalYAML(unmarshal func(interface{}) error) error
  • func (s *State) UpdateStateForHook(hi hook.Info, log logger.Logger)
  • func (s *State) Validate(hi hook.Info) (err error)
  • func (s *State) YamlString() (string, error)
• type StateManager
  • func NewStateManager(ctx context.Context, rw UnitStateReadWriter, logger logger.Logger) (StateManager, error)
• type StateTrackerClient
• type SubordinateDestroyer
• type UnitGetter
• type UnitStateReadWriter

Functions

func NewCreatedRelationResolver

func NewCreatedRelationResolver(stateTracker RelationStateTracker, logger 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.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 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(stdcontext.Context, 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(stdcontext.Context, 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(stdcontext.Context) (life.Value, life.Value, error)

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

func NewRelationStateTracker

func NewRelationStateTracker(ctx stdcontext.Context, cfg RelationStateTrackerConfig) (RelationStateTracker, error)

NewRelationStateTracker returns a new RelationStateTracker instance.

type RelationStateTrackerConfig

type RelationStateTrackerConfig struct {
	Client            StateTrackerClient
	Unit              api.Unit
	CharmDir          string
	LeadershipContext context.LeadershipContext
	Abort             <-chan struct{}
	Logger            logger.Logger
}

RelationStateTrackerConfig contains configuration values for creating a new RelationStateTracker instance.

type Relationer

type Relationer interface {
	// CommitHook persists the fact of the supplied hook's completion.
	CommitHook(ctx stdcontext.Context, 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(ctx stdcontext.Context) 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() api.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(ctx stdcontext.Context) error
}

Relationer encapsulates the methods from relationer required by a stateTracker.

func NewRelationer

func NewRelationer(ru api.RelationUnit, stateMgr StateManager, unitGetter UnitGetter, logger 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, log 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(stdcontext.Context, *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(ctx stdcontext.Context, id int, unitGetter UnitGetter, knownUnits map[string]bool) error
}

StateManager encapsulates methods required to handle relation state.

func NewStateManager

func NewStateManager(ctx context.Context, rw UnitStateReadWriter, logger logger.Logger) (StateManager, error)

NewStateManager creates a new StateManager instance.

type StateTrackerClient

type StateTrackerClient interface {
	// Unit returns the existing unit with the given tag.
	Unit(ctx stdcontext.Context, tag names.UnitTag) (api.Unit, error)

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

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

StateTrackerClient encapsulates the uniter client API methods required by a relationStateTracker.

type SubordinateDestroyer

type SubordinateDestroyer interface {
	DestroyAllSubordinates(stdcontext.Context) error
}

SubordinateDestroyer destroys all subordinates of a unit.

type UnitGetter

type UnitGetter interface {
	// Unit returns the existing unit with the given tag.
	Unit(ctx stdcontext.Context, tag names.UnitTag) (api.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(ctx stdcontext.Context, 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(ctx stdcontext.Context) (params.UnitStateResult, error)
}

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