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
- Variables
- func AttemptLabel(name string) string
- func AttemptName(namespace string, uid types.UID, operationID, jobName string) (string, error)
- func MemberOf(recorded *api.PtahResultRecord, b Binding) bool
- func Name(b Binding) (string, error)
- func ValidateRecordUpdate(old, next *api.PtahResultRecord) error
- type Binding
- type Receipt
- type Store
- func (s Store) Load(ctx context.Context, b Binding) ([]byte, Receipt, error)
- func (s Store) LoadAttempt(ctx context.Context, namespace string, uid types.UID, ...) (Binding, []byte, Receipt, error)
- func (s Store) Publish(ctx context.Context, b Binding, payload []byte, expectedDigest string) (Receipt, error)
- func (s Store) PublishAuthorized(ctx context.Context, b Binding, payload []byte, expectedDigest string, ...) (Receipt, error)
- func (s Store) ValidateRecordCreate(ctx context.Context, candidate *api.PtahResultRecord) (Binding, []byte, error)
Constants ¶
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 ¶
Functions ¶
func AttemptLabel ¶
AttemptLabel indexes metadata only. Full binding and owner identity remain authoritative. The alphabet and fixed alphanumeric ends form a label value.
func AttemptName ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.