leadership

Documentation

Overview

Package leadership holds code pertaining to application leadership in juju. It's expected to grow as we're able to extract (e.g.) the Ticket and Tracker interfaces from worker/leadership; and quite possible the implementations themselves; but that'll have to wait until it can all be expressed without reference to non-core code.

Index

• Constants
• func IsNotLeaderError(err error) bool
• func NewNotLeaderError(unit, application string) error
• type Checker
• type Claimer
• type Pinner
• type Reader
• type Revoker
• type Ticket
• type Token
• type Tracker
• type TrackerWorker

Constants

const (
	// ErrClaimDenied is the error which will be returned when a
	// leadership claim has been denied.
	ErrClaimDenied = errors.ConstError("leadership claim denied")

	// ErrClaimNotHeld is the error which will be returned when a
	// leadership lease is not held.
	ErrClaimNotHeld = errors.ConstError("leadership lease not held")

	// ErrBlockCancelled is returned from BlockUntilLeadershipReleased
	// if the client cancels the request by closing the cancel channel.
	ErrBlockCancelled = errors.ConstError("waiting for leadership cancelled by client")
)

Functions

func IsNotLeaderError

func IsNotLeaderError(err error) bool

IsNotLeaderError returns whether this error represents a token check that failed because the unit in question wasn't the leader.

func NewNotLeaderError

func NewNotLeaderError(unit, application string) error

NewNotLeaderError returns an error indicating that this unit is not the leader of that application.

Types

type Checker

type Checker interface {

	// LeadershipCheck returns a Token representing the supplied unit's
	// application leadership. The existence of the token does not imply
	// its accuracy; you need to Check() it.
	//
	// This method returns a token that accepts a *[]txn.Op, into which
	// it will (on success) copy mgo/txn operations that can be used to
	// verify the unit's continued leadership as part of another txn.
	LeadershipCheck(applicationId, unitId string) Token
}

Checker exposes leadership testing capabilities.

type Claimer

type Claimer interface {

	// ClaimLeadership claims leadership of the named application on behalf of the
	// named unit. If no error is returned, leadership will be guaranteed for
	// at least the supplied duration from the point when the call was made.
	ClaimLeadership(ctx context.Context, applicationId, unitId string, duration time.Duration) error

	// BlockUntilLeadershipReleased blocks until the named application is known
	// to have no leader, in which case it returns no error; or until the
	// manager is stopped, in which case it will fail.
	BlockUntilLeadershipReleased(ctx context.Context, applicationId string) (err error)
}

Claimer exposes leadership acquisition capabilities.

type Pinner

type Pinner interface {

	// PinLeadership ensures that the leadership of the input application will
	// not expire. The input entity records the party responsible for the
	// pinning operation.
	PinLeadership(applicationId string, entity string) error

	// UnpinLeadership reverses a PinLeadership operation for the same
	// application and entity. Normal expiry behaviour is restored when no
	// entities remain with pins for the application.
	UnpinLeadership(applicationId string, entity string) error

	// PinnedLeadership returns a map keyed on pinned application names,
	// with entities that require the application's pinned behaviour.
	PinnedLeadership() (map[string][]string, error)
}

Pinner describes methods used to manage suspension of application leadership expiry. All methods should be idempotent.

type Reader

type Reader interface {

	// Leaders returns all application leaders in the current model.
	// TODO (manadart 2019-02-27): The return in this signature includes error
	// in order to support state.ApplicationLeaders for legacy leases.
	// When legacy leases are removed, so can the error return.
	Leaders() (map[string]string, error)
}

Reader describes the capability to read the current state of leadership.

type Revoker

type Revoker interface {
	// RevokeLeadership revokes leadership of the named application
	// on behalf of the named unit.
	RevokeLeadership(applicationName string, unitName unit.Name) error
}

Revoker exposes leadership revocation capabilities.

type Ticket

type Ticket interface {

	// Wait returns true if its Tracker is prepared to guarantee leadership
	// for some period from the ticket request. The guaranteed duration depends
	// upon the Tracker.
	Wait() bool

	// Ready returns a channel that will be closed when a result is available
	// to Wait(), and is helpful for clients that want to select rather than
	// block on long-waiting tickets.
	Ready() <-chan struct{}
}

Ticket is used to communicate leadership status to Tracker clients.

type Token

type Token interface {
	// Check returns an error if the condition it embodies no longer holds.
	Check() error
}

Token represents a unit's leadership of its application.

type Tracker

type Tracker interface {

	// ApplicationName returns the name of the application for which leadership claims
	// are made.
	ApplicationName() string

	// ClaimDuration returns the duration for which a Ticket's true Wait result
	// is guaranteed valid.
	ClaimDuration() time.Duration

	// ClaimLeader will return a Ticket which, when Wait()ed for, will return
	// true if leadership is guaranteed for at least the tracker's duration from
	// the time the ticket was issued. Leadership claims should be resolved
	// relatively quickly.
	ClaimLeader() Ticket

	// WaitLeader will return a Ticket which, when Wait()ed for, will block
	// until the tracker attains leadership.
	WaitLeader() Ticket

	// WaitMinion will return a Ticket which, when Wait()ed for, will block
	// until the tracker's future leadership can no longer be guaranteed.
	WaitMinion() Ticket
}

Tracker allows clients to discover current leadership status by attempting to claim it for themselves.

type TrackerWorker

type TrackerWorker interface {
	worker.Worker
	Tracker
}

TrackerWorker represents a leadership tracker worker.