jobregistry

package
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source
const (
	DefaultScopeWarnPrefixes = 10000
	DefaultScopeMaxPrefixes  = 50000
)
View Source
const (
	LivenessLiveMatching   = procidentity.LiveMatching
	LivenessLiveMismatched = procidentity.LiveMismatched
	LivenessGone           = procidentity.Gone
	LivenessIndeterminate  = procidentity.Indeterminate
)
View Source
const (
	RecoveryPhaseFenced          = "fenced"
	RecoveryPhaseClaimed         = "claimed"
	RecoveryPhaseBound           = "bound"
	RecoveryPhaseTermIntent      = "term-intent"
	RecoveryPhaseTermSent        = "term-sent"
	RecoveryPhaseKillIntent      = "kill-intent"
	RecoveryPhaseKillSent        = "kill-sent"
	RecoveryPhaseDeathObserved   = "death-observed"
	RecoveryPhaseLeaseReconciled = "lease-reconciled"
	RecoveryPhaseFinalized       = "finalized"
)

Recovery phase names (entarch hybrid A+B). Signal transport is at-least-once against the same instance-stable bind; phases prevent silent double-finalize.

View Source
const (
	JobTypeIndexBuild           = "index.build"
	IndexBuildInvocationVersion = 1
)
View Source
const ProcessTokenVersionV1 = 1

ProcessTokenVersionV1 is the versioned native birth-token schema.

View Source
const RecoveryIntentStalled = "stalled"

RecoveryIntentStalled is the durable fence label for managed stalled recovery.

Variables

View Source
var (
	// ErrRecoveryFenced is returned when a write would overwrite an active
	// stalled-recovery fence (restore running or claim success/partial).
	ErrRecoveryFenced = errors.New("job is under stalled-recovery fence")
	// ErrRecoveryNotOwned is returned when a recovery action's owner does not
	// match the durable fence owner.
	ErrRecoveryNotOwned = errors.New("stalled-recovery fence owner mismatch")
	// ErrRecoveryNotActive is returned when a recovery action expects a fence
	// that is not present.
	ErrRecoveryNotActive = errors.New("no active stalled-recovery fence")
	// ErrRecoveryAlreadyActive is returned when BeginStalledRecovery finds an
	// existing fence held by another owner.
	ErrRecoveryAlreadyActive = errors.New("stalled-recovery fence already active")
	// ErrRecoveryPlanSnapshotMismatch is returned when plan-time authorization
	// fields (heartbeat, state, identity) no longer match at fence acquisition.
	ErrRecoveryPlanSnapshotMismatch = errors.New("recovery plan snapshot mismatch")
	// ErrRecoverySignalBusy is returned when another caller holds the exclusive
	// signal/finalize phase under an active fence.
	ErrRecoverySignalBusy = errors.New("stalled-recovery signal phase already claimed")
	// ErrRecoverySnapshotRequired is returned when a new fence is requested
	// without MatchPlanSnapshot (snapshot CAS is mandatory for first fence).
	ErrRecoverySnapshotRequired = errors.New("plan snapshot match is required to acquire a recovery fence")
)
View Source
var (
	ErrJobNoPID      = errors.New("job has no pid recorded")
	ErrJobNotRunning = errors.New("job is not running")
	ErrInvalidSignal = errors.New("invalid stop signal")
)
View Source
var ErrDeliveryPersistFailed = errors.New("signal accepted but delivery persistence failed")

ErrDeliveryPersistFailed means the OS signal was accepted but durable delivery mark/phase advance failed — callers must report Signalled=true and not finalize.

View Source
var ErrW2NotFinalizing = errors.New("W2 lease state is not finalizing")

ErrW2NotFinalizing means W2 observed held/invalid residue — no receipt written.

Functions

func ApplyProcessIdentity

func ApplyProcessIdentity(rec *JobRecord, id ProcessIdentity)

ApplyProcessIdentity persists a versioned birth token onto the job record.

func BoundTargetMatches

