ttsc 0.30.4 → 0.31.0

package/internal/sourceprocess/run.go

@@ -0,0 +1,216 @@
+// Package sourceprocess owns a native command and its process boundary until
+// completion or cancellation. It serves the SDK's synchronous worker relay.
+package sourceprocess
+
+import (
+  "bufio"
+  "bytes"
+  "encoding/base64"
+  "encoding/json"
+  "errors"
+  "fmt"
+  "io"
+  "os"
+  "os/exec"
+  "path/filepath"
+  "sort"
+  "sync"
+  "time"
+)
+
+// Run executes the private source-process protocol. The first stdin line is a
+// JSON command; subsequent EOF cancels it. Child stdin is independent of this
+// control stream. Output streams carry only the child's bytes, while the
+// caller-owned result pathname receives an atomic completion record.
+//
+// @evidence contracts/common.md#principled-implementation Command decoding precedes acquisition; the OS owner returns only after its direct child and process boundary have been observed, and publication preserves failure instead of inventing successful completion.
+// @evidence contracts/common.md#clear-and-simple-design One entry separates control input, native execution and completion publication; platform adapters own containment and private inner dispatch.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts EOF invokes actual process retirement, without extending command deadlines or substituting a warm artifact.
+// @evidence contracts/common.md#meaningful-documentation The declaration explains separate control and child input streams and the private result-file contract.
+// @evidence contracts/portability.md#os-neutral-implementation JSON preserves argv and environment values; native adapters implement Windows Job and POSIX process-group distinctions without shell concatenation.
+// @evidence contracts/performance.md#efficient-algorithms Decoding retains one complete request and optional decoded stdin; command output streams directly to the supplied writers instead of buffering it in this owner.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Commands can have effects and are executed independently; plugin-key reuse remains with the SDK.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The standalone helper owns one control reader until process exit and delegates native handles to its OS adapter; publication failure exits unsuccessfully without claiming cleanup or a usable completion record.
+func Run(args []string, in io.Reader, out, stderr io.Writer) int {
+  if len(args) > 0 && args[0] == "--inner" {
+    return runInner(args[1:], in, out, stderr)
+  }
+  if len(args) != 2 || args[0] != "--result" || !filepath.IsAbs(args[1]) {
+    fmt.Fprintln(stderr, "ttsc: source process requires --result and an absolute private result path")
+    return 2
+  }
+  reader := bufio.NewReader(in)
+  line, readErr := reader.ReadBytes('\n')
+  req, decodeErr := decodeRequest(line)
+  var completed result
+  if readErr != nil || decodeErr != nil {
+    if decodeErr == nil {
+      decodeErr = readErr
+    }
+    completed = failure("EINVAL", fmt.Sprintf("invalid source process request: %v", decodeErr))
+  } else {
+    cancel := make(chan struct{})
+    go func() {
+      _, _ = io.Copy(io.Discard, reader)
+      close(cancel)
+    }()
+    completed = runCommand(req, cancel, out, stderr)
+  }
+  if err := writeResult(args[1], completed); err != nil {
+    fmt.Fprintf(stderr, "ttsc: source process completion publication failed: %v\n", err)
+    return 1
+  }
+  return 0
+}
+
+type request struct {
+  Version                  int               `json:"version"`
+  Command                  string            `json:"command"`
+  Argv0                    *string           `json:"argv0,omitempty"`
+  Args                     []string          `json:"args"`
+  Cwd                      string            `json:"cwd"`
+  Env                      map[string]string `json:"env"`
+  InputBase64              string            `json:"inputBase64,omitempty"`
+  WindowsVerbatimArguments bool              `json:"windowsVerbatimArguments,omitempty"`
+  TimeoutMs                int64             `json:"timeoutMs,omitempty"`
+}
+
+type result struct {
+  Version   int           `json:"version"`
+  Pid       int           `json:"pid"`
+  Status    *int          `json:"status"`
+  Signal    *string       `json:"signal"`
+  Error     *processError `json:"error,omitempty"`
+  Cancelled bool          `json:"cancelled"`
+  Cleanup   cleanupProof  `json:"cleanup"`
+}
+
+type processError struct {
+  Code    string `json:"code"`
+  Message string `json:"message"`
+}
+
+type cleanupProof struct {
+  DirectChildJoined bool   `json:"directChildJoined"`
+  BoundaryEmpty     bool   `json:"boundaryEmpty"`
+  OrphanReaping     string `json:"orphanReaping"`
+}
+
+func decodeRequest(data []byte) (request, error) {
+  var req request
+  decoder := json.NewDecoder(bytes.NewReader(data))
+  decoder.DisallowUnknownFields()
+  if err := decoder.Decode(&req); err != nil {
+    return req, err
+  }
+  var extra any
+  if err := decoder.Decode(&extra); err != io.EOF {
+    return req, errors.New("request must contain exactly one JSON value")
+  }
+  if req.Version != 1 || req.Command == "" || !filepath.IsAbs(req.Cwd) || req.Env == nil || req.TimeoutMs < 0 || req.TimeoutMs > int64((1<<63-1)/time.Millisecond) {
+    return req, errors.New("invalid version, executable, cwd, environment or timeout")
+  }
+  if _, err := inputBytes(req); err != nil {
+    return req, err
+  }
+  return req, nil
+}
+
+func inputBytes(req request) ([]byte, error) { return base64.StdEncoding.DecodeString(req.InputBase64) }
+
+// openInput supplies a native regular handle, not a copy goroutine that can
+// remain blocked after the direct child exits while a descendant holds stdin.
+func openInput(req request, directory string) (*os.File, func() error, error) {
+  input, err := inputBytes(req)
+  if err != nil {
+    return nil, nil, err
+  }
+  if len(input) == 0 {
+    file, err := os.Open(os.DevNull)
+    if err != nil {
+      return nil, nil, err
+    }
+    return file, file.Close, nil
+  }
+  file, err := os.CreateTemp(directory, "stdin-*")
+  if err != nil {
+    return nil, nil, err
+  }
+  var once sync.Once
+  var cleanupErr error
+  cleanup := func() error {
+    once.Do(func() { cleanupErr = errors.Join(file.Close(), os.Remove(file.Name())) })
+    return cleanupErr
+  }
+  if _, err = file.Write(input); err != nil {
+    return nil, nil, errors.Join(err, cleanup())
+  }
+  if _, err = file.Seek(0, io.SeekStart); err != nil {
+    return nil, nil, errors.Join(err, cleanup())
+  }
+  return file, cleanup, nil
+}
+
+func environment(values map[string]string) []string {
+  keys := make([]string, 0, len(values))
+  for key := range values {
+    keys = append(keys, key)
+  }
+  sort.Strings(keys)
+  entries := make([]string, 0, len(keys))
+  for _, key := range keys {
+    entries = append(entries, key+"="+values[key])
+  }
+  return entries
+}
+
+func failure(code, message string) result {
+  return result{Version: 1, Error: &processError{Code: code, Message: message}}
+}
+
+func commandResult(cmd *exec.Cmd, err error) result {
+  value := result{Version: 1}
+  if cmd.Process != nil {
+    value.Pid = cmd.Process.Pid
+  }
+  if cmd.ProcessState != nil {
+    value.Cleanup.DirectChildJoined = true
+    code := cmd.ProcessState.ExitCode()
+    if code >= 0 {
+      value.Status = &code
+    }
+    value.Signal = commandSignal(cmd.ProcessState)
+  }
+  var exit *exec.ExitError
+  if err != nil && !errors.As(err, &exit) {
+    value.Error = &processError{Code: "EIO", Message: err.Error()}
+    if errors.Is(err, os.ErrNotExist) || errors.Is(err, exec.ErrNotFound) {
+      value.Error.Code = "ENOENT"
+    }
+    if errors.Is(err, os.ErrPermission) {
+      value.Error.Code = "EACCES"
+    }
+  }
+  return value
+}
+
+func writeResult(location string, value result) error {
+  data, err := json.Marshal(value)
+  if err != nil {
+    return err
+  }
+  file, err := os.CreateTemp(filepath.Dir(location), ".source-process-result-*")
+  if err != nil {
+    return err
+  }
+  temporary := file.Name()
+  defer os.Remove(temporary)
+  if _, err = file.Write(data); err != nil {
+    _ = file.Close()
+    return err
+  }
+  if err = file.Close(); err != nil {
+    return err
+  }
+  return os.Rename(temporary, location)
+}

