winproc 0.1.0

data/lib/winproc/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Winproc
+  VERSION = "0.1.0"
+end

data/lib/winproc.rb

@@ -0,0 +1,454 @@
+# frozen_string_literal: true
+
+require "winproc/version"
+require "winproc/winproc" # native extension: classes + errors + SLOT_*/SW_*/CREATE_* constants
+
+# 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.
+#
+#   require "winproc"
+#
+#   Winproc::Job.new do |job|                 # kill_on_close: true (default)
+#     p = Winproc.spawn("ruby", "-e", "puts 6*7", stdout: :pipe, job: job)
+#     out = +""
+#     while (chunk = p.stdout.read) then out << chunk end
+#     p.wait        # => 0
+#     p.close
+#   end                                       # any stragglers die with the job
+module Winproc
+  # A Windows API failure carries the originating error code (GetLastError /
+  # the failing return), set on the exception in C.
+  class OSError
+    def code
+      @code
+    end
+  end
+
+  # The four privilege names winproc supports (process-wide, scoped by
+  # #with_privilege). The token must already HOLD the privilege.
+  PRIVILEGE_NAMES = {
+    debug:          "SeDebugPrivilege",
+    backup:         "SeBackupPrivilege",
+    restore:        "SeRestorePrivilege",
+    increase_quota: "SeIncreaseQuotaPrivilege"
+  }.freeze
+
+  module_function
+
+  # Run a blocking native call cooperatively. Under a Fiber scheduler (e.g.
+  # winloop) the call is offloaded to a worker Thread so the calling fiber parks
+  # (Thread#value routes through the scheduler's block/unblock hooks) and the
+  # event loop keeps serving other fibers; with no scheduler it runs inline (the
+  # C call already releases the GVL). On fiber unwind the worker is killed +
+  # joined so it can't leak or consume data destined for a later op.
+  #
+  # Caveat (same as winipc): a fiber unwound in the instant after the worker
+  # acquired a resource but before the value was delivered loses that
+  # acquisition — the inherent cancelled-read-already-pulled-bytes limitation.
+  def run_blocking
+    sched = Fiber.scheduler
+    return yield unless sched
+
+    worker = Thread.new do
+      Thread.current.report_on_exception = false
+      yield
+    end
+    begin
+      worker.value
+    ensure
+      if worker.alive?
+        worker.kill
+        worker.join
+      end
+    end
+  end
+
+  # Seconds -> milliseconds for the native waits. nil => -1 (INFINITE); a tiny
+  # positive value rounds up to 1 ms (never collapse a wait into a poll). A
+  # finite timeout always yields a finite, in-range ms: the result is clamped to
+  # the signed 64-bit ceiling the C waits accept (NUM2LL), so an absurdly large
+  # timeout becomes a very long finite wait (~292 million years) instead of a
+  # RangeError — never an INFINITE wait. Clamping here also means the in-flight
+  # guards in the C waits can never wedge on a conversion raise.
+  MS_MAX = 0x7FFF_FFFF_FFFF_FFFF # LLONG_MAX: the largest ms NUM2LL accepts
+
+  def ms_for(timeout)
+    return -1 if timeout.nil?
+
+    t = Float(timeout)
+    raise ArgumentError, "timeout must be non-negative, got #{timeout.inspect}" if t.negative?
+
+    ms = (t * 1000).round
+    return 1 if ms.zero? && t.positive?
+
+    ms > MS_MAX ? MS_MAX : ms
+  end
+
+  # Quote an argv Array into a single command line per the CommandLineToArgvW /
+  # CRT rules ("everyone quotes command line arguments the wrong way"). Pure,
+  # unit-tested. Raises ArgumentError on an empty argv or a NUL in any element.
+  #
+  # NOTE: these are the rules of the C runtime / CommandLineToArgvW parser.
+  # cmd.exe batch files and programs that parse their own command line
+  # differently (notably `cmd /c`) have their own metacharacter rules — winproc
+  # never invokes a shell and does not escape for cmd.exe.
+  def quote_argv(argv)
+    raise ArgumentError, "argv must not be empty" if argv.empty?
+
+    argv.map { |arg| quote_one(arg) }.join(" ")
+  end
+
+  def quote_one(arg)
+    s = String(arg)
+    raise ArgumentError, "argument contains a NUL byte: #{s.inspect}" if s.include?("\0")
+    return '""' if s.empty?
+    return s unless s.match?(/[ \t"]/)
+
+    out = +'"'
+    backslashes = 0
+    s.each_char do |ch|
+      case ch
+      when "\\"
+        backslashes += 1
+      when '"'
+        out << ("\\" * (backslashes * 2 + 1)) << '"'
+        backslashes = 0
+      else
+        out << ("\\" * backslashes) << ch
+        backslashes = 0
+      end
+    end
+    out << ("\\" * (backslashes * 2)) # trailing run, before the closing quote
+    out << '"'
+    out
+  end
+  private_class_method :quote_one
+
+  # Build the merged, sorted, NUL-joined environment block (a single UTF-8
+  # String with embedded NULs) from +env+ (Hash{String=>String|nil}) merged over
+  # the parent ENV case-insensitively, or nil to inherit unchanged.
+  def build_env_block(env)
+    return nil if env.nil?
+
+    merged = ENV.to_h
+    env.each do |key, value|
+      validate_env_key(key)
+      validate_env_value(value)
+      # delete any existing key that matches case-insensitively
+      merged.delete_if { |k, _| k.casecmp?(key) }
+      merged[key] = value unless value.nil?
+    end
+    # Sorted by upcased UTF-16 code-unit order (CreateProcessW requirement:
+    # "sorted alphabetically, case-insensitive, Unicode order, without regard to
+    # locale"). encode UTF-16LE to get code-unit ordering.
+    pairs = merged.sort_by { |k, _| k.upcase.encode("UTF-16LE") }
+    block = +""
+    pairs.each { |k, v| block << k << "=" << v << "\0" }
+    block
+  end
+  private_class_method :build_env_block
+
+  def validate_env_key(key)
+    raise TypeError, "env key must be a String, got #{key.class}" unless key.is_a?(String)
+    raise ArgumentError, "env key must not be empty" if key.empty?
+    raise ArgumentError, "env key must not contain '=': #{key.inspect}" if key.include?("=")
+    raise ArgumentError, "env key must not contain NUL: #{key.inspect}" if key.include?("\0")
+  end
+  private_class_method :validate_env_key
+
+  def validate_env_value(value)
+    return if value.nil?
+    raise TypeError, "env value must be a String or nil, got #{value.class}" unless value.is_a?(String)
+    raise ArgumentError, "env value must not contain NUL: #{value.inspect}" if value.include?("\0")
+  end
+  private_class_method :validate_env_value
+
+  # Encode a stdio kwarg into a [kind, io_or_std] pair for the C layer. +std+ is
+  # the GetStdHandle selector used when an INHERIT slot needs a parent std value.
+  def stdio_spec(value, allow_merge: false)
+    case value
+    when nil      then [SLOT_INHERIT, nil]
+    when :null    then [SLOT_NULL, nil]
+    when :pipe    then [SLOT_PIPE, nil]
+    when :stdout
+      raise ArgumentError, "stdio :stdout is only valid for stderr:" unless allow_merge
+
+      [SLOT_MERGE, nil]
+    when IO       then [SLOT_IO, value]
+    else
+      if value.respond_to?(:to_io)
+        [SLOT_IO, value.to_io]
+      else
+        raise ArgumentError, "stdio must be nil/:null/:pipe/an IO#{allow_merge ? '/:stdout' : ''}, " \
+                             "got #{value.inspect}"
+      end
+    end
+  end
+  private_class_method :stdio_spec
+
+  # Spawn a child process from an argv ARRAY (no shell is ever invoked). Returns
+  # a Winproc::Process; with a block, yields it and ensure-closes the handles
+  # (closing does NOT kill the child — use job: for guaranteed reaping).
+  def spawn(*argv, app: nil, cwd: nil, env: nil,
+            stdin: nil, stdout: nil, stderr: nil,
+            job: nil, new_process_group: false, no_window: false)
+    cmdline = quote_argv(argv)
+    envblock = build_env_block(env)
+    ik, iio = stdio_spec(stdin)
+    ok, oio = stdio_spec(stdout)
+    ek, eio = stdio_spec(stderr, allow_merge: true)
+
+    flags = 0
+    flags |= CREATE_NEW_PROCESS_GROUP if new_process_group
+    flags |= CREATE_NO_WINDOW if no_window
+
+    process = _spawn(app && String(app), cmdline, cwd && String(cwd), envblock,
+                     flags, job, 0, 0, ik, iio, ok, oio, ek, eio)
+    return process unless block_given?
+
+    begin
+      yield process
+    ensure
+      process.close
+    end
+  end
+
+  # Spawn a child attached to a ConPTY pseudoconsole. Returns a Winproc::PTY;
+  # with a block, yields it and ensure-closes (kill: true). stdio redirection
+  # kwargs are deliberately absent (ConPTY and pipe redirection are mutually
+  # exclusive).
+  def pty(*argv, cols: 80, rows: 24, app: nil, cwd: nil, env: nil, job: nil)
+    raise Unsupported, "winproc: ConPTY requires Windows 10 1809+" unless pty_available?
+
+    c = Integer(cols)
+    r = Integer(rows)
+    raise ArgumentError, "cols/rows must be 1..32767" unless (1..0x7FFF).cover?(c) && (1..0x7FFF).cover?(r)
+
+    cmdline = quote_argv(argv)
+    envblock = build_env_block(env)
+    pty = _spawn(app && String(app), cmdline, cwd && String(cwd), envblock,
+                 0, job, c, r,
+                 SLOT_INHERIT, nil, SLOT_INHERIT, nil, SLOT_INHERIT, nil)
+    return pty unless block_given?
+
+    begin
+      yield pty
+    ensure
+      pty.close(kill: true)
+    end
+  end
+
+  # Is ConPTY available on this OS? (GetProcAddress probe; never raises.)
+  def pty_available?
+    __pty_available
+  end
+
+  # Is the current process running with an elevated token? (TokenElevation)
+  def elevated?
+    __elevated
+  end
+
+  # Is the current USER an administrator, even if not currently elevated?
+  def admin?
+    __admin
+  end
+
+  # Relaunch/launch a program elevated via the shell "runas" verb (UAC prompt).
+  # +args+ is an argv-style Array quoted by winproc with the same quote_argv
+  # rules as spawn (a String raises TypeError). Returns a Winproc::Process when
+  # the shell reports a new process handle; nil when it launched without one.
+  def runas(exe, args = [], cwd: nil, show: :normal)
+    raise TypeError, "runas args must be an Array, got #{args.class}" unless args.is_a?(Array)
+
+    params = args.empty? ? nil : quote_argv(args)
+    sw = case show
+         when :normal    then SW_SHOWNORMAL
+         when :hide      then SW_HIDE
+         when :minimized then SW_SHOWMINIMIZED
+         when :maximized then SW_SHOWMAXIMIZED
+         else raise ArgumentError, "show must be :normal/:hide/:minimized/:maximized, got #{show.inspect}"
+         end
+    run_blocking { __runas(String(exe), params, cwd && String(cwd), sw) }
+  end
+
+  # Enable a process-token privilege for the duration of the block, restoring its
+  # previous state afterwards (even on raise). The token is PROCESS-wide.
+  def with_privilege(name)
+    se = PRIVILEGE_NAMES[name]
+    raise ArgumentError, "unknown privilege #{name.inspect}; one of #{PRIVILEGE_NAMES.keys.inspect}" unless se
+
+    was_enabled = __privilege(se, true) # raises PrivilegeNotHeld if not held
+    begin
+      yield
+    ensure
+      __privilege(se, was_enabled)
+    end
+  end
+
+  # ---------------------------------------------------------------- Process ---
+  class Process
+    # Block until the process exits; returns the exit code (Integer). +timeout+
+    # in seconds (nil = infinite); returns nil on timeout. Cooperative under a
+    # scheduler. Memoizes the exit code.
+    def wait(timeout: nil)
+      Winproc.run_blocking { _wait(Winproc.ms_for(timeout)) }
+    end
+
+    # Hard kill (TerminateProcess); does NOT touch children (use a Job for trees).
+    def kill(exit_code = 1)
+      _kill(exit_code)
+    end
+
+    # The writable/readable pipe ends, present only for :pipe stdio slots.
+    def stdin  = @stdin
+    def stdout = @stdout
+    def stderr = @stderr
+  end
+
+  # -------------------------------------------------------------------- Job ---
+  class Job
+    # Create an ANONYMOUS job object and apply limits. A private IOCP is created
+    # and associated with the job before any process can join, so #wait_empty
+    # can never miss messages.
+    def self.new(kill_on_close: true, memory: nil, process_memory: nil,
+                 cpu_percent: nil, active_processes: nil, cpu_time: nil)
+      mem  = memory && nonneg_int(memory, "memory")
+      pmem = process_memory && nonneg_int(process_memory, "process_memory")
+      act  = active_processes && positive_int(active_processes, "active_processes")
+      cpu  = cpu_percent && cpu_percent_int(cpu_percent)
+      time = cpu_time && cpu_time_ticks(cpu_time)
+
+      job = _create(kill_on_close, mem, pmem, cpu, act, time)
+      return job unless block_given?
+
+      begin
+        yield job
+      ensure
+        job.close
+      end
+    end
+
+    def self.nonneg_int(v, name)
+      i = Integer(v)
+      raise ArgumentError, "#{name} must be >= 0, got #{v.inspect}" if i.negative?
+
+      i
+    end
+    private_class_method :nonneg_int
+
+    def self.positive_int(v, name)
+      i = Integer(v)
+      raise ArgumentError, "#{name} must be >= 1, got #{v.inspect}" if i < 1
+
+      i
+    end
+    private_class_method :positive_int
+
+    def self.cpu_percent_int(v)
+      i = Integer(v)
+      raise ArgumentError, "cpu_percent must be 1..100, got #{v.inspect}" unless (1..100).cover?(i)
+
+      i
+    end
+    private_class_method :cpu_percent_int
+
+    # seconds (Float) -> user-mode CPU 100 ns ticks for PerJobUserTimeLimit.
+    def self.cpu_time_ticks(v)
+      t = Float(v)
+      raise ArgumentError, "cpu_time must be > 0 seconds, got #{v.inspect}" unless t.positive?
+
+      (t * 10_000_000).round
+    end
+    private_class_method :cpu_time_ticks
+
+    # AssignProcessToJobObject — the fallback path for a process NOT placed at
+    # creation. Prefer Winproc.spawn(job: job).
+    def assign(process)
+      _assign(process)
+    end
+
+    # TerminateJobObject: kill every process in the job (and nested child jobs).
+    def terminate(exit_code = 1)
+      _terminate(exit_code)
+    end
+
+    # Block until the job has zero active processes. true on empty, false on
+    # timeout. Only ONE wait_empty may be in flight per Job.
+    def wait_empty(timeout: nil)
+      Winproc.run_blocking { _wait_empty(Winproc.ms_for(timeout)) }
+    end
+  end
+
+  # ----------------------------------------------------------------- Stream ---
+  class Stream
+    # Up to +maxlen+ bytes as a binary (ASCII-8BIT) String; nil at EOF. Blocks
+    # until at least 1 byte. Cooperative under a scheduler.
+    def read(maxlen = 65_536)
+      Winproc.run_blocking { _read(maxlen) }
+    end
+
+    # Write ALL +bytes+ (loops on partial); returns the byte count. Binary-safe.
+    def write(bytes)
+      Winproc.run_blocking { _write(bytes) }
+    end
+
+    def <<(bytes)
+      write(bytes)
+      self
+    end
+  end
+
+  # -------------------------------------------------------------------- PTY ---
+  class PTY
+    # Raw bytes from the terminal output stream (UTF-8 text interleaved with VT
+    # escape sequences, verbatim). Binary (ASCII-8BIT) String; nil at EOF.
+    def read(maxlen = 65_536)
+      Winproc.run_blocking { @output._read(maxlen) }
+    end
+
+    # Bytes to the terminal input stream. Plain text = keystrokes; control keys
+    # are VT sequences. Send UTF-8. "\r" is Enter (not "\n").
+    def write(bytes)
+      Winproc.run_blocking { @input._write(bytes) }
+    end
+
+    # ResizePseudoConsole. 1..32767 each (COORD is SHORT).
+    def resize(cols, rows)
+      _resize(Integer(cols), Integer(rows))
+    end
+
+    # The child Process; use it for wait/kill/exitstatus.
+    def process = @process
+
+    # Deadlock-free teardown, exact order (§2.6):
+    #   1. kill: true and child alive -> process.kill
+    #   2. close the OUTPUT stream (cancels any in-flight read; the blocked
+    #      reader raises Closed) — makes step 4 safe on pre-24H2 Windows
+    #   3. close the INPUT stream
+    #   4. ClosePseudoConsole(hPC) (GVL released; output pipe gone, no deadlock)
+    #   5. memoize the child's exit code if exited, then process.close
+    # Idempotent. After close, pty.process.exitstatus still answers (memoized).
+    def close(kill: true)
+      return nil if closed?
+
+      begin
+        @process.kill if kill && process_alive_safely?
+      rescue Winproc::Error
+        # best-effort; teardown must proceed
+      end
+      @output.close
+      @input.close
+      Winproc.run_blocking { _close_pty }
+      @process.close
+      nil
+    end
+
+    def process_alive_safely?
+      @process.alive?
+    rescue Winproc::Closed
+      false
+    end
+    private :process_alive_safely?
+  end
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: winproc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ned
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: vcvars
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+description: |
+  winproc is a native extension for controlling Windows processes the way the
+  OS intends: argv-array spawning with exact quoting and per-handle inheritance
+  (PROC_THREAD_ATTRIBUTE_HANDLE_LIST), job objects with kill-on-close so a
+  spawned tree can never outlive you (even across a crash), atomic job
+  placement at creation, ConPTY pseudoconsoles for real interactive terminal
+  I/O, and elevation helpers (elevated?/admin?, ShellExecuteEx "runas",
+  scoped token privileges). Blocking waits release the GVL and cooperate with
+  a fiber scheduler. Windows MSVC (mswin) Ruby only.
+executables: []
+extensions:
+- ext/winproc/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/winproc/extconf.rb
+- ext/winproc/winproc.c
+- lib/winproc.rb
+- lib/winproc/version.rb
+homepage: https://github.com/main-path/winproc
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/main-path/winproc
+  source_code_uri: https://github.com/main-path/winproc
+  changelog_uri: https://github.com/main-path/winproc/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/main-path/winproc/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'Windows process control for Ruby: job-object process trees, ConPTY terminals,
+  hygienic spawning, and UAC elevation helpers.'
+test_files: []