func BoundTargetMatches(rec *JobRecord) bool

BoundTargetMatches reports whether the durable bound snapshot is complete and still matches job/index/fence/attempt/generation + native token (D-R13-02). Missing snapshot fails closed (false).

func FormatProcessIdentity

func FormatProcessIdentity(id ProcessIdentity) string

FormatProcessIdentity returns a short diagnostic form.

func IndexBuildInvocationFingerprint

func IndexBuildInvocationFingerprint(inv IndexBuildInvocation) (string, error)

func IsProcessAlive

func IsProcessAlive(pid int) bool

IsProcessAlive reports whether a process with the given PID is currently alive. It is the exported liveness signal used by lease-attribution joins to tell a live holder apart from dead-holder residue.

Alive means the process has not exited. It does not mean the process is running: one that has been stopped has not exited, and is alive. A process that has exited is reported dead even while its PID is still addressable, which it remains until the exit status is collected. Where the platform cannot tell the two apart, the PID being addressable is the answer.

Liveness never decides lock authority: a live PID does not prove a lock is held, and a dead or missing PID must never be read as "unheld". Only a non-mutating lock probe decides the held/unheld verdict.

That limit is about lock verdicts alone. Within the registry liveness does carry weight: a job claiming to run under a PID that has exited is demoted.

func ManifestSHA256

func ManifestSHA256(path string) (string, error)

ManifestSHA256 hashes manifest content without persisting the content itself.

func ProcessIdentityMatch

func ProcessIdentityMatch(expected, observed ProcessIdentity) bool

ProcessIdentityMatch reports whether two proven identities name the same process instance.

func ReadManifestBytesAndSHA256

func ReadManifestBytesAndSHA256(path string) ([]byte, string, error)

ReadManifestBytesAndSHA256 returns one read of the manifest and the digest of those exact bytes so callers can parse without reopening the path.

func ValidateIndexBuildSince

func ValidateIndexBuildSince(value string) error

ValidateIndexBuildSince validates the typed incremental lower bound before it can be persisted or forwarded on argv.

func ValidateManagedJobName

func ValidateManagedJobName(value string) error

ValidateManagedJobName validates the bounded display-only name accepted by managed build APIs before it can be persisted or forwarded on argv.

Types

type AdvanceRecoveryPhaseOptions

type AdvanceRecoveryPhaseOptions struct {
	FenceOwner         string
	AttemptID          string
	ExpectedGeneration int64
	FromPhase          string // empty allows any current phase (first transition after claim)
	ToPhase            string
}

AdvanceRecoveryPhase is a fail-closed generation/from→to CAS for recovery phases.

type BackgroundOptions

type BackgroundOptions struct {
	Dedupe     bool
	Since      string
	JobType    string
	Metadata   map[string]string
	Invocation *IndexBuildInvocation
}

type BeginStalledRecoveryOptions

type BeginStalledRecoveryOptions struct {
	// Owner is an opaque recovery-attempt id. Empty mints a new UUID.
	Owner string
	// ExpectedPID must match the record (PID-reuse protection at fence time).
	ExpectedPID int
	// ExpectedStartMS is the recorded birth token; required and must match.
	ExpectedStartMS uint64
	// ExpectedBootID must match when non-empty on the record.
	ExpectedBootID string
	// Expected native token fields (D-R12-02) — plan snapshot must include them.
	ExpectedTokenVersion int
	ExpectedStartTicks   uint64
	ExpectedStartSec     int64
	ExpectedStartUsec    int64
	ExpectedFiletime     uint64
	// ExpectedIndexSetID must match the record when non-empty.
	ExpectedIndexSetID string
	// MatchPlanSnapshot, when true, requires the durable record to still match
	// the plan-time authorization snapshot (state running, heartbeat, heartbeat
	// write error) before a new fence is acquired. Same-owner resume skips this.
	MatchPlanSnapshot bool
	// ExpectedLastHeartbeat is compared when MatchPlanSnapshot is true.
	// Both nil means "record also has no last_heartbeat".
	ExpectedLastHeartbeat *time.Time
	// ExpectedHeartbeatPersistError is compared when MatchPlanSnapshot is true.
	ExpectedHeartbeatPersistError string
	// ExpectedAuthorityRoot is the set-authority root for later W2 (D-R15-02).
	// Required for a new fence; stored durably as RecoveryAuthorityRoot.
	ExpectedAuthorityRoot string
}

