ttsc 0.30.3 → 0.31.0

package/internal/sourceprocess/windows_target_owns_suspended_admission_test.go

@@ -0,0 +1,179 @@
+//go:build windows
+
+package sourceprocess
+
+import (
+  "fmt"
+  "os"
+  "path/filepath"
+  "strconv"
+  "testing"
+  "unsafe"
+
+  "golang.org/x/sys/windows"
+)
+
+// TestWindowsTargetOwnsSuspendedAdmission checks original-handle admission
+// before any target code runs, then distinguishes resume from retirement.
+// The authored helper only publishes its PID and exits; it creates no children.
+//
+// 1. Create this test executable suspended with a caller-private marker.
+// 2. Retain its exact creation in an owned job before RUN and reject foreign identities.
+// 3. Resume once and join exit seven through the original process handle.
+// 4. Create another suspended helper, retire it without RUN and require no marker.
+//
+// @evidence contracts/testing.md#behavioral-verification The owning Windows target abstraction creates actual suspended native commands. Actual job assignment and retainWindowsTarget validate PID, creation and membership before RUN; a separate retained handle remains usable after the creation handles close. ResumeThread and original-object waits preserve nonzero completion and retirement without execution.
+// @evidence contracts/testing.md#independent-expectations The authored helper publishes its actual os.Getpid and exits seven. A suspended primary thread cannot publish the marker; retirement before resumption cannot execute the helper body.
+// @evidence contracts/testing.md#distinguishing-cases Resumed completion contrasts with job termination before RUN. Missing/version/PID/creation identities, a different real job and invalid job handles refuse enrollment; invalid wait handles refuse completion. Pending suspended targets cannot certify retirement. Product descendant ownership, cancellation during the START publication window and SDK overflow remain separate installed-protocol E2E coverage.
+// @evidence contracts/testing.md#execution-ownership This native package unit directly exercises its owning process primitive and launches only its own authored test helper, without building another artifact, installing a consumer or launching a compiler/product host. It joins each original process and closes every acquired native handle and input file.
+func TestWindowsTargetOwnsSuspendedAdmission(t *testing.T) {
+  if marker := os.Getenv("TTSC_SOURCEPROCESS_UNIT_MARKER"); marker != "" {
+    if err := os.WriteFile(marker, []byte(strconv.Itoa(os.Getpid())), 0600); err != nil {
+      os.Exit(8)
+    }
+    os.Exit(7)
+  }
+  executable, err := os.Executable()
+  if err != nil {
+    t.Fatal(err)
+  }
+  for _, resume := range []bool{true, false} {
+    t.Run(fmt.Sprintf("resume-%t", resume), func(t *testing.T) {
+      directory := t.TempDir()
+      marker := filepath.Join(directory, "executed.pid")
+      input, err := os.Open(os.DevNull)
+      if err != nil {
+        t.Fatal(err)
+      }
+      defer input.Close()
+      owner, err := startWindowsTarget(request{Version: 1, Command: executable, Args: []string{"-test.run=^TestWindowsTargetOwnsSuspendedAdmission$"}, Cwd: directory, Env: map[string]string{"TTSC_SOURCEPROCESS_UNIT_MARKER": marker, "SystemRoot": os.Getenv("SystemRoot")}}, input)
+      if err != nil {
+        t.Fatal(err)
+      }
+      ownerClosed := false
+      defer func() {
+        if !ownerClosed {
+          if err := windows.TerminateProcess(owner.info.Process, 1); err == nil {
+            _ = waitWindowsTarget(owner.info.Process, windows.INFINITE)
+          }
+          if err := owner.close(); err != nil {
+            t.Error(err)
+          }
+        }
+      }()
+      job, err := windows.CreateJobObject(nil, nil)
+      if err != nil {
+        t.Fatal(err)
+      }
+      defer 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.AssignProcessToJobObject(job, owner.info.Process); err != nil {
+        t.Fatal(err)
+      }
+      identity, err := owner.started()
+      if err != nil {
+        t.Fatal(err)
+      }
+      for name, invalid := range map[string]windowsStarted{
+        "missing": {},
+        "version": {Version: 2, Pid: identity.Pid, Created: identity.Created},
+        "pid": {Version: 1, Created: identity.Created},
+        "foreign-pid": {Version: 1, Pid: uint32(os.Getpid()), Created: identity.Created},
+        "missing-creation": {Version: 1, Pid: identity.Pid},
+        "creation": {Version: 1, Pid: identity.Pid, Created: identity.Created + 1},
+      } {
+        t.Run(name, func(t *testing.T) {
+          handle, err := retainWindowsTarget(invalid, job)
+          if err == nil || handle != 0 {
+            t.Fatalf("foreign identity admitted handle=%v error=%v", handle, err)
+          }
+        })
+      }
+      foreignJob, err := windows.CreateJobObject(nil, nil)
+      if err != nil {
+        t.Fatal(err)
+      }
+      defer windows.CloseHandle(foreignJob)
+      for _, boundary := range []windows.Handle{0, windows.InvalidHandle, foreignJob} {
+        if handle, err := retainWindowsTarget(identity, boundary); err == nil || handle != 0 {
+          t.Fatalf("foreign job admitted handle=%v error=%v", handle, err)
+        }
+      }
+      retained, err := retainWindowsTarget(identity, job)
+      if err != nil {
+        t.Fatal(err)
+      }
+      defer windows.CloseHandle(retained)
+      if err := waitWindowsTarget(retained, 0); err == nil {
+        t.Fatal("suspended original target certified completion")
+      }
+      if err := waitWindowsTarget(windows.InvalidHandle, 0); err == nil {
+        t.Fatal("invalid handle certified completion")
+      }
+      if err := windows.TerminateJobObject(windows.InvalidHandle, 1); err == nil {
+        t.Fatal("invalid termination unexpectedly succeeded")
+      }
+      if err := waitWindowsTarget(retained, 0); err == nil {
+        t.Fatal("failed termination certified a live target")
+      }
+      if owner.info.ProcessId == 0 || owner.info.ThreadId == 0 || owner.info.Process == 0 || owner.info.Thread == 0 {
+        t.Fatal("creation did not preserve original process/thread identity")
+      }
+      pid, err := windows.GetProcessId(owner.info.Process)
+      if err != nil || pid != owner.info.ProcessId {
+        t.Fatalf("original process identity=%d error=%v", pid, err)
+      }
+      var created, exited, kernel, user windows.Filetime
+      if err := windows.GetProcessTimes(owner.info.Process, &created, &exited, &kernel, &user); err != nil {
+        t.Fatal(err)
+      }
+      if created.HighDateTime == 0 && created.LowDateTime == 0 {
+        t.Fatal("original creation identity is absent")
+      }
+      state, err := windows.WaitForSingleObject(owner.info.Process, 0)
+      if err != nil || state != uint32(windows.WAIT_TIMEOUT) {
+        t.Fatalf("suspended process wait=%d error=%v", state, err)
+      }
+      if _, err := os.Stat(marker); !os.IsNotExist(err) {
+        t.Fatalf("target executed before RUN: %v", err)
+      }
+      if resume {
+        if err := owner.resume(); err != nil {
+          t.Fatal(err)
+        }
+      } else if err := windows.TerminateJobObject(job, 1); err != nil {
+        t.Fatal(err)
+      }
+      result := owner.wait()
+      expected := 1
+      if resume {
+        expected = 7
+      }
+      if result.Error != nil || result.Status == nil || *result.Status != expected || result.Pid != int(pid) || !result.Cleanup.DirectChildJoined {
+        t.Fatalf("original target completion: %#v", result)
+      }
+      if err := waitWindowsTarget(retained, windows.INFINITE); err != nil {
+        t.Fatal(err)
+      }
+      if err := owner.close(); err != nil {
+        t.Fatal(err)
+      }
+      ownerClosed = true
+      if err := waitWindowsTarget(retained, 0); err != nil {
+        t.Fatalf("retained original authority was lost with creation handles: %v", err)
+      }
+      if resume {
+        data, err := os.ReadFile(marker)
+        if err != nil || string(data) != strconv.Itoa(int(pid)) {
+          t.Fatalf("actual target identity=%q error=%v", data, err)
+        }
+      } else if _, err := os.Stat(marker); !os.IsNotExist(err) {
+        t.Fatalf("retired suspended target executed: %v", err)
+      }
+    })
+  }
+}

