claims

package

v0.44.1 Latest Latest Go to latest Published: Sep 23, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/Fluent-Health/terraform-stack-plan

Links

Open Source Insights

Documentation ¶

Overview ¶

Package claims is the pure event-sourced domain core for the apply-lock claim ledger. It follows the Decider pattern: Decide emits Events, Evolve folds them into a ClaimSet. No I/O, no store imports — this is a pure leaf package.

Index ¶

func Lease() time.Duration
func MarshalEvent(e Event) (string, []byte, error)
func MarshalSnapshot(cs ClaimSet) ([]byte, error)
type AcquireClaim
type Claim
type ClaimAcquired
type ClaimReleased
type ClaimRenewed
type ClaimSet
type ClaimStackReleased
type Command
type Event
- func Decide(s ClaimSet, c Command) []Event
- func UnmarshalEvent(tag string, data []byte) (Event, error)
type ReleaseClaim
type ReleaseClaimStack
type RenewClaim
type Verdict
- func Held(s ClaimSet, pr int, stacks []string, now time.Time) Verdict

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func Lease ¶

func Lease() time.Duration

Lease is the duration for which a claim is valid before it must be renewed.

func MarshalEvent ¶

func MarshalEvent(e Event) (string, []byte, error)

MarshalEvent serializes a domain Event to a neutral (typeTag, JSON) pair. The tag is the variant's Go type name; the data is its JSON. No store dependency. Keep this switch and UnmarshalEvent in sync with the Event variants in claim.go (the round-trip-every-variant test enforces it).

func MarshalSnapshot ¶

func MarshalSnapshot(cs ClaimSet) ([]byte, error)

MarshalSnapshot serializes a folded ClaimSet to JSON. ClaimSet is a plain map so it round-trips directly via encoding/json.

Types ¶

type AcquireClaim ¶

type AcquireClaim struct {
	PR     int
	Stacks []string
	Now    time.Time
}

AcquireClaim requests that pr acquire a claim on the given stacks.

type Claim ¶

type Claim struct {
	PR        int
	ExpiresAt time.Time
}

Claim holds the ownership record for a single stack slot.

type ClaimAcquired ¶

type ClaimAcquired struct {
	PR        int
	Stacks    []string
	ExpiresAt time.Time
}

ClaimAcquired records that pr has acquired claims on the given stacks.

type ClaimReleased ¶

type ClaimReleased struct {
	PR int
}

ClaimReleased records that all stacks claimed by pr have been released.

type ClaimRenewed ¶

type ClaimRenewed struct {
	PR        int
	ExpiresAt time.Time
}

ClaimRenewed records that pr's claims have been extended to ExpiresAt.

type ClaimSet ¶

type ClaimSet map[string]Claim

ClaimSet is the folded state of the claim ledger: stack path → Claim.

func Empty ¶

func Empty() ClaimSet

Empty returns an empty ClaimSet (the initial state for the fold).

func Evolve ¶

func Evolve(s ClaimSet, e Event) ClaimSet

Evolve applies a single domain Event to a ClaimSet, returning the new state. It is total (never panics on any state/event combination), pure (no I/O), and deterministic. Crucially, it NEVER mutates the input map — it always clones first so that replay (folding the same event sequence multiple times) is safe.

func UnmarshalSnapshot ¶

func UnmarshalSnapshot(b []byte) (ClaimSet, error)

UnmarshalSnapshot reverses MarshalSnapshot.

type ClaimStackReleased ¶

type ClaimStackReleased struct {
	PR    int
	Stack string
}

ClaimStackReleased records that a single stack claimed by pr has been released.

type Command ¶

type Command interface {
	// contains filtered or unexported methods
}

Command is a request to change claim state.

type Event ¶

type Event interface {
	// contains filtered or unexported methods
}

Event is a past-tense domain fact produced by Decide and folded by Evolve.

func Decide ¶

func Decide(s ClaimSet, c Command) []Event

Decide maps a Command to the set of Events it produces. It is pure: no I/O, no time.Now() — all temporal inputs arrive via the command itself. The caller (the shell) is responsible for providing the current time inside Now fields.

func UnmarshalEvent ¶

func UnmarshalEvent(tag string, data []byte) (Event, error)

UnmarshalEvent reverses MarshalEvent.

type ReleaseClaim ¶

type ReleaseClaim struct {
	PR int
}

ReleaseClaim requests that all stacks claimed by pr be released.

type ReleaseClaimStack ¶

type ReleaseClaimStack struct {
	PR    int
	Stack string
}

ReleaseClaimStack requests that a single stack claimed by pr be released.

type RenewClaim ¶

type RenewClaim struct {
	PR  int
	Now time.Time
}

RenewClaim requests that the existing claim by pr be renewed.

type Verdict ¶

type Verdict struct {
	Held        bool
	Blocking    []string // blocked stacks, sorted
	BlockingPRs []int    // owning PRs of the blocking claims, sorted, de-duplicated
}

Verdict is the result of a Held query.

func Held ¶

func Held(s ClaimSet, pr int, stacks []string, now time.Time) Verdict

Held reports whether any of pr's stacks is claimed by ANOTHER pr with an unexpired lease at now. Blocking is sorted for determinism. Mirrors the old evalApplyLock/overlap + the `expires_at > now` filter.

Note: expiry is ONLY enforced here at read time — there is no ClaimExpired event. The log replays deterministically; stale entries are simply invisible to Held once their lease lapses.

Source Files ¶

View all Source files

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