package/internal/sourceprocess/target_windows.go

@@ -0,0 +1,211 @@
+//go:build windows
+
+package sourceprocess
+
+import (
+  "errors"
+  "fmt"
+  "os"
+  "os/exec"
+  "path/filepath"
+  "runtime"
+  "strings"
+  "unsafe"
+
+  "golang.org/x/sys/windows"
+)
+
+// windowsTarget retains the original process and primary-thread handles from
+// suspended creation. The outer owner receives its PID before RUN permits any
+// target code or output, and native waiting never substitutes a reused PID.
+// Only duplicated standard handles are inherited; no broker, shell or global
+// process/thread enumeration participates in execution.
+//
+// CreateProcess returns both original handles atomically. CREATE_SUSPENDED
+// places PID publication before execution; ResumeThread uses the original
+// primary-thread handle and requires exactly one suspended count. The outer
+// Job owns cancellation and retires suspended or running targets after any
+// handshake failure.
+//
+// The owner preserves the selected executable, argv0, verbatim argument policy,
+// UTF-16 environment and cwd. Encoding is linear in command and environment
+// bytes. Three duplicated descriptors and one attribute list have fixed size
+// and are released after creation on every path. Each invocation owns its
+// command effects and identity independently. The inner retains the original
+// process/thread handles until target wait and result publication or inner exit.
+type windowsTarget struct{ info windows.ProcessInformation }
+
+// windowsStarted binds admission to the original suspended process. The inner
+// holds its creation handles until RUN or helper exit; the outer acquires and
+// validates its own non-inheritable wait handle before authorizing execution.
+type windowsStarted struct {
+  Version int    `json:"version"`
+  Pid     uint32 `json:"pid"`
+  Created uint64 `json:"created"`
+}
+
+func (owner *windowsTarget) started() (windowsStarted, error) {
+  created, err := windowsProcessCreation(owner.info.Process)
+  return windowsStarted{Version: 1, Pid: owner.info.ProcessId, Created: created}, err
+}
+
+// retainWindowsTarget runs while the inner still holds the suspended original.
+// PID is only an enrollment coordinate: creation and job membership must match,
+// and subsequent retirement waits use this retained object without a lookup.
+// Failure closes the newly acquired handle and never authorizes RUN.
+func retainWindowsTarget(started windowsStarted, job windows.Handle) (windows.Handle, error) {
+  if started.Version != 1 || started.Pid == 0 || started.Created == 0 || job == 0 || job == windows.InvalidHandle {
+    return 0, fmt.Errorf("invalid suspended target identity or job")
+  }
+  handle, err := windows.OpenProcess(windows.SYNCHRONIZE|windows.PROCESS_QUERY_LIMITED_INFORMATION, false, started.Pid)
+  if err != nil {
+    return 0, err
+  }
+  pid, identityErr := windows.GetProcessId(handle)
+  created, creationErr := windowsProcessCreation(handle)
+  var member int32
+  isProcessInJob := windows.NewLazySystemDLL("kernel32.dll").NewProc("IsProcessInJob")
+  ok, _, membershipErr := isProcessInJob.Call(uintptr(handle), uintptr(job), uintptr(unsafe.Pointer(&member)))
+  if identityErr != nil || creationErr != nil || pid != started.Pid || created != started.Created || ok == 0 || member == 0 {
+    err = errors.Join(identityErr, creationErr)
+    if ok == 0 {
+      err = errors.Join(err, membershipErr)
+    }
+    return 0, errors.Join(fmt.Errorf("suspended target identity or job membership differs: %v", err), windows.CloseHandle(handle))
+  }
+  return handle, nil
+}
+
+func windowsProcessCreation(handle windows.Handle) (uint64, error) {
+  var created, exited, kernel, user windows.Filetime
+  err := windows.GetProcessTimes(handle, &created, &exited, &kernel, &user)
+  return uint64(created.HighDateTime)<<32 | uint64(created.LowDateTime), err
+}
+
+// waitWindowsTarget distinguishes completed original-object waiting from job
+// accounting. Callers use INFINITE only after successful owned termination or
+// normal original completion; failed termination must not hang on a live target.
+func waitWindowsTarget(handle windows.Handle, milliseconds uint32) error {
+  state, err := windows.WaitForSingleObject(handle, milliseconds)
+  if err != nil {
+    return err
+  }
+  if state != windows.WAIT_OBJECT_0 {
+    return fmt.Errorf("unexpected native target wait state %d", state)
+  }
+  return nil
+}
+
+func startWindowsTarget(req request, input *os.File) (*windowsTarget, error) {
+  selected := exec.Command(req.Command, req.Args...)
+  if selected.Err != nil {
+    return nil, selected.Err
+  }
+  selected.Env = environment(req.Env)
+  argv := append([]string{req.Command}, req.Args...)
+  if req.Argv0 != nil {
+    argv[0] = *req.Argv0
+  }
+  // The inner already runs in req.Cwd, matching exec.Cmd's relative executable
+  // authority before CreateProcess performs its own child-directory change.
+  executable, err := filepath.Abs(selected.Path)
+  if err != nil {
+    return nil, err
+  }
+  application, err := windows.UTF16PtrFromString(executable)
+  if err != nil {
+    return nil, err
+  }
+  encodedArgs := make([]string, len(argv))
+  for i, arg := range argv {
+    encodedArgs[i] = windows.EscapeArg(arg)
+  }
+  if req.WindowsVerbatimArguments {
+    copy(encodedArgs[1:], req.Args)
+  }
+  commandLine, err := windows.UTF16PtrFromString(strings.Join(encodedArgs, " "))
+  if err != nil {
+    return nil, err
+  }
+  cwd, err := windows.UTF16PtrFromString(req.Cwd)
+  if err != nil {
+    return nil, err
+  }
+  var environmentBlock []uint16
+  for _, entry := range selected.Environ() {
+    encoded, err := windows.UTF16FromString(entry)
+    if err != nil {
+      return nil, err
+    }
+    environmentBlock = append(environmentBlock, encoded...)
+  }
+  environmentBlock = append(environmentBlock, 0)
+  if len(environmentBlock) == 1 {
+    environmentBlock = append(environmentBlock, 0)
+  }
+  handles := make([]windows.Handle, 3)
+  defer func() {
+    for _, handle := range handles {
+      if handle != 0 {
+        _ = windows.CloseHandle(handle)
+      }
+    }
+  }()
+  for i, file := range []*os.File{input, os.Stdout, os.Stderr} {
+    if err := windows.DuplicateHandle(windows.CurrentProcess(), windows.Handle(file.Fd()), windows.CurrentProcess(), &handles[i], 0, true, windows.DUPLICATE_SAME_ACCESS); err != nil {
+      return nil, err
+    }
+  }
+  attributes, err := windows.NewProcThreadAttributeList(1)
+  if err != nil {
+    return nil, err
+  }
+  defer attributes.Delete()
+  if err = attributes.Update(windows.PROC_THREAD_ATTRIBUTE_HANDLE_LIST, unsafe.Pointer(&handles[0]), uintptr(len(handles))*unsafe.Sizeof(handles[0])); err != nil {
+    return nil, err
+  }
+  startup := windows.StartupInfoEx{ProcThreadAttributeList: attributes.List()}
+  startup.Cb = uint32(unsafe.Sizeof(startup))
+  startup.Flags = windows.STARTF_USESTDHANDLES
+  startup.StdInput, startup.StdOutput, startup.StdErr = handles[0], handles[1], handles[2]
+  owner := &windowsTarget{}
+  err = windows.CreateProcess(application, commandLine, nil, nil, true, windows.CREATE_SUSPENDED|windows.CREATE_UNICODE_ENVIRONMENT|windows.EXTENDED_STARTUPINFO_PRESENT, &environmentBlock[0], cwd, &startup.StartupInfo, &owner.info)
+  runtime.KeepAlive(handles)
+  runtime.KeepAlive(environmentBlock)
+  if err != nil {
+    return nil, err
+  }
+  return owner, nil
+}
+
+func (owner *windowsTarget) resume() error {
+  count, err := windows.ResumeThread(owner.info.Thread)
+  if err != nil {
+    return err
+  }
+  if count != 1 {
+    return fmt.Errorf("source target primary thread had unexpected suspend count %d", count)
+  }
+  return nil
+}
+
+func (owner *windowsTarget) wait() result {
+  value := result{Version: 1, Pid: int(owner.info.ProcessId)}
+  if err := waitWindowsTarget(owner.info.Process, windows.INFINITE); err != nil {
+    value.Error = &processError{Code: "EPROCESS", Message: err.Error()}
+    return value
+  }
+  value.Cleanup.DirectChildJoined = true
+  var code uint32
+  if err := windows.GetExitCodeProcess(owner.info.Process, &code); err != nil {
+    value.Error = &processError{Code: "EPROCESS", Message: err.Error()}
+    return value
+  }
+  status := int(code)
+  value.Status = &status
+  return value
+}
+
+func (owner *windowsTarget) close() error {
+  return errors.Join(windows.CloseHandle(owner.info.Thread), windows.CloseHandle(owner.info.Process))
+}

