Documentation
¶
Index ¶
- Constants
- Variables
- func ApplyProcessIdentity(rec *JobRecord, id ProcessIdentity)
- func BoundTargetMatches(rec *JobRecord) bool
- func FormatProcessIdentity(id ProcessIdentity) string
- func IndexBuildInvocationFingerprint(inv IndexBuildInvocation) (string, error)
- func IsProcessAlive(pid int) bool
- func ManifestSHA256(path string) (string, error)
- func ProcessIdentityMatch(expected, observed ProcessIdentity) bool
- func ReadManifestBytesAndSHA256(path string) ([]byte, string, error)
- func ValidateIndexBuildSince(value string) error
- func ValidateManagedJobName(value string) error
- type AdvanceRecoveryPhaseOptions
- type BackgroundOptions
- type BeginStalledRecoveryOptions
- type BeginStalledRecoveryResult
- type BuildReceiptIdentity
- type EffectiveIdentity
- type Executor
- type IndexBuildInvocation
- type JobRecord
- type JobState
- type Liveness
- type ProcessIdentity
- type RecoveryW2Receipt
- type SignalSession
- func (sess *SignalSession) Close() error
- func (sess *SignalSession) DeliverKill() error
- func (sess *SignalSession) DeliverTerm() error
- func (sess *SignalSession) HardStopOnly() bool
- func (sess *SignalSession) Terminated() (bool, error)
- func (sess *SignalSession) WaitTerminated(timeout, poll time.Duration) (bool, error)
- type StopOptions
- type StopResult
- type Store
- func (s *Store) AdvanceRecoveryPhase(jobID string, opts AdvanceRecoveryPhaseOptions) error
- func (s *Store) BeginStalledRecovery(jobID string, opts BeginStalledRecoveryOptions) (*BeginStalledRecoveryResult, error)
- func (s *Store) CheckRecoveryAuthorityRoot(jobID, fenceOwner, expectedRoot string) error
- func (s *Store) ClaimQueued(jobID string, pid int, validate func(*JobRecord) error) (*JobRecord, error)
- func (s *Store) ClaimStalledRecoverySignal(jobID, fenceOwner, attemptID string) error
- func (s *Store) ClaimStalledRecoverySignalVerifiedTakeover(jobID, fenceOwner, attemptID string) error
- func (s *Store) FailStalledRecovery(jobID, fenceOwner, attemptID, reason string) (*JobRecord, error)
- func (s *Store) FinalizeStalledRecoveryGen(jobID, fenceOwner, attemptID string, expectedGeneration int64, forcedKill bool) (*JobRecord, error)
- func (s *Store) Get(jobID string) (*JobRecord, error)
- func (s *Store) GetReadOnlyStrict(jobID string) (*JobRecord, error)
- func (s *Store) JobDir(jobID string) string
- func (s *Store) JobPath(jobID string) string
- func (s *Store) List() ([]JobRecord, error)
- func (s *Store) ListReadOnlyStrict() ([]JobRecord, error)
- func (s *Store) OpenLog(jobID, name string, truncate bool) (*os.File, error)
- func (s *Store) OpenLogRead(jobID, name string) (*os.File, error)
- func (s *Store) OpenSignalSession(jobID, fenceOwner, attemptID string, expectedGeneration int64, ...) (*SignalSession, error)
- func (s *Store) ReconcileStalledW2(jobID, fenceOwner, attemptID string, expectedGeneration int64) error
- func (s *Store) RecordHeartbeatPersistError(jobID string, persistErr error) error
- func (s *Store) RootDir() string
- func (s *Store) Stop(jobID string, opts StopOptions) (*StopResult, error)
- func (s *Store) TouchHeartbeat(jobID string, expectedPID int, expectedStartMS *uint64, expectedBootID string) error
- func (s *Store) Write(record *JobRecord) error
Constants ¶
const ( DefaultScopeWarnPrefixes = 10000 DefaultScopeMaxPrefixes = 50000 )
const ( LivenessLiveMatching = procidentity.LiveMatching LivenessLiveMismatched = procidentity.LiveMismatched LivenessGone = procidentity.Gone LivenessIndeterminate = procidentity.Indeterminate )
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.
const ( JobTypeIndexBuild = "index.build" IndexBuildInvocationVersion = 1 )
const ProcessTokenVersionV1 = 1
ProcessTokenVersionV1 is the versioned native birth-token schema.
const RecoveryIntentStalled = "stalled"
RecoveryIntentStalled is the durable fence label for managed stalled recovery.
Variables ¶
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") )
var ( ErrJobNoPID = errors.New("job has no pid recorded") ErrJobNotRunning = errors.New("job is not running") ErrInvalidSignal = errors.New("invalid stop signal") )
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.
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 ¶
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 ¶
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 ¶
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 ¶
ReadManifestBytesAndSHA256 returns one read of the manifest and the digest of those exact bytes so callers can parse without reopening the path.
func ValidateIndexBuildSince ¶
ValidateIndexBuildSince validates the typed incremental lower bound before it can be persisted or forwarded on argv.
func ValidateManagedJobName ¶
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 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 (*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 (*Executor) StdoutPath ¶
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 StopResult ¶
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 (*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 ¶
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 ¶
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) GetReadOnlyStrict ¶
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) ListReadOnlyStrict ¶
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 ¶
OpenLog creates or opens a registry-owned log without following a final symlink. The caller owns the returned handle.
func (*Store) OpenLogRead ¶
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 ¶
RecordHeartbeatPersistError records that a heartbeat write failed so planners can refuse to treat heartbeat age as stop authority.
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).