BeginStalledRecoveryOptions gates acquisition of the recovery fence.

type BeginStalledRecoveryResult

type BeginStalledRecoveryResult struct {
	Record *JobRecord
	Owner  string
	// AlreadyOwned is true when this owner already held the fence (idempotent
	// re-entry for crash resume).
	AlreadyOwned bool
}

BeginStalledRecoveryResult is the fenced record after a successful claim.

type BuildReceiptIdentity

type BuildReceiptIdentity struct {
	Type             string   `json:"type"`
	SchemaVersion    string   `json:"schema_version"`
	Status           string   `json:"status"`
	RequestedFormat  string   `json:"requested_format"`
	FormatsCommitted []string `json:"formats_committed"`
	IndexSetID       string   `json:"index_set_id"`
	RunID            string   `json:"run_id"`
	ScopeHash        string   `json:"scope_hash,omitempty"`
	ManifestSHA256   string   `json:"manifest_sha256,omitempty"`
}

BuildReceiptIdentity is the stable, metadata-only committed-artifact identity attached to a terminal managed job without parsing its logs.

type EffectiveIdentity

type EffectiveIdentity struct {
	StorageProvider string `json:"storage_provider,omitempty"`
	CloudProvider   string `json:"cloud_provider,omitempty"`
	RegionKind      string `json:"region_kind,omitempty"`
	Region          string `json:"region,omitempty"`
	EndpointHost    string `json:"endpoint_host,omitempty"`
}

EffectiveIdentity is a minimal identity summary captured for operator clarity.

This is intentionally shallow and string-only so the job registry stays stable even if deeper identity schemas evolve.

type Executor

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

Executor spawns and manages background jobs.

v0.1.4 design: spawn a child process that runs `gonimbus index build` in managed mode, capturing stdout/stderr to per-job log files.

func NewExecutor

func NewExecutor(root string) *Executor

func (*Executor) StartIndexBuildBackground

func (e *Executor) StartIndexBuildBackground(manifestPath string, name string, opts BackgroundOptions) (*JobRecord, error)

StartIndexBuildBackground spawns a managed child process running:

gonimbus index build --job <manifest> --_managed-job-id <job_id>

It returns after the child successfully starts.

func (*Executor) StderrPath

func (e *Executor) StderrPath(jobID string) string

func (*Executor) StdoutPath

func (e *Executor) StdoutPath(jobID string) string

func (*Executor) Store

func (e *Executor) Store() *Store

type IndexBuildInvocation

type IndexBuildInvocation struct {
	SchemaVersion     int    `json:"schema_version"`
	ManifestPath      string `json:"manifest_path"`
	ManifestSHA256    string `json:"manifest_sha256"`
	RequestedFormat   string `json:"requested_format"`
	EffectiveFormat   string `json:"effective_format"`
	ConfigPath        string `json:"config_path,omitempty"`
	DataRoot          string `json:"data_root,omitempty"`
	Verbose           bool   `json:"verbose,omitempty"`
	ReadOnly          bool   `json:"readonly,omitempty"`
	DBPath            string `json:"db_path,omitempty"`
	Since             string `json:"since,omitempty"`
	Name              string `json:"name,omitempty"`
	StorageProvider   string `json:"storage_provider,omitempty"`
	CloudProvider     string `json:"cloud_provider,omitempty"`
	RegionKind        string `json:"region_kind,omitempty"`
	Region            string `json:"region,omitempty"`
	EndpointHost      string `json:"endpoint_host,omitempty"`
	ScopeWarnPrefixes int    `json:"scope_warn_prefixes"`
	ScopeMaxPrefixes  int    `json:"scope_max_prefixes"`
}