package/internal/sourceprocess/windows_job_accounting_rejects_invalid_boundary_test.go

@@ -0,0 +1,97 @@
+//go:build windows
+
+package sourceprocess
+
+import (
+  "os"
+  "testing"
+  "unsafe"
+
+  "golang.org/x/sys/windows"
+)
+
+// TestWindowsJobAccountingRejectsInvalidBoundary verifies that a native job
+// reports its empty population while ambient and invalid handles cannot prove
+// ownership of the command's boundary.
+//
+// 1. Create a real unnamed job and configure descendant retirement on closure.
+// 2. Assign a real suspended target, distinguish its original wait from the populated job, then retire both.
+// 3. Close the job and reject ambient/null and invalid handles as ownership proof.
+//
+// @evidence contracts/testing.md#behavioral-verification The test executes actual Job Object creation, assignment, limits, termination and windowsJobActive accounting. A retained original target wait and an empty owned boundary are independently required after retirement; null/ambient and invalid handles cannot prove containment.
+// @evidence contracts/testing.md#independent-expectations A newly created job has no assigned processes, so the Windows job contract independently requires zero active members. The helper requires an explicitly acquired job; an ambient query would certify unrelated ownership even when Windows accepts a null handle.
+// @evidence contracts/testing.md#distinguishing-cases Empty and populated jobs contrast with the separate pending and retired original target. Null/ambient and invalid handles are rejected ownership boundaries. Surviving descendants and SDK cancellation belong to the platform protocol E2E scenarios.
+// @evidence contracts/testing.md#execution-ownership This Go package unit calls its owning native accounting and suspended-creation operations without building an artifact, installing a consumer or launching a product host. Its own test executable is terminated without ever running target code; original process, thread, input and job handles are closed.
+func TestWindowsJobAccountingRejectsInvalidBoundary(t *testing.T) {
+  job, err := windows.CreateJobObject(nil, nil)
+  if err != nil {
+    t.Fatal(err)
+  }
+  closed := false
+  defer func() {
+    if !closed {
+      _ = windows.CloseHandle(job)
+    }
+  }()
+  limits := windows.JOBOBJECT_EXTENDED_LIMIT_INFORMATION{}
+  limits.BasicLimitInformation.LimitFlags = windows.JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+  if _, err = windows.SetInformationJobObject(job, windows.JobObjectExtendedLimitInformation, uintptr(unsafe.Pointer(&limits)), uint32(unsafe.Sizeof(limits))); err != nil {
+    t.Fatal(err)
+  }
+  if err = windows.TerminateJobObject(job, 1); err != nil {
+    t.Fatal(err)
+  }
+  active, err := windowsJobActive(job)
+  if err != nil || active != 0 {
+    t.Fatalf("empty job active=%d error=%v", active, err)
+  }
+  executable, err := os.Executable()
+  if err != nil {
+    t.Fatal(err)
+  }
+  input, err := os.Open(os.DevNull)
+  if err != nil {
+    t.Fatal(err)
+  }
+  defer input.Close()
+  owner, err := startWindowsTarget(request{Version: 1, Command: executable, Cwd: t.TempDir(), Env: map[string]string{"SystemRoot": os.Getenv("SystemRoot")}}, input)
+  if err != nil {
+    t.Fatal(err)
+  }
+  defer func() {
+    if err := windows.TerminateProcess(owner.info.Process, 1); err == nil {
+      _ = waitWindowsTarget(owner.info.Process, windows.INFINITE)
+    }
+    _ = owner.close()
+  }()
+  if err := windows.AssignProcessToJobObject(job, owner.info.Process); err != nil {
+    t.Fatal(err)
+  }
+  active, err = windowsJobActive(job)
+  if err != nil || active != 1 {
+    t.Fatalf("populated job active=%d error=%v", active, err)
+  }
+  if err := waitWindowsTarget(owner.info.Process, 0); err == nil {
+    t.Fatal("populated suspended target reported retired")
+  }
+  if err := windows.TerminateJobObject(job, 1); err != nil {
+    t.Fatal(err)
+  }
+  if err := waitWindowsTarget(owner.info.Process, windows.INFINITE); err != nil {
+    t.Fatal(err)
+  }
+  active, err = windowsJobActive(job)
+  if err != nil || active != 0 {
+    t.Fatalf("retired job active=%d error=%v", active, err)
+  }
+  if err = windows.CloseHandle(job); err != nil {
+    t.Fatal(err)
+  }
+  closed = true
+  if _, err = windowsJobActive(0); err == nil {
+    t.Fatal("null job handle certified an empty boundary")
+  }
+  if _, err = windowsJobActive(windows.InvalidHandle); err == nil {
+    t.Fatal("invalid job handle certified an empty boundary")
+  }
+}