targetlock

package
v0.2.9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package targetlock serializes database operations in the same user-declared physical coordination realm. Locks are deliberately owner-neutral so different Ptah resource kinds can coordinate through the same Lease.

Index

Constants

View Source
const (
	// MinLeaseDuration prevents hot-looping on locks that cannot be renewed in
	// time under normal API server latency.
	MinLeaseDuration = 5 * time.Second
	// MaxLeaseDuration covers the maximum 24-hour Job active deadline plus a
	// scheduling grace period. This keeps a running Job protected through a
	// manager outage while still bounding recovery from an abandoned Lease.
	MaxLeaseDuration = 24*time.Hour + time.Minute
)

Variables

View Source
var (
	// ErrInvalidRequest means the lock request did not meet the package's
	// credential-free input contract.
	ErrInvalidRequest = errors.New("invalid target lock request")
	// ErrConcurrentUpdate means repeated compare-and-swap attempts raced with
	// another writer. Callers should reconcile again from fresh state.
	ErrConcurrentUpdate = errors.New("target lease changed concurrently")
	// ErrMalformedLease means a foreign non-empty holder lacks enough valid
	// timing evidence to prove that takeover is safe. Callers must fail closed.
	ErrMalformedLease = errors.New("malformed target lease")
)

Functions

func LeaseName

func LeaseName(coordinationDigest string) (string, error)

LeaseName derives a deterministic DNS label from all 256 bits of a SHA-256 coordination realm. The base32 encoding is lower-case and has no padding.

Types

type AcquireResult

type AcquireResult struct {
	Acquired   bool
	Contention *Contention
	// Epoch is a random, non-secret acquisition identity that remains stable
	// across renewals and rotates on every release/reacquisition, takeover, or
	// Lease recreation. Consumers persist it before dispatch and reject results
	// produced across an epoch change.
	Epoch string
	// ContinuityLost reports that ExpectedEpoch did not describe an
	// uninterrupted existing acquisition. The caller may hold the Lease now,
	// but must discard any result produced before this acquisition.
	ContinuityLost bool
}

AcquireResult distinguishes successful acquisition from expected lock contention without using errors for normal coordination.

type Clock

type Clock interface {
	Now() time.Time
}

Clock supplies reconciliation time and makes expiration behavior testable.

type Contention

type Contention struct {
	RequeueAfter time.Duration
}

Contention describes a live lock held by a different operation. It does not disclose the other holder's identity.

type Holder

type Holder struct {
	SchemaUID   types.UID
	OperationID string
}

Holder identifies one resource operation. Its persisted representation is a hash of both fields, so even an accidentally sensitive OperationID cannot be copied into a Lease.

type Locker

type Locker struct {
	// contains filtered or unexported fields
}

Locker coordinates through coordination.k8s.io/v1 Lease objects. Reader should be the manager's uncached APIReader so every decision uses current resourceVersion state; Writer performs compare-and-swap updates.

func New

func New(reader client.Reader, writer client.Writer, clock Clock) *Locker

New constructs a Locker. A nil clock selects the wall clock.

func (*Locker) Acquire

func (l *Locker) Acquire(ctx context.Context, request Request) (AcquireResult, error)

Acquire creates, renews, or takes over an expired Lease. An unexpired Lease held by another operation returns a typed contention result and no error.

func (*Locker) Release

func (l *Locker) Release(ctx context.Context, request Request) error

Release clears a Lease only while it is still held by the requesting operation under the exact persisted acquisition epoch. A missing Lease, a Lease acquired by another holder, or a later acquisition by the same holder is already a successful release from this caller's perspective.

type Request

type Request struct {
	// CoordinationNamespace is shared by every resource that may address the
	// same database. Using the schema's own namespace here would permit two
	// namespaces to apply concurrently to one target.
	CoordinationNamespace string
	CoordinationDigest    string
	Holder                Holder
	Duration              time.Duration
	// ExpectedEpoch is generated and persisted by the caller before dispatch.
	// When non-empty, a successful acquisition reports continuity loss unless
	// the same holder already owns the Lease under this exact epoch.
	ExpectedEpoch string
}

Request contains the complete inputs needed to acquire or release a target lock. CoordinationNamespace must be common to all managed resources, while CoordinationDigest must be an OCI-style SHA-256 digest computed from the normalized engine and exact stable coordination key.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL