winproc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9197e883045d6e76b5dacc657103c377b4ae4ad40a9bd0b92eec8df2fe4c03f4
+  data.tar.gz: 1882aedae0b563784feb28585bea6da6887d80489606de8c74bac27b3631fdef
+SHA512:
+  metadata.gz: e13824edecf831eaf21e0111e61e5f62d0c39be1dc4593fbcaec5c46fcd66f5448e692040d2115a2969168e7c217869c85bf7faeee4743c5c696f8cb92a8a47a
+  data.tar.gz: 9e52f01d45d520668d89634c998db2992b22e1167ea71b22b73855d5677a2f255faf79dbd2317952ed0feba7a1fa80a7a77f9c6b0922aac6837f445d2dc0b236

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## [0.1.0] - 2026-06-27
+
+Initial release.
+
+- `Winproc.spawn(*argv, ...)` — argv-array process spawning (no shell ever
+  invoked) with CommandLineToArgvW-compatible quoting, exact per-handle
+  inheritance (`PROC_THREAD_ATTRIBUTE_HANDLE_LIST`), case-insensitive env
+  merge, `:pipe`/`:null`/IO/`:stdout`-merge stdio redirection, atomic job
+  placement (`PROC_THREAD_ATTRIBUTE_JOB_LIST`), and `new_process_group:` /
+  `no_window:` flags.
+- `Winproc::Process` — `#wait(timeout:)` (GVL-released, interruptible,
+  memoizing), `#alive?`, `#exitstatus` (259 STILL_ACTIVE guarded), `#kill`,
+  `#pid`, `#stdin`/`#stdout`/`#stderr`, idempotent `#close`/`#closed?`.
+- `Winproc::Job` — anonymous job objects with `kill_on_close:` (crash-safe
+  process-tree reaping via `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`), `memory:`,
+  `process_memory:`, `cpu_percent:` (hard cap), `active_processes:`, and
+  `cpu_time:` limits; `#assign`, `#terminate`, `#wait_empty(timeout:)` over a
+  private completion port, `#active_processes`, `#close`.
+- `Winproc.pty(*argv, ...)` / `Winproc::PTY` — ConPTY pseudoconsole sessions
+  with `#read`/`#write` (binary, VT pass-through), `#resize`, `#process`, and
+  deadlock-free `#close`. Resolved at runtime via `GetProcAddress` so the gem
+  loads on Windows < 10 1809 (`pty` raises `Unsupported`); `pty_available?`.
+- `Winproc::Stream` — one end of a redirection/ConPTY pipe: `#read`/`#write`
+  (binary-safe, GVL-released, `CancelSynchronousIo`-interruptible), `#<<`,
+  idempotent `#close`.
+- Elevation helpers — `Winproc.elevated?` (TokenElevation), `Winproc.admin?`
+  (linked-token `CheckTokenMembership`), `Winproc.runas` (ShellExecuteEx
+  "runas", UAC), `Winproc.with_privilege(name) { ... }` (scoped token
+  privileges with the `ERROR_NOT_ALL_ASSIGNED` lie checked).
+- `Winproc.run_blocking` — the winipc cooperation shim: offloads blocking
+  native calls to a worker Thread under a fiber scheduler (e.g. winloop) and
+  runs inline otherwise. Zero runtime dependencies.
+- A typed error hierarchy (`Error` → `OSError` → `NotFound`/`AccessDenied`/
+  `Canceled`/`BrokenPipe`/`ElevationRequired`/`PrivilegeNotHeld`/`Unsupported`,
+  plus `ModeError`/`Closed`), each `OSError` carrying `#code`.
+
+Windows MSVC (mswin) Ruby only. x64; arm64-mswin is expected to work but is
+untested and unsupported until an arm64-mswin Ruby distribution exists.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ned
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,312 @@
+# winproc
+
+**Windows process control for Ruby: job-object process trees that can never leak, ConPTY terminals, hygienic spawning, and UAC-aware elevation helpers — safe by default, cooperative with a fiber scheduler.**
+
+Ruby's `Process.spawn` on Windows gives you a pid and little else. You cannot
+control a process *tree*: kill the shell you launched and its grandchildren
+sail on as orphans.
+
+```
+> p = Process.spawn("cmd", "/c", "start /b ping -n 600 127.0.0.1")
+> Process.kill(:KILL, p)          # cmd dies...
+> # ...the ping keeps running. Forever. Nothing reaps it.
+```
+
+There is no terminal emulation either — a spawned CLI detects a pipe instead of
+a console and goes dumb (no color, no prompts, line-buffered) — and there is no
+`runas`, so you cannot elevate from Ruby at all. `childprocess` and `open3`
+don't fill the gap: no job objects, no ConPTY, and they are MinGW-oriented.
+
+**This is the gap nothing else filled.** winproc binds the Win32 primitives
+the OS actually intends for this: job objects with kill-on-close (a spawned
+tree dies with you, *even if your Ruby process crashes*), `CreateProcessW` with
+exact argv quoting and per-handle inheritance (`PROC_THREAD_ATTRIBUTE_HANDLE_LIST`,
+no inheritance races), ConPTY pseudoconsoles for real interactive terminal I/O,
+and the UAC/token helpers (`elevated?`, `admin?`, `runas`, scoped privileges).
+Blocking waits release the GVL and cooperate with a fiber scheduler.
+
+| What | API |
+|---|---|
+| Spawn (argv array, no shell) | `Winproc.spawn(*argv, …)` → `Winproc::Process` |
+| Process control | `#wait` `#alive?` `#exitstatus` `#kill` `#pid` `#close` |
+| Kill-proof process trees | `Winproc::Job.new(kill_on_close: true, …)` |
+| Job control | `#assign` `#terminate` `#wait_empty` `#active_processes` |
+| Interactive terminals | `Winproc.pty(*argv, …)` → `Winproc::PTY` |
+| Redirection pipes | `Winproc::Stream#read` `#write` `#close` |
+| Elevation | `Winproc.elevated?` `.admin?` `.runas` `.with_privilege` |
+
+## Requirements
+
+- **Windows 10 or newer.** ConPTY (`Winproc.pty`) needs Windows 10 1809+
+  (build 17763); everything else needs Windows 10. `Winproc.pty_available?`
+  probes at runtime, and `Winproc.pty` raises `Winproc::Unsupported` on older
+  builds — the gem still loads.
+- A **native MSVC (mswin) Ruby**, version ≥ 3.1 (`x64-mswin64`). **Not
+  supported on MinGW/UCRT** Rubies — winproc binds Win32 process/job/
+  pseudoconsole/token APIs and is built with `cl.exe`.
+- Visual Studio 2017+ or the Build Tools with the **"Desktop development with
+  C++"** workload. Building from source needs no Developer Command Prompt — the
+  Rakefile loads the toolchain via the [vcvars](https://github.com/main-path/vcvars)
+  gem (`require "vcvars/rake"`); point failures at `vcvars doctor`.
+
+x64 only. arm64-mswin is expected to work but is untested and unsupported until
+an arm64-mswin Ruby distribution exists.
+
+## Install
+
+```sh
+gem install winproc
+```
+
+## Spawn & capture
+
+argv is always an **array** — winproc quotes every element (including
+`argv[0]`) per the CommandLineToArgvW rules, so the classic
+`C:\Program Files\…` token-splitting trap is closed. No shell is ever invoked.
+
+```ruby
+require "winproc"
+
+p = Winproc.spawn("ruby", "-e", "puts 6*7; STDERR.puts 'log'",
+                  stdout: :pipe, stderr: :stdout)
+out = +""
+while (chunk = p.stdout.read)   # binary chunks, nil at EOF
+  out << chunk
+end
+p.wait     # => 0
+out        # => "42\nlog\n"  (stderr merged into stdout)
+p.close
+```
+
+Feed stdin through a pipe and close it for EOF:
+
+```ruby
+Winproc.spawn("ruby", "-e", "print STDIN.read.upcase",
+              stdin: :pipe, stdout: :pipe) do |p|
+  p.stdin.write("hello")
+  p.stdin.close            # EOF for the child
+  p.stdout.read            # => "HELLO"
+  p.wait                   # => 0
+end                        # block form ensure-closes the handles
+```
+
+## Never leak a process tree
+
+A `Job` with `kill_on_close: true` (the default) is the safety net: when the
+job handle is closed — by `#close`, by GC, **or by your Ruby process crashing**
+— the OS terminates every process in the tree. Children are placed in the job
+*atomically at creation*, so a child can never spawn a grandchild before being
+jobbed.
+
+```ruby
+Winproc::Job.new do |job|                       # kill_on_close: true
+  p = Winproc.spawn("cmd.exe", "/c", "ping -n 600 127.0.0.1 >NUL", job: job)
+  # ... do work ...
+  p.close
+end                                             # job closed: the whole tree dies
+```
+
+Kill a tree explicitly with an exit code:
+
+```ruby
+job = Winproc::Job.new
+p = Winproc.spawn("cmd.exe", "/c", "ping -n 60 127.0.0.1 >NUL", job: job)
+job.terminate(9)                                # ping AND cmd die together
+p.wait                                          # => 9
+p.close; job.close
+```
+
+## Limits
+
+```ruby
+job = Winproc::Job.new(memory: 256 * 1024 * 1024,   # job-wide commit cap (bytes)
+                       active_processes: 8,          # max concurrent processes
+                       cpu_time: 30.0,               # user-mode CPU seconds
+                       cpu_percent: 50)              # hard CPU cap (1..100)
+p = Winproc.spawn("cmd.exe", "/c", "exit 3", job: job, no_window: true)
+p.wait                                              # => 3
+job.wait_empty(timeout: 5)                          # => true (tree fully gone)
+p.close; job.close
+```
+
+`cpu_percent:` raises `Winproc::Unsupported` under Remote Desktop / Dynamic
+Fair Share Scheduling (the other limits still apply).
+
+## Interactive terminals (ConPTY)
+
+```ruby
+if Winproc.pty_available?
+  Winproc.pty("cmd.exe", cols: 120, rows: 30) do |pty|
+    pty.write("echo hi conpty\r")               # "\r" is Enter (not "\n")
+    buf = +""
+    buf << pty.read until buf.include?("hi conpty")
+    pty.write("exit\r")
+    pty.process.wait(timeout: 5)                 # => 0
+  end                                            # close(kill: true) if still alive
+end
+```
+
+`pty.read` returns **binary** bytes: UTF-8 text interleaved with VT escape
+sequences, passed through verbatim. A read may split a multi-byte character or
+a VT sequence — reassembly (and `force_encoding("UTF-8")`) is the caller's job.
+
+**Drain before close for full output:** `PTY#close` tears the output pipe down
+to stay deadlock-free, which discards any final frame. To capture everything,
+read until `nil` (after the child exits) *before* closing.
+
+## Elevation
+
+```ruby
+Winproc.elevated?     # => false  (typical desktop session)
+Winproc.admin?        # => true   (admin user with a split token)
+
+begin
+  p = Winproc.runas("cmd.exe", ["/c", "exit 0"])  # UAC prompt appears here
+  p&.wait
+  p&.close
+rescue Winproc::Canceled
+  warn "user declined elevation"
+end
+
+Winproc.with_privilege(:debug) do
+  # SeDebugPrivilege enabled for the whole process inside this block
+end
+# raises Winproc::PrivilegeNotHeld if the token doesn't hold it
+```
+
+`runas` takes an **argv array** (quoted exactly like `spawn`), never a raw
+command line. It returns a `Winproc::Process`, or `nil` when the shell launched
+without a process handle.
+
+## With a fiber scheduler (winloop)
+
+Every blocking call (`Process#wait`, `Stream#read`/`#write`, `Job#wait_empty`,
+`PTY#read`/`#write`, `runas`) releases the GVL and is interruptible standalone.
+Under a live `Fiber.scheduler` (e.g. [winloop](https://github.com/main-path/winloop))
+the call is offloaded to a worker Thread so the calling fiber parks and the
+event loop keeps serving other fibers — with no link-time or require-time
+dependency on the scheduler (it is duck-typed through `Fiber.scheduler`).
+
+```ruby
+Winloop.run do
+  Fiber.schedule do
+    p = Winproc.spawn("ruby", "-e", "sleep 1")
+    p.wait        # parks this fiber; the loop keeps running
+    p.close
+  end
+  Fiber.schedule { 50.times { do_other_work; sleep 0.02 } }
+end
+```
+
+## Library API
+
+```ruby
+Winproc.spawn(*argv, app:, cwd:, env:, stdin:, stdout:, stderr:, job:,
+              new_process_group:, no_window:) # => Winproc::Process
+Winproc.pty(*argv, cols:, rows:, app:, cwd:, env:, job:)  # => Winproc::PTY
+Winproc.pty_available?            # => true | false
+Winproc.elevated?                 # => true | false  (TokenElevation)
+Winproc.admin?                    # => true | false  (linked-token membership)
+Winproc.runas(exe, args = [], cwd:, show:)  # => Winproc::Process | nil
+Winproc.with_privilege(name) { ... }        # => block value
+Winproc.run_blocking { ... }                # => block value (scheduler shim)
+
+process.wait(timeout: nil)  # => Integer exit code | nil (timeout)
+process.alive?              # => true | false
+process.exitstatus          # => Integer | nil (nil while running)
+process.kill(exit_code = 1) # => self  (TerminateProcess; no children)
+process.pid                 # => Integer
+process.stdin / .stdout / .stderr  # => Winproc::Stream | nil (:pipe slots)
+process.close / .closed?
+
+Winproc::Job.new(kill_on_close: true, memory:, process_memory:,
+                 cpu_percent:, active_processes:, cpu_time:)  # => Job
+job.assign(process)         # => self  (fallback; prefer spawn(job:))
+job.terminate(exit_code = 1)# => self  (kill the whole tree, now)
+job.wait_empty(timeout: nil)# => true (empty) | false (timeout)
+job.active_processes        # => Integer
+job.close / .closed?
+
+stream.read(maxlen = 65536) # => binary String | nil (EOF)
+stream.write(bytes)         # => Integer bytes written (all of them)
+stream << bytes             # => stream
+stream.close / .closed?
+
+pty.read(maxlen = 65536)    # => binary String | nil (EOF)
+pty.write(bytes)            # => Integer
+pty.resize(cols, rows)      # => self
+pty.cols / .rows            # => Integer
+pty.process                 # => Winproc::Process
+pty.close(kill: true) / .closed?
+```
+
+## How it works
+
+- **Inheritance hygiene.** Redirected spawns name *exactly* the ≤3 child std
+  handles in `PROC_THREAD_ATTRIBUTE_HANDLE_LIST` (deduped, never pseudo-handles)
+  and pass `bInheritHandles = TRUE`, so concurrent spawns from multiple threads
+  can never leak each other's pipe ends. Non-redirected spawns inherit nothing.
+- **Crash-safe trees.** `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` is a kernel
+  guarantee: the OS reaps the job's processes when its last handle closes — and
+  the handle closes when your process dies, however it dies. The job's IOCP is
+  associated *before* any process can join, so `wait_empty` never misses the
+  "tree empty" message; it also re-verifies the accounting query, so a stale
+  message can never produce a false positive.
+- **ConPTY teardown.** `PTY#close` closes the output pipe *before*
+  `ClosePseudoConsole` (and never on the thread blocked in `read`), the
+  documented ordering that avoids the pre-24H2 deadlock.
+- **Cooperation.** Blocking native calls release the GVL with a cancel-capable
+  unblock function, then `Winproc.run_blocking` offloads them to a worker
+  Thread under a fiber scheduler. All `close`/`wait`/`read` operations are
+  idempotent and safe to call concurrently with an in-flight wait (the waiter
+  is woken and raises `Winproc::Closed` before any handle is closed).
+
+## Errors
+
+```
+Winproc::Error               < StandardError
+  Winproc::OSError           < Error          # carries #code (Win32 GetLastError)
+    Winproc::NotFound                         # 2 / 3   program not found
+    Winproc::AccessDenied                     # 5
+    Winproc::Canceled                         # 995 / 1223  (UAC "No")
+    Winproc::BrokenPipe                       # 109 / 232 / 233
+    Winproc::ElevationRequired                # 740  (exe needs UAC — use runas)
+    Winproc::PrivilegeNotHeld                 # 1300
+    Winproc::Unsupported                      # 50 / 120 / 127  (e.g. ConPTY < 1809)
+  Winproc::ModeError         < Error          # read a write end, write a read end
+  Winproc::Closed            < Error          # operation on a closed object
+```
+
+Plain argument mistakes raise Ruby's own `ArgumentError`/`TypeError`.
+
+## Caveats
+
+- **Hard kills only.** `Process#kill` is `TerminateProcess` (no children);
+  `Job#terminate` / closing a kill-on-close job kills the whole tree. Windows
+  has no SIGTERM-style graceful kill; for console apps see `new_process_group:`
+  (Ctrl-Break delivery is out of scope for v1).
+- **Ruby can't reap these children.** `Process.wait(p.pid)` raises `ECHILD` —
+  winproc spawns via raw `CreateProcessW` and owns all waiting via the native
+  handle. Don't mix winproc processes with Ruby's `Process.wait`.
+- **PTY close discards the final frame** unless you drain `pty.read` to `nil`
+  first. And a PTY that is GC'd without `#close` **leaks its conhost** until
+  process exit (the GC free hook deliberately never calls `ClosePseudoConsole`,
+  to avoid an unbounded GVL-held hang during GC). **Always close PTYs
+  explicitly.**
+- **The UAC wait is uninterruptible** — there is no API to cancel a consent
+  dialog; `runas` blocks until the user answers (cooperative under a scheduler,
+  but the worker can't be cancelled mid-prompt).
+- **Quoting covers CRT/CommandLineToArgvW parsers.** Programs that re-parse
+  `GetCommandLineW` themselves (notably `cmd.exe` batch files) have their own
+  metacharacter rules; winproc never invokes a shell and does not escape for
+  `cmd.exe`.
+- **STILL_ACTIVE (259).** `#exitstatus`/`#wait` only read the exit code after
+  the process is confirmed exited, so 259 is never reported for a live process
+  — but a child that genuinely `exit 259`s is reported as 259 (a Windows
+  oddity).
+- **`with_privilege` is process-wide** — the privilege is enabled for every
+  thread while the block runs.
+
+## License
+
+[MIT](LICENSE.txt).

data/ext/winproc/extconf.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+#
+# extconf.rb for the winproc extension — Windows process control (CreateProcessW
+# spawning, job objects, ConPTY pseudoconsoles, and UAC elevation helpers).
+
+require "mkmf"
+
+unless RbConfig::CONFIG["target_os"] =~ /mswin/
+  abort <<~MSG
+    winproc requires a native Windows MSVC (mswin) Ruby — it binds Win32
+    process/job/pseudoconsole control and is built with cl.exe. Your Ruby is
+    "#{RbConfig::CONFIG['arch']}".
+  MSG
+end
+
+# System import libs (bare "NAME.lib" tokens on mswin):
+#   advapi32 - token/privilege/SID APIs (OpenProcessToken, AdjustTokenPrivileges,
+#              CheckTokenMembership, LookupPrivilegeValueW, AllocateAndInitializeSid)
+#   shell32  - ShellExecuteExW ("runas" elevation)
+#   ole32    - CoInitializeEx/CoUninitialize (ShellExecuteEx may activate COM shell extensions)
+# kernel32 (process/job/pipe/pseudoconsole) is linked by default.
+# ConPTY entry points (CreatePseudoConsole etc.) are resolved at RUNTIME via
+# GetProcAddress, so the gem loads on Windows < 10 1809 (pty raises Unsupported).
+#
+# Pure C — no -EHsc, so rb_raise/longjmp is the normal, safe error mechanism.
+#
+# Arch-neutral: the guard above keys on /mswin/ only (never the x64 literal) and
+# no /MACHINE:/-arch flags are passed; the C source gates on _WIN64, not _M_X64,
+# and uses ULONG_PTR for handle-sized values, so an arm64-mswin Ruby would build
+# this unchanged once such a distribution exists.
+$libs = [$libs, "advapi32.lib", "shell32.lib", "ole32.lib"].join(" ")
+
+create_makefile("winproc/winproc")