@opensoha/contracts 0.1.29 → 0.2.0

package/resource/runtime/pod_execution_test.go

@@ -0,0 +1,194 @@
+package runtime
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"reflect"
+	"strings"
+	"testing"
+
+	contractresource "github.com/opensoha/soha/contracts/resource"
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
+	"k8s.io/client-go/kubernetes"
+	"k8s.io/client-go/kubernetes/fake"
+	"k8s.io/client-go/rest"
+	"k8s.io/client-go/tools/remotecommand"
+	utilexec "k8s.io/client-go/util/exec"
+)
+
+type podExecutorStub struct {
+	run func(context.Context, remotecommand.StreamOptions) error
+}
+
+func (s podExecutorStub) Stream(options remotecommand.StreamOptions) error {
+	return s.run(context.Background(), options)
+}
+func (s podExecutorStub) StreamWithContext(ctx context.Context, options remotecommand.StreamOptions) error {
+	return s.run(ctx, options)
+}
+
+func executionFixturePod() *corev1.Pod {
+	return &corev1.Pod{ObjectMeta: metav1.ObjectMeta{Name: "fixture", Namespace: "test", UID: types.UID("reviewed")}, Spec: corev1.PodSpec{Containers: []corev1.Container{{Name: "main"}}}}
+}
+
+func TestPodArgvPreservesUpgradeHTTPDenialWithoutReadingProviderBody(t *testing.T) {
+	for _, code := range []int{400, 401, 403, 404} {
+		t.Run(http.StatusText(code), func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) {
+				if strings.HasSuffix(request.URL.Path, "/exec") {
+					w.WriteHeader(code)
+					_, _ = io.WriteString(w, strings.Repeat("PRIVATE_PROVIDER_MARKER", 5000))
+					return
+				}
+				w.Header().Set("Content-Type", "application/json")
+				_ = json.NewEncoder(w).Encode(executionFixturePod())
+			}))
+			defer server.Close()
+			config := &rest.Config{Host: server.URL}
+			client, err := kubernetes.NewForConfig(config)
+			if err != nil {
+				t.Fatal(err)
+			}
+			_, err = ExecutePodArgv(t.Context(), client, config, "test", "fixture", contractresource.PodArgvInput{ExpectedUID: "reviewed", Argv: []string{"true"}}, nil)
+			var status apierrors.APIStatus
+			if !errors.As(err, &status) || int(status.Status().Code) != code || strings.Contains(err.Error(), "PRIVATE_PROVIDER_MARKER") {
+				t.Fatalf("upgrade lost its safe HTTP category: %v", err)
+			}
+		})
+	}
+}
+
+func TestPodArgvUsesExactArgumentsAndCombinedOutputBudget(t *testing.T) {
+	pod := executionFixturePod()
+	client := fake.NewClientset(pod)
+	input := contractresource.PodArgvInput{ExpectedUID: "reviewed", Argv: []string{"printf", "; $(literal)\n", ""}, StdinBase64: base64.StdEncoding.EncodeToString([]byte("input")), MaxOutputBytes: 8}
+	calls := 0
+	factory := func(namespace, name string, options corev1.PodExecOptions) (remotecommand.Executor, error) {
+		calls++
+		if namespace != "test" || name != "fixture" || !reflect.DeepEqual(options.Command, input.Argv) || options.Container != "main" || options.TTY || !options.Stdin || !options.Stdout || !options.Stderr {
+			t.Fatalf("changed exec options: %+v", options)
+		}
+		return podExecutorStub{run: func(_ context.Context, streams remotecommand.StreamOptions) error {
+			data, _ := io.ReadAll(streams.Stdin)
+			if string(data) != "input" {
+				t.Fatal("stdin changed")
+			}
+			_, _ = io.WriteString(streams.Stdout, "123456")
+			_, _ = io.WriteString(streams.Stderr, "abcdef")
+			return nil
+		}}, nil
+	}
+	result, err := ExecutePodArgv(t.Context(), client, nil, "test", "fixture", input, factory)
+	if err != nil || calls != 1 || result.Output.Status != "succeeded" || result.Output.ExitCode == nil || *result.Output.ExitCode != 0 || result.Output.Stdout != "123456" || result.Output.Stderr != "ab" || result.Output.StdoutBytes != 6 || result.Output.StderrBytes != 6 || result.Output.StdoutTruncated || !result.Output.StderrTruncated || result.Target.UID != "reviewed" {
+		t.Fatalf("result=%+v err=%v calls=%d", result, err, calls)
+	}
+}
+
+func TestPodArgvRetainsKnownExitCodeButNeverEchoesTransportErrors(t *testing.T) {
+	for _, scenario := range []string{"exit", "transport", "changed", "binary", "canceled"} {
+		t.Run(scenario, func(t *testing.T) {
+			client := fake.NewClientset(executionFixturePod())
+			ctx, cancel := context.WithCancel(t.Context())
+			defer cancel()
+			input := contractresource.PodArgvInput{ExpectedUID: "reviewed", Argv: []string{"diagnostic"}, MaxOutputBytes: 1}
+			factory := func(_, _ string, _ corev1.PodExecOptions) (remotecommand.Executor, error) {
+				return podExecutorStub{run: func(_ context.Context, streams remotecommand.StreamOptions) error {
+					switch scenario {
+					case "exit":
+						return utilexec.CodeExitError{Err: errors.New("PRIVATE_VALUE"), Code: 42}
+					case "transport":
+						return errors.New("PRIVATE_VALUE")
+					case "changed":
+						pod, _ := client.CoreV1().Pods("test").Get(t.Context(), "fixture", metav1.GetOptions{})
+						pod.UID = "replacement"
+						_, err := client.CoreV1().Pods("test").Update(t.Context(), pod, metav1.UpdateOptions{})
+						return err
+					case "binary":
+						_, _ = streams.Stdout.Write([]byte{255, 254})
+						return nil
+					case "canceled":
+						cancel()
+						return context.Canceled
+					default:
+						return nil
+					}
+				}}, nil
+			}
+			result, err := ExecutePodArgv(ctx, client, nil, "test", "fixture", input, factory)
+			if err != nil {
+				t.Fatal(err)
+			}
+			raw, _ := json.Marshal(result)
+			if strings.Contains(string(raw), "PRIVATE_VALUE") {
+				t.Fatal("transport error leaked")
+			}
+			switch scenario {
+			case "exit":
+				if result.Output.Status != "failed" || result.Output.ExitCode == nil || *result.Output.ExitCode != 42 {
+					t.Fatalf("exit=%+v", result.Output)
+				}
+			case "transport":
+				if result.Output.Status != "transport_lost" || result.Output.ExitCode != nil {
+					t.Fatalf("transport=%+v", result.Output)
+				}
+			case "changed":
+				if result.Output.Status != "unknown" || !result.Output.TargetChanged {
+					t.Fatalf("target=%+v", result.Output)
+				}
+			case "binary":
+				data, err := contractresource.DecodePodExecutionStream(result.Output.Stdout, result.Output.StdoutEncoding)
+				if err != nil || len(data) != 1 || data[0] != 255 || !result.Output.StdoutTruncated {
+					t.Fatalf("binary=%+v err=%v", result.Output, err)
+				}
+			case "canceled":
+				if result.Output.Status != "canceled" || result.Output.ExitCode != nil || len(client.Actions()) != 1 {
+					t.Fatalf("cancel=%+v actions=%d", result.Output, len(client.Actions()))
+				}
+			}
+		})
+	}
+}
+
+func TestPodArgvRejectsChangedUIDAndAmbiguousContainerBeforeFactory(t *testing.T) {
+	for _, scenario := range []string{"uid", "container", "deleting", "canceled"} {
+		t.Run(scenario, func(t *testing.T) {
+			pod := executionFixturePod()
+			if scenario == "uid" {
+				pod.UID = "replacement"
+			}
+			if scenario == "container" {
+				pod.Spec.Containers = append(pod.Spec.Containers, corev1.Container{Name: "other"})
+			}
+			if scenario == "deleting" {
+				now := metav1.Now()
+				pod.DeletionTimestamp = &now
+			}
+			client := fake.NewClientset(pod)
+			ctx, cancel := context.WithCancel(t.Context())
+			defer cancel()
+			if scenario == "canceled" {
+				cancel()
+			}
+			calls := 0
+			factory := func(_, _ string, _ corev1.PodExecOptions) (remotecommand.Executor, error) {
+				calls++
+				return nil, errors.New("must not open exec")
+			}
+			_, err := ExecutePodArgv(ctx, client, nil, "test", "fixture", contractresource.PodArgvInput{ExpectedUID: "reviewed", Argv: []string{"true"}}, factory)
+			if err == nil || calls != 0 {
+				t.Fatalf("err=%v calls=%d", err, calls)
+			}
+			if scenario == "uid" && !apierrors.IsConflict(err) {
+				t.Fatal(err)
+			}
+		})
+	}
+}

