resultstore

package
v0.2.13 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package resultstore persists an already authenticated and validated runner payload. It provides storage integrity, not sender authentication or protocol validation. The receiver must perform those checks before calling Publish.

Index

Constants

View Source
const (
	ChunkBytes      = plancontract.ChunkBytes
	MaxPayloadBytes = plancontract.MaxResultPayloadBytes
	// InlinePayloadBytes leaves room for the binding and JSON/base64 envelope
	// inside one record. Larger results keep the chunked publication protocol.
	InlinePayloadBytes = ChunkBytes / 2

	LabelAttempt = "operator.ptah.run/result-attempt"
	LabelRecord  = labelRecord
)

Variables

View Source
var (
	ErrIncomplete = errors.New("runner result publication is incomplete")
	ErrConflict   = errors.New("runner result publication conflicts with stored evidence")
	ErrInvalid    = errors.New("invalid runner result publication")
)

Functions

func AttemptLabel

func AttemptLabel(name string) string

AttemptLabel indexes metadata only. Full binding and owner identity remain authoritative. The alphabet and fixed alphanumeric ends form a label value.

func AttemptName

func AttemptName(namespace string, uid types.UID, operationID, jobName string) (string, error)

AttemptName locates a publication without requiring its producing Pod to remain present. Finding a name does not authorize consuming its contents.

func MemberOf

func MemberOf(recorded *api.PtahResultRecord, b Binding) bool

MemberOf validates immutable child metadata even after its intent is lost. This permits collecting an orphan under its retained retirement fence. The caller must verify that fence, recovery pins, retention age, and Job absence.

func Name

func Name(b Binding) (string, error)

Name reserves one publication per attempt. A replacement Pod, Job, generation, or epoch cannot obtain a second receipt under the same reserved attempt name.

func ValidateRecordUpdate

func ValidateRecordUpdate(old, next *api.PtahResultRecord) error

ValidateRecordUpdate preserves both immutable bytes and their ownership. API bookkeeping may change without changing publication authority.

Types

type Binding

type Binding struct {
	Namespace          string    `json:"namespace"`
	Kind               string    `json:"kind"`
	Name               string    `json:"name"`
	UID                types.UID `json:"uid"`
	Generation         int64     `json:"generation"`
	ExecutionBindingID string    `json:"executionBindingID"`
	InputFingerprint   string    `json:"inputFingerprint"`
	Operation          string    `json:"operation"`
	OperationID        string    `json:"operationID"`
	JobName            string    `json:"jobName"`
	JobUID             types.UID `json:"jobUID"`
	PodName            string    `json:"podName"`
	PodUID             types.UID `json:"podUID"`
}

Binding is the authority the receiver verified, including the actual Pod UID. None of these fields may be taken on trust from an upload's body.

func StoredBinding

func StoredBinding(intent *api.PtahResultRecord) (Binding, error)

StoredBinding reads the binding of an admission-protected intent for cleanup. Unlike Load, it accepts an API-controlled foreground deletion in progress; it grants no read receipt or authority to resume publication.

type Receipt

type Receipt struct {
	Name   string
	UID    types.UID
	Digest string
	Size   int64
}

Receipt identifies the immutable record that commits the result: the intent itself for an inline result, or the chunked completion. It contains no SQL, payload bytes, database credentials, or delivery credentials.

type Store

type Store struct {
	Client client.Client
	Reader client.Reader
}

Store requires a direct API reader. A cached read cannot certify a completed publication. The caller supplies request deadlines and limits concurrency. Result records are not projected into operation Pods.

func (Store) Load

func (s Store) Load(ctx context.Context, b Binding) ([]byte, Receipt, error)

Load returns nothing until the completion record, identities, lengths, and hashes of every chunk agree. It does not read a Job, Pod, or container log.

func (Store) LoadAttempt

func (s Store) LoadAttempt(ctx context.Context, namespace string, uid types.UID, operationID, jobName string) (Binding, []byte, Receipt, error)

LoadAttempt returns verified storage evidence without reading a Job, Pod, credential, or log. The consumer must hold the returned binding to its full persisted claim and revalidate its current execution epoch and inputs.

func (Store) Publish

func (s Store) Publish(ctx context.Context, b Binding, payload []byte, expectedDigest string) (Receipt, error)

Publish commits small results atomically in their intent. Larger results fix the digest before writing chunks, then create the completion record last. Identical retries resume; conflicting bytes never replace even a partial publication. A successful return includes a complete readback. It is the only storage state on which a receiver may acknowledge.

payload must already be protocol-validated and independently readable after process key loss; storing an old process-sealed Plan is not sufficient.

func (Store) PublishAuthorized

func (s Store) PublishAuthorized(ctx context.Context, b Binding, payload []byte, expectedDigest string, check func(context.Context) error) (Receipt, error)

PublishAuthorized checks live authority immediately before the first write. Chunked publication checks again after chunk writes, before completion or returning an existing receipt. An atomic publication commits at its first write; identical retries still pass that check. Admission and the consuming controller also enforce the current execution epoch.

func (Store) ValidateRecordCreate

func (s Store) ValidateRecordCreate(ctx context.Context, candidate *api.PtahResultRecord) (Binding, []byte, error)

ValidateRecordCreate checks publication structure through direct API reads. It returns the intent's binding and, for a completion, the complete payload. The caller must authenticate the writer, authorize this binding against live operation authority, and validate the completed protocol before admitting it. Nothing is written and no receipt is issued here.

Jump to

Keyboard shortcuts

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