lease

Documentation

Index

• Constants
• func IsAborted(err error) bool
• func IsHeld(err error) bool
• func IsInvalid(err error) bool
• func IsNotHeld(err error) bool
• func IsTimeout(err error) bool
• func ValidateString(s string) error
• type Checker
• type Claimer
• type Info
• type Key
• type Manager
• type Pinner
• type Reader
• type Request
  • func (request Request) Validate() error
• type Revoker
• type Store
• type Token

Constants

const (
	// ErrClaimDenied indicates that a Claimer.Claim() has been denied.
	ErrClaimDenied = errors.ConstError("lease claim denied")

	// ErrNotHeld indicates that some holder does not hold some lease.
	ErrNotHeld = errors.ConstError("lease not held")

	// ErrWaitCancelled is returned by Claimer.WaitUntilExpired if the
	// cancel channel is closed.
	ErrWaitCancelled = errors.ConstError("waiting for lease cancelled by client")

	// ErrInvalid indicates that a Store operation failed because latest state
	// indicates that it's a logical impossibility. It's a short-range signal to
	// calling code only; that code should never pass it on, but should inspect
	// the Store's updated Leases() and either attempt a new operation or return
	// a new error at a suitable level of abstraction.
	ErrInvalid = errors.ConstError("invalid lease operation")

	// ErrHeld indicates that a claim operation was impossible to fulfill
	// because the lease has been claimed on behalf of another entity.
	// This operation should not be retried.
	ErrHeld = errors.ConstError("lease already held")

	// ErrTimeout indicates that a Store operation failed because it
	// couldn't update the underlying lease information. This is probably
	// a transient error due to changes in the cluster, and indicates that
	// the operation should be retried.
	ErrTimeout = errors.ConstError("lease operation timed out")

	// ErrAborted indicates that the stop channel returned before the operation
	// succeeded or failed.
	ErrAborted = errors.ConstError("lease operation aborted")
)

const (
	// ApplicationLeadershipNamespace is the namespace used to manage
	// leadership leases.
	ApplicationLeadershipNamespace = "application-leadership"

	// SingularControllerNamespace is the namespace used to manage
	// controller leases.
	SingularControllerNamespace = "singular-controller"
)

Functions

func IsAborted

func IsAborted(err error) bool