package/resource/runtime/pod_execution_transport.go

@@ -0,0 +1,79 @@
+package runtime
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"sync/atomic"
+
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+	"k8s.io/client-go/rest"
+	"k8s.io/client-go/tools/remotecommand"
+	"k8s.io/client-go/transport/spdy"
+)
+
+func newPodExecutionExecutor(config *rest.Config, name string, target *url.URL) (remotecommand.Executor, error) {
+	transport, upgrader, err := spdy.RoundTripperFor(config)
+	if err != nil {
+		return nil, err
+	}
+	status := &atomic.Int32{}
+	executor, err := remotecommand.NewSPDYExecutorRejectRedirects(podExecutionStatusTransport{base: transport, status: status}, upgrader, http.MethodPost, target)
+	if err != nil {
+		return nil, err
+	}
+	return podExecutionStatusExecutor{Executor: executor, status: status, name: name}, nil
+}
+
+type podExecutionStatusExecutor struct {
+	remotecommand.Executor
+	status *atomic.Int32
+	name   string
+}
+
+func (executor podExecutionStatusExecutor) Stream(options remotecommand.StreamOptions) error {
+	return executor.StreamWithContext(context.Background(), options)
+}
+
+func (executor podExecutionStatusExecutor) StreamWithContext(ctx context.Context, options remotecommand.StreamOptions) error {
+	err := executor.Executor.StreamWithContext(ctx, options)
+	// Negotiate also stringifies transport errors. Keep the HTTP category in
+	// this attempt's private state, rather than parsing a provider message.
+	if code := executor.status.Load(); code != 0 {
+		return apierrors.NewGenericServerResponse(int(code), http.MethodPost, schema.GroupResource{Resource: "pods/exec"}, executor.name, "Pod exec upgrade rejected", 0, false)
+	}
+	return err
+}
+
+type podExecutionStatusTransport struct {
+	base   http.RoundTripper
+	status *atomic.Int32
+}
+
+func (transport podExecutionStatusTransport) RoundTrip(request *http.Request) (*http.Response, error) {
+	response, err := transport.base.RoundTrip(request)
+	if err != nil || response == nil {
+		return response, err
+	}
+	if validPodExecutionUpgrade(response) {
+		return response, nil
+	}
+	// Never read the raw error body: it can be unbounded or contain command
+	// secrets. The original transport still applies authentication and TLS.
+	if response.Body != nil {
+		_ = response.Body.Close()
+	}
+	code := response.StatusCode
+	if code < http.StatusBadRequest {
+		code = http.StatusBadGateway
+	}
+	transport.status.Store(int32(code))
+	return nil, fmt.Errorf("pod exec HTTP upgrade rejected")
+}
+
+func validPodExecutionUpgrade(response *http.Response) bool {
+	return response.StatusCode == http.StatusSwitchingProtocols && strings.Contains(strings.ToLower(response.Header.Get("Connection")), "upgrade") && strings.Contains(strings.ToLower(response.Header.Get("Upgrade")), "spdy/3.1")
+}

