exsys 0.5 → 1.0

data/test/support/fake_hub.rb

@@ -0,0 +1,165 @@
+# A model of the ExSYS managed hub's serial protocol, faithful enough
+# to drive ExSYS::ManagedUSB end to end without hardware.
+#
+# The wire encoding here is written out independently of the library's
+# own pack/unpack, so that a disagreement between the two shows up as a
+# test failure rather than both sharing the same mistake.
+class FakeHub
+    DEFAULT_PASSWORD = 'pass'.ljust(8)
+
+    attr_reader   :log, :opens, :locks, :line, :speed, :mode, :lock_path
+    attr_accessor :password, :silent, :lockable, :garbage, :lock_error,
+                  :ident
+
+    # @param state    [Integer] initial port bitmap
+    # @param path     [String]  file backing the state, so that separate
+    #                            processes share one hub
+    # @param lock     [String]  file used for a real flock, so that the
+    #                            locking is genuinely exercised
+    # @param delay    [Float]   pause inside a write, widening the
+    #                            window a concurrent process could slip
+    #                            into
+    # @param ports [Integer] how many ports this hub has
+    # @param width [Integer] hex digits in its state word.  Real hubs
+    #                         answer wider than their port count: a
+    #                         16-port unit answers eight, and the ports
+    #                         it does not have read as 1.
+    def initialize(password: DEFAULT_PASSWORD, state: 0x0000,
+                   ports: 16, width: 8,
+                   path: nil, lock: nil, delay: 0)
+        @password = password
+        @state    = state
+        @flash    = state
+        @path     = path
+        @lock_path = lock
+        @delay    = delay
+        @log      = []
+        @opens    = 0
+        @locks    = 0
+        @silent   = false     # hub answers nothing at all
+        @lockable = true      # platform allows locking the line
+        @garbage  = nil       # hub answers this instead, when set
+        @lock_error = nil     # raised by flock; for the propagation test
+        @ports    = ports
+        @width    = width
+        @ident    = format('CENTOS0005%02dv02', ports)  # nil = refuse ?Q
+
+        # Attach to the hub the file already describes, so that a test
+        # can inspect what its subprocesses did; seed it otherwise.
+        if @path && File.exist?(@path) then load
+        else                                save
+        end
+    end
+
+    # Build from the environment, for the executable's subprocesses.
+    def self.from_env(env = ENV)
+        new(path:     env['EXSYS_TEST_HUB'],
+            lock:     env['EXSYS_TEST_LOCK'],
+            delay:    env['EXSYS_TEST_DELAY'].to_f).tap do |hub|
+            hub.silent   = !env['EXSYS_TEST_SILENT'].nil?
+            hub.lockable =  env['EXSYS_TEST_NOLOCK'].nil?
+            hub.garbage  =  env['EXSYS_TEST_GARBAGE']
+        end
+    end
+
+    def state = (load; @state)
+    def flash = (load; @flash)
+
+    # Ports currently powered, as a sorted list -- the oracle the tests
+    # compare against.
+    def ports_on
+        1.upto(@ports).select {|p| state & (1 << (p-1)) != 0 }
+    end
+
+    # The power-on state the hub would come back to.
+    def flash_ports
+        1.upto(@ports).select {|p| flash & (1 << (p-1)) != 0 }
+    end
+
+    # Bits for ports this hub does not have.  A real one reports them
+    # set, which is why a client must write back what it read.
+    def absent = ((1 << (@width * 4)) - 1) & ~real
+
+    def real = (1 << @ports) - 1
+
+    # Record how the line was opened, so a test can check the library
+    # asks for the device and the speed the hub actually needs.
+    def opened(line, speed, mode)
+        @line, @speed, @mode = line, speed, mode
+        @opens += 1
+    end
+
+    # Called by each opened line before it locks.  The lock handle
+    # itself belongs to the line, not to the hub, so that two threads
+    # hold two of them and genuinely contend.
+    def lock_attempted
+        raise @lock_error            if @lock_error   # must NOT be swallowed
+        raise Errno::ENOTSUP         unless @lockable # platform refusal
+        @locks += 1
+    end
+
+    # Answer one command, as the hub would.
+    def command(cmd)
+        @log << cmd
+        return ''       if @silent
+        return @garbage if @garbage
+
+        load
+        reply = dispatch(cmd)
+        save
+        reply
+    end
+
+    private
+
+    def dispatch(cmd)
+        code = cmd[0, 2]
+        args = cmd[2..].to_s
+
+        # GP and ?Q are the two commands the hub answers without a
+        # password, both with a bare payload rather than a G/E status.
+        return encode(@state | absent)  if code == 'GP'
+        return @ident || 'E01'         if code == '?Q'
+
+        return 'E01' unless args.start_with?(@password)
+        rest = args[@password.size..]
+
+        sleep @delay if @delay.positive?
+
+        case code
+        when 'SP' then @state = decode(rest) & real      ; 'G'
+        when 'FP' then @state = @flash = decode(rest) & real ; 'G'
+        when 'WP' then @flash = @state                   ; 'G'
+        when 'RD' then @state = @flash = 0
+                       @password = DEFAULT_PASSWORD            ; 'G'
+        when 'RH' then @state = @flash                   ; nil
+        when 'CP' then @password = rest                  ; 'G'
+        else           'E02'
+        end
+    end
+
+    # Little-endian, any width, spelled out rather than packed.  Upper
+    # case because that is what a real hub answers -- observed on an
+    # ExSYS 16-port unit, which replies to GP with "C4FFFFFF".
+    def encode(v)
+        (@width / 2).times.map {|i| format('%02X', (v >> (8 * i)) & 0xff) }
+                    .join
+    end
+
+    def decode(str)
+        str.scan(/\h\h/).each_with_index
+           .sum {|byte, i| byte.to_i(16) << (8 * i) }
+    end
+
+    def load
+        return if @path.nil? || !File.exist?(@path)
+        @state, @flash, @password = File.read(@path).split("\n", 3)
+        @state = @state.to_i(16)
+        @flash = @flash.to_i(16)
+    end
+
+    def save
+        return if @path.nil?
+        File.write(@path, "%04x\n%04x\n%s" % [ @state, @flash, @password ])
+    end
+end