IndexBuildInvocation is the disclosure-minimal, versioned command contract shared by a background-build parent and its managed child. It intentionally contains only accepted build controls; credentials and provider endpoints are resolved by the child through the normal manifest/config credential chain.

func PrepareIndexBuildInvocation

func PrepareIndexBuildInvocation(manifestPath, name string, in *IndexBuildInvocation) (*IndexBuildInvocation, string, error)

PrepareIndexBuildInvocation canonicalizes and binds an invocation to the exact manifest bytes that were present when the job was accepted.

type JobRecord

type JobRecord struct {
	JobID            string     `json:"job_id"`
	Type             string     `json:"type,omitempty"`
	Name             string     `json:"name,omitempty"`
	State            JobState   `json:"state"`
	ManifestPath     string     `json:"manifest_path"`
	IndexDir         string     `json:"index_dir,omitempty"`
	IndexSetID       string     `json:"index_set_id,omitempty"`
	RunID            string     `json:"run_id,omitempty"`
	PID              int        `json:"pid,omitempty"`
	CreatedAt        time.Time  `json:"created_at"`
	EnqueueOwnerPID  int        `json:"enqueue_owner_pid,omitempty"`
	EnqueueExpiresAt *time.Time `json:"enqueue_expires_at,omitempty"`

	StartedAt     *time.Time `json:"started_at,omitempty"`
	EndedAt       *time.Time `json:"ended_at,omitempty"`
	LastHeartbeat *time.Time `json:"last_heartbeat,omitempty"`
	// ProcessStartTimeUnixMS is the OS process birth token captured at claim.
	// Together with PID (and ProcessBootID when present) it is the durable
	// process identity used for PID-reuse protection. Job StartedAt is wall
	// clock for the job, not this token.
	ProcessStartTimeUnixMS *uint64 `json:"process_start_time_unix_ms,omitempty"`
	// ProcessBootID binds ProcessStartTimeUnixMS to a boot/session when the
	// platform exposes one (e.g. Linux boot_id). Empty when unavailable.
	ProcessBootID string `json:"process_boot_id,omitempty"`
	// HeartbeatPersistError records the last failed heartbeat write. A non-empty
	// value means heartbeat age must not authorize termination (writes were not
	// proven). Cleared on the next successful heartbeat persist.
	HeartbeatPersistError string `json:"heartbeat_persist_error,omitempty"`
	// RecoveryIntent is set when a stalled-recovery fence owns the job
	// (value "stalled"). While set with state stopping, heartbeat and child
	// terminal writers must not restore running or claim success.
	RecoveryIntent string `json:"recovery_intent,omitempty"`
	// RecoveryOwner is an opaque id for the recovery attempt that holds the
	// fence. Concurrent recoveries must not steal an active owner.
	RecoveryOwner string `json:"recovery_owner,omitempty"`
	// RecoverySignalOwner is the exclusive claim for bind/signal/finalize under
	// an active fence. Multiple callers may share RecoveryOwner (resume), but
	// only one may hold RecoverySignalOwner and perform the signal sequence.
	RecoverySignalOwner string `json:"recovery_signal_owner,omitempty"`
	// RecoverySignalClaimedAt is when RecoverySignalOwner was acquired.
	RecoverySignalClaimedAt *time.Time `json:"recovery_signal_claimed_at,omitempty"`
	// RecoverySignalClaimerPID is the OS PID of the recover process that holds
	// the signal claim. Used with claimer birth token to prove the claimer is gone.
	RecoverySignalClaimerPID int `json:"recovery_signal_claimer_pid,omitempty"`
	// RecoverySignalClaimerStartMS is legacy display ms of the claimer process.
	RecoverySignalClaimerStartMS *uint64 `json:"recovery_signal_claimer_start_ms,omitempty"`
	// Full versioned claimer birth token (same contract as managed process).
	RecoverySignalClaimerTokenVersion int    `json:"recovery_signal_claimer_token_version,omitempty"`
	RecoverySignalClaimerBootID       string `json:"recovery_signal_claimer_boot_id,omitempty"`
	RecoverySignalClaimerStartTicks   uint64 `json:"recovery_signal_claimer_start_ticks,omitempty"`
	RecoverySignalClaimerStartSec     int64  `json:"recovery_signal_claimer_start_sec,omitempty"`
	RecoverySignalClaimerStartUsec    int64  `json:"recovery_signal_claimer_start_usec,omitempty"`
	RecoverySignalClaimerFiletime     uint64 `json:"recovery_signal_claimer_filetime,omitempty"`
	// RecoveryStartedAt is when the fence was acquired.
	RecoveryStartedAt *time.Time `json:"recovery_started_at,omitempty"`
	// RecoveryPhase is the durable recovery state machine phase (entarch A+B).
	// Values: fenced, claimed, bound, term-intent, term-sent, kill-intent,
	// kill-sent, death-observed, lease-reconciled, finalized. Empty when idle.
	RecoveryPhase string `json:"recovery_phase,omitempty"`
	// RecoveryGeneration increments on each fence acquisition; phase CAS binds to it.
	RecoveryGeneration int64 `json:"recovery_generation,omitempty"`
	// RecoveryW2Receipt is the identity-bound lease reconciliation proof (E-R10-1).
	// Finalize-only resume trusts this receipt rather than re-probing the path.
	RecoveryW2Receipt *RecoveryW2Receipt `json:"recovery_w2_receipt,omitempty"`
	// RecoveryDeliverySignalled is durable proof that at least one stop syscall
	// was accepted under this generation (set only after accepted transport).
	RecoveryDeliverySignalled bool `json:"recovery_delivery_signalled,omitempty"`
	// RecoveryDeliveryForced is durable proof that a hard-stop/KILL was accepted.
	RecoveryDeliveryForced bool `json:"recovery_delivery_forced,omitempty"`
	// RecoveryBound* is the generation/attempt-bound target snapshot for replay.
	RecoveryBoundPID          int    `json:"recovery_bound_pid,omitempty"`
	RecoveryBoundTokenVersion int    `json:"recovery_bound_token_version,omitempty"`
	RecoveryBoundStartMS      uint64 `json:"recovery_bound_start_ms,omitempty"`
	RecoveryBoundBootID       string `json:"recovery_bound_boot_id,omitempty"`
	RecoveryBoundStartTicks   uint64 `json:"recovery_bound_start_ticks,omitempty"`
	RecoveryBoundStartSec     int64  `json:"recovery_bound_start_sec,omitempty"`
	RecoveryBoundStartUsec    int64  `json:"recovery_bound_start_usec,omitempty"`
	RecoveryBoundFiletime     uint64 `json:"recovery_bound_filetime,omitempty"`
	RecoveryBoundAttempt      string `json:"recovery_bound_attempt,omitempty"`
	RecoveryBoundFenceOwner   string `json:"recovery_bound_fence_owner,omitempty"`
	RecoveryBoundGeneration   int64  `json:"recovery_bound_generation,omitempty"`
	RecoveryBoundIndexSetID   string `json:"recovery_bound_index_set_id,omitempty"`
	RecoveryBoundJobID        string `json:"recovery_bound_job_id,omitempty"`
	// RecoveryAuthorityRoot is the canonical set-authority root bound at fence time.
	// W2 may only operate against this exact root (D-R15-02 / D-R17-03).
	RecoveryAuthorityRoot string `json:"recovery_authority_root,omitempty"`
	// RecoveryAuthorityDev/Ino bind directory identity of the authority root when
	// the platform exposes them (Unix). Used to detect symlink retarget/replace.
	RecoveryAuthorityDev uint64 `json:"recovery_authority_dev,omitempty"`
	RecoveryAuthorityIno uint64 `json:"recovery_authority_ino,omitempty"`
	// ProcessTokenVersion is the birth-token schema (1 = native fields authoritative).
	ProcessTokenVersion int `json:"process_token_version,omitempty"`
	// ProcessStartTicks is Linux /proc starttime ticks (authoritative when version=1).
	ProcessStartTicks uint64 `json:"process_start_ticks,omitempty"`
	// ProcessStartSec/Usec are Darwin kinfo starttime components.
	ProcessStartSec  int64 `json:"process_start_sec,omitempty"`
	ProcessStartUsec int64 `json:"process_start_usec,omitempty"`
	// ProcessFiletime is Windows FILETIME 100ns ticks since 1601 (authoritative).
	ProcessFiletime uint64 `json:"process_filetime,omitempty"`

	Identity              *EffectiveIdentity    `json:"effective_identity,omitempty"`
	StdoutPath            string                `json:"stdout_path,omitempty"`
	StderrPath            string                `json:"stderr_path,omitempty"`
	Metadata              map[string]string     `json:"metadata,omitempty"`
	Invocation            *IndexBuildInvocation `json:"effective_invocation,omitempty"`
	InvocationFingerprint string                `json:"invocation_fingerprint,omitempty"`
	Receipt               *BuildReceiptIdentity `json:"terminal_receipt,omitempty"`
}