package/resource/runtime/pod_terminal.go

@@ -0,0 +1,178 @@
+package runtime
+
+import (
+	"context"
+	"errors"
+	"io"
+	"sync/atomic"
+	"time"
+
+	contractresource "github.com/opensoha/soha/contracts/resource"
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/client-go/kubernetes"
+	"k8s.io/client-go/kubernetes/scheme"
+	"k8s.io/client-go/rest"
+	"k8s.io/client-go/tools/remotecommand"
+	utilexec "k8s.io/client-go/util/exec"
+)
+
+var errTerminalInputLimit = errors.New("terminal input limit")
+var errTerminalOutputLimit = errors.New("terminal output limit")
+
+// StreamPodTerminal uses a single PTY with merged stdout/stderr. It never
+// retries. Cancellation closes this transport; it does not prove that a remote
+// process has terminated. Callers own stream authorization and durable leases.
+func StreamPodTerminal(ctx context.Context, client kubernetes.Interface, config *rest.Config, namespace, name string, input contractresource.PodTerminalInput, stdin io.ReadCloser, stdout io.Writer, sizes contractresource.NativeTerminalSizeQueue, factory PodExecutorFactory) (contractresource.PodTerminalResult, error) {
+	var result contractresource.PodTerminalResult
+	input, err := input.Normalized()
+	if err != nil {
+		return result, apierrors.NewBadRequest(err.Error())
+	}
+	if stdin == nil || stdout == nil || sizes == nil {
+		return result, apierrors.NewBadRequest("terminal streams are required")
+	}
+	runCtx, cancel := context.WithTimeout(ctx, time.Duration(input.TimeoutSeconds)*time.Second)
+	defer cancel()
+	stopInput := context.AfterFunc(runCtx, func() { _ = stdin.Close() })
+	defer stopInput()
+	target, err := InspectPodExecutionTarget(runCtx, client, namespace, name, input.ExpectedUID, input.Container)
+	if err != nil {
+		return result, err
+	}
+	if err = runCtx.Err(); err != nil {
+		return result, err
+	}
+	options := corev1.PodExecOptions{Container: target.Container, Command: []string{input.Shell}, Stdin: true, Stdout: true, Stderr: false, TTY: true}
+	if factory == nil {
+		if config == nil || client.CoreV1().RESTClient() == nil {
+			return result, apierrors.NewBadRequest("Pod terminal transport is unavailable")
+		}
+		factory = func(namespace, name string, options corev1.PodExecOptions) (remotecommand.Executor, error) {
+			request := client.CoreV1().RESTClient().Post().Resource("pods").Name(name).Namespace(namespace).SubResource("exec")
+			request.VersionedParams(&options, scheme.ParameterCodec)
+			return newPodExecutionExecutor(config, name, request.URL())
+		}
+	}
+	executor, err := factory(namespace, name, options)
+	if err != nil {
+		return result, err
+	}
+	reader := &terminalInputReader{reader: stdin, cancel: cancel}
+	writer := &terminalOutputWriter{writer: stdout, cancel: cancel}
+	execErr := executor.StreamWithContext(runCtx, remotecommand.StreamOptions{Stdin: reader, Stdout: writer, Tty: true, TerminalSizeQueue: terminalSizeQueue{ctx: runCtx, source: sizes}})
+	if apierrors.IsForbidden(execErr) || apierrors.IsUnauthorized(execErr) || apierrors.IsNotFound(execErr) || apierrors.IsBadRequest(execErr) {
+		return result, execErr
+	}
+	result = terminalStreamResult(execErr, runCtx.Err(), reader, writer)
+	if runCtx.Err() == nil {
+		verifyCtx, verifyCancel := context.WithTimeout(runCtx, 3*time.Second)
+		defer verifyCancel()
+		_, verifyErr := InspectPodExecutionTarget(verifyCtx, client, namespace, name, input.ExpectedUID, target.Container)
+		if verifyErr != nil {
+			result.Status, result.ExitCode, result.ReasonCode = "unknown", nil, "target_verification_unavailable"
+			if apierrors.IsConflict(verifyErr) || apierrors.IsNotFound(verifyErr) {
+				result.TargetChanged = true
+				result.ReasonCode = "target_changed"
+			}
+		}
+	}
+	return result, nil
+}
+
+func terminalStreamResult(execErr, ctxErr error, reader *terminalInputReader, writer *terminalOutputWriter) contractresource.PodTerminalResult {
+	result := contractresource.PodTerminalResult{Status: "transport_lost", ReasonCode: "transport_lost", UIDVerifiedBeforeStart: true, InputBytes: reader.count.Load(), OutputBytes: writer.count.Load()}
+	var remoteExit utilexec.ExitError
+	switch {
+	case reader.limited.Load():
+		result.Status, result.ReasonCode = "input_limit", "input_limit"
+	case writer.limited.Load():
+		result.Status, result.ReasonCode = "output_limit", "output_limit"
+	case errors.Is(ctxErr, context.DeadlineExceeded):
+		result.Status, result.ReasonCode = "timed_out", "deadline_exceeded"
+	case errors.Is(ctxErr, context.Canceled):
+		result.Status, result.ReasonCode = "canceled", "request_canceled"
+	case execErr == nil:
+		code := int64(0)
+		result.Status, result.ReasonCode, result.ExitCode = "succeeded", "", &code
+	case errors.As(execErr, &remoteExit) && remoteExit.Exited() && remoteExit.ExitStatus() > 0 && int64(remoteExit.ExitStatus()) <= 4294967295:
+		code := int64(remoteExit.ExitStatus())
+		result.Status, result.ReasonCode, result.ExitCode = "failed", "process_exited", &code
+	}
+	return result
+}
+
+type terminalSizeQueue struct {
+	ctx    context.Context
+	source contractresource.NativeTerminalSizeQueue
+}
+
+func (queue terminalSizeQueue) Next() *remotecommand.TerminalSize {
+	if queue.ctx.Err() != nil {
+		return nil
+	}
+	size := queue.source.Next(queue.ctx)
+	if size == nil || queue.ctx.Err() != nil || size.Width < 1 || size.Height < 1 || size.Width > contractresource.NativeTerminalMaxDimension || size.Height > contractresource.NativeTerminalMaxDimension {
+		return nil
+	}
+	return &remotecommand.TerminalSize{Width: size.Width, Height: size.Height}
+}
+
+type terminalInputReader struct {
+	reader  io.Reader
+	cancel  context.CancelFunc
+	count   atomic.Int64
+	limited atomic.Bool
+}
+
+func (reader *terminalInputReader) Read(data []byte) (int, error) {
+	if len(data) == 0 {
+		return 0, nil
+	}
+	remaining := contractresource.NativePodTerminalMaxInputBytes - reader.count.Load()
+	if int64(len(data)) > remaining {
+		data = data[:remaining]
+	}
+	if len(data) == 0 {
+		if remaining > 0 {
+			return 0, nil
+		}
+		var probe [1]byte
+		n, err := reader.reader.Read(probe[:])
+		if n == 0 {
+			return 0, err
+		}
+		reader.limited.Store(true)
+		reader.cancel()
+		return 0, errTerminalInputLimit
+	}
+	n, err := reader.reader.Read(data)
+	reader.count.Add(int64(n))
+	return n, err
+}
+
+type terminalOutputWriter struct {
+	writer  io.Writer
+	cancel  context.CancelFunc
+	count   atomic.Int64
+	limited atomic.Bool
+}
+
+func (writer *terminalOutputWriter) Write(data []byte) (int, error) {
+	remaining := contractresource.NativePodTerminalMaxOutputBytes - writer.count.Load()
+	keep := min(int64(len(data)), remaining)
+	n, err := writer.writer.Write(data[:keep])
+	writer.count.Add(int64(n))
+	if err != nil {
+		return n, err
+	}
+	if int64(n) != keep {
+		return n, io.ErrShortWrite
+	}
+	if keep < int64(len(data)) {
+		writer.limited.Store(true)
+		writer.cancel()
+		return n, errTerminalOutputLimit
+	}
+	return n, nil
+}

