Documentation
¶
Overview ¶
Package resultdelivery implements authenticated, bounded delivery of an already executed operation. It never starts a SQL executor.
Index ¶
- Constants
- Variables
- func CertificateURI(identity Identity) (*url.URL, error)
- func Decode(identity Identity, payload []byte) (runner.Result, error)
- func Encode(identity Identity, result runner.Result) ([]byte, error)
- func ValidToken(token string) bool
- type AuthenticateToken
- type Identity
- type Publisher
- type Receiver
- type ReceiverConfig
- type RetryPolicy
- type Sender
- type TokenSource
Constants ¶
const ( PathPrefix = "/v1/results/" DigestHeader = "X-Ptah-Result-Digest" ContentType = "application/vnd.ptah.result.v1+json" )
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 ¶
var ( ErrAuthority = errors.New("result delivery authority is invalid or expired") ErrPayload = errors.New("result delivery payload is invalid") )
Functions ¶
func CertificateURI ¶
CertificateURI constructs a SAN for an identity the certificate issuer has already authorized. It neither issues a certificate nor verifies authority.
func Decode ¶
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 ¶
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 ¶
ValidToken bounds header memory and refuses whitespace and non-ASCII bytes. Cryptographic verification belongs to TokenReview, never to this predicate.
Types ¶
type AuthenticateToken ¶
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 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 ¶
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.
type TokenSource ¶
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. |