package/internal/watchhelper/run.go

@@ -0,0 +1,32 @@
+package watchhelper
+
+import "io"
+
+// Run serves the protocol over stdin and stdout and returns an exit code.
+// End of scanned input, including a scanner error, ends the request stream;
+// backend failures or an output flush failure can also end service.
+//
+// One loop polls the inotify instance and a wake pipe the stdin reader writes
+// after queueing each request. That loop serializes emitted messages and a
+// `sync` drains the instance to an observed empty read before answering. This
+// is not a total ordering of kernel event creation and request arrival, nor a
+// guarantee that no event arrives after that read.
+//
+// stdin and the output streams remain caller-owned. The helper owns its inotify
+// and wake descriptors and attempts their closure on every return. Its reader can remain
+// blocked on caller input after an early backend failure; the command process
+// ends when Run returns, while a library caller must close its input.
+// Queue sends are canceled on return, and wake writes are synchronized with
+// descriptor closure so a delayed reader cannot write to a reused descriptor.
+//
+// @evidence contracts/common.md#principled-implementation The Linux inotify instance reports actual overflow and directory loss. One poll loop drains queued events before acknowledging sync, preserving the protocol's observation ordering without guessing that quiet means unchanged.
+// @evidence contracts/common.md#clear-and-simple-design A stdin reader only decodes and queues requests; one helper loop owns watch state, ordered emission and synchronization. Kernel handles remain behind this native backend.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Supported syscalls supply watch capabilities; no foreign runtime method is replaced and no test event substitutes for an actual ready or drain boundary.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs state ordering, exit and stream ownership, including the blocked-reader limitation. The package describes every protocol message separately under documentation-skill guidance.
+// @evidence contracts/portability.md#os-neutral-implementation A Linux build constraint isolates inotify and poll. Native directory paths remain syscall inputs, not shell text; other platforms select an explicit unsupported implementation that reports usage code 2 and use adapter-owned watching.
+// @evidence contracts/performance.md#efficient-algorithms Each kernel batch is decoded linearly in its bytes; fanout visits K subscribers and JSON output also costs the repeated name bytes. Sorting O(K log K) is shared until membership changes. Removal uses indexed descriptor lookup, and the loop performs no userspace directory traversal. A drain has no event-count or time cap and may keep reading under continuous activity; native syscalls and caller writes have their own blocking costs.
+// @evidence contracts/performance.md#reuse-equivalent-work Kernel watch descriptors are shared by subscribers of the same directory. Ordered subscriber IDs are cached per descriptor and invalidated on add, remove or directory loss; all mutation belongs to the same event loop.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Deferred cleanup cancels queued reader sends and attempts closure of all three owned descriptors; a mutex prevents late wake writes after closure. Blocking input reads and output writes remain caller-owned. The request channel holds at most 256 values, the scanner buffer is limited to 16 MiB, and event decoding reuses 64 KiB. Subscription maps and order slices have no independent numeric cap; matching remove/gone paths reclaim entries and process exit releases state. Reusing an ID for another descriptor without removal can leave its earlier subscription until that directory is gone or the process exits.
+func Run(stdin io.Reader, stdout io.Writer, stderr io.Writer) int {
+  return run(stdin, stdout, stderr)
+}

