rpremote 0.1.0

data/lib/rpremote/mrbgems_command.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "mrbgems"
+
+module Rpremote
+  class MrbgemsCommand
+    DEFAULT_PATH = Mrbgems::DEFAULT_PATH
+
+    def self.run(args, output: $stdout, mrbgems: Mrbgems)
+      command = args.shift
+      options = { path: DEFAULT_PATH, lock_path: nil }
+      OptionParser.new do |opts|
+        opts.on("--file FILE") { |value| options[:path] = value }
+        opts.on("--lockfile FILE") { |value| options[:lock_path] = value }
+      end.parse!(args)
+      raise ArgumentError, "mrbgems does not accept arguments" unless args.empty?
+
+      manager = mrbgems.new(**options)
+      case command
+      when "check"
+        dependencies = manager.check
+        output.puts("checked #{dependencies.length} mrbgems: #{manager.path}")
+      when "list"
+        list(manager, output)
+      when "lock", "update"
+        result = manager.lock(update: command == "update")
+        output.puts("locked #{result.fetch("gems").length} mrbgems: #{manager.lock_path}")
+      else
+        raise ArgumentError, "unknown mrbgems command: #{command || "(none)"}"
+      end
+    end
+
+    def self.list(manager, output)
+      dependencies = manager.check
+      lock = manager.read_lock(required: false)
+      entries = lock&.fetch("gems", []) || []
+      dependencies.each do |dependency|
+        entry = entries.find do |item|
+          item["type"] == dependency.type.to_s && item["source"] == dependency.source
+        end
+        suffix = entry && (entry["commit"] || entry["sha256"])
+        output.puts([dependency.type, dependency.source, suffix&.slice(0, 12)].compact.join(" "))
+      end
+    end
+    private_class_method :list
+  end
+end

