lock

type AcquireAnyLockInput struct {
	// Keys is required
	Keys []string
	// Owner is Required
	Owner string

	// RandomizeOrder is optional (defaults to false). If true, Locker will attempt to lock each key in a random order.
	RandomizeOrder *bool

	// Exactly one of LeaseEnd and LeaseDuration should be provided, the other nil
	// LeaseEnd is the time at which the lease should expire.
	LeaseEnd *time.Time
	// LeaseDuration is a convenience field that will be converted into a LeaseEnd by adding it to time.Now() before sending to the backend
	LeaseDuration *time.Duration
}

type AcquireLockInput struct {
	// Key is required
	Key string
	// Owner is required
	Owner string

	// Exactly one of LeaseEnd and LeaseDuration should be provided, the other nil
	// LeaseEnd is the time at which the lease should expire.
	LeaseEnd *time.Time
	// LeaseDuration is a convenience field that will be converted into a LeaseEnd by adding it to time.Now() before sending to the backend
	LeaseDuration *time.Duration
}

type HeartbeatLockInput struct {
	// Note that the LeasedUntil field is ignored, but Owner and Key must be correct.
	OriginalLock Lock

	// Exactly one of LeaseEnd and LeaseDuration should be provided, the other nil
	// They work the same as in AcquireLockInput
	// LeaseEnd is the time at which the lease should expire.
	LeaseEnd *time.Time
	// LeaseDuration is a convenience field that will be converted into a LeaseEnd by adding it to time.Now() before sending to the backend
	LeaseDuration *time.Duration
}

type Lock struct {
	// Note: these struct tags need to match the values for attribute names in lock.go
	Key         string    `dynamodbav:"key"`
	Owner       string    `dynamodbav:"owner"`
	LeasedUntil time.Time `dynamodbav:"leasedUntil"`
	CreatedAt   time.Time `dynamodbav:"createdAt"`
	TTL         time.Time `dynamodbav:"ttl"`
}

type Locker interface {
	// AcquireLock attepts to get the lock for a given input key. A lock can be acquired if there is not an active lease by a different owner.
	// If there is an active lease by the same owner as provided in the input, Acquire will succeed and the active lease will be replaced by input's lease.
	// Key and Owner are required inputs, as well as exactly one of LeaseEnd or LeaseDuration
	// If LeaseDuration is provided, it will be converted into a LeaseEnd before sending the request to the backend.
	// Returns either a non-nil Lock and a nil error, or a nil lock and non-nil error.
	// The error will be of type UnavailableError when there is an active lease on the key by a different owner.
	// Other errors may indicate e.g. a network problem talking to the backend, a validation error in the input, etc.
	AcquireLock(ctx context.Context, input AcquireLockInput) (*Lock, error)

	// AcquireAnyLock is a thin wrapper around AcquireLock for attepting to lock any one of a list of keys.
	// Underneath, it simply attempts to lock them one at a time and returns the first successful lock or an error.
	// It returns UnavailableError only when every single key was unavailable.
	AcquireAnyLock(ctx context.Context, input AcquireAnyLockInput) (*Lock, error)

	// HeartbeatLock is similar to AcquireLock except that it also fails if another owner held the lock in between acquiring the original lock and now, even if they have since released it.
	// In particular, Heartbeat succeeds in refreshing the lock if the lock's lease has expired but no one else used the lock in the mean time.
	HeartbeatLock(ctx context.Context, input HeartbeatLockInput) (*Lock, error)

	// StartBackgroundHeartbeats starts a goroutine to heartbeat the lock at set intervals.
	// It can be used to extend a lease during a long-running execution.
	// It stops if its context is cancelled, or if it gets an error. It reports the error via returned channel.
	// The lock pointer passed to it will be updated each time the heartbeat succeeds.
	// Since the lock isn't behind a mutex, take care if updating it manually after calling this.
	StartBackgroundHeartbeats(ctx context.Context, lockPointer *Lock, heartbeatInterval time.Duration, leaseDuration time.Duration) <-chan error

	// A lock can be released so long as it isn't owned by someone else i.e. if lock.Owner could acquire the lock.
	// That means that is is NOT an error to release a lock that wasn't owned by anyone.
	// An error means that the lock was NOT released. Either it is currently held by someone else, or there was a system error trying to release the lock.
	// If the lock is held by someone else, that's generally not retryable, and that is represented by the error type UnavailableError. In this case, the caller can be certain that the caller does not still hold the lock.
	// Any other error type could indicate that caller still holds the lock e.g. if there were a dynamo system error.
	ReleaseLock(ctx context.Context, lock Lock) error

	// GetCurrentLock will return the current lock for a key.  This is meant to help troubleshoot lock starvation.
	// If there is no lock, nil will be returned for both lock and error
	// This should not be used to "pre-check" for a lock as AcquireLock may still fail.
	GetCurrentLock(ctx context.Context, key string) (*Lock, error)
}

type UnavailableError struct {
	Err error
}