juju: github.com/juju/juju/worker/uniter/relation Index | Files | Directories

package relation

import "github.com/juju/juju/worker/uniter/relation"

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

Index

Package Files

interface.go relationer.go resolver.go shim.go state.go statemanager.go statetracker.go

func NewCreatedRelationResolver Uses

func NewCreatedRelationResolver(stateTracker RelationStateTracker) resolver.Resolver

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

func NewRelationResolver Uses

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.

type Application Uses

type Application interface {
    Life() life.Value
}

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

type LeadershipContextFunc Uses

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

LeadershipContextFunc is a function that returns a leadership context.

type Logger Uses

type Logger interface {
    Errorf(string, ...interface{})
    Warningf(string, ...interface{})
    Infof(string, ...interface{})
}

Logger represents the logging methods used in this package.

type Relation Uses

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 Uses

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

    // SyncronizeScopes 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)
}

func NewRelationStateTracker Uses

func NewRelationStateTracker(cfg RelationStateTrackerConfig) (RelationStateTracker, error)

NewRelationStateTracker returns a new RelationStateTracker instance.

type RelationStateTrackerConfig Uses

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 RlationStateTracker instance.

type RelationUnit Uses

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 Uses

type RelationUnitShim struct {
    *uniter.RelationUnit
}

func (*RelationUnitShim) Relation Uses

func (r *RelationUnitShim) Relation() Relation

type Relationer Uses

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 Uses

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

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

type State Uses

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 Uses

func NewState(relationId int) *State

NewState returns an initial State for relationId.

func (*State) UnmarshalYAML Uses

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

UnmarshalYAML implements the yaml.Unmarshaler interface.

func (*State) UpdateStateForHook Uses

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

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 Uses

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 Uses

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

type StateManager Uses

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) error
}

StateManager encapsulates methods required to handle relation state.

func NewStateManager Uses

func NewStateManager(rw UnitStateReadWriter) (StateManager, error)

NewStateManager

type StateTrackerState Uses

type StateTrackerState interface {
    // 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 Uses

type SubordinateDestroyer interface {
    DestroyAllSubordinates() error
}

SubordinateDestroyer destroys all subordinates of a unit.

type Unit Uses

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 UnitStateReadWriter Uses

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.

Directories

PathSynopsis
mocksPackage mocks is a generated GoMock package.

Package relation imports 21 packages (graph) and is imported by 49 packages. Updated 2020-08-13. Refresh now. Tools for package owners.