data/lib/rpremote/picomodem.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require "io/wait"
+
+module Rpremote
+  class PicoModem
+    STX = 0x02
+    ACK = 0x06
+
+    FILE_READ = 0x01
+    FILE_WRITE = 0x02
+    DFU_START = 0x03
+    CHUNK = 0x04
+    ABORT = 0xFF
+
+    FILE_DATA = 0x81
+    FILE_ACK = 0x82
+    DFU_ACK = 0x83
+    CHUNK_ACK = 0x84
+    DONE_ACK = 0x8F
+    ERROR = 0xFE
+
+    OK = 0x00
+    READY = 0x01
+
+    CHUNK_SIZE = 480
+    DEFAULT_TIMEOUT = 10.0
+    MAX_FRAME_BODY = 65_535
+    DFU_MAGIC = "DFU\0".b
+    DFU_VERSION = 1
+    DFU_TYPES = %w[RUBY RITE].freeze
+
+    class Error < Rpremote::Error; end
+    class TimeoutError < Error; end
+    class ProtocolError < Error; end
+    class ChecksumError < ProtocolError; end
+    class DeviceError < Error; end
+
+    attr_reader :io, :timeout
+
+    def initialize(io, timeout: DEFAULT_TIMEOUT)
+      raise ArgumentError, "timeout must be positive" unless timeout.positive?
+
+      @io = io
+      @timeout = timeout
+    end
+
+    def upload(path, data)
+      path = validate_path(path)
+      data = data.b
+      in_session do
+        send_frame(FILE_WRITE, [data.bytesize].pack("N") + path)
+        expect_status(FILE_ACK, READY, "device readiness")
+        send_chunks(data)
+
+        status, remote_crc = completion
+        raise DeviceError, format("upload failed with status 0x%02x", status) unless status == OK
+
+        local_crc = Checksum.crc32(data)
+        raise ChecksumError, checksum_mismatch("CRC32", local_crc, remote_crc, 8) unless remote_crc == local_crc
+      end
+      data.bytesize
+    end
+
+    def download(path)
+      path = validate_path(path)
+      data = +"".b
+      total = nil
+
+      in_session do
+        send_frame(FILE_READ, path)
+        loop do
+          command, payload = receive_frame
+          case command
+          when FILE_DATA
+            if total.nil?
+              raise ProtocolError, "first FILE_DATA frame has no size" if payload.bytesize < 4
+
+              total = payload.unpack1("N")
+              data << payload.byteslice(4..)
+            else
+              data << payload
+            end
+            raise ProtocolError, "received more bytes than declared" if total && data.bytesize > total
+
+            send_frame(CHUNK_ACK, [OK].pack("C"))
+          when DONE_ACK
+            status, remote_crc = parse_completion(payload)
+            raise DeviceError, format("download failed with status 0x%02x", status) unless status == OK
+            if total && data.bytesize != total
+              raise ProtocolError, "file size mismatch: expected #{total}, received #{data.bytesize}"
+            end
+
+            local_crc = Checksum.crc32(data)
+            raise ChecksumError, checksum_mismatch("CRC32", local_crc, remote_crc, 8) unless remote_crc == local_crc
+
+            break
+          when ERROR
+            raise DeviceError, payload.force_encoding(Encoding::UTF_8)
+          else
+            raise ProtocolError, format("unexpected response 0x%02x during download", command)
+          end
+        end
+      end
+      data
+    end
+
+    def dfu(data, type:)
+      data = data.b
+      type = validate_dfu_type(type)
+      header = [DFU_MAGIC, DFU_VERSION, type, data.bytesize, Checksum.crc32(data), 0].pack("a4Ca4NNn")
+      in_session do
+        send_frame(DFU_START, header)
+        expect_status(DFU_ACK, READY, "DFU readiness")
+        send_chunks(data)
+        expect_dfu_completion
+      end
+      data.bytesize
+    end
+
+    def send_frame(command, payload = +"".b)
+      body = [command].pack("C") + payload.b
+      raise ProtocolError, "frame body is too large" if body.bytesize > MAX_FRAME_BODY
+
+      frame = [STX, body.bytesize].pack("Cn") + body + [Checksum.crc16(body)].pack("n")
+      write_all(frame)
+      frame.bytesize
+    end
+
+    def receive_frame
+      deadline = monotonic_time + timeout
+      scan_for(STX, deadline, "PicoModem frame")
+      length = read_exact(2, deadline).unpack1("n")
+      raise ProtocolError, "invalid empty frame" if length.zero?
+      raise ProtocolError, "frame body is too large: #{length}" if length > MAX_FRAME_BODY
+
+      body = read_exact(length, deadline)
+      expected_crc = read_exact(2, deadline).unpack1("n")
+      actual_crc = Checksum.crc16(body)
+      raise ChecksumError, checksum_mismatch("CRC16", actual_crc, expected_crc, 4) unless actual_crc == expected_crc
+
+      [body.getbyte(0), body.byteslice(1..) || +"".b]
+    end
+
+    private
+
+    def in_session
+      entered = false
+      completed = false
+      enter_mode
+      entered = true
+      result = yield
+      completed = true
+      result
+    ensure
+      abort_transfer if entered && !completed
+    end
+
+    def enter_mode
+      write_all([STX].pack("C"))
+      scan_for(ACK, monotonic_time + timeout, "PicoModem ACK")
+    end
+
+    def abort_transfer
+      send_frame(ABORT)
+    rescue IOError, SystemCallError, Error
+      nil
+    end
+
+    def completion
+      command, payload = receive_frame
+      raise DeviceError, payload.force_encoding(Encoding::UTF_8) if command == ERROR
+      raise ProtocolError, format("expected DONE_ACK, got 0x%02x", command) unless command == DONE_ACK
+
+      parse_completion(payload)
+    end
+
+    def expect_dfu_completion
+      command, payload = receive_frame
+      raise DeviceError, payload.force_encoding(Encoding::UTF_8) if command == ERROR
+      raise ProtocolError, format("expected DFU DONE_ACK, got 0x%02x", command) unless command == DONE_ACK
+      raise ProtocolError, "DFU DONE_ACK has no status" if payload.empty?
+      return if payload.getbyte(0) == OK
+
+      raise DeviceError, format("DFU failed with status 0x%02x", payload.getbyte(0))
+    end
+
+    def parse_completion(payload)
+      raise ProtocolError, "DONE_ACK has no CRC32" if payload.bytesize < 5
+
+      payload.unpack("CN")
+    end
+
+    def expect_status(expected_command, expected_status, context)
+      command, payload = receive_frame
+      raise DeviceError, payload.force_encoding(Encoding::UTF_8) if command == ERROR
+      unless command == expected_command
+        raise ProtocolError, "unexpected response #{hex(command, 2)} while waiting for #{context}"
+      end
+      raise ProtocolError, "#{context} has no status" if payload.empty?
+      return if payload.getbyte(0) == expected_status
+
+      raise DeviceError, "#{context} failed with status #{hex(payload.getbyte(0), 2)}"
+    end
+
+    def send_chunks(data)
+      offset = 0
+      while offset < data.bytesize
+        chunk = data.byteslice(offset, CHUNK_SIZE)
+        send_frame(CHUNK, chunk)
+        expect_status(CHUNK_ACK, OK, "chunk acknowledgement")
+        offset += chunk.bytesize
+      end
+    end
+
+    def validate_dfu_type(type)
+      type = String(type).upcase
+      return type if DFU_TYPES.include?(type)
+
+      raise ArgumentError, "DFU type must be one of: #{DFU_TYPES.join(", ")}"
+    end
+
+    def validate_path(path)
+      path = String(path)
+      raise ArgumentError, "remote path must be absolute" unless path.start_with?("/")
+      raise ArgumentError, "remote path contains a null byte" if path.include?("\0")
+      raise ArgumentError, "remote path must not contain .." if path.split("/").include?("..")
+
+      path.b
+    end
+
+    def scan_for(byte, deadline, description)
+      loop do
+        return if read_exact(1, deadline).getbyte(0) == byte
+      rescue TimeoutError
+        raise TimeoutError, "timed out waiting for #{description}"
+      end
+    end
+
+    def read_exact(length, deadline)
+      buffer = +"".b
+      while buffer.bytesize < length
+        begin
+          remaining = deadline - monotonic_time
+          raise TimeoutError, "timed out after #{timeout} seconds" unless remaining.positive?
+
+          wait_readable(remaining)
+          chunk = io.read_nonblock(length - buffer.bytesize)
+          raise IOError, "serial connection closed" if chunk.nil? || chunk.empty?
+
+          buffer << chunk
+        rescue IO::WaitReadable
+          next
+        rescue EOFError
+          raise IOError, "serial connection closed"
+        end
+      end
+      buffer
+    end
+
+    def write_all(data)
+      offset = 0
+      while offset < data.bytesize
+        written = io.write(data.byteslice(offset..))
+        raise IOError, "serial connection closed while writing" unless written&.positive?
+
+        offset += written
+      end
+      io.flush if io.respond_to?(:flush)
+    end
+
+    def wait_readable(timeout_seconds)
+      selectable = io.respond_to?(:to_io) ? io.to_io : io
+      return unless selectable.respond_to?(:fileno)
+
+      return if selectable.wait_readable(timeout_seconds)
+
+      raise TimeoutError, "timed out after #{timeout} seconds"
+    end
+
+    def checksum_mismatch(name, local, remote, width)
+      "#{name} mismatch: local=#{hex(local, width)} remote=#{hex(remote, width)}"
+    end
+
+    def hex(value, width)
+      "0x#{value.to_s(16).rjust(width, "0")}"
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/rpremote/remote_path.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Rpremote
+  module RemotePath
+    PREFIX = ":"
+
+    module_function
+
+    def remote?(path)
+      path.start_with?(PREFIX)
+    end
+
+    def unwrap(path)
+      path.delete_prefix(PREFIX)
+    end
+
+    def validate(path)
+      raise ArgumentError, "path must be remote (prefix it with :)" unless remote?(path)
+
+      remote = unwrap(path)
+      raise ArgumentError, "remote path must be absolute" unless remote.start_with?("/")
+      raise ArgumentError, "remote path must not contain .." if remote.split("/").include?("..")
+
+      remote
+    end
+  end
+end

