winsvc 0.1.0

data/lib/winsvc.rb

@@ -0,0 +1,723 @@
+# frozen_string_literal: true
+
+require "winsvc/version"
+require "winsvc/winsvc" # native extension: module bridges + error classes
+require "rbconfig"
+
+# winsvc — host a Ruby process as a Windows service (SERVICE_WIN32_OWN_PROCESS)
+# with correct SCM integration, plus a minimal installer.
+#
+#   require "winsvc"   # require winsvc EARLY (30 s dispatcher window from start);
+#                      # heavy app requires belong INSIDE the block.
+#
+#   Winsvc.run("myapp", log: "C:/ProgramData/myapp/service.log") do |svc|
+#     require_relative "app"        # heavy boot AFTER START_PENDING is reported
+#     app = MyApp.new(svc.args)
+#     app.start
+#     svc.wait                      # parks; Ctrl-C in a console injects :stop
+#     app.stop
+#   end                            # block returned ⇒ STOPPED reported, run returns
+#
+# The same block runs unchanged as a console program (`ruby service.rb`): the
+# dispatcher fails with 1063 when not launched by the SCM, which winsvc detects
+# as console mode. No Ruby ever runs on an SCM thread; controls arrive on a
+# Thread::Queue, so the body cooperates with a Fiber scheduler (winloop) when one
+# is active and works standalone otherwise.
+module Winsvc
+  # ---- Win32 service-control codes (verified) ----------------------------
+  SERVICE_CONTROL_STOP          = 0x00000001
+  SERVICE_CONTROL_PAUSE         = 0x00000002
+  SERVICE_CONTROL_CONTINUE      = 0x00000003
+  SERVICE_CONTROL_SHUTDOWN      = 0x00000005
+  SERVICE_CONTROL_POWEREVENT    = 0x0000000D
+  SERVICE_CONTROL_SESSIONCHANGE = 0x0000000E
+  SERVICE_CONTROL_PRESHUTDOWN   = 0x0000000F
+
+  # ---- Win32 accept-mask bits (verified) ---------------------------------
+  SERVICE_ACCEPT_STOP           = 0x00000001
+  SERVICE_ACCEPT_PAUSE_CONTINUE = 0x00000002
+  SERVICE_ACCEPT_SHUTDOWN       = 0x00000004
+  SERVICE_ACCEPT_POWEREVENT     = 0x00000040
+  SERVICE_ACCEPT_SESSIONCHANGE  = 0x00000080
+  SERVICE_ACCEPT_PRESHUTDOWN    = 0x00000100
+
+  # ---- Win32 service states (verified) -----------------------------------
+  SERVICE_STOPPED          = 0x00000001
+  SERVICE_START_PENDING    = 0x00000002
+  SERVICE_STOP_PENDING     = 0x00000003
+  SERVICE_RUNNING          = 0x00000004
+  SERVICE_CONTINUE_PENDING = 0x00000005
+  SERVICE_PAUSE_PENDING    = 0x00000006
+  SERVICE_PAUSED           = 0x00000007
+
+  # ---- Win32 start types (verified) --------------------------------------
+  SERVICE_AUTO_START   = 0x00000002
+  SERVICE_DEMAND_START = 0x00000003
+
+  # ---- Win32 event-type values (verified) --------------------------------
+  PBT_APMSUSPEND           = 0x0004
+  PBT_APMRESUMESUSPEND     = 0x0007
+  PBT_APMPOWERSTATUSCHANGE = 0x000A
+  PBT_APMRESUMEAUTOMATIC   = 0x0012
+  PBT_POWERSETTINGCHANGE   = 0x8013
+
+  WTS_CONSOLE_CONNECT        = 1
+  WTS_CONSOLE_DISCONNECT     = 2
+  WTS_REMOTE_CONNECT         = 3
+  WTS_REMOTE_DISCONNECT      = 4
+  WTS_SESSION_LOGON          = 5
+  WTS_SESSION_LOGOFF         = 6
+  WTS_SESSION_LOCK           = 7
+  WTS_SESSION_UNLOCK         = 8
+  WTS_SESSION_REMOTE_CONTROL = 9
+  WTS_SESSION_CREATE         = 0xA
+  WTS_SESSION_TERMINATE      = 0xB
+
+  # Map accept: symbols -> the accept-mask bit.
+  ACCEPT_BITS = {
+    stop:           SERVICE_ACCEPT_STOP,
+    shutdown:       SERVICE_ACCEPT_SHUTDOWN,
+    preshutdown:    SERVICE_ACCEPT_PRESHUTDOWN,
+    pause_continue: SERVICE_ACCEPT_PAUSE_CONTINUE,
+    power:          SERVICE_ACCEPT_POWEREVENT,
+    session_change: SERVICE_ACCEPT_SESSIONCHANGE
+  }.freeze
+
+  # Map a SERVICE_CONTROL_* code -> the Control#control symbol.
+  CONTROL_SYMBOLS = {
+    SERVICE_CONTROL_STOP          => :stop,
+    SERVICE_CONTROL_SHUTDOWN      => :shutdown,
+    SERVICE_CONTROL_PRESHUTDOWN   => :preshutdown,
+    SERVICE_CONTROL_PAUSE         => :pause,
+    SERVICE_CONTROL_CONTINUE      => :continue,
+    SERVICE_CONTROL_POWEREVENT    => :power,
+    SERVICE_CONTROL_SESSIONCHANGE => :session_change
+  }.freeze
+
+  STOP_CLASS = %i[stop shutdown preshutdown].freeze
+
+  # A Windows API failure carries the originating error code (GetLastError),
+  # set on the exception in C.
+  class OSError
+    def code
+      @code
+    end
+  end
+
+  # A control message delivered to the service body. Every instance is frozen.
+  #
+  #   control      :stop :shutdown :preshutdown :pause :continue :power :session_change
+  #   event_type   Integer|nil — PBT_* (:power), WTS_* (:session_change)
+  #   session_id   Integer|nil — WTSSESSION_NOTIFICATION.dwSessionId (:session_change)
+  #   data         String|nil  — frozen ASCII-8BIT POWERBROADCAST_SETTING bytes
+  #                              (≤ 512, truncated beyond) for PBT_POWERSETTINGCHANGE
+  #   time         Float       — Process::CLOCK_MONOTONIC seconds at delivery
+  Control = Struct.new(:control, :event_type, :session_id, :data, :time,
+                       keyword_init: true) do
+    # Every instance is frozen at construction (§2.4).
+    def initialize(*)
+      super
+      freeze
+    end
+
+    # True for the stop-class controls (:stop, :shutdown, :preshutdown).
+    def stop?
+      STOP_CLASS.include?(control)
+    end
+
+    # Build a frozen Control from one raw C record [code, etype, sid, data, tick].
+    def self.from_raw(raw)
+      code, etype, sid, data, _tick = raw
+      sym = CONTROL_SYMBOLS[code] || :unknown
+      event_type = sym == :power || sym == :session_change ? etype : nil
+      session_id = sym == :session_change ? sid : nil
+      new(control: sym,
+          event_type: event_type,
+          session_id: session_id,
+          data: data, # already frozen ASCII-8BIT or nil
+          time: Process.clock_gettime(Process::CLOCK_MONOTONIC))
+    end
+  end
+
+  # The object yielded to the Winsvc.run block. A plain Ruby object holding no
+  # native pointer; all methods are safe from any thread or fiber.
+  class Service
+    # +name+ frozen UTF-8; +mode+ :service or :console; +queue+ the control queue.
+    def initialize(name, mode, queue)
+      @name  = name
+      @mode  = mode
+      @queue = queue
+      @args  = nil
+    end
+
+    # The name passed to run (frozen UTF-8).
+    def name
+      @name
+    end
+
+    def service?
+      @mode == :service
+    end
+
+    def console?
+      @mode == :console
+    end
+
+    # In service mode, the ServiceMain start parameters minus argv[0] (which
+    # Windows sets to the service name). In console mode, a frozen copy of ARGV.
+    # Frozen array of frozen UTF-8 strings; computed once, memoized.
+    def args
+      @args ||=
+        if service?
+          raw = Winsvc.send(:_host_args)
+          raw.shift # drop argv[0] (the service name)
+          raw.map(&:freeze).freeze
+        else
+          ARGV.map { |a| a.dup.freeze }.freeze
+        end
+    end
+
+    # Pop the next control from the queue. +timeout+ in seconds (nil = block
+    # forever). Returns nil on timeout, and nil immediately once run has torn
+    # down (the queue is closed). Under a Fiber scheduler the calling fiber
+    # parks; without one it blocks the thread (GVL released by MRI).
+    def wait(timeout: nil)
+      ms = Winsvc.send(:secs_to_timeout, timeout)
+      if ms.nil?
+        @queue.pop # block forever (returns nil when the queue is closed)
+      else
+        @queue.pop(timeout: ms)
+      end
+    rescue ClosedQueueError
+      nil
+    end
+
+    # Non-blocking. True from the instant the C handler saw STOP/SHUTDOWN/
+    # PRESHUTDOWN (interlocked flag — earlier than queue delivery), or after the
+    # first console Ctrl-C.
+    def stop_requested?
+      Winsvc.send(:_stop_requested)
+    end
+
+    # wait in a loop, yielding every control INCLUDING the final stop-class one,
+    # then return it. Raises ArgumentError without a block.
+    def each_control
+      raise ArgumentError, "winsvc: each_control requires a block" unless block_given?
+
+      loop do
+        c = wait
+        break c if c.nil?
+
+        yield c
+        break c if c.stop?
+      end
+    end
+
+    # Report SERVICE_RUNNING with the configured accept mask. Used to leave
+    # START_PENDING (manual_ready: true) and to resume after :continue.
+    def running!
+      Winsvc.send(:_set_running) if service?
+      self
+    end
+    alias ready! running!
+
+    # Report SERVICE_PAUSED (accept mask kept). Call after handling :pause.
+    def paused!
+      Winsvc.send(:_set_paused) if service?
+      self
+    end
+
+    # Re-report the current pending state with dwCheckPoint + 1. +wait_hint+ (ms)
+    # overrides the hint for this report. No-op when no transition is pending.
+    # Call only on real progress. Raises ArgumentError on a non-positive hint.
+    def checkpoint!(wait_hint: nil)
+      hint =
+        if wait_hint.nil?
+          -1
+        else
+          unless wait_hint.is_a?(Integer) && wait_hint > 0
+            raise ArgumentError, "winsvc: wait_hint must be a positive Integer, got #{wait_hint.inspect}"
+          end
+
+          wait_hint
+        end
+      Winsvc.send(:_checkpoint, hint) if service?
+      self
+    end
+  end
+
+  module_function
+
+  # Validate a service name: String, 1..256 chars, no "/" or "\". Raises
+  # ArgumentError otherwise. Returns the frozen name. (Exposed for unit tests.)
+  def validate_name!(name)
+    raise ArgumentError, "winsvc: name must be a String, got #{name.class}" unless name.is_a?(String)
+
+    n = name.length
+    if n < 1 || n > 256
+      raise ArgumentError, "winsvc: name must be 1..256 chars, got #{n}"
+    end
+    if name.include?("/") || name.include?("\\")
+      raise ArgumentError, "winsvc: name must not contain '/' or '\\' (got #{name.inspect})"
+    end
+
+    name
+  end
+
+  # Compose the accept mask from accept: symbols. Must include :stop. Unknown
+  # symbols raise ArgumentError naming the offender and the valid set.
+  def accept_mask!(accept)
+    unless accept.is_a?(Array)
+      raise ArgumentError, "winsvc: accept: must be an Array of Symbols, got #{accept.class}"
+    end
+
+    mask = 0
+    accept.each do |sym|
+      bit = ACCEPT_BITS[sym]
+      unless bit
+        raise ArgumentError,
+              "winsvc: unknown accept symbol #{sym.inspect}; valid: #{ACCEPT_BITS.keys.inspect}"
+      end
+
+      mask |= bit
+    end
+    unless accept.include?(:stop)
+      raise ArgumentError, "winsvc: accept: must include :stop (an unstoppable service is a footgun)"
+    end
+
+    mask
+  end
+  private_class_method :accept_mask!
+
+  def positive_hint!(value, label)
+    unless value.is_a?(Integer) && value > 0
+      raise ArgumentError, "winsvc: #{label} must be a positive Integer (ms), got #{value.inspect}"
+    end
+
+    value
+  end
+  private_class_method :positive_hint!
+
+  # seconds -> ms Integer for Thread::Queue#pop(timeout:). nil -> nil (block
+  # forever). Negative raises; a tiny-but-positive timeout never collapses to a
+  # non-blocking poll (the winipc ms_for discipline, in seconds for Queue#pop).
+  def secs_to_timeout(timeout)
+    return nil if timeout.nil?
+
+    t = Float(timeout)
+    raise ArgumentError, "winsvc: timeout must be non-negative, got #{timeout.inspect}" if t.negative?
+
+    # Queue#pop(timeout:) takes seconds; keep a floor so a tiny positive value
+    # still blocks rather than polling.
+    t.zero? ? 0.0 : [t, 0.001].max
+  end
+  private_class_method :secs_to_timeout
+
+  @ran = false
+
+  # Run your Ruby program as a Windows service. See the module docs and README
+  # for the full contract. Returns the block's value (re-raises a block
+  # exception after reporting STOPPED).
+  def run(name,
+          accept: %i[stop shutdown],
+          start_wait_hint: 30_000,
+          stop_wait_hint: 30_000,
+          manual_ready: false,
+          log: nil)
+    validate_name!(name)
+    mask = accept_mask!(accept)
+    positive_hint!(start_wait_hint, "start_wait_hint")
+    positive_hint!(stop_wait_hint, "stop_wait_hint")
+    validate_log!(log)
+    raise ArgumentError, "winsvc: Winsvc.run requires a block" unless block_given?
+
+    # Callable once per process (Win32: one StartServiceCtrlDispatcherW per
+    # process). A second call raises StateError, forever.
+    if @ran
+      raise StateError, "winsvc: Winsvc.run may be called only once per process"
+    end
+
+    @ran = true
+    frozen_name = name.dup.freeze
+
+    _host_start(frozen_name, mask, start_wait_hint, stop_wait_hint)
+
+    # EVERYTHING after a successful _host_start runs inside one begin/ensure so
+    # ServiceMain can never park on hRubyDone forever.
+    pump = nil
+    queue = nil
+    saved_int = saved_break = nil
+    exit_specific = 0
+    mode = nil
+
+    begin
+      mode = _host_wait_mode # :service or :console (raises OSError on dispatch fail)
+
+      redirect_stdio(log) if mode == :service
+
+      queue = Thread::Queue.new
+      svc = Service.new(frozen_name, mode, queue)
+
+      pump = start_pump(queue)
+
+      if mode == :console
+        saved_int, saved_break = install_console_traps(queue)
+      end
+
+      _set_running unless manual_ready || mode == :console
+
+      begin
+        return yield svc
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        # Service mode: write the diagnostic to the redirected stderr and FLUSH
+        # it BEFORE STOPPED is reported (post-STOPPED Ruby is best-effort).
+        if mode == :service
+          begin
+            $stderr.puts(e.full_message(highlight: false))
+            $stderr.flush
+          rescue StandardError
+            # diagnostics are best-effort; never mask the original exception
+          end
+          exit_specific = 1
+        end
+        raise
+      end
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      # Any failure between a successful _host_start and the block's return — a
+      # log: open error, an interrupt during mode-wait — reports STOPPED with
+      # 1066/specific 1 (service mode), then propagates.
+      exit_specific = 1 if mode == :service && exit_specific.zero?
+      raise
+    ensure
+      restore_console_traps(saved_int, saved_break) if saved_int || saved_break
+      if queue
+        queue.close
+      end
+      if pump
+        pump.kill
+        pump.join
+      end
+      _host_done(exit_specific)
+    end
+  end
+
+  # Validate the log: kwarg (service mode only; ignored in console mode).
+  def validate_log!(log)
+    return if log.nil? || log.is_a?(String) || log.is_a?(IO)
+
+    raise ArgumentError, "winsvc: log: must be nil, a path String, or an IO, got #{log.class}"
+  end
+  private_class_method :validate_log!
+
+  # Redirect stdio for service mode (SCM-launched processes have invalid std
+  # handles). nil ⇒ all → NUL; String ⇒ stdout/stderr append to the file;
+  # IO ⇒ stdout/stderr → that IO. STDIN always → NUL.
+  def redirect_stdio(log)
+    $stdin.reopen(IO::NULL, "r")
+    case log
+    when nil
+      $stdout.reopen(IO::NULL, "w")
+      $stderr.reopen(IO::NULL, "w")
+    when String
+      f = File.open(log, "a") # raises before the block runs on a bad path
+      $stdout.reopen(f)
+      $stderr.reopen(f)
+      $stdout.sync = true
+      $stderr.sync = true
+    when IO
+      $stdout.reopen(log)
+      $stderr.reopen(log)
+      $stdout.sync = true
+      $stderr.sync = true
+    end
+  end
+  private_class_method :redirect_stdio
+
+  # The pump Thread: drain raw control records from C into the Queue as frozen
+  # Controls. An ordinary Ruby Thread (so pushing to the Queue is legal); the
+  # SCM threads never touch Ruby.
+  def start_pump(queue)
+    Thread.new do
+      Thread.current.report_on_exception = false
+      loop do
+        recs = _wait_control(-1)
+        next if recs.nil?
+
+        recs.each { |r| queue.push(Control.from_raw(r)) }
+      end
+    rescue ClosedQueueError
+      # queue closed during teardown — done
+    end
+  end
+  private_class_method :start_pump
+
+  # Console mode: first Ctrl-C/Ctrl-Break injects a synthetic :stop into the
+  # same queue (the pywin32 debug-mode pattern), then rebinds both signals to
+  # DEFAULT so a second Ctrl-C terminates the process. Returns the previous
+  # [INT, BREAK] handlers to restore on return.
+  def install_console_traps(_queue)
+    rebind = lambda do
+      Signal.trap("INT", "DEFAULT")
+      begin
+        Signal.trap("BREAK", "DEFAULT")
+      rescue ArgumentError
+        # BREAK may be unavailable in some contexts; ignore
+      end
+    end
+    handler = lambda do |_sig|
+      _inject(SERVICE_CONTROL_STOP, nil, nil, nil)
+      rebind.call
+    end
+    saved_int = Signal.trap("INT", handler)
+    saved_break =
+      begin
+        Signal.trap("BREAK", handler)
+      rescue ArgumentError
+        nil
+      end
+    [saved_int, saved_break]
+  end
+  private_class_method :install_console_traps
+
+  def restore_console_traps(saved_int, saved_break)
+    Signal.trap("INT", saved_int) if saved_int
+    begin
+      Signal.trap("BREAK", saved_break) if saved_break
+    rescue ArgumentError
+      # ignore
+    end
+  end
+  private_class_method :restore_console_traps
+
+  # ---------------------------------------------------------------- install --
+
+  # Install the service. REQUIRED kwarg: script: (path to the entry .rb).
+  # Requires elevation. Returns true. See README for the full contract.
+  def install(name,
+              script:,
+              display_name: name,
+              description: nil,
+              args: [],
+              start: :demand,
+              account: nil,
+              password: nil,
+              ruby: RbConfig.ruby,
+              preshutdown_timeout: nil,
+              restart_on_failure: nil)
+    validate_name!(name)
+    raise ArgumentError, "winsvc: display_name must be a String" unless display_name.is_a?(String)
+    unless description.nil? || description.is_a?(String)
+      raise ArgumentError, "winsvc: description must be a String or nil"
+    end
+
+    binpath = compose_binpath(ruby, script, args)
+    start_type, delayed = start_flags(start)
+
+    if password && account.nil?
+      raise ArgumentError, "winsvc: password: requires account:"
+    end
+
+    pre_ms = validate_preshutdown(preshutdown_timeout)
+    restart, rdelay, reset, noncrash = restart_actions(restart_on_failure)
+
+    _install(name, display_name, binpath, description, account, password,
+             start_type, delayed, pre_ms,
+             restart, rdelay, reset, noncrash)
+    true
+  end
+
+  # Stop (bounded) then delete the service. Returns true. Requires elevation.
+  def uninstall(name, timeout: 30)
+    validate_name!(name)
+    t = Float(timeout)
+    raise ArgumentError, "winsvc: timeout must be non-negative, got #{timeout.inspect}" if t.negative?
+
+    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + t
+
+    # Stop the service first (a delete of a running service would mark-for-delete
+    # and zombify). 1062 ERROR_SERVICE_NOT_ACTIVE (already stopped — proceed) and
+    # 1061 ERROR_SERVICE_CANNOT_ACCEPT_CTRL (START_PENDING/STOP_PENDING — keep
+    # polling and re-send) are retriable, not errors. Polls every 250 ms with a
+    # plain Ruby sleep, so it stays interruptible and scheduler-friendly.
+    unless _service_state(name) == SERVICE_STOPPED # raises NotFound if absent
+      until current_state_or_stopped(name) == SERVICE_STOPPED
+        case _control_stop(name)
+        when :stopped
+          break # 1062 — it stopped under us
+        # :sent / :retry — keep polling within the budget
+        end
+
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          raise TimeoutError,
+                "winsvc: service '#{name}' did not stop within #{timeout}s (not deleted)"
+        end
+
+        sleep 0.25 # interruptible + scheduler-friendly for free
+      end
+    end
+
+    _delete_service(name)
+    true
+  end
+
+  # Current state of +name+, or SERVICE_STOPPED if it has already disappeared.
+  def current_state_or_stopped(name)
+    _service_state(name)
+  rescue NotFound
+    SERVICE_STOPPED
+  end
+  private_class_method :current_state_or_stopped
+
+  # Return the equivalent, correctly quoted sc.exe incantation(s), one command
+  # per line. Pure function: touches no OS API, needs no elevation. Same
+  # validation and binPath composer as install, so the two can never drift.
+  def install_command(name,
+                      script:,
+                      display_name: name,
+                      description: nil,
+                      args: [],
+                      start: :demand,
+                      account: nil,
+                      password: nil,
+                      ruby: RbConfig.ruby,
+                      preshutdown_timeout: nil,
+                      restart_on_failure: nil)
+    validate_name!(name)
+    binpath = compose_binpath(ruby, script, args)
+    start_type, delayed = start_flags(start)
+    pre_ms = validate_preshutdown(preshutdown_timeout)
+    restart, rdelay, reset, _noncrash = restart_actions(restart_on_failure)
+
+    # The service name must be quoted exactly like every other value: a valid
+    # Windows name may contain spaces (or, if the caller's validate_name! is ever
+    # loosened, other metacharacters), and a bare interpolation would let sc.exe
+    # mis-parse `my svc` as name `my` + stray token `svc`, or let `foo & calc`
+    # inject a shell command. sc_quote keeps whitespace-free names bare, so the
+    # common case is unchanged while the install/install_command pair stay aligned.
+    qname = sc_quote(name)
+
+    lines = []
+    create = +"sc create #{qname} binpath= #{sc_quote(binpath)}"
+    # sc create takes start= demand|auto; delayed-auto is set by a follow-up
+    # `sc config` line (the standard sc.exe idiom), so the create line uses auto.
+    create << " start= #{sc_start_word(start_type)}"
+    create << " obj= #{sc_quote(account)}" if account
+    create << " password= #{sc_quote(password)}" if password
+    create << " displayname= #{sc_quote(display_name)}" if display_name != name
+    lines << create
+
+    lines << "sc config #{qname} start= delayed-auto" if delayed && start_type == SERVICE_AUTO_START
+    lines << "sc description #{qname} #{sc_quote(description)}" if description
+    lines << "sc preshutdown #{qname} #{pre_ms}" if pre_ms
+    if restart
+      actions = "restart/#{rdelay}/restart/#{rdelay}/restart/#{rdelay}"
+      lines << "sc failure #{qname} reset= #{reset} actions= #{actions}"
+    end
+    lines.join("\n")
+  end
+
+  # ----------------------------------------------------- shared helpers ------
+
+  # Compose lpBinaryPathName: "<ruby>" "<script>" <quoted args...>. The ruby and
+  # script elements are ALWAYS double-quoted (the interpreter + entry script are
+  # the canonical quoted pair); extra args are double-quoted iff they contain
+  # whitespace. Embedded double quotes anywhere in ruby/script/args raise
+  # ArgumentError (refuse rather than mis-escape — the hard-to-misuse choice).
+  # Shared by install and install_command so they can never drift.
+  def compose_binpath(ruby, script, args)
+    raise ArgumentError, "winsvc: script: is required" if script.nil?
+
+    ruby_s   = ruby.to_s
+    script_s = File.expand_path(script.to_s)
+    arg_strs = Array(args).map(&:to_s)
+    [ruby_s, script_s, *arg_strs].each do |p|
+      if p.include?('"')
+        raise ArgumentError, "winsvc: embedded double quote in #{p.inspect} (refusing to mis-escape)"
+      end
+    end
+    quoted = [%("#{ruby_s}"), %("#{script_s}")] + arg_strs.map { |a| quote_if_space(a) }
+    quoted.join(" ")
+  end
+  private_class_method :compose_binpath
+
+  def quote_if_space(s)
+    s =~ /\s/ ? %("#{s}") : s
+  end
+  private_class_method :quote_if_space
+
+  # sc.exe value quoting: the binPath needs nested escaped quotes, and any value
+  # with whitespace or inner quotes is wrapped + its quotes doubled-as-escaped.
+  def sc_quote(value)
+    s = value.to_s
+    if s.include?('"') || s =~ /\s/
+      %("#{s.gsub('"', '\\"')}")
+    else
+      s
+    end
+  end
+  private_class_method :sc_quote
+
+  def sc_start_word(start_type)
+    start_type == SERVICE_AUTO_START ? "auto" : "demand"
+  end
+  private_class_method :sc_start_word
+
+  # :demand | :auto | :delayed_auto -> [start_type, delayed_flag].
+  def start_flags(start)
+    case start
+    when :demand       then [SERVICE_DEMAND_START, false]
+    when :auto         then [SERVICE_AUTO_START, false]
+    when :delayed_auto then [SERVICE_AUTO_START, true]
+    else
+      raise ArgumentError, "winsvc: start: must be :demand, :auto, or :delayed_auto, got #{start.inspect}"
+    end
+  end
+  private_class_method :start_flags
+
+  def validate_preshutdown(value)
+    return nil if value.nil?
+
+    unless value.is_a?(Integer) && value > 0
+      raise ArgumentError, "winsvc: preshutdown_timeout must be a positive Integer (ms), got #{value.inspect}"
+    end
+
+    value
+  end
+  private_class_method :validate_preshutdown
+
+  # restart_on_failure: nil | true | { delay:, reset:, on_non_crash: } ->
+  # [restart?, delay_ms, reset_secs, on_non_crash?].
+  def restart_actions(spec)
+    case spec
+    when nil
+      [false, nil, nil, false]
+    when true
+      [true, 5_000, 86_400, true]
+    when Hash
+      allowed = %i[delay reset on_non_crash]
+      unknown = spec.keys - allowed
+      raise ArgumentError, "winsvc: restart_on_failure: unknown keys #{unknown.inspect}" unless unknown.empty?
+
+      delay = spec.fetch(:delay, 5_000)
+      reset = spec.fetch(:reset, 86_400)
+      noncrash = spec.fetch(:on_non_crash, true)
+      unless delay.is_a?(Integer) && delay >= 0
+        raise ArgumentError, "winsvc: restart_on_failure delay: must be a non-negative Integer (ms), got #{delay.inspect}"
+      end
+      unless reset.is_a?(Integer) && reset >= 0
+        raise ArgumentError, "winsvc: restart_on_failure reset: must be a non-negative Integer (s), got #{reset.inspect}"
+      end
+
+      [true, delay, reset, noncrash ? true : false]
+    else
+      raise ArgumentError, "winsvc: restart_on_failure must be nil, true, or a Hash, got #{spec.class}"
+    end
+  end
+  private_class_method :restart_actions
+
+  # Hide the C bridges so callers can't skip the validation layer.
+  private_class_method :_host_start, :_host_wait_mode, :_host_args, :_wait_control,
+                       :_inject, :_set_running, :_set_paused, :_checkpoint,
+                       :_stop_requested, :_dropped_count, :_host_done,
+                       :_install, :_service_state, :_control_stop, :_delete_service
+end