JobRecord is the persistent record written to job.json.

The schema is designed for backward-compatible extension (additive fields).

type JobState

type JobState string

JobState is the lifecycle state of a managed job.

NOTE: These values are persisted in job.json and are part of the stable on-disk contract.

const (
	JobStateQueued   JobState = "queued"
	JobStateRunning  JobState = "running"
	JobStateStopping JobState = "stopping"
	JobStateStopped  JobState = "stopped"
	JobStateSuccess  JobState = "success"
	JobStatePartial  JobState = "partial"
	JobStateFailed   JobState = "failed"
	JobStateUnknown  JobState = "unknown"
)

type Liveness

type Liveness = procidentity.Liveness

Liveness aliases for callers that must not use boolean IsProcessAlive.

func ClassifyProcess

func ClassifyProcess(id ProcessIdentity) Liveness

ClassifyProcess returns typed liveness for a recorded identity.

type ProcessIdentity

type ProcessIdentity = procidentity.Identity

ProcessIdentity is the durable OS birth token stored on a managed job record.

func ObserveProcessIdentity

func ObserveProcessIdentity(pid int) ProcessIdentity

ObserveProcessIdentity re-reads the live process birth token for pid.

func ProcessIdentityFromRecord

func ProcessIdentityFromRecord(rec *JobRecord) ProcessIdentity

