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 ExpiryStore
- type Info
- type Key
- type LeaseManager
- type LeaseManagerGetter
- type Manager
- type ModelLeaseManagerGetter
- type Pinner
- type Reader
- type Request
- type Revoker
- type Secretary
- type SecretaryFinder
- type Store
- type Token
- type Waiter
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" // ObjectStoreNamespace is the namespace used to manage // object store files. ObjectStoreNamespace = "object-store" // BackupCreationNamespace serialises archive creation across the // controller. BackupCreationNamespace = "backup-creation" )
Variables ¶
This section is empty.
Functions ¶
func IsAborted ¶
IsAborted returns whether the specified error represents ErrAborted (even if it's wrapped).
func IsInvalid ¶
IsInvalid returns whether the specified error represents ErrInvalid (even if it's wrapped).
func IsNotHeld ¶
IsNotHeld returns whether the specified error represents ErrNotHeld (even if it's wrapped).
func IsTimeout ¶
IsTimeout returns whether the specified error represents ErrTimeout (even if it's wrapped).
func ValidateString ¶
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 {
Waiter
// 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 and expiry.
type Claimer ¶
type Claimer interface {
Waiter
// 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
}
Claimer exposes lease acquisition and expiry notification capabilities.
type ExpiryStore ¶
type ExpiryStore interface {
// ExpireLeases deletes all leases that have expired.
ExpireLeases(ctx context.Context) error
}
ExpiryStore defines a store for expiring leases.
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 LeaseManager ¶
LeaseManager is an interface that provides methods to manage leases for applications and units within a model.
type LeaseManagerGetter ¶
type LeaseManagerGetter interface {
// GetLeaseManager returns a lease manager for the given model UUID.
GetLeaseManager(model.UUID) (LeaseManager, error)
}
LeaseManagerGetter is an interface that provides a method to get a lease manager for a given lease using its UUID. The lease namespace could be a model or an application.
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 ModelLeaseManagerGetter ¶
type ModelLeaseManagerGetter interface {
// GetLeaseManager returns a lease manager for the given model UUID.
GetLeaseManager() (LeaseManager, error)
}
ModelLeaseManagerGetter is an interface that provides a method to get a lease manager in the scope of a model.
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 returns a map of lease names to their current holders.
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.
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 Secretary ¶
type Secretary interface {
// CheckLease returns an error if the supplied lease name is not valid.
CheckLease(key Key) error
// CheckHolder returns an error if the supplied holder name is not valid.
CheckHolder(name string) error
// CheckDuration returns an error if the supplied duration is not valid.
CheckDuration(duration time.Duration) error
}
Secretary is responsible for validating the sanity of lease and holder names before bothering the manager with them.
type SecretaryFinder ¶
type SecretaryFinder interface {
// SecretaryFor returns the Secretary for the given namespace.
// Returns an error if the namespace is not valid.
SecretaryFor(namespace string) (Secretary, error)
}
SecretaryFinder is responsible for returning the correct Secretary for a given namespace.
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.
type Waiter ¶
type Waiter interface {
// WaitUntilExpired returns nil when the named lease is no longer held. If
// it returns any error, no reasonable inferences may be made. The supplied
// context can be used to cancel the request; in this case, the method will
// return ErrWaitCancelled.
// The started channel when non-nil is closed when the wait begins.
WaitUntilExpired(ctx context.Context, leaseName string, started chan<- struct{}) error
}
Waiter exposes the lease expiry notification capabilities.