data/lib/rpremote/resetter.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Rpremote
+  class Resetter
+    DEFAULT_TIMEOUT = 10.0
+    RETRY_INTERVAL = 0.1
+    PROBE_TIMEOUT = 1.0
+
+    class TimeoutError < Rpremote::Error; end
+
+    def initialize(
+      serial: Serial,
+      timeout: DEFAULT_TIMEOUT,
+      shell_class: Shell,
+      sleeper: nil,
+      clock: nil,
+      port_probe: nil
+    )
+      @serial = serial
+      @timeout = Float(timeout)
+      @shell_class = shell_class
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @port_probe = port_probe || ->(path) { File.exist?(path) }
+      raise ArgumentError, "timeout must be positive" unless @timeout.positive?
+    end
+
+    def reset(port_path, baud: Serial::BAUD_RATE)
+      deadline = clock.call + timeout
+      send_reboot(port_path, baud)
+      wait_until("USB serial port to disconnect", deadline) { !port_probe.call(port_path) }
+      wait_until_ready(port_path, baud, deadline)
+      port_path
+    end
+
+    private
+
+    attr_reader :serial, :timeout, :shell_class, :sleeper, :clock, :port_probe
+
+    def send_reboot(port_path, baud)
+      serial.open(port_path, baud: baud) do |port|
+        shell = shell_class.new(port, timeout: [timeout, PROBE_TIMEOUT].min)
+        shell.synchronize!
+        shell.send_command("reboot")
+      end
+    end
+
+    def wait_until_ready(port_path, baud, deadline)
+      wait_until("R2P2 Shell after reset", deadline) do
+        remaining = deadline - clock.call
+        shell_ready?(port_path, baud, [remaining, PROBE_TIMEOUT].min) if remaining.positive?
+      end
+    end
+
+    def wait_until(description, deadline)
+      loop do
+        return if yield
+        raise TimeoutError, "timed out waiting for #{description}" if clock.call >= deadline
+
+        sleeper.call(RETRY_INTERVAL)
+      end
+    end
+
+    def shell_ready?(port_path, baud, probe_timeout)
+      serial.open(port_path, baud: baud) do |port|
+        shell_class.new(port, timeout: probe_timeout).synchronize!
+      end
+      true
+    rescue IOError, SystemCallError, Rpremote::Error
+      false
+    end
+  end
+end