data/test/support/uart.rb

@@ -0,0 +1,57 @@
+# Test double for the `uart` gem.
+#
+# test/helper.rb puts this directory on the load path ahead of the real
+# gem, so `require "uart"` inside ExSYS::ManagedUSB picks this up and
+# the suite runs against FakeHub.  That is what lets the tests run with
+# no hub attached and with neither the uart nor the termios gem
+# installed.
+require_relative 'fake_hub'
+
+module UART
+    class << self
+        attr_writer :hub
+
+        # In-process tests set the hub directly; the subprocesses the
+        # executable's tests spawn build theirs from the environment.
+        def hub = @hub ||= FakeHub.from_env
+
+        def reset! = @hub = nil
+    end
+
+    # Stands in for the File that UART.open normally yields.  Each one
+    # carries its own lock handle, as a real open would, so that two of
+    # them contend instead of sharing one.
+    class Serial
+        def initialize(hub)
+            @hub  = hub
+            @lock = hub.lock_path &&
+                    File.open(hub.lock_path, File::RDWR|File::CREAT, 0o600)
+        end
+
+        def flock(mode)
+            @hub.lock_attempted
+            @lock ? @lock.flock(mode) : 0
+        end
+
+        def write(cmd) = @reply = @hub.command(cmd.chomp("\r"))
+
+        # A real hub ends every reply CR LF -- seen in the hex off the
+        # wire -- so a read to the terminator takes the whole line.
+        def gets(_sep = "\n")
+            @reply.nil? ? nil : "#{@reply}\r\n"
+        end
+        def close      = @lock&.close
+    end
+
+    def self.open(line, speed = 9600, mode = '8N1')
+        hub.opened(line, speed, mode)
+        serial = Serial.new(hub)
+        return serial unless block_given?
+
+        begin
+            yield serial
+        ensure
+            serial.close
+        end
+    end
+end

data/test/test_exsys_usb.rb