ProcessIdentityFromRecord reconstructs the token persisted on a job record.

type RecoveryW2Receipt

type RecoveryW2Receipt struct {
	SchemaVersion int    `json:"schema_version"`
	Generation    int64  `json:"generation"`
	FenceOwner    string `json:"fence_owner"`
	// OriginAttempt is the attempt that produced the receipt (may differ from resume attempt).
	OriginAttempt string    `json:"origin_attempt"`
	JobID         string    `json:"job_id"`
	IndexSetID    string    `json:"index_set_id"`
	LeaseVerdict  string    `json:"lease_verdict"`
	Reclaimed     bool      `json:"reclaimed"`
	Signalled     bool      `json:"signalled"`
	ForcedKill    bool      `json:"forced_kill"`
	ReconciledAt  time.Time `json:"reconciled_at"`
	// LeasePath is the authority path when known (successor race control).
	LeasePath string `json:"lease_path,omitempty"`
	// LeaseDev/LeaseIno bind the old lease file identity when available.
	LeaseDev uint64 `json:"lease_dev,omitempty"`
	LeaseIno uint64 `json:"lease_ino,omitempty"`
}

RecoveryW2Receipt proves what lease reconciliation did for a generation/attempt.

type SignalSession

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

SignalSession owns the exact instance-bound target from RecoveryBound* and couples transport with durable delivery marking (D-R15-01 / D-R16-01). The raw *procidentity.Target is never exposed — only non-destructive waits and coupled Deliver* are public.

