workerstore

package
v1.10.4 Latest Latest
Warning

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

 Go to latest Published: Nov 4, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package workerstore persists worker ownership without granting execution.

Index

Constants

View Source 
const JournalVersion = 3

JournalVersion includes the separately revisioned artifact capture table. Older daemons refuse this version instead of ignoring pending captures.

View Source 
const RecordVersion = 2

RecordVersion is the current worker ownership record format.

Variables

View Source 
var ErrConflict = broker.ErrConflict

ErrConflict prevents identity reuse and stale worker or reaper writes.

View Source 
var ErrCorrupt = errors.New("cortex: corrupt sandbox worker journal")

ErrCorrupt means persisted state cannot establish a safe ownership decision.

Functions

This section is empty.

Types

type CaptureRecord 

type CaptureRecord struct {
	SchemaVersion int          `json:"schema_version"`
	JobID         id.ID        `json:"job_id"`
	JobDigest     string       `json:"job_digest"`
	ClaimRevision uint64       `json:"claim_revision"`
	Ref           evidence.Ref `json:"ref"`
	State         CaptureState `json:"state"`
	Revision      uint64       `json:"revision"`
	RecordedAt    time.Time    `json:"recorded_at"`
	VerifiedAt    time.Time    `json:"verified_at,omitempty"`
	DiscardedAt   time.Time    `json:"discarded_at,omitempty"`
	DiscardReason string       `json:"discard_reason,omitempty"`
}

CaptureRecord survives worker exit and job finalization. Its revision is independent of execution ownership; capture never renews or fences a claim. Intent does not assert whether the repository accepted an upload.

type CaptureState 

type CaptureState string

CaptureState describes repository handling, never a grading verdict. 

const (
	// CaptureIntent preserves the exact binding before an upload may begin.
	CaptureIntent CaptureState = "intent"
	// CaptureVerified records the worker's authenticated readback confirmation.
	CaptureVerified CaptureState = "verified"
	// CaptureDiscarded retains a binding after authorized repository cleanup.
	CaptureDiscarded CaptureState = "discarded"
)

type Claim 

type Claim struct {
	Record Record
	Token  string
}

Claim carries the single-use execution ownership grant. The caller must authenticate and supervise the worker; this capability does not launch it.

type Config 

type Config struct {
	Database, Broker string
	PublicKey        ed25519.PublicKey
	MaxJobs          int
	Now              func() time.Time
}

Config binds a journal to one trusted broker identity. Keep the database and its private directory for the lifetime of accepted job identities. MaxJobs includes terminal tombstones; there is no automatic deletion or rollover.

type PendingJob 

type PendingJob struct {
	ID       id.ID
	Phase    Phase
	Revision uint64
}

PendingJob is a bounded recovery index. Load verifies its full receipt before a reaper acts; external containment discovery must also handle journal faults.

type Phase 

type Phase string

Phase is the durable ownership state, not a correctness verdict. 

const (
	// Accepted is an enrolled job that has never granted a worker claim.
	Accepted Phase = "accepted"
	// Claimed means execution may have started, even after a lost response.
	Claimed Phase = "claimed"
	// Reaping fences worker completion until external containment is stopped.
	Reaping Phase = "reaping"
	// Terminal permanently prevents another claim for this identity.
	Terminal Phase = "terminal"
)
const Finalizing Phase = "finalizing"

Finalizing holds a proposed result while independent cleanup remains pending.

type Proposal 

type Proposal struct {
	ClaimRevision uint64          `json:"claim_revision"`
	ReceivedAt    time.Time       `json:"received_at"`
	Digest        string          `json:"digest"`
	Discarded     bool            `json:"discarded,omitempty"`
	Result        *sandbox.Result `json:"result,omitempty"`
}

Proposal binds a report to its original claim. Terminal records retain the digest and receipt time, while their Result field owns any collectible bytes.

type Record 

type Record struct {
	SchemaVersion   int             `json:"schema_version"`
	Receipt         sandbox.Receipt `json:"receipt"`
	Phase           Phase           `json:"phase"`
	Revision        uint64          `json:"revision"`
	TokenHash       string          `json:"token_hash,omitempty"`
	CancelRequested bool            `json:"cancel_requested"`
	Result          *sandbox.Result `json:"result,omitempty"`
	Proposal        *Proposal       `json:"proposal,omitempty"`
}

Record is an immutable acceptance plus monotonic worker state. TokenHash never reveals the worker capability; losing the Claim response requires reaping.

type Store 

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

Store serializes one daemon's transitions under an exclusive process lock. Other processes cannot open the journal concurrently. Workers communicate through the owning daemon, not by opening this database themselves.

func Open 

func Open(ctx context.Context, cfg Config) (*Store, error)

