github.com/juju/juju@v0.0.0-20240327075706-a90865de2538/core/lease/interface.go (about)

     1  // Copyright 2015 Canonical Ltd.
     2  // Licensed under the AGPLv3, see LICENCE file for details.
     3  
     4  package lease
     5  
     6  import (
     7  	"time"
     8  )
     9  
    10  const (
    11  	// ApplicationLeadershipNamespace is the namespace used to manage
    12  	// leadership leases.
    13  	ApplicationLeadershipNamespace = "application-leadership"
    14  
    15  	// SingularControllerNamespace is the namespace used to manage
    16  	// controller leases.
    17  	SingularControllerNamespace = "singular-controller"
    18  )
    19  
    20  // Claimer exposes lease acquisition and expiry notification capabilities.
    21  type Claimer interface {
    22  
    23  	// Claim acquires or extends the named lease for the named holder. If it
    24  	// succeeds, the holder is guaranteed to keep the lease until at least
    25  	// duration after the *start* of the call. If it returns ErrClaimDenied,
    26  	// the holder is guaranteed not to have the lease. If it returns any other
    27  	// error, no reasonable inferences may be made.
    28  	Claim(leaseName, holderName string, duration time.Duration) error
    29  
    30  	// WaitUntilExpired returns nil when the named lease is no longer held. If it
    31  	// returns any error, no reasonable inferences may be made. If the supplied
    32  	// cancel channel is non-nil, it can be used to cancel the request; in this
    33  	// case, the method will return ErrWaitCancelled.
    34  	WaitUntilExpired(leaseName string, cancel <-chan struct{}) error
    35  }
    36  
    37  // Revoker exposes lease revocation capabilities.
    38  type Revoker interface {
    39  	// Revoke releases the named lease for the named holder.
    40  	Revoke(leaseName, holderName string) error
    41  }
    42  
    43  // Pinner describes methods used to manage suspension of lease expiry.
    44  type Pinner interface {
    45  
    46  	// Pin ensures that the current holder of input lease name will not lose
    47  	// the lease to expiry.
    48  	// If there is no current holder of the lease, the next claimant will be
    49  	// the recipient of the pin behaviour.
    50  	// The input entity denotes the party responsible for the
    51  	// pinning operation.
    52  	Pin(leaseName string, entity string) error
    53  
    54  	// Unpin reverses a Pin operation for the same application and entity.
    55  	// Normal expiry behaviour is restored when no entities remain with
    56  	// pins for the application.
    57  	Unpin(leaseName string, entity string) error
    58  
    59  	// Pinned returns all names for pinned leases, with the entities requiring
    60  	// their pinned behaviour.
    61  	Pinned() (map[string][]string, error)
    62  }
    63  
    64  // Checker exposes facts about lease ownership.
    65  type Checker interface {
    66  
    67  	// Token returns a Token that can be interrogated at any time to discover
    68  	// whether the supplied lease is currently held by the supplied holder.
    69  	Token(leaseName, holderName string) Token
    70  }
    71  
    72  // Token represents a fact -- but not necessarily a *true* fact -- about some
    73  // holder's ownership of some lease.
    74  type Token interface {
    75  	// Check returns ErrNotHeld if the lease it represents is not held
    76  	// by the holder it represents.
    77  	Check() error
    78  }
    79  
    80  // Reader describes retrieval of all leases and holders
    81  // for a known namespace and model.
    82  type Reader interface {
    83  	Leases() (map[string]string, error)
    84  }
    85  
    86  // Manager describes methods for acquiring objects that manipulate and query
    87  // leases for different models.
    88  type Manager interface {
    89  	Checker(namespace string, modelUUID string) (Checker, error)
    90  	Claimer(namespace string, modelUUID string) (Claimer, error)
    91  	Revoker(namespace string, modelUUID string) (Revoker, error)
    92  	Pinner(namespace string, modelUUID string) (Pinner, error)
    93  	Reader(namespace string, modelUUID string) (Reader, error)
    94  }