@opensoha/contracts 0.1.29 → 0.2.0

package/proxytransport/username.go

@@ -0,0 +1,51 @@
+package proxytransport
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"regexp"
+	"strings"
+)
+
+// MaxUsernameBytes bounds HTTP Basic usernames, including opaque mapped IDs.
+// Two maximum-length identifiers encode to fewer than 360 bytes.
+const MaxUsernameBytes = 512
+
+var mappedIdentifier = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`)
+
+// EncodeMappedUsername encodes exactly [credentialID,nodeID] as canonical JSON
+// with unpadded URL-safe base64. Unlike the IDs, the result never contains ':',
+// which is reserved as HTTP Basic's username/password separator.
+func EncodeMappedUsername(credentialID, nodeID string) (string, error) {
+	if !mappedIdentifier.MatchString(credentialID) || !mappedIdentifier.MatchString(nodeID) {
+		return "", errors.New("invalid mapped proxy identifier")
+	}
+	data, err := json.Marshal([2]string{credentialID, nodeID})
+	if err != nil {
+		return "", err
+	}
+	return "v1." + base64.RawURLEncoding.EncodeToString(data), nil
+}
+
+// DecodeMappedUsername accepts only the canonical v1 encoding. It rejects
+// alternate JSON/base64 spellings so callers share one unambiguous identity key.
+func DecodeMappedUsername(username string) (credentialID, nodeID string, err error) {
+	invalid := errors.New("invalid mapped proxy username")
+	if len(username) > MaxUsernameBytes || !strings.HasPrefix(username, "v1.") {
+		return "", "", invalid
+	}
+	data, err := base64.RawURLEncoding.Strict().DecodeString(username[len("v1."):])
+	if err != nil {
+		return "", "", invalid
+	}
+	var identifiers []string
+	if json.Unmarshal(data, &identifiers) != nil || len(identifiers) != 2 {
+		return "", "", invalid
+	}
+	canonical, err := EncodeMappedUsername(identifiers[0], identifiers[1])
+	if err != nil || canonical != username {
+		return "", "", invalid
+	}
+	return identifiers[0], identifiers[1], nil
+}

package/proxytransport/username_test.go

@@ -0,0 +1,98 @@
+package proxytransport
+
+import (
+	"context"
+	"encoding/base64"
+	"net"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestMappedUsernameRoundTrip(t *testing.T) {
+	for _, ids := range [][2]string{{"c", "n"}, {"credential.a:b", "node:c.d"}, {"c" + strings.Repeat(":", 127), "n" + strings.Repeat(".", 127)}} {
+		username, err := EncodeMappedUsername(ids[0], ids[1])
+		if err != nil || strings.Contains(username, ":") || len(username) > MaxUsernameBytes {
+			t.Fatalf("encode: length=%d err=%v", len(username), err)
+		}
+		credentialID, nodeID, err := DecodeMappedUsername(username)
+		if err != nil || credentialID != ids[0] || nodeID != ids[1] {
+			t.Fatalf("round trip: %q %q %v", credentialID, nodeID, err)
+		}
+	}
+}
+
+func TestMappedUsernameRejectsInvalidEncodings(t *testing.T) {
+	encodedJSON := func(raw string) string { return "v1." + base64.RawURLEncoding.EncodeToString([]byte(raw)) }
+	canonical, err := EncodeMappedUsername("credential", "node")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range []struct{ name, username string }{
+		{"unknown version", "v2." + strings.TrimPrefix(canonical, "v1.")},
+		{"oversized", strings.Repeat("a", MaxUsernameBytes+1)},
+		{"bad base64", "v1.!"},
+		{"empty payload", "v1."},
+		{"padded base64", canonical + "="},
+		{"base64 newline", canonical + "\n"},
+		{"not an array", encodedJSON(`{"credential":"node"}`)},
+		{"one item", encodedJSON(`["credential"]`)},
+		{"three items", encodedJSON(`["credential","node","extra"]`)},
+		{"nonstring item", encodedJSON(`["credential",1]`)},
+		{"null item", encodedJSON(`[null,"node"]`)},
+		{"invalid identifier", encodedJSON(`["credential","node/path"]`)},
+		{"trailing data", encodedJSON(`["credential","node"][]`)},
+		{"JSON whitespace", encodedJSON(`["credential", "node"]`)},
+		{"escaped spelling", encodedJSON(`["\u0063redential","node"]`)},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if c, n, err := DecodeMappedUsername(tc.username); err == nil || c != "" || n != "" {
+				t.Fatalf("accepted noncanonical username: %q %q %v", c, n, err)
+			}
+		})
+	}
+	for _, id := range []string{"", ".leading", "contains space", "node/path", "节点", "a" + strings.Repeat("x", 128)} {
+		if _, err := EncodeMappedUsername(id, "node"); err == nil {
+			t.Fatalf("invalid identifier accepted: %q", id)
+		}
+		if _, err := EncodeMappedUsername("credential", id); err == nil {
+			t.Fatalf("invalid node identifier accepted: %q", id)
+		}
+	}
+}
+
+func TestMappedUsernameBasicAuthenticationAndLimit(t *testing.T) {
+	username, err := EncodeMappedUsername("c"+strings.Repeat(":", 127), "n"+strings.Repeat(".", 127))
+	if err != nil || len(username) <= 128 {
+		t.Fatalf("expected long encoded username: %d %v", len(username), err)
+	}
+	password := strings.Repeat("p", 32)
+	dial := func(context.Context, string, string) (net.Conn, error) { return nil, nil }
+	h, err := New(map[string]string{username: password}, dial, time.Now().Add(time.Minute))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = h.Close() }()
+	r := httptest.NewRequest("CONNECT", "http://example.invalid", nil)
+	r.SetBasicAuth(username, password)
+	r.Header.Set("Proxy-Authorization", r.Header.Get("Authorization"))
+	r.Header.Del("Authorization")
+	if got, ok := h.authenticate(r); !ok || got != username {
+		t.Fatal("mapped IDs containing colons failed Basic authentication")
+	}
+	r.SetBasicAuth(username, strings.Repeat("q", 32))
+	r.Header.Set("Proxy-Authorization", r.Header.Get("Authorization"))
+	if _, ok := h.authenticate(r); ok {
+		t.Fatal("wrong password accepted")
+	}
+	for _, size := range []int{MaxUsernameBytes, MaxUsernameBytes + 1} {
+		handler, err := New(map[string]string{strings.Repeat("u", size): password}, dial, time.Now().Add(time.Minute))
+		if size == MaxUsernameBytes && err != nil || size > MaxUsernameBytes && err == nil {
+			t.Fatalf("username size %d: %v", size, err)
+		}
+		if handler != nil {
+			_ = handler.Close()
+		}
+	}
+}

package/resource/conditional_workload_action.go

@@ -0,0 +1,63 @@
+package resource
+
+import (
+	"fmt"
+	"strconv"
+)
+
+type ConditionalWorkloadActionInput struct {
+	Preconditions ResourceMutationPreconditions `json:"preconditions"`
+	Replicas      *int32                        `json:"replicas,omitempty"`
+	Revision      string                        `json:"revision,omitempty"`
+	DryRun        bool                          `json:"dryRun,omitempty"`
+}
+
+func (input ConditionalWorkloadActionInput) Validate(kind, action string) error {
+	if err := input.Preconditions.Validate(); err != nil {
+		return err
+	}
+	switch action {
+	case "restart":
+		if (kind != "Deployment" && kind != "StatefulSet" && kind != "DaemonSet") || input.Replicas != nil || input.Revision != "" {
+			return fmt.Errorf("restart supports Deployment, StatefulSet and DaemonSet without replicas or revision")
+		}
+	case "scale":
+		if (kind != "Deployment" && kind != "StatefulSet") || input.Replicas == nil || *input.Replicas < 0 || input.Revision != "" {
+			return fmt.Errorf("scale requires Deployment or StatefulSet and nonnegative replicas without revision")
+		}
+	case "rollback":
+		if kind != "Deployment" || input.Replicas != nil || !validWorkloadRevision(input.Revision) {
+			return fmt.Errorf("rollback requires Deployment and one positive revision without replicas")
+		}
+	default:
+		return fmt.Errorf("unsupported conditional workload action")
+	}
+	return nil
+}
+
+func validWorkloadRevision(value string) bool {
+	if value == "" || len(value) > 19 || value[0] == '0' {
+		return false
+	}
+	for _, r := range value {
+		if r < '0' || r > '9' {
+			return false
+		}
+	}
+	revision, err := strconv.ParseInt(value, 10, 64)
+	return err == nil && revision > 0
+}
+
+// The returned UID/version belongs to the API response. Applied acknowledges
+// an update, not observed rollout readiness. DryRun never changes live state.
+type ConditionalWorkloadActionReceipt struct {
+	Applied         bool                          `json:"applied"`
+	DryRun          bool                          `json:"dryRun"`
+	Kind            string                        `json:"kind"`
+	Name            string                        `json:"name"`
+	Namespace       string                        `json:"namespace"`
+	Action          string                        `json:"action"`
+	UID             string                        `json:"uid"`
+	ResourceVersion string                        `json:"resourceVersion"`
+	Preconditions   ResourceMutationPreconditions `json:"preconditions"`
+}

package/resource/mutation_preconditions.go

@@ -0,0 +1,67 @@
+package resource
+
+import (
+	"fmt"
+	"strings"
+	"time"
+	"unicode"
+)
+
+// ResourceMutationPreconditions pins the object reviewed by the caller. Values
+// are opaque; in particular, resourceVersion must not be parsed as a number.
+type ResourceMutationPreconditions struct {
+	ExpectedUID             string `json:"expectedUid"`
+	ExpectedResourceVersion string `json:"expectedResourceVersion"`
+}
+
+func (p ResourceMutationPreconditions) Validate() error {
+	for _, value := range []string{p.ExpectedUID, p.ExpectedResourceVersion} {
+		if value == "" || len(value) > 256 || strings.IndexFunc(value, func(r rune) bool { return unicode.IsSpace(r) || unicode.IsControl(r) }) >= 0 {
+			return fmt.Errorf("expectedUid and expectedResourceVersion must be non-empty opaque values of at most 256 bytes without whitespace or control characters")
+		}
+	}
+	return nil
+}
+
+// ResourceIdentity deliberately contains no resource content or Secret data.
+type ResourceIdentity struct {
+	APIVersion        string     `json:"apiVersion"`
+	Kind              string     `json:"kind"`
+	Name              string     `json:"name"`
+	Namespace         string     `json:"namespace,omitempty"`
+	UID               string     `json:"uid"`
+	ResourceVersion   string     `json:"resourceVersion"`
+	DeletionTimestamp *time.Time `json:"deletionTimestamp,omitempty"`
+}
+
+type ConditionalResourceYAMLInput struct {
+	Content       string                        `json:"content"`
+	Preconditions ResourceMutationPreconditions `json:"preconditions"`
+}
+
+// ResourceDeletionReceipt reports acceptance for the frozen target only.
+// Callers must observe the target UID separately before reporting completion.
+type ResourceDeletionReceipt struct {
+	Accepted      bool                          `json:"accepted"`
+	State         string                        `json:"state"`
+	Kind          string                        `json:"kind"`
+	Name          string                        `json:"name"`
+	Namespace     string                        `json:"namespace,omitempty"`
+	Preconditions ResourceMutationPreconditions `json:"preconditions"`
+}
+
+// ConditionalResourceMutationRequest is the Agent transport. Core derives the
+// target from its authorized route rather than accepting an arbitrary API path.
+type ConditionalResourceMutationRequest struct {
+	Namespace     string                        `json:"namespace,omitempty"`
+	Kind          string                        `json:"kind"`
+	Name          string                        `json:"name"`
+	Preconditions ResourceMutationPreconditions `json:"preconditions"`
+}
+
+type ConditionalResourceYAMLRequest struct {
+	Namespace string `json:"namespace,omitempty"`
+	Kind      string `json:"kind"`
+	Name      string `json:"name"`
+	ConditionalResourceYAMLInput
+}

package/resource/pod_execution.go

@@ -0,0 +1,206 @@
+package resource
+
+import (
+	"encoding/base64"
+	"fmt"
+	"strings"
+	"time"
+	"unicode"
+	"unicode/utf8"
+
+	"k8s.io/apimachinery/pkg/util/validation"
+)
+
+const (
+	PodExecutionProtocolVersion        = "1"
+	PodExecDefaultTimeoutSeconds int64 = 10
+	PodExecMaxTimeoutSeconds     int64 = 300
+	PodExecDefaultOutputBytes    int64 = 64 << 10
+	PodArgvMaxOutputBytes        int64 = 1 << 20
+	PodExecMaxStdinBytes               = 64 << 10
+)
+
+// PodArgvInput never adds a shell. A caller may explicitly select a shell in
+// argv, under the same exec authorization and immutable execution receipt.
+type PodArgvInput struct {
+	ExpectedUID    string   `json:"expectedUid"`
+	Container      string   `json:"container,omitempty"`
+	Argv           []string `json:"argv"`
+	StdinBase64    string   `json:"stdinBase64,omitempty"`
+	TimeoutSeconds int64    `json:"timeoutSeconds,omitempty"`
+	MaxOutputBytes int64    `json:"maxOutputBytes,omitempty"`
+}
+
+func (input PodArgvInput) Normalized() (PodArgvInput, error) {
+	if input.ExpectedUID == "" || len(input.ExpectedUID) > 256 || strings.IndexFunc(input.ExpectedUID, func(r rune) bool { return unicode.IsSpace(r) || unicode.IsControl(r) }) >= 0 {
+		return PodArgvInput{}, fmt.Errorf("a reviewed Pod UID of at most 256 bytes without whitespace or controls is required")
+	}
+	if input.Container != "" && len(validation.IsDNS1123Label(input.Container)) > 0 {
+		return PodArgvInput{}, fmt.Errorf("container must be one valid Kubernetes container name")
+	}
+	if len(input.Argv) < 1 || len(input.Argv) > 64 || strings.TrimSpace(input.Argv[0]) == "" {
+		return PodArgvInput{}, fmt.Errorf("argv requires one executable and at most 64 arguments")
+	}
+	total := 0
+	for _, arg := range input.Argv {
+		if len(arg) > 8192 || strings.ContainsRune(arg, 0) {
+			return PodArgvInput{}, fmt.Errorf("argv values must be bounded and contain no NUL")
+		}
+		total += len(arg)
+		if total > 32768 {
+			return PodArgvInput{}, fmt.Errorf("argv exceeds the 32768 byte budget")
+		}
+	}
+	if input.TimeoutSeconds < 0 || input.TimeoutSeconds > PodExecMaxTimeoutSeconds || input.MaxOutputBytes < 0 || input.MaxOutputBytes > PodArgvMaxOutputBytes {
+		return PodArgvInput{}, fmt.Errorf("exec timeout or combined output budget is outside the supported bounds")
+	}
+	if input.TimeoutSeconds == 0 {
+		input.TimeoutSeconds = PodExecDefaultTimeoutSeconds
+	}
+	if input.MaxOutputBytes == 0 {
+		input.MaxOutputBytes = PodExecDefaultOutputBytes
+	}
+	if len(input.StdinBase64) > base64.StdEncoding.EncodedLen(PodExecMaxStdinBytes) {
+		return PodArgvInput{}, fmt.Errorf("stdin exceeds the 65536 byte budget")
+	}
+	stdin, err := base64.StdEncoding.Strict().DecodeString(input.StdinBase64)
+	if err != nil || len(stdin) > PodExecMaxStdinBytes || base64.StdEncoding.EncodeToString(stdin) != input.StdinBase64 {
+		return PodArgvInput{}, fmt.Errorf("stdin must be bounded standard base64")
+	}
+	input.StdinBase64 = base64.StdEncoding.EncodeToString(stdin)
+	input.Argv = append([]string(nil), input.Argv...)
+	return input, nil
+}
+
+type PodExecutionOutput struct {
+	Status                 string `json:"status"`
+	ExitCode               *int64 `json:"exitCode,omitempty"`
+	Stdout                 string `json:"stdout"`
+	Stderr                 string `json:"stderr"`
+	StdoutEncoding         string `json:"stdoutEncoding"`
+	StderrEncoding         string `json:"stderrEncoding"`
+	StdoutBytes            int64  `json:"stdoutBytes"`
+	StderrBytes            int64  `json:"stderrBytes"`
+	MaxOutputBytes         int64  `json:"maxOutputBytes"`
+	StdoutTruncated        bool   `json:"stdoutTruncated"`
+	StderrTruncated        bool   `json:"stderrTruncated"`
+	UIDVerifiedBeforeStart bool   `json:"uidVerifiedBeforeStart"`
+	TargetChanged          bool   `json:"targetChanged"`
+	ReasonCode             string `json:"reasonCode,omitempty"`
+}
+
+func DecodePodExecutionStream(value, encoding string) ([]byte, error) {
+	switch encoding {
+	case "utf-8":
+		if len(value) > int(PodArgvMaxOutputBytes) || !utf8.ValidString(value) {
+			return nil, fmt.Errorf("invalid or oversized UTF-8 process output")
+		}
+		return []byte(value), nil
+	case "base64":
+		if len(value) > base64.StdEncoding.EncodedLen(int(PodArgvMaxOutputBytes)) {
+			return nil, fmt.Errorf("oversized process output")
+		}
+		data, err := base64.StdEncoding.Strict().DecodeString(value)
+		if err != nil || int64(len(data)) > PodArgvMaxOutputBytes || base64.StdEncoding.EncodeToString(data) != value {
+			return nil, fmt.Errorf("invalid base64 process output")
+		}
+		return data, nil
+	default:
+		return nil, fmt.Errorf("unsupported process output encoding")
+	}
+}
+
+type PodExecutionTarget struct {
+	Namespace string    `json:"namespace"`
+	PodName   string    `json:"podName"`
+	UID       string    `json:"uid"`
+	Container string    `json:"container"`
+	CheckedAt time.Time `json:"checkedAt"`
+}
+
+type PodArgvResult struct {
+	Target PodExecutionTarget `json:"target"`
+	Output PodExecutionOutput `json:"output"`
+}
+
+// Validate rejects a response from a mismatched or incompatible execution
+// adapter before its data can enter a durable receipt.
+func (result PodArgvResult) Validate(namespace, name string, input PodArgvInput) error {
+	target, output := result.Target, result.Output
+	if target.Namespace != namespace || target.PodName != name || target.UID != input.ExpectedUID || target.CheckedAt.IsZero() || len(validation.IsDNS1123Label(target.Container)) > 0 || input.Container != "" && target.Container != input.Container {
+		return fmt.Errorf("pod execution response target does not match")
+	}
+	if err := output.Validate(input.MaxOutputBytes); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (output PodExecutionOutput) Validate(maximum int64) error {
+	if maximum < 1 || maximum > PodArgvMaxOutputBytes || output.MaxOutputBytes != maximum || !output.UIDVerifiedBeforeStart || output.TargetChanged && output.Status != "unknown" {
+		return fmt.Errorf("invalid Pod execution output bounds or identity")
+	}
+	switch output.Status {
+	case "succeeded":
+		if output.ExitCode == nil || *output.ExitCode != 0 {
+			return fmt.Errorf("successful Pod execution requires exit code zero")
+		}
+	case "failed":
+		if output.ExitCode == nil {
+			return fmt.Errorf("failed process requires a known exit code")
+		}
+	case "timed_out", "canceled", "transport_lost", "unknown":
+	default:
+		return fmt.Errorf("invalid Pod execution status")
+	}
+	if output.ExitCode != nil && (*output.ExitCode < 0 || *output.ExitCode > 4294967295) {
+		return fmt.Errorf("invalid process exit code")
+	}
+	stdout, err := DecodePodExecutionStream(output.Stdout, output.StdoutEncoding)
+	if err != nil {
+		return err
+	}
+	stderr, err := DecodePodExecutionStream(output.Stderr, output.StderrEncoding)
+	if err != nil {
+		return err
+	}
+	if int64(len(stdout)+len(stderr)) > maximum || !validPodStreamCount(output.StdoutBytes, len(stdout), output.StdoutTruncated) || !validPodStreamCount(output.StderrBytes, len(stderr), output.StderrTruncated) {
+		return fmt.Errorf("inconsistent Pod execution output counters")
+	}
+	return nil
+}
+
+func validPodStreamCount(observed int64, retained int, truncated bool) bool {
+	if truncated {
+		return observed > int64(retained)
+	}
+	return observed == int64(retained)
+}
+
+type PodExecutionReceipt struct {
+	ID              string              `json:"id"`
+	Status          string              `json:"status"`
+	ClusterID       string              `json:"clusterId"`
+	Namespace       string              `json:"namespace"`
+	PodName         string              `json:"podName"`
+	ExpectedUID     string              `json:"expectedUid"`
+	Container       string              `json:"container"`
+	CreatedAt       time.Time           `json:"createdAt"`
+	DeadlineAt      time.Time           `json:"deadlineAt"`
+	ExpiresAt       time.Time           `json:"expiresAt"`
+	FinishedAt      *time.Time          `json:"finishedAt,omitempty"`
+	OutputAvailable bool                `json:"outputAvailable"`
+	Output          *PodExecutionOutput `json:"output,omitempty"`
+}
+
+type AgentPodExecutionCapabilities struct {
+	TerminalVersion        string `json:"terminalVersion,omitempty"`
+	MaxSessionSeconds      int64  `json:"maxSessionSeconds,omitempty"`
+	MaxTerminalInputBytes  int64  `json:"maxTerminalInputBytes,omitempty"`
+	MaxTerminalOutputBytes int64  `json:"maxTerminalOutputBytes,omitempty"`
+	ProtocolVersion        string `json:"protocolVersion"`
+	ArgvVersion            string `json:"argvVersion"`
+	Ready                  bool   `json:"ready"`
+	MaxTimeoutSeconds      int64  `json:"maxTimeoutSeconds"`
+	MaxOutputBytes         int64  `json:"maxOutputBytes"`
+}

package/resource/pod_execution_gateway.go

@@ -0,0 +1,119 @@
+package resource
+
+import (
+	"fmt"
+	"regexp"
+	"time"
+	"unicode"
+	"unicode/utf8"
+
+	"k8s.io/apimachinery/pkg/util/validation"
+)
+
+// PodArgvToolInput mirrors the closed KubernetesPodArgvToolInput schema.
+// Gateway-only schemas are not HTTP operations and are pruned by the Go HTTP
+// generator. These helpers share the existing runtime's semantic validation;
+// they neither authorize a caller nor start a process.
+type PodArgvToolInput struct {
+	ClusterID      string       `json:"clusterId"`
+	Namespace      string       `json:"namespace"`
+	PodName        string       `json:"podName"`
+	IdempotencyKey string       `json:"idempotencyKey"`
+	Execution      PodArgvInput `json:"execution"`
+}
+
+func (input PodArgvToolInput) Normalized() (PodArgvToolInput, error) {
+	if !validPodToolTarget(input.ClusterID, input.Namespace, input.PodName) || !validPodToolKey(input.IdempotencyKey) {
+		return PodArgvToolInput{}, fmt.Errorf("valid cluster, namespace, Pod and original execution key are required")
+	}
+	execution, err := input.Execution.Normalized()
+	if err != nil {
+		return PodArgvToolInput{}, err
+	}
+	input.Execution = execution
+	return input, nil
+}
+
+type PodExecutionLookupInput struct {
+	ClusterID      string `json:"clusterId"`
+	Namespace      string `json:"namespace"`
+	PodName        string `json:"podName"`
+	ExecutionID    string `json:"executionId,omitempty"`
+	IdempotencyKey string `json:"idempotencyKey,omitempty"`
+}
+
+// PodGatewayResult is a safe Gateway projection, not the raw native receipt.
+// Receipt never carries Output and always has OutputAvailable=false. Text
+// output may be redacted; its byte counters retain original source counts.
+// Binary output must be withheld instead of forwarding encoded secret bytes.
+type PodGatewayResult struct {
+	Receipt     PodGatewayReceipt   `json:"receipt"`
+	OutputState string              `json:"outputState"`
+	Output      *PodExecutionOutput `json:"output,omitempty"`
+}
+
+// PodGatewayReceipt cannot hold raw process streams. Construct Gateway results
+// through NewPodGatewayResult; its outputAvailable flag is always false.
+type PodGatewayReceipt struct {
+	ID              string     `json:"id"`
+	Status          string     `json:"status"`
+	ClusterID       string     `json:"clusterId"`
+	Namespace       string     `json:"namespace"`
+	PodName         string     `json:"podName"`
+	ExpectedUID     string     `json:"expectedUid"`
+	Container       string     `json:"container"`
+	CreatedAt       time.Time  `json:"createdAt"`
+	DeadlineAt      time.Time  `json:"deadlineAt"`
+	ExpiresAt       time.Time  `json:"expiresAt"`
+	FinishedAt      *time.Time `json:"finishedAt,omitempty"`
+	OutputAvailable bool       `json:"outputAvailable"`
+}
+
+func NewPodGatewayResult(receipt PodExecutionReceipt) PodGatewayResult {
+	return PodGatewayResult{OutputState: "unavailable", Receipt: PodGatewayReceipt{
+		ID: receipt.ID, Status: receipt.Status, ClusterID: receipt.ClusterID,
+		Namespace: receipt.Namespace, PodName: receipt.PodName,
+		ExpectedUID: receipt.ExpectedUID, Container: receipt.Container,
+		CreatedAt: receipt.CreatedAt, DeadlineAt: receipt.DeadlineAt,
+		ExpiresAt: receipt.ExpiresAt, FinishedAt: receipt.FinishedAt,
+	}}
+}
+
+var podToolExecutionID = regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`)
+
+func (input PodExecutionLookupInput) Validate() error {
+	if !validPodToolTarget(input.ClusterID, input.Namespace, input.PodName) {
+		return fmt.Errorf("valid cluster, namespace and Pod are required")
+	}
+	if (input.ExecutionID == "") == (input.IdempotencyKey == "") {
+		return fmt.Errorf("exactly one original execution ID or key is required")
+	}
+	if input.ExecutionID != "" && !podToolExecutionID.MatchString(input.ExecutionID) || input.IdempotencyKey != "" && !validPodToolKey(input.IdempotencyKey) {
+		return fmt.Errorf("invalid original execution ID or key")
+	}
+	return nil
+}
+
+func validPodToolTarget(cluster, namespace, pod string) bool {
+	if cluster == "" || !utf8.ValidString(cluster) || utf8.RuneCountInString(cluster) > 256 {
+		return false
+	}
+	for _, char := range cluster {
+		if unicode.IsControl(char) || unicode.IsSpace(char) || char == '\ufeff' {
+			return false
+		}
+	}
+	return len(validation.IsDNS1123Label(namespace)) == 0 && len(validation.IsDNS1123Subdomain(pod)) == 0
+}
+
+func validPodToolKey(key string) bool {
+	if len(key) < 1 || len(key) > 128 {
+		return false
+	}
+	for _, char := range key {
+		if char < '!' || char > '~' {
+			return false
+		}
+	}
+	return true
+}