Open acquires durable ownership and verifies the schema and broker key pin.

func (*Store) Cancel 

func (s *Store) Cancel(ctx context.Context, key id.ID) (Record, error)

Cancel durably prevents a future claim. Claimed work remains nonterminal until the external reaper proves that every descendant has stopped.

func (*Store) CaptureJobs 

func (s *Store) CaptureJobs(ctx context.Context, after string, limit int) ([]id.ID, error)

CaptureJobs pages recovery candidates even after execution becomes terminal. Load each job and its Captures before acting. Every non-discarded binding stays indexed until authorized cleanup, including previously verified artifacts.

func (*Store) Captures 

func (s *Store) Captures(ctx context.Context, key id.ID) ([]CaptureRecord, error)

Captures loads at most sixteen detached bindings, including tombstones and records for terminal jobs. This is an internal recovery read, not a user API.

func (*Store) CheckBroker 

func (s *Store) CheckBroker(name string, key ed25519.PublicKey) error

CheckBroker binds daemon assembly to the journal's pinned broker identity. It reads immutable configuration and does not grant execution or user access.

func (*Store) Claim 

func (s *Store) Claim(ctx context.Context, key id.ID) (Claim, error)

Claim grants ownership once. Neither expiration, process exit nor a lost acknowledgement makes a claimed identity runnable again.

func (*Store) Close 

func (s *Store) Close() error

Close releases ownership without cancelling or forgetting accepted work.

func (*Store) ConfirmCapture 

func (s *Store) ConfirmCapture(ctx context.Context, key id.ID, token string, claimRevision uint64, ref evidence.Ref) (CaptureRecord, error)

ConfirmCapture records readback only for the exact retained upload intent. Call after repository readback and current evidence authorization succeed. It does not prove correctness or grant another upload/execution attempt.

func (*Store) DiscardCapture 

func (s *Store) DiscardCapture(ctx context.Context, key, artifact id.ID, expected uint64, reason string) (CaptureRecord, error)

DiscardCapture records a trusted recovery worker's proof of authorized durable repository cleanup. It requires independently finalized whole-service cleanup (a terminal job), not merely a missing process or expired execution deadline. Callers must prove a repository tombstone or authoritative absence separately.

func (*Store) Enroll 

func (s *Store) Enroll(ctx context.Context, receipt sandbox.Receipt) (Record, error)

Enroll persists the exact signed acceptance before a worker can claim it. Identical retries return the original record, including terminal tombstones.

func (*Store) Finalized 

func (s *Store) Finalized(ctx context.Context, key id.ID, expected uint64) (Record, error)

Finalized commits a report at the exact revision whose whole-service cleanup was independently proved by the caller. Recheck grants before calling; this journal checks the original acceptance and qualification deadlines once more. Workers cannot call this method through the private control transport.

func (*Store) Load 

func (s *Store) Load(ctx context.Context, key id.ID) (Record, error)

Load returns detached state after checking the receipt and record bindings. This internal operation is not an authorized user-facing read endpoint.

func (*Store) Pending 

func (s *Store) Pending(ctx context.Context, after string, limit int) ([]PendingJob, error)

Pending returns at most 256 lightweight recovery entries after an ID cursor.

func (*Store) Propose 

func (s *Store) Propose(ctx context.Context, key id.ID, token string, expected uint64, result sandbox.Result) (Record, error)

Propose fences the claim and persists a report for independent finalization. The daemon must authenticate the worker and recheck grants before this call. Identical retries return current state without granting execution authority.

func (*Store) Reaped 

func (s *Store) Reaped(ctx context.Context, key id.ID, expected uint64) (Record, error)

Reaped records a trusted external containment proof at the expected revision. The caller must independently stop the worker and sandbox cgroups, including ambiguous launches. An absent runtime state file alone is not proof.

func (*Store) RecordCapture 

func (s *Store) RecordCapture(ctx context.Context, key id.ID, token string, claimRevision uint64, ref evidence.Ref) (CaptureRecord, error)

RecordCapture commits an immutable upload intent under the current claim. The daemon must authenticate the worker and current grants before calling. An identical retry returns the existing record; changed metadata conflicts.

func (*Store) RequireReap 

func (s *Store) RequireReap(ctx context.Context, key id.ID) (Record, error)

RequireReap fences a lost worker without authorizing another execution.

func (*Store) VerifyClaim 

func (s *Store) VerifyClaim(ctx context.Context, key id.ID, token string, revision uint64) (Record, error)

VerifyClaim checks current ownership without issuing another execution grant. The daemon must authenticate the worker's service identity and recheck user grants separately. Cancellation, reaping, completion and expiration invalidate an old credential even when its signed receipt remains cryptographically valid.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.