github.com/mhilton/juju-juju@v0.0.0-20150901100907-a94dd2c73455/state/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  	"github.com/juju/errors"
    10  	"gopkg.in/mgo.v2/txn"
    11  )
    12  
    13  // Client manipulates leases backed by MongoDB. Client implementations are not
    14  // expected to be goroutine-safe.
    15  type Client interface {
    16  
    17  	// ClaimLease records the supplied holder's claim to the supplied lease. If
    18  	// it succeeds, the claim is guaranteed until at least the supplied duration
    19  	// after the call to ClaimLease was initiated. If it returns ErrInvalid,
    20  	// check Leases() for updated state.
    21  	ClaimLease(lease string, request Request) error
    22  
    23  	// ExtendLease records the supplied holder's continued claim to the supplied
    24  	// lease, if necessary. If it succeeds, the claim is guaranteed until at
    25  	// least the supplied duration after the call to ExtendLease was initiated.
    26  	// If it returns ErrInvalid, check Leases() for updated state.
    27  	ExtendLease(lease string, request Request) error
    28  
    29  	// ExpireLease records the vacation of the supplied lease. It will fail if
    30  	// we cannot verify that the lease's writer considers the expiry time to
    31  	// have passed. If it returns ErrInvalid, check Leases() for updated state.
    32  	ExpireLease(lease string) error
    33  
    34  	// Leases returns a recent snapshot of lease state. Expiry times are
    35  	// expressed according to the Clock the client was configured with.
    36  	Leases() map[string]Info
    37  
    38  	// Refresh reads all lease state from the database.
    39  	Refresh() error
    40  }
    41  
    42  // Info holds information about a lease. It's MongoDB-specific, because it
    43  // includes information that can be used with the mgo/txn package to gate
    44  // transaction operations on lease state.
    45  type Info struct {
    46  
    47  	// Holder is the name of the current leaseholder.
    48  	Holder string
    49  
    50  	// Expiry is the latest time at which it's possible the lease might still
    51  	// be valid. Attempting to expire the lease before this time will fail.
    52  	Expiry time.Time
    53  
    54  	// AssertOp, if included in a mgo/txn transaction, will gate the transaction
    55  	// on the lease remaining held by Holder. If we didn't need this, we could
    56  	// easily implement Clients backed by other substrates.
    57  	AssertOp txn.Op
    58  }
    59  
    60  // Request describes a lease request.
    61  type Request struct {
    62  
    63  	// Holder identifies the lease holder.
    64  	Holder string
    65  
    66  	// Duration specifies the time for which the lease is required.
    67  	Duration time.Duration
    68  }
    69  
    70  // Validate returns an error if any fields are invalid or inconsistent.
    71  func (request Request) Validate() error {
    72  	if err := validateString(request.Holder); err != nil {
    73  		return errors.Annotatef(err, "invalid holder")
    74  	}
    75  	if request.Duration <= 0 {
    76  		return errors.Errorf("invalid duration")
    77  	}
    78  	return nil
    79  }
    80  
    81  // ErrInvalid indicates that a client operation failed because latest state
    82  // indicates that it's a logical impossibility. It's a short-range signal to
    83  // calling code only; that code should never pass it on, but should inspect
    84  // the Client's updated Leases() and either attempt a new operation or return
    85  // a new error at a suitable level of abstraction.
    86  var ErrInvalid = errors.New("invalid lease operation")