func (*SignalSession) Close

func (sess *SignalSession) Close() error

Close releases the owned target handle.

func (*SignalSession) DeliverKill

func (sess *SignalSession) DeliverKill() error

DeliverKill signals KILL on the session-owned target then records kill-sent.

func (*SignalSession) DeliverTerm

func (sess *SignalSession) DeliverTerm() error

DeliverTerm signals TERM on the session-owned target then records term-sent.

func (*SignalSession) HardStopOnly

func (sess *SignalSession) HardStopOnly() bool

HardStopOnly reports whether the owned target is hard-stop-only.

func (*SignalSession) Terminated

func (sess *SignalSession) Terminated() (bool, error)

Terminated reports whether the session-owned instance is gone.

func (*SignalSession) WaitTerminated

func (sess *SignalSession) WaitTerminated(timeout, poll time.Duration) (bool, error)

WaitTerminated waits for the session-owned instance to exit.

type StopOptions

type StopOptions struct {
	Signal       string
	WaitTimeout  time.Duration
	PollInterval time.Duration
}

type StopResult

type StopResult struct {
	JobID      string `json:"job_id"`
	Signal     string `json:"signal"`
	ForcedKill bool   `json:"forced_kill"`
	State      string `json:"state"`
}

type Store

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

Store persists and loads JobRecords from an on-disk directory.

Directory layout:

<root>/<job_id>/job.json
<root>/<job_id>/stdout.log
<root>/<job_id>/stderr.log

Root is expected to be under the app data dir.

func NewStore

func NewStore(root string) *Store

func (*Store) AdvanceRecoveryPhase

func (s *Store) AdvanceRecoveryPhase(jobID string, opts AdvanceRecoveryPhaseOptions) error

AdvanceRecoveryPhase persists a legal phase transition. Generation, from-phase, fence owner, and attempt owner are mandatory (E-R7-01 / D-R7-01).

func (*Store) BeginStalledRecovery

func (s *Store) BeginStalledRecovery(jobID string, opts BeginStalledRecoveryOptions) (*BeginStalledRecoveryResult, error)

BeginStalledRecovery acquires a durable recovery fence under the start lock: state running → stopping with RecoveryIntent=stalled. It refuses identity or index-set drift and converges concurrent attempts onto one owner.

func (*Store) CheckRecoveryAuthorityRoot

func (s *Store) CheckRecoveryAuthorityRoot(jobID, fenceOwner, expectedRoot string) error

CheckRecoveryAuthorityRoot verifies the durable root on an active fence matches the caller's expected root identity. Missing root refuses (D-R16-02 / D-R17-03).

func (*Store) ClaimQueued

func (s *Store) ClaimQueued(jobID string, pid int, validate func(*JobRecord) error) (*JobRecord, error)

ClaimQueued atomically validates and promotes one queued job to running.

func (*Store) ClaimStalledRecoverySignal

func (s *Store) ClaimStalledRecoverySignal(jobID, fenceOwner, attemptID string) error

ClaimStalledRecoverySignal acquires the exclusive signal phase.

func (*Store) ClaimStalledRecoverySignalVerifiedTakeover

func (s *Store) ClaimStalledRecoverySignalVerifiedTakeover(jobID, fenceOwner, attemptID string) error

ClaimStalledRecoverySignalVerifiedTakeover replaces a busy claim only when the store verifies (under lock) that the prior claimer process is gone (orphan claim). Live concurrent claimers must receive ErrRecoverySignalBusy — a dead managed target alone does not authorize stealing an exclusive signal phase from a still-live claimer (that would stampede multi-winner finalize). No caller-asserted force flag.

func (*Store) FailStalledRecovery