@@ -0,0 +1,325 @@
+require_relative 'helper'
+
+# Behaviour of the bin/exsys-usb executable, run as a subprocess so
+# that its exit status -- what a calling script actually reads -- is
+# part of what is asserted.
+class TestExsysUsb < Minitest::Test
+    include CLI
+
+    ## Switching #########################################################
+
+    def test_on_and_off_reach_the_hub
+        _, _, st = exsys_usb('on', '1', '2')
+        assert_predicate st, :success?
+        assert_equal [ 1, 2 ], hub.ports_on
+
+        exsys_usb('off', '1')
+        assert_equal [ 2 ], hub.ports_on
+    end
+
+    def test_bare_on_and_off_cover_every_port
+        exsys_usb('on')
+        assert_equal ExSYS::ManagedUSB::PORTS, hub.ports_on
+        exsys_usb('off')
+        assert_empty hub.ports_on
+    end
+
+    def test_toggle
+        exsys_usb('on', '1', '3')
+        exsys_usb('toggle', '3', '4')
+        assert_equal [ 1, 4 ], hub.ports_on
+    end
+
+    def test_set_pairs
+        exsys_usb('on', '5')
+        _, _, st = exsys_usb('set', '3:on', '5:off')
+        assert_predicate st, :success?
+        assert_equal [ 3 ], hub.ports_on
+    end
+
+    def test_set_accepts_every_documented_spelling
+        exsys_usb('set', '1:on', '2:ON', '3:true', '4:t', '5:1')
+        assert_equal [ 1, 2, 3, 4, 5 ], hub.ports_on
+        exsys_usb('set', '1:off', '2:OFF', '3:false', '4:f', '5:0')
+        assert_empty hub.ports_on
+    end
+
+    def test_default_flag_forces_the_unlisted_ports
+        exsys_usb('on', '8')
+        exsys_usb('-D', 'false', 'set', '3:on')
+        assert_equal [ 3 ], hub.ports_on
+    end
+
+    def test_commit_saves_the_power_on_state
+        exsys_usb('on', '1')
+        exsys_usb('commit')
+        exsys_usb('on', '2')
+        assert_equal [ 1, 2 ], hub.ports_on
+        assert_equal [ 1 ],    hub.flash_ports
+    end
+
+    def test_commit_flag_writes_through
+        exsys_usb('-c', 'on', '4')
+        exsys_usb('on', '5')
+        assert_equal [ 4, 5 ], hub.ports_on
+        assert_equal [ 4 ],    hub.flash_ports
+    end
+
+    # restore issues RD, the hub's factory reset -- not the inverse of
+    # commit.  Nothing in the protocol reloads the flashed state.
+    def test_restore_is_a_factory_reset
+        exsys_usb('on', '1')
+        exsys_usb('commit')
+        _, err, st = exsys_usb('--yes', 'factory-reset')
+        assert_equal 0, st.exitstatus, err
+        assert_empty hub.ports_on
+        assert_empty hub.flash_ports
+    end
+
+    ## Reading the hub ##################################################
+
+    def test_status_lists_every_port
+        exsys_usb('on', '1', '3')
+        out, _, st = exsys_usb('status')
+        assert_equal 0, st.exitstatus
+        assert_equal 16, out.lines.size
+        assert_includes out.lines, "1 on\n"
+        assert_includes out.lines, "2 off\n"
+        assert_includes out.lines, "3 on\n"
+    end
+
+    def test_status_can_be_asked_about_named_ports
+        exsys_usb('on', '3')
+        out, _, = exsys_usb('status', '3', '4')
+        assert_equal "3 on\n4 off\n", out
+    end
+
+    def test_status_refuses_a_port_the_hub_does_not_have
+        _, err, st = exsys_usb('status', '99')
+        assert_equal 1, st.exitstatus
+        assert_match(/invalid port: 99/, err)
+    end
+
+    def test_query_reports_what_the_hub_says_it_is
+        out, _, st = exsys_usb('query')
+        assert_equal 0, st.exitstatus
+        assert_match(/^id:\s+CENTOS$/,   out)
+        assert_match(/^ports:\s+16$/,    out)
+        assert_match(/^firmware:\s+v02$/, out)
+    end
+
+    ## Verbose ##########################################################
+
+    def test_verbose_reports_the_state_after_a_change
+        out, _, = exsys_usb('-v', 'on', '2')
+        assert_includes out.lines, "2 on\n"
+        assert_equal 16, out.lines.size
+    end
+
+    def test_without_verbose_a_change_says_nothing
+        out, _, st = exsys_usb('on', '2')
+        assert_equal 0, st.exitstatus
+        assert_empty out
+    end
+
+    ## Confirming the irreversible ######################################
+
+    def test_reset_refuses_without_yes
+        _, err, st = exsys_usb('reset')
+        assert_equal 1, st.exitstatus
+        assert_match(/--yes/, err)
+    end
+
+    def test_reset_runs_when_meant
+        _, err, st = exsys_usb('--yes', 'reset')
+        assert_equal 0, st.exitstatus, err
+    end
+
+    def test_factory_reset_refuses_without_yes
+        exsys_usb('on', '1')
+        _, err, st = exsys_usb('factory-reset')
+        assert_equal 1, st.exitstatus
+        assert_match(/--yes/, err)
+        assert_equal [ 1 ], hub.ports_on, 'the hub must not have been touched'
+    end
+
+    def test_factory_reset_runs_when_meant
+        exsys_usb('on', '1')
+        _, err, st = exsys_usb('--yes', 'factory-reset')
+        assert_equal 0, st.exitstatus, err
+        assert_empty hub.ports_on
+    end
+
+    ## Exit status -- regression.  Every failure used to be printed and
+    ## then exited 0, so that `exsys-usb off 3 || alert` never fired.
+    ######################################################################
+
+    def test_a_refused_command_exits_non_zero
+        seed_hub(password: 'other')
+        _, err, st = exsys_usb('off', '3')
+        refute_predicate st, :success?
+        assert_equal 1, st.exitstatus
+        assert_match(/exsys-usb: 01/, err)
+    end
+
+    def test_a_silent_hub_exits_non_zero
+        _, err, st = exsys_usb('off', '3', env: { 'EXSYS_TEST_SILENT' => '1' })
+        assert_equal 1, st.exitstatus
+        assert_match(/exsys-usb:/, err)
+    end
+
+    def test_a_successful_command_exits_zero
+        _, _, st = exsys_usb('on', '1')
+        assert_equal 0, st.exitstatus
+    end
+
+    ## Argument handling #################################################
+
+    # Regression: a port outside 1..16, or a word that to_i turned into
+    # 0, used to be accepted and quietly do nothing.
+    def test_an_out_of_range_port_is_refused
+        [ '0', '17', '99' ].each do |p|
+            _, err, st = exsys_usb('on', p)
+            assert_equal 1, st.exitstatus, "port #{p} should be refused"
+            assert_match(/invalid port: #{p}/, err)
+        end
+    end
+
+    def test_a_port_that_is_not_a_number_is_refused
+        _, err, st = exsys_usb('off', 'usb3')
+        assert_equal 1, st.exitstatus
+        assert_match(/invalid port/, err)
+    end
+
+    def test_a_refused_port_leaves_the_hub_alone
+        exsys_usb('on', '1')
+        exsys_usb('on', '17')
+        assert_equal [ 1 ], hub.ports_on
+    end
+
+    # Regression: an action the case did not know fell through it, so
+    # the tool exited 0 having done nothing at all.
+    def test_an_unknown_action_is_refused
+        _, err, st = exsys_usb('onn', '1')
+        assert_equal 1, st.exitstatus
+        assert_match(/unknown action: onn/, err)
+    end
+
+    def test_a_malformed_set_pair_is_refused
+        [ 'foo', '3:maybe', ':on', '3:' ].each do |a|
+            _, err, st = exsys_usb('set', a)
+            assert_equal 1, st.exitstatus, "#{a} should be refused"
+            assert_match(/invalid argument/, err)
+        end
+    end
+
+    ## Startup failures -- regression.  Option parsing, the debug file
+    ## and the hub were all built before the rescue, so their failures
+    ## escaped as a Ruby backtrace.
+    ######################################################################
+
+    def test_an_over_long_password_is_reported_not_dumped
+        _, err, st = exsys_usb('-p', 'verylongpassword', 'on', '1')
+        assert_equal 1, st.exitstatus
+        assert_equal "exsys-usb: password too long\n", err
+    end
+
+    def test_an_unopenable_debug_file_is_reported_not_dumped
+        _, err, st = exsys_usb('--debug=/nonexistent-dir/x.log', 'on', '1')
+        assert_equal 1, st.exitstatus
+        assert_match(/\Aexsys-usb: /, err)
+        refute_match(/\.rb:\d+:in/, err)
+    end
+
+    def test_a_bad_option_value_is_reported_not_dumped
+        _, err, st = exsys_usb('-D', '0', 'set', '3:on')
+        assert_equal 1, st.exitstatus
+        assert_match(/\Aexsys-usb: /, err)
+        refute_match(/\.rb:\d+:in/, err)
+    end
+
+    ## Help ##############################################################
+
+    def test_no_action_prints_the_usage
+        out, _, st = exsys_usb
+        assert_equal 0, st.exitstatus
+        assert_match(/Usage: exsys-usb ACTION/, out)
+    end
+
+    def test_help_and_version
+        out, _, st = exsys_usb('-h')
+        assert_equal 0, st.exitstatus
+        assert_match(/--device/, out)
+
+        out, _, st = exsys_usb('-V')
+        assert_equal 0, st.exitstatus
+        assert_match(/#{ExSYS::VERSION}/, out)
+    end
+
+    ## Debug file ########################################################
+
+    # Regression: opened RDWR without truncating, so a shorter session
+    # left the tail of a longer previous one in place, reading as if the
+    # hub had sent it.
+    def test_the_debug_file_is_appended_to
+        log = File.join(@tmp, 'debug.log')
+        File.write(log, "PREVIOUS SESSION#{'.' * 200}\n")
+        exsys_usb("--debug=#{log}", 'on', '1')
+        assert_match(/\APREVIOUS SESSION/, File.read(log))
+        assert_match(/<-- GP/,             File.read(log))
+        refute_match(/\.{20}\z/,           File.read(log).lines.last)
+    end
+
+    def test_two_runs_both_survive_in_the_debug_file
+        log = File.join(@tmp, 'debug.log')
+        exsys_usb("--debug=#{log}", 'on', '1')
+        exsys_usb("--debug=#{log}", 'off', '1')
+        assert_equal 2, File.read(log).scan(/<-- GP/).size
+    end
+
+    # Regression: the trace carries the password, in a file that used to
+    # be created world-readable.
+    def test_the_debug_file_is_private_and_redacted
+        log = File.join(@tmp, 'debug.log')
+        seed_hub(password: 's3cret')
+        exsys_usb('-p', 's3cret', "--debug=#{log}", 'on', '1')
+        assert_equal 0o600, File.stat(log).mode & 0o777
+        refute_match(/s3cret/,      File.read(log))
+        assert_match(/<-- SP\*{8}/, File.read(log))
+    end
+
+    ## Concurrency #######################################################
+
+    # Regression: the GP and the SP were separate openings of the line,
+    # so two processes could both read the old state and the second
+    # write would drop the first one's port.
+    def test_two_concurrent_invocations_do_not_lose_an_update
+        env = { 'EXSYS_TEST_LOCK'  => File.join(@tmp, 'lock'),
+                'EXSYS_TEST_DELAY' => '0.2' }
+
+        results = [ '1', '2' ].map do |port|
+            Thread.new { exsys_usb('on', port, env: env) }
+        end.map(&:value)
+
+        results.each {|(_, err, st)| assert_equal 0, st.exitstatus, err }
+        assert_equal [ 1, 2 ], hub.ports_on
+    end
+
+    # Typing the old name must not silently do nothing, nor quietly do
+    # the reset: it must say what the command actually is.
+    def test_the_old_restore_action_explains_itself
+        _, err, st = exsys_usb('restore')
+        assert_equal 1, st.exitstatus
+        assert_match(/renamed factory-reset/, err)
+        assert_match(/factory defaults/,      err)
+        assert_equal [], hub.ports_on
+    end
+
+    ## Packaging #########################################################
+
+    # Regression: the file carried a shebang but no execute bit, so a
+    # fresh clone could not run the examples in the README.
+    def test_the_executable_is_executable
+        assert_predicate File.stat(EXE).mode & 0o111, :positive?
+    end
+end