lock

type CtxMutex interface {

	// Lock will wait until either the mutex can be locked, or
	// the context is done (cancelled/deadlined). If the lock
	// succeeds, it will return nil. If the context is done,
	// it will return a stack-wrapped version of the context's error.
	Lock(ctx context.Context) (err stackerr.Error)

	// TryLock will attempt to lock the mutex, but will not
	// wait if it cannot immediately do so.
	TryLock() (locked bool)

	// Unlock will unlock the mutex, and will panic if the mutex
	// is not currently locked.
	Unlock()

	// TryUnlock will attempt to unlock the mutex, but will not
	// panic if the mutex is not currently locked.
	TryUnlock() (unlocked bool)
}

type DistributedLock interface {
	/*
		Unlock will release this lock.

		Arguments:

		ctx - the context to use for all operations in the unlock. If the context is cancelled,
		the unlock attempt will be cancelled and the expiry will eventually expire.

		Return Values:

		err - an error generated by this function
	*/
	Unlock(ctx context.Context) (err stackerr.Error)

	// Include all of the functions for lock data
	LockData
}

type DistributedLocker interface {
	/*
		Lock will attempt to acquire a distributed lock for the given key.

		Arguments:

		ctx - the context to use for all operations in the lock. If the context is cancelled,
		the lock will not be updated and the lock will eventually expire.

		key - the key of the distributed lock to acquire.

		metadata - a map of metadata that should be stored with the lock. This can be useful
		for debugging or logging when a lock cannot be acquired because it's already held.

		Return Values:

		newCtx - a context that will be cancelled if the heartbeat fails (but will NOT be
		cancelled if the heartbeat exits because the lock was intentionally released).

		newLock - the new lock that was acquired, if it could be acquried. If not, this will be nil.

		existingLock - the existing lock, if there already was one. If a new lock was acquired,
		this will be nil.

		err - an error generated by this function
	*/
	Lock(ctx context.Context, key string, metadata map[string]any) (newCtx context.Context, newLock DistributedLock, existingLock LockData, err stackerr.Error)

	// GetAllLocks will get a map of all locks that are stored in the lock table, regardless of whether they're active
	GetAllLocks(ctx context.Context) (map[string]LockData, stackerr.Error)

	// GetActiveLocks will get a map of all active locks
	GetActiveLocks(ctx context.Context) (map[string]LockData, stackerr.Error)

	// GetExpiredLocks will get a map of all expired locks
	GetExpiredLocks(ctx context.Context) (map[string]LockData, stackerr.Error)
}

type DistributedLockerConfig struct {
	TableArn      string `json:"arn"`
	KeyColumn     string `json:"key_column"`
	VersionColumn string `json:"version_column"`
	// OPTIONAL. An AWS config to use. If not provided,
	// the default config will be used.
	AwsConfig *aws.Config
}

type LockData interface {
	// Gets the key for the lock
	Key() string
	// Gets the version for the lock
	Version() string
	// Gets the time the lock was acquired
	Acquired() time.Time
	// Gets the time the lock will expire. Only provided
	// for getting existing locks (will be zero-value when
	// used on a lock that is held by this process)
	Expires() time.Time
	// Gets the CloudWatch Logs URL for the entity that holds
	// the lock
	LogsUrl() string
	// Gets the metadata that was set for the lock
	Metadata() map[string]json.RawMessage
	// Active checks whether the lock is currently active (held by something).
	Active() bool
}