package/internal/watchhelper/run_linux.go

@@ -0,0 +1,323 @@
+//go:build linux
+
+package watchhelper
+
+import (
+  "bufio"
+  "encoding/binary"
+  "encoding/json"
+  "fmt"
+  "io"
+  "sort"
+  "sync"
+
+  "golang.org/x/sys/unix"
+)
+
+// watchMask is libuv's mask for a directory watch (src/unix/linux.c), so the
+// helper hears exactly what `fs.watch` heard.
+const watchMask = unix.IN_ATTRIB | unix.IN_CREATE | unix.IN_MODIFY |
+  unix.IN_DELETE | unix.IN_DELETE_SELF | unix.IN_MOVE_SELF |
+  unix.IN_MOVED_FROM | unix.IN_MOVED_TO
+
+// endMask holds the events after which a watch reports nothing more about the
+// directory it was opened on.
+const endMask = unix.IN_IGNORED | unix.IN_DELETE_SELF | unix.IN_MOVE_SELF |
+  unix.IN_UNMOUNT
+
+// run is the Linux implementation behind Run.
+func run(stdin io.Reader, stdout io.Writer, stderr io.Writer) int {
+  fd, err := unix.InotifyInit1(unix.IN_NONBLOCK | unix.IN_CLOEXEC)
+  if err != nil {
+    fmt.Fprintf(stderr, "ttsc __watch: %v\n", err)
+    return 1
+  }
+  defer unix.Close(fd)
+  var wake [2]int
+  if err := unix.Pipe2(wake[:], unix.O_NONBLOCK|unix.O_CLOEXEC); err != nil {
+    fmt.Fprintf(stderr, "ttsc __watch: %v\n", err)
+    return 1
+  }
+  defer unix.Close(wake[0])
+  requests := make(chan Request, 256)
+  done := make(chan struct{})
+  var wakeMu sync.Mutex
+  notify := func() {
+    wakeMu.Lock()
+    defer wakeMu.Unlock()
+    select {
+    case <-done:
+      return
+    default:
+      // A full nonblocking pipe already holds a wake-up.
+      _, _ = unix.Write(wake[1], []byte{0})
+    }
+  }
+  defer func() {
+    wakeMu.Lock()
+    close(done)
+    _ = unix.Close(wake[1])
+    wakeMu.Unlock()
+  }()
+  go readRequests(stdin, requests, done, notify)
+
+  h := newHelper(fd, stdout)
+  fds := []unix.PollFd{
+    {Fd: int32(fd), Events: unix.POLLIN},
+    {Fd: int32(wake[0]), Events: unix.POLLIN},
+  }
+  for {
+    fds[0].Revents, fds[1].Revents = 0, 0
+    if _, err := unix.Poll(fds, -1); err != nil {
+      if err == unix.EINTR {
+        continue
+      }
+      fmt.Fprintf(stderr, "ttsc __watch: %v\n", err)
+      return 1
+    }
+    if fds[0].Revents != 0 {
+      if err := h.drain(); err != nil {
+        fmt.Fprintf(stderr, "ttsc __watch: %v\n", err)
+        return 1
+      }
+    }
+    if fds[1].Revents != 0 {
+      emptyWake(wake[0])
+      for pending := true; pending; {
+        select {
+        case request, open := <-requests:
+          if !open {
+            h.out.Flush()
+            return 0
+          }
+          if err := h.handle(request); err != nil {
+            fmt.Fprintf(stderr, "ttsc __watch: %v\n", err)
+            return 1
+          }
+        default:
+          pending = false
+        }
+      }
+    }
+    // A client that went away cannot be told anything more.
+    if err := h.out.Flush(); err != nil {
+      return 0
+    }
+  }
+}
+
+// readRequests decodes stdin into requests, waking the loop after each, and
+// closes the channel at the end of input.
+func readRequests(stdin io.Reader, requests chan<- Request, done <-chan struct{}, notify func()) {
+  defer notify()
+  defer close(requests)
+  scanner := bufio.NewScanner(stdin)
+  scanner.Buffer(make([]byte, 64*1024), 16*1024*1024)
+  for scanner.Scan() {
+    var request Request
+    if json.Unmarshal(scanner.Bytes(), &request) != nil {
+      continue
+    }
+    select {
+    case requests <- request:
+      notify()
+    case <-done:
+      return
+    }
+  }
+}
+
+// emptyWake reads the wake pipe empty.
+func emptyWake(fd int) {
+  var buffer [64]byte
+  for {
+    n, err := unix.Read(fd, buffer[:])
+    if err == unix.EINTR {
+      continue
+    }
+    if err != nil || n <= 0 {
+      return
+    }
+  }
+}
+
+// helper holds one inotify instance and the subscriptions sharing its watch
+// descriptors.
+type helper struct {
+  fd      int
+  out     *bufio.Writer
+  encoder *json.Encoder
+
+  // watches maps a watch descriptor to the subscriptions it serves.
+  watches map[int32]map[int64]struct{}
+
+  // descriptors maps a subscription to its watch descriptor.
+  descriptors map[int64]int32
+
+  // ordered shares deterministic subscriber order until membership changes.
+  ordered map[int32][]int64
+
+  buffer []byte
+}
+
+func newHelper(fd int, stdout io.Writer) *helper {
+  out := bufio.NewWriter(stdout)
+  return &helper{
+    fd:          fd,
+    out:         out,
+    encoder:     json.NewEncoder(out),
+    watches:     map[int32]map[int64]struct{}{},
+    descriptors: map[int64]int32{},
+    ordered:     map[int32][]int64{},
+    buffer:      make([]byte, 64*1024),
+  }
+}
+
+func (h *helper) emit(response Response) {
+  // Encoding these fields cannot fail, and a write error surfaces at the
+  // loop's flush.
+  h.encoder.Encode(response)
+}
+
+func (h *helper) handle(request Request) error {
+  switch request.Op {
+  case "add":
+    h.add(request.ID, request.Path)
+  case "remove":
+    h.remove(request.ID)
+  case "sync":
+    if err := h.drain(); err != nil {
+      return err
+    }
+    h.emit(Response{ID: request.ID, Synced: true})
+  }
+  return nil
+}
+
+func (h *helper) add(id int64, path string) {
+  wd, err := unix.InotifyAddWatch(h.fd, path, watchMask)
+  if err != nil {
+    h.emit(Response{ID: id, Error: err.Error()})
+    return
+  }
+  descriptor := int32(wd)
+  subscriptions := h.watches[descriptor]
+  if subscriptions == nil {
+    subscriptions = map[int64]struct{}{}
+    h.watches[descriptor] = subscriptions
+  }
+  subscriptions[id] = struct{}{}
+  h.descriptors[id] = descriptor
+  delete(h.ordered, descriptor)
+  h.emit(Response{ID: id, Ready: true})
+}
+
+func (h *helper) remove(id int64) {
+  descriptor, ok := h.descriptors[id]
+  if !ok {
+    return
+  }
+  delete(h.descriptors, id)
+  subscriptions := h.watches[descriptor]
+  delete(subscriptions, id)
+  delete(h.ordered, descriptor)
+  if len(subscriptions) != 0 {
+    return
+  }
+  delete(h.watches, descriptor)
+  // The kernel may have removed the watch already; its IN_IGNORED then finds
+  // no subscription.
+  unix.InotifyRmWatch(h.fd, uint32(descriptor))
+}
+
+// drain reads the instance until it is empty.
+func (h *helper) drain() error {
+  for {
+    n, err := unix.Read(h.fd, h.buffer)
+    if err == unix.EINTR {
+      continue
+    }
+    if err == unix.EAGAIN {
+      return nil
+    }
+    if err != nil {
+      return err
+    }
+    if n <= 0 {
+      return nil
+    }
+    h.dispatch(h.buffer[:n])
+  }
+}
+
+// dispatch reports every event in one read of the instance.
+func (h *helper) dispatch(data []byte) {
+  for offset := 0; offset+unix.SizeofInotifyEvent <= len(data); {
+    wd := int32(binary.NativeEndian.Uint32(data[offset:]))
+    mask := binary.NativeEndian.Uint32(data[offset+4:])
+    length := int(binary.NativeEndian.Uint32(data[offset+12:]))
+    start := offset + unix.SizeofInotifyEvent
+    end := start + length
+    if end > len(data) {
+      return
+    }
+    name := data[start:end]
+    for len(name) != 0 && name[len(name)-1] == 0 {
+      name = name[:len(name)-1]
+    }
+    h.event(wd, mask, string(name))
+    offset = end
+  }
+}
+
+// event reports one inotify event to the subscriptions it concerns.
+func (h *helper) event(wd int32, mask uint32, name string) {
+  if mask&unix.IN_Q_OVERFLOW != 0 {
+    h.emit(Response{Overflow: true})
+    return
+  }
+  subscriptions := h.watches[wd]
+  if len(subscriptions) == 0 {
+    return
+  }
+  ids := h.ordered[wd]
+  if ids == nil {
+    ids = sortedIDs(subscriptions)
+    h.ordered[wd] = ids
+  }
+  if mask&endMask != 0 {
+    for _, id := range ids {
+      delete(h.descriptors, id)
+      h.emit(Response{ID: id, Gone: true})
+    }
+    delete(h.watches, wd)
+    delete(h.ordered, wd)
+    // A moved directory keeps its watch, which now follows another path.
+    if mask&unix.IN_IGNORED == 0 {
+      unix.InotifyRmWatch(h.fd, uint32(wd))
+    }
+    return
+  }
+  // The directory's own attributes say nothing about its entries.
+  if name == "" {
+    return
+  }
+  // libuv reports CHANGE only for an event that is nothing but an attribute
+  // or content change, and RENAME for every other.
+  kind := "change"
+  if mask&^uint32(unix.IN_ATTRIB|unix.IN_MODIFY) != 0 {
+    kind = "rename"
+  }
+  for _, id := range ids {
+    h.emit(Response{ID: id, Type: kind, Name: name})
+  }
+}
+
+func sortedIDs(subscriptions map[int64]struct{}) []int64 {
+  ids := make([]int64, 0, len(subscriptions))
+  for id := range subscriptions {
+    ids = append(ids, id)
+  }
+  sort.Slice(ids, func(i, j int) bool { return ids[i] < ids[j] })
+  return ids
+}