resultdelivery

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: 21 Imported by: 0

Documentation

Overview

Package resultdelivery implements authenticated, bounded delivery of an already executed operation. It never starts a SQL executor.

Index

Constants

View Source
const (
	PathPrefix   = "/v1/results/"
	DigestHeader = "X-Ptah-Result-Digest"
	ContentType  = "application/vnd.ptah.result.v1+json"
)
View Source
const TokenAudience = "operator.ptah.run/results"

TokenAudience is deliberately distinct from the Kubernetes API audience. Installations must not add it to the API server's accepted audiences.

Variables

View Source
var (
	ErrAuthority = errors.New("result delivery authority is invalid or expired")
	ErrPayload   = errors.New("result delivery payload is invalid")
)

Functions

func CertificateURI

func CertificateURI(identity Identity) (*url.URL, error)

CertificateURI constructs a SAN for an identity the certificate issuer has already authorized. It neither issues a certificate nor verifies authority.

func Decode

func Decode(identity Identity, payload []byte) (runner.Result, error)

Decode refuses noncanonical documents (including duplicate or unknown JSON fields), foreign operations, and plans that cannot survive process-key loss. The controller must still check policy, target fingerprints, and provenance.

func Encode

func Encode(identity Identity, result runner.Result) ([]byte, error)

Encode encodes the durable wire document. For a changed Plan, Stdout must contain the exact plaintext plan, not a process-sealed legacy log payload. These bytes are only for authenticated TLS delivery and confidential result-record storage.

func ValidToken

func ValidToken(token string) bool

ValidToken bounds header memory and refuses whitespace and non-ASCII bytes. Cryptographic verification belongs to TokenReview, never to this predicate.

Types

type AuthenticateToken

type AuthenticateToken func(context.Context, string, Identity) error

AuthenticateToken verifies a Pod-bound token against an untrusted identity claim. Authorize must still verify the operation and its immutable Pod pin.

type Identity

type Identity struct {
	Binding resultstore.Binding `json:"binding"`
	Engine  string              `json:"engine"`
}

Identity is carried in the client certificate's sole URI SAN. Engine is the target engine fixed by the claim; it is empty only for operations that have no database target. The issuer and live authorizer must derive it from the claim, never from an upload body or an unverified certificate request.

func ClientIdentity

func ClientIdentity(certificate tls.Certificate) (Identity, error)

ClientIdentity reads the binding from a locally provisioned client certificate. It refuses an expired or non-client leaf, but does not authenticate its issuer; the receiver's TLS verification establishes that trust.

func StoredClientIdentity

func StoredClientIdentity(certificate tls.Certificate) (Identity, error)

StoredClientIdentity decodes an immutable credential's recorded binding for cleanup after expiry or CA retirement. It authenticates neither the issuer nor current execution authority and must never authorize delivery. The caller must establish the stored object's provenance and check live retention pins.

type Publisher

type Publisher interface {
	PublishAuthorized(context.Context, resultstore.Binding, []byte, string, func(context.Context) error) (resultstore.Receipt, error)
}

Publisher returns only a durable, fully read-back receipt. check must run before the first write and again after chunk writes, before committing or returning a chunked receipt. One atomic write needs only the first check.

type Receiver

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

func NewReceiver

func NewReceiver(config ReceiverConfig) (*Receiver, error)

func (*Receiver) ServeHTTP

func (r *Receiver) ServeHTTP(w http.ResponseWriter, request *http.Request)

func (*Receiver) Server

func (r *Receiver) Server(certificate tls.Certificate, clientCAs *x509.CertPool) (*http.Server, error)

Server owns a dedicated listener; it is independent of reconcile workers. A token-authenticated receiver accepts no client CA. The certificate transport requires a dedicated client CA and exact per-Pod certificate issuance.

type ReceiverConfig

type ReceiverConfig struct {
	Store     Publisher
	Authorize func(context.Context, Identity) error
	// VerifyClient optionally adds a current-trust check to the mandatory mTLS
	// identity check. Rotating receivers use it to revoke preexisting connections.
	VerifyClient func(*tls.ConnectionState) error
	// AuthenticateToken selects Pod-bound tokens instead of mTLS. This is an
	// installation choice, not a request-controlled authentication fallback.
	AuthenticateToken AuthenticateToken
	MaxConcurrent     int
	Timeout           time.Duration
}

ReceiverConfig has no permissive authorization default. Authorize must use direct API reads to validate the complete identity, claim, epoch, Job, and Pod. It returns ErrAuthority for a definitive refusal and another error for a transient failure. It must return promptly when ctx is canceled. Admission and the consuming controller retain their own authority checks across concurrent state changes.

type RetryPolicy

type RetryPolicy struct {
	Attempts       int
	Interval       time.Duration
	AttemptTimeout time.Duration
	TotalTimeout   time.Duration
}

type Sender

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

Sender holds only delivery configuration, not an executor or SQL callback. Send retries the one immutable payload it was handed.

func NewSender

func NewSender(endpoint string, identity Identity, tlsConfig *tls.Config, retry RetryPolicy) (*Sender, error)

NewSender requires authenticated TLS in both directions and refuses redirects. endpoint is the receiver origin, with no path, query, or user information.

func NewTokenSender

func NewTokenSender(endpoint string, identity Identity, tlsConfig *tls.Config, retry RetryPolicy, source TokenSource) (*Sender, error)

NewTokenSender authenticates the server using TLS and sends a receiver-only Pod-bound token. It never falls back to client certificates or follows a redirect. The source is reread for preflight and each retransmission.

func (*Sender) Check

func (s *Sender) Check(parent context.Context) error

Check authenticates the projected credential with the configured receiver before a runner starts its child. Having a projected credential does not prove the runner's current authority. This bounded, read-only request catches unusable projections without executing SQL or publishing a result. A busy upload slot or a transient API/transport failure uses the same retry bounds as delivery. A definitive authority refusal still stops immediately. Returned errors omit credentials and receiver response bodies.

func (*Sender) Close

func (s *Sender) Close()

func (*Sender) Send

func (s *Sender) Send(parent context.Context, payload []byte) (resultstore.Receipt, error)

Send never changes bytes between attempts, never follows a redirect, and returns no payload or server response body in an error. A lost response after durable persistence may be retried; a definitive refusal is returned at once.

type TokenSource

type TokenSource func() (string, error)

TokenSource reads the current kubelet projection for every HTTP attempt. Neither Sender nor the durable store retains tokens between attempts.

Directories

Path Synopsis
Package jobconfig fixes the runner's durable-delivery inputs in its immutable Job template.
Package jobconfig fixes the runner's durable-delivery inputs in its immutable Job template.
Package resulttest shares production Job fixtures for delivery component tests.
Package resulttest shares production Job fixtures for delivery component tests.

Jump to

Keyboard shortcuts

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