package/resource/runtime/pod_terminal_test.go

@@ -0,0 +1,170 @@
+package runtime
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	contractresource "github.com/opensoha/soha/contracts/resource"
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/client-go/kubernetes/fake"
+	"k8s.io/client-go/tools/remotecommand"
+	utilexec "k8s.io/client-go/util/exec"
+)
+
+type terminalSizes struct{}
+
+func (terminalSizes) Next(context.Context) *contractresource.NativeTerminalSize {
+	return &contractresource.NativeTerminalSize{Width: 120, Height: 40}
+}
+
+func TestNativeTerminalUsesPTYMergedOutputAndExactShell(t *testing.T) {
+	client := fake.NewClientset(executionFixturePod())
+	stdin := []byte{0, 255, '\n'}
+	var output bytes.Buffer
+	factory := func(_, _ string, options corev1.PodExecOptions) (remotecommand.Executor, error) {
+		if !options.TTY || !options.Stdin || !options.Stdout || options.Stderr || options.Container != "main" || !reflect.DeepEqual(options.Command, []string{"/bin/bash"}) {
+			t.Fatalf("unsafe PTY options: %+v", options)
+		}
+		return podExecutorStub{run: func(_ context.Context, streams remotecommand.StreamOptions) error {
+			if streams.Stderr != nil || !streams.Tty {
+				t.Fatal("PTY must negotiate TTY and merged output in the stream transport")
+			}
+			size := streams.TerminalSizeQueue.Next()
+			if size == nil || size.Width != 120 || size.Height != 40 {
+				t.Fatal("resize lost")
+			}
+			data, _ := io.ReadAll(streams.Stdin)
+			if !bytes.Equal(data, stdin) {
+				t.Fatal("binary stdin changed")
+			}
+			_, err := streams.Stdout.Write([]byte{255, 0, 27})
+			return err
+		}}, nil
+	}
+	result, err := StreamPodTerminal(t.Context(), client, nil, "test", "fixture", contractresource.PodTerminalInput{ExpectedUID: "reviewed", Shell: "bash"}, io.NopCloser(bytes.NewReader(stdin)), &output, terminalSizes{}, factory)
+	if err != nil || result.Status != "succeeded" || result.InputBytes != 3 || result.OutputBytes != 3 || !bytes.Equal(output.Bytes(), []byte{255, 0, 27}) {
+		t.Fatalf("result=%+v err=%v", result, err)
+	}
+	if err = result.Validate(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestNativeTerminalExitCancelTimeoutAndChangedTarget(t *testing.T) {
+	for _, scenario := range []string{"exit", "transport", "changed", "canceled", "deadline", "invalid-exit"} {
+		t.Run(scenario, func(t *testing.T) {
+			client := fake.NewClientset(executionFixturePod())
+			ctx, cancel := context.WithCancel(t.Context())
+			defer cancel()
+			factory := func(_, _ string, _ corev1.PodExecOptions) (remotecommand.Executor, error) {
+				return podExecutorStub{run: func(runCtx context.Context, _ remotecommand.StreamOptions) error {
+					switch scenario {
+					case "exit":
+						return utilexec.CodeExitError{Err: errors.New("PRIVATE"), Code: 42}
+					case "transport":
+						return errors.New("PRIVATE")
+					case "invalid-exit":
+						return utilexec.CodeExitError{Err: errors.New("PRIVATE"), Code: 0}
+					case "changed":
+						pod, _ := client.CoreV1().Pods("test").Get(ctx, "fixture", metav1.GetOptions{})
+						pod.UID = "replacement"
+						_, err := client.CoreV1().Pods("test").Update(ctx, pod, metav1.UpdateOptions{})
+						return err
+					case "canceled":
+						cancel()
+						return nil
+					case "deadline":
+						<-runCtx.Done()
+						return nil
+					}
+					return nil
+				}}, nil
+			}
+			input := contractresource.PodTerminalInput{ExpectedUID: "reviewed", TimeoutSeconds: 1}
+			result, err := StreamPodTerminal(ctx, client, nil, "test", "fixture", input, io.NopCloser(strings.NewReader("")), io.Discard, terminalSizes{}, factory)
+			if err != nil {
+				t.Fatal(err)
+			}
+			want := map[string]string{"exit": "failed", "transport": "transport_lost", "changed": "unknown", "canceled": "canceled", "deadline": "timed_out", "invalid-exit": "transport_lost"}[scenario]
+			if result.Status != want {
+				t.Fatalf("result=%+v want=%s", result, want)
+			}
+			if err = result.Validate(); err != nil {
+				t.Fatal(err)
+			}
+			if scenario == "canceled" && len(client.Actions()) != 1 {
+				t.Fatal("read Kubernetes after cancellation")
+			}
+		})
+	}
+}
+
+func TestNativeTerminalRejectsUIDBeforeOpeningAndRetainsForbidden(t *testing.T) {
+	client := fake.NewClientset(executionFixturePod())
+	called := false
+	factory := func(_, _ string, _ corev1.PodExecOptions) (remotecommand.Executor, error) {
+		called = true
+		return nil, errors.New("must not call")
+	}
+	_, err := StreamPodTerminal(t.Context(), client, nil, "test", "fixture", contractresource.PodTerminalInput{ExpectedUID: "changed"}, io.NopCloser(strings.NewReader("")), io.Discard, terminalSizes{}, factory)
+	if !apierrors.IsConflict(err) || called {
+		t.Fatalf("err=%v called=%v", err, called)
+	}
+	factory = func(_, _ string, _ corev1.PodExecOptions) (remotecommand.Executor, error) {
+		return podExecutorStub{run: func(context.Context, remotecommand.StreamOptions) error { return apierrors.NewUnauthorized("PRIVATE") }}, nil
+	}
+	_, err = StreamPodTerminal(t.Context(), client, nil, "test", "fixture", contractresource.PodTerminalInput{ExpectedUID: "reviewed"}, io.NopCloser(strings.NewReader("")), io.Discard, terminalSizes{}, factory)
+	if !apierrors.IsUnauthorized(err) {
+		t.Fatalf("lost API denial: %v", err)
+	}
+}
+
+func TestNativeTerminalBoundsProviderIOAndUnblocksStdinOnDeadline(t *testing.T) {
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+	reader := &terminalInputReader{reader: bytes.NewReader(make([]byte, contractresource.NativePodTerminalMaxInputBytes+1)), cancel: cancel}
+	if n, err := io.Copy(io.Discard, reader); n != contractresource.NativePodTerminalMaxInputBytes || !errors.Is(err, errTerminalInputLimit) {
+		t.Fatalf("input n=%d err=%v", n, err)
+	}
+	if ctx.Err() == nil {
+		t.Fatal("input limit did not cancel")
+	}
+	ctx, cancel = context.WithCancel(t.Context())
+	defer cancel()
+	writer := &terminalOutputWriter{writer: io.Discard, cancel: cancel}
+	writer.count.Store(contractresource.NativePodTerminalMaxOutputBytes - 2)
+	if n, err := writer.Write([]byte("abcd")); n != 2 || !errors.Is(err, errTerminalOutputLimit) {
+		t.Fatalf("output n=%d err=%v", n, err)
+	}
+	if ctx.Err() == nil {
+		t.Fatal("output limit did not cancel")
+	}
+	client := fake.NewClientset(executionFixturePod())
+	pipe, peer := io.Pipe()
+	defer func() { _ = peer.Close() }()
+	finished := make(chan error, 1)
+	factory := func(_, _ string, _ corev1.PodExecOptions) (remotecommand.Executor, error) {
+		return podExecutorStub{run: func(_ context.Context, streams remotecommand.StreamOptions) error {
+			_, err := io.Copy(io.Discard, streams.Stdin)
+			finished <- err
+			return err
+		}}, nil
+	}
+	result, err := StreamPodTerminal(t.Context(), client, nil, "test", "fixture", contractresource.PodTerminalInput{ExpectedUID: "reviewed", TimeoutSeconds: 1}, pipe, io.Discard, terminalSizes{}, factory)
+	if err != nil || result.Status != "timed_out" {
+		t.Fatalf("result=%+v err=%v", result, err)
+	}
+	select {
+	case <-finished:
+	case <-time.After(time.Second):
+		t.Fatal("stdin remained blocked")
+	}
+}

package/resource/runtime/presence.go

@@ -0,0 +1,58 @@
+package runtime
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	contractresource "github.com/opensoha/soha/contracts/resource"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/fields"
+)
+
+type ResourceMetadataLister interface {
+	List(context.Context, metav1.ListOptions) (*metav1.PartialObjectMetadataList, error)
+}
+
+// ObserveResourcePresence uses a successful complete metadata-only collection,
+// never GET/404, as the object-presence oracle. A missing API, RBAC denial, stale
+// transport or unsupported partial metadata produces an error, not absence.
+func ObserveResourcePresence(ctx context.Context, client ResourceMetadataLister, kind, namespace, name string) (contractresource.ResourcePresence, error) {
+	definition, ok := contractresource.LookupKubernetesResourceKind(kind)
+	if !ok || !definition.GenericYAML || client == nil {
+		return contractresource.ResourcePresence{}, fmt.Errorf("unsupported resource presence target")
+	}
+	apiVersion := definition.Version
+	if definition.Group != "" {
+		apiVersion = definition.Group + "/" + definition.Version
+	}
+	result := contractresource.ResourcePresence{Protocol: contractresource.ResourcePresenceProtocol, APIVersion: apiVersion,
+		Resource: definition.Resource, Kind: kind, Namespace: namespace, Name: name, CollectionResourceVersion: "pending", State: "absent"}
+	if err := result.ValidateFor(kind, namespace, name); err != nil {
+		return contractresource.ResourcePresence{}, err
+	}
+	query, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	// Empty resourceVersion requests the current collection; "0" would permit
+	// an older cached snapshot. Never follow pagination or expand the selector.
+	items, err := client.List(query, metav1.ListOptions{FieldSelector: fields.OneTermEqualSelector("metadata.name", name).String(), Limit: 2})
+	if err != nil {
+		return contractresource.ResourcePresence{}, err
+	}
+	if items == nil || items.ResourceVersion == "" || items.Continue != "" || len(items.Items) > 1 || items.RemainingItemCount != nil && *items.RemainingItemCount != 0 {
+		return contractresource.ResourcePresence{}, fmt.Errorf("resource presence collection is incomplete")
+	}
+	result.CollectionResourceVersion = items.ResourceVersion
+	if len(items.Items) == 1 {
+		item := items.Items[0]
+		if item.Name != name || item.Namespace != namespace {
+			return contractresource.ResourcePresence{}, fmt.Errorf("resource presence collection target changed")
+		}
+		result.State, result.UID, result.ResourceVersion = "present", string(item.UID), item.ResourceVersion
+		if item.DeletionTimestamp != nil {
+			stamp := item.DeletionTimestamp.Time
+			result.DeletionTimestamp = &stamp
+		}
+	}
+	return result, result.ValidateFor(kind, namespace, name)
+}