IsAborted returns whether the specified error represents ErrAborted (even if it's wrapped).

func IsHeld

func IsHeld(err error) bool

IsHeld returns whether the specified error represents ErrHeld (even if it's wrapped).

func IsInvalid

func IsInvalid(err error) bool

IsInvalid returns whether the specified error represents ErrInvalid (even if it's wrapped).

func IsNotHeld

func IsNotHeld(err error) bool

IsNotHeld returns whether the specified error represents ErrNotHeld (even if it's wrapped).

func IsTimeout

func IsTimeout(err error) bool

IsTimeout returns whether the specified error represents ErrTimeout (even if it's wrapped).

func ValidateString

func ValidateString(s string) error

ValidateString returns an error if the string is empty, or if it contains whitespace, or if it contains any character in `.#$`. Store implementations are expected to always reject invalid strings, and never to produce them.

Types

type Checker

type Checker interface {

	// Token returns a Token that can be interrogated at any time to discover
	// whether the supplied lease is currently held by the supplied holder.
	Token(leaseName, holderName string) Token
}

Checker exposes facts about lease ownership.

type Claimer

type Claimer interface {

	// Claim acquires or extends the named lease for the named holder. If it
	// succeeds, the holder is guaranteed to keep the lease until at least
	// duration after the *start* of the call. If it returns ErrClaimDenied,
	// the holder is guaranteed not to have the lease. If it returns any other
	// error, no reasonable inferences may be made.
	Claim(leaseName, holderName string, duration time.Duration) error

	// WaitUntilExpired returns nil when the named lease is no longer held. If it
	// returns any error, no reasonable inferences may be made. If the supplied
	// cancel channel is non-nil, it can be used to cancel the request; in this
	// case, the method will return ErrWaitCancelled.
	WaitUntilExpired(leaseName string, cancel <-chan struct{}) error
}

Claimer exposes lease acquisition and expiry notification capabilities.

type Info

type Info struct {
	// Holder is the name of the current leaseholder.
	Holder string

	// Expiry is the latest time at which it's possible the lease might still
	// be valid. Attempting to expire the lease before this time will fail.
	Expiry time.Time
}

Info holds substrate-independent information about a lease.

type Key

type Key struct {
	Namespace string
	ModelUUID string
	Lease     string
}

Key fully identifies a lease, including the namespace and model it belongs to.

type Manager

type Manager interface {
	Checker(namespace string, modelUUID string) (Checker, error)
	Claimer(namespace string, modelUUID string) (Claimer, error)
	Revoker(namespace string, modelUUID string) (Revoker, error)
	Pinner(namespace string, modelUUID string) (Pinner, error)
	Reader(namespace string, modelUUID string) (Reader, error)
}

Manager describes methods for acquiring objects that manipulate and query leases for different models.

type Pinner

type Pinner interface {

	// Pin ensures that the current holder of input lease name will not lose
	// the lease to expiry.
	// If there is no current holder of the lease, the next claimant will be
	// the recipient of the pin behaviour.
	// The input entity denotes the party responsible for the
	// pinning operation.
	Pin(leaseName string, entity string) error

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

	// Pinned returns all names for pinned leases, with the entities requiring
	// their pinned behaviour.
	Pinned() (map[string][]string, error)
}

Pinner describes methods used to manage suspension of lease expiry.

type Reader

type Reader interface {
	Leases() (map[string]string, error)
}

Reader describes retrieval of all leases and holders for a known namespace and model.

type Request

type Request struct {

	// Holder identifies the lease holder.
	Holder string

	// Duration specifies the time for which the lease is required.
	Duration time.Duration
}

Request describes a lease request.

func (Request) Validate

func (request Request) Validate() error

Validate returns an error if any fields are invalid or inconsistent.

type Revoker

type Revoker interface {
	// Revoke releases the named lease for the named holder.
	Revoke(leaseName, holderName string) error
}

Revoker exposes lease revocation capabilities.

type Store

type Store interface {
	// ClaimLease records the supplied holder's claim to the supplied lease. If
	// it succeeds, the claim is guaranteed until at least the supplied duration
	// after the call to ClaimLease was initiated. If it returns ErrInvalid,
	// check Leases() for updated state.
	ClaimLease(ctx context.Context, lease Key, request Request) error

	// ExtendLease records the supplied holder's continued claim to the supplied
	// lease, if necessary. If it succeeds, the claim is guaranteed until at
	// least the supplied duration after the call to ExtendLease was initiated.
	// If it returns ErrInvalid, check Leases() for updated state.
	ExtendLease(ctx context.Context, lease Key, request Request) error

	// RevokeLease records the vacation of the supplied lease. It will fail if
	// the lease is not held by the holder.
	RevokeLease(ctx context.Context, lease Key, holder string) error

	// Leases returns a recent snapshot of lease state. Expiry times are
	// expressed according to the Clock the store was configured with.
	// Supplying any lease keys will filter the return for those requested.
	Leases(ctx context.Context, keys ...Key) (map[Key]Info, error)

	// LeaseGroup returns a snapshot of all of the leases for a
	// particular namespace/model combination. This is useful for
	// reporting holder information for a model, and can often be
	// implemented more efficiently than getting all leases when there
	// are many models.
	LeaseGroup(ctx context.Context, namespace, modelUUID string) (map[Key]Info, error)

	// PinLease ensures that the current holder of the lease for the input key
	// will not lose the lease to expiry.
	// If there is no current holder of the lease, the next claimant will be
	// the recipient of the pin behaviour.
	// The input entity denotes the party responsible for the
	// pinning operation.
	PinLease(ctx context.Context, lease Key, entity string) error

	// UnpinLease reverses a Pin operation for the same key and entity.
	// Normal expiry behaviour is restored when no entities remain with
	// pins for the application.
	UnpinLease(ctx context.Context, lease Key, entity string) error

	// Pinned returns a snapshot of pinned leases.
	// The return consists of each pinned lease and the collection of entities
	// requiring its pinned behaviour.
	Pinned(ctx context.Context) (map[Key][]string, error)
}

Store manipulates leases directly, and is most likely to be seen set on a worker/lease.ManagerConfig struct (and used by the Manager). Implementations of Store are not expected to be goroutine-safe.

type Token

type Token interface {
	// Check returns ErrNotHeld if the lease it represents is not held
	// by the holder it represents.
	Check() error
}

Token represents a fact -- but not necessarily a *true* fact -- about some holder's ownership of some lease.