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 ¶
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 ¶
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 ¶
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 Contention ¶
Contention describes a live lock held by a different operation. It does not disclose the other holder's identity.
type Holder ¶
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 (*Locker) Acquire ¶
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 ¶
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.