func (s *Store) FailStalledRecovery(jobID, fenceOwner, attemptID, reason string) (*JobRecord, error)

FailStalledRecovery leaves an honest non-success result when recovery cannot prove termination. The signal claim is released so a crash-retry can re-claim.

func (*Store) FinalizeStalledRecoveryGen

func (s *Store) FinalizeStalledRecoveryGen(jobID, fenceOwner, attemptID string, expectedGeneration int64, forcedKill bool) (*JobRecord, error)

FinalizeStalledRecoveryGen finalizes after lease-reconciled with mandatory generation.

func (*Store) Get

func (s *Store) Get(jobID string) (*JobRecord, error)

func (*Store) GetReadOnlyStrict

func (s *Store) GetReadOnlyStrict(jobID string) (*JobRecord, error)

GetReadOnlyStrict returns one job record without demoting state, updating heartbeats, creating directories, or otherwise mutating the registry. Recovery planners must use this surface so a dead-PID "zombie" demotion cannot erase the terminal-contradiction evidence the plan is meant to judge.

func (*Store) JobDir

func (s *Store) JobDir(jobID string) string

func (*Store) JobPath

func (s *Store) JobPath(jobID string) string

func (*Store) List

func (s *Store) List() ([]JobRecord, error)

func (*Store) ListReadOnlyStrict

func (s *Store) ListReadOnlyStrict() ([]JobRecord, error)

ListReadOnlyStrict returns a byte-preserving snapshot of every registry job. Unlike List, it never promotes zombie state or creates registry directories, and it rejects every unrecognized or unreadable entry instead of skipping it. Destructive planners use this surface so damaged registry state cannot make an active job disappear from safety checks.

func (*Store) OpenLog

func (s *Store) OpenLog(jobID, name string, truncate bool) (*os.File, error)

OpenLog creates or opens a registry-owned log without following a final symlink. The caller owns the returned handle.

func (*Store) OpenLogRead

func (s *Store) OpenLogRead(jobID, name string) (*os.File, error)

OpenLogRead opens a canonical registry-owned log without following a final symlink. Callers must not use persisted record paths as read authority.

func (*Store) OpenSignalSession

func (s *Store) OpenSignalSession(jobID, fenceOwner, attemptID string, expectedGeneration int64, deadline time.Time) (*SignalSession, error)

OpenSignalSession validates fence/attempt/generation/bound/authority, Binds the exact bound identity, and returns a session for DeliverTerm/DeliverKill. deadline must be non-zero and still live (D-R17-01).

func (*Store) ReconcileStalledW2

func (s *Store) ReconcileStalledW2(jobID, fenceOwner, attemptID string, expectedGeneration int64) error

ReconcileStalledW2 is the store-owned W2 path (D-R15-02). Authority root, index set, and holder are taken only from the locked job record — callers cannot substitute empty/foreign coordinates.

func (*Store) RecordHeartbeatPersistError

func (s *Store) RecordHeartbeatPersistError(jobID string, persistErr error) error

RecordHeartbeatPersistError records that a heartbeat write failed so planners can refuse to treat heartbeat age as stop authority.

func (*Store) RootDir

func (s *Store) RootDir() string

func (*Store) Stop

func (s *Store) Stop(jobID string, opts StopOptions) (*StopResult, error)

func (*Store) TouchHeartbeat

func (s *Store) TouchHeartbeat(jobID string, expectedPID int, expectedStartMS *uint64, expectedBootID string) error

TouchHeartbeat persists a heartbeat for a still-running job using a start-lock-serialized re-read so a concurrent stop/recovery transition is not overwritten from a stale in-memory snapshot. It refuses when the record is no longer running or the PID/birth identity no longer match the caller.

recover-stalled recovery fencing will share this lock; terminal writers that must not be clobbered by a heartbeat should also enter withStartLock (or a future CAS).

func (*Store) Write

func (s *Store) Write(record *JobRecord) error

Jump to

Keyboard shortcuts

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