data/lib/rpremote/runner.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Rpremote
+  class Runner
+    REMOTE_DIRECTORY = "/home"
+
+    attr_reader :io, :timeout
+
+    def initialize(
+      io,
+      timeout: Shell::DEFAULT_TIMEOUT,
+      modem_class: PicoModem,
+      shell_class: Shell,
+      path_factory: nil
+    )
+      @io = io
+      @timeout = timeout
+      @modem_class = modem_class
+      @shell_class = shell_class
+      @path_factory = path_factory || method(:temporary_path)
+    end
+
+    def run(data)
+      remote_path = @path_factory.call
+      shell = @shell_class.new(io, timeout: timeout)
+      shell.synchronize!
+      @modem_class.new(io, timeout: timeout).upload(remote_path, data)
+      shell.synchronize!
+      shell_ready = true
+      shell.execute("./#{File.basename(remote_path)}")
+    ensure
+      cleanup(shell, remote_path) if shell_ready && remote_path
+    end
+
+    private
+
+    def cleanup(shell, remote_path)
+      shell.execute("rm #{remote_path}")
+    rescue IOError, SystemCallError, Shell::Error
+      nil
+    end
+
+    def temporary_path
+      stamp = (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1_000_000).to_i
+      "#{REMOTE_DIRECTORY}/.rpremote-run-#{Process.pid}-#{stamp}.rb"
+    end
+  end
+end

data/lib/rpremote/serial.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Rpremote
+  class Serial
+    BAUD_RATE = 115_200
+
+    class ConfigurationError < Rpremote::Error; end
+
+    def self.open(path, baud: BAUD_RATE)
+      port = new(path, baud: baud)
+      return port unless block_given?
+
+      begin
+        yield port
+      ensure
+        port.close
+      end
+    end
+
+    attr_reader :path, :baud, :io
+
+    def initialize(path, baud: BAUD_RATE)
+      @path = path
+      @baud = Integer(baud)
+      configure!
+      @io = File.open(path, File::RDWR)
+      @io.binmode
+      @io.sync = true
+    rescue SystemCallError => e
+      raise ConfigurationError, "cannot open serial port #{path}: #{e.message}"
+    end
+
+    def read_nonblock(length)
+      io.read_nonblock(length)
+    end
+
+    def write(data)
+      io.write(data)
+    end
+
+    def flush
+      io.flush
+    end
+
+    def close
+      io.close unless io.closed?
+    end
+
+    def closed?
+      io.closed?
+    end
+
+    def to_io
+      io
+    end
+
+    private
+
+    def configure!
+      output, status = Open3.capture2e(
+        "stty", "-f", path, baud.to_s, "cs8", "-cstopb", "-parenb", "raw", "-echo"
+      )
+      return if status.success?
+
+      raise ConfigurationError, "cannot configure serial port #{path}: #{output.strip}"
+    rescue Errno::ENOENT
+      raise ConfigurationError, "stty was not found; rpremote currently requires macOS"
+    end
+  end
+end

data/lib/rpremote/setup_command.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Rpremote
+  class SetupCommand
+    def self.run(args, defaults:, config:, config_filename:, output: $stdout)
+      options = {
+        force: false,
+        cache_dir: defaults.fetch(:cache, Target::DEFAULT_CACHE_DIR),
+        language: defaults.fetch(:language, Target::DEFAULT_LANGUAGE),
+        language_version: defaults.fetch(:language_version, Target::DEFAULT_LANGUAGE_VERSION)
+      }
+      OptionParser.new do |parser|
+        parser.on("--force") { options[:force] = true }
+        parser.on("--cache DIR") { |value| options[:cache_dir] = value }
+        parser.on("--language LANGUAGE") { |value| options[:language] = value }
+        parser.on("--language-version VERSION") { |value| options[:language_version] = value }
+      end.parse!(args)
+      raise ArgumentError, "setup does not accept arguments" unless args.empty?
+
+      target = Target.new(**options.slice(:cache_dir, :language, :language_version))
+      Language.validate!(target.language)
+      result = config.setup(filename: config_filename)
+      output.puts("#{result.created ? "created" : "exists"} config: #{result.path}")
+      path = LanguageSource.new(
+        language: target.language,
+        version: target.language_version,
+        cache_dir: target.cache_dir
+      ).setup(force: options[:force])
+      output.puts("installed #{target.language} #{target.language_version}: #{path}")
+    end
+  end
+end