rshelly 0.1.0

data/lib/rshelly/discovery.rb

@@ -0,0 +1,371 @@
+# frozen_string_literal: true
+
+require "open3"
+require "ipaddr"
+require "resolv"
+require "shellwords"
+require "socket"
+require "timeout"
+
+module Shelly
+  class Discovery
+    HTTP_SERVICE = "_http._tcp"
+    DEFAULT_TIMEOUT = 5
+    DEFAULT_CONCURRENCY = 32
+    COMMAND_TIMEOUT_GRACE = 1
+
+    class << self
+      def scan(network: nil, timeout: DEFAULT_TIMEOUT, concurrency: DEFAULT_CONCURRENCY, max_hosts: 4096, client_options: {})
+        network ||= default_ipv4_network
+        raise DiscoveryError, "could not determine local IPv4 network; pass a CIDR such as 192.168.0.0/24" unless network
+
+        addresses = network_addresses(network)
+        if max_hosts && addresses.length > max_hosts
+          raise DiscoveryError, "refusing to scan #{addresses.length} hosts; use --max-hosts to raise the limit"
+        end
+
+        scan_addresses(addresses, timeout: timeout, concurrency: concurrency, client_options: client_options).sort_by do |device|
+          IPAddr.new(device["ip"]).to_i
+        end
+      end
+
+      def discover(timeout: DEFAULT_TIMEOUT, verify: false, concurrency: DEFAULT_CONCURRENCY, client_options: {})
+        records = if executable?("avahi-browse")
+          discover_with_avahi(timeout: timeout)
+        elsif executable?("dns-sd")
+          discover_with_dns_sd(timeout: timeout)
+        else
+          raise DiscoveryError, "no mDNS discovery command found; install avahi-browse on Linux or use dns-sd on macOS"
+        end
+
+        records = records.select { |record| shelly_name?(record[:name]) || shelly_name?(record[:hostname]) }
+        return records.map { |record| stringify_keys(record) } unless verify
+
+        records = records.reject { |record| link_local_ipv6?(record[:ip]) }
+        verify_records(records, timeout: timeout, concurrency: concurrency, client_options: client_options)
+      end
+
+      def discover_with_avahi(timeout: DEFAULT_TIMEOUT)
+        command_timeout = timeout + COMMAND_TIMEOUT_GRACE
+        output, status = capture_command_for(command_timeout, "avahi-browse", "-r", "-p", "-t", HTTP_SERVICE)
+        raise DiscoveryError, output.strip.empty? ? "avahi-browse failed" : output.strip unless status&.success?
+
+        parse_avahi_output(output)
+      rescue Errno::ENOENT
+        raise DiscoveryError, "avahi-browse not found"
+      end
+
+      def discover_with_dns_sd(timeout: DEFAULT_TIMEOUT)
+        browse_output = capture_for(timeout, "dns-sd", "-B", HTTP_SERVICE, "local")
+        instances = parse_dns_sd_browse(browse_output)
+
+        instances.filter_map do |instance|
+          output = capture_for(timeout, "dns-sd", "-L", instance, HTTP_SERVICE, "local")
+          parse_dns_sd_resolve(instance, output)
+        rescue DiscoveryError
+          nil
+        end
+      rescue Errno::ENOENT
+        raise DiscoveryError, "dns-sd not found"
+      end
+
+      def parse_avahi_output(output)
+        output.lines.filter_map do |line|
+          fields = line.strip.split(";")
+          next unless fields[0] == "=" && fields.length >= 9
+
+          name = fields[3]
+          hostname = fields[6]
+          ip = fields[7]
+          port = fields[8].to_i
+          txt = parse_avahi_txt(fields[9])
+
+          {
+            source: "avahi",
+            interface: fields[1],
+            protocol: fields[2],
+            name: name,
+            hostname: hostname,
+            ip: ip,
+            port: port,
+            gen: txt["gen"]&.to_i,
+            mac: extract_mac(name),
+            txt: txt
+          }
+        end
+      end
+
+      def parse_dns_sd_browse(output)
+        output.lines.filter_map do |line|
+          next unless line.include?(HTTP_SERVICE)
+
+          parts = line.strip.split(/\s+/, 7)
+          instance = parts[6]
+          next unless instance && shelly_name?(instance)
+
+          instance
+        end.uniq
+      end
+
+      def parse_dns_sd_resolve(instance, output)
+        target = output.lines.find { |line| line.include?(" can be reached at ") }
+        return nil unless target
+
+        match = target.match(/ can be reached at ([^:]+):(\d+)/)
+        return nil unless match
+
+        hostname = match[1]
+        port = match[2].to_i
+        ip = Resolv.getaddress(hostname)
+        txt = parse_dns_sd_txt(output)
+
+        {
+          source: "dns-sd",
+          name: instance,
+          hostname: hostname,
+          ip: ip,
+          port: port,
+          gen: txt["gen"]&.to_i,
+          mac: extract_mac(instance),
+          txt: txt
+        }
+      rescue Resolv::ResolvError
+        nil
+      end
+
+      def parse_avahi_txt(txt_field)
+        return {} unless txt_field
+
+        txt_field.scan(/"([^"]*)"/).flatten.each_with_object({}) do |part, result|
+          key, value = part.split("=", 2)
+          result[key] = value if key && value
+        end
+      end
+
+      def parse_dns_sd_txt(output)
+        output.lines.each_with_object({}) do |line, result|
+          line.scan(/([\w.-]+)=("[^"]*"|\S+)/).each do |key, value|
+            result[key] = value.delete_prefix('"').delete_suffix('"')
+          end
+        end
+      end
+
+      def extract_mac(name)
+        match = name.to_s.match(/-([0-9a-fA-F]{6,12})$/)
+        match && match[1].upcase
+      end
+
+      def shelly_name?(value)
+        value.to_s.downcase.include?("shelly")
+      end
+
+      def link_local_ipv6?(value)
+        value.to_s.start_with?("fe80:")
+      end
+
+      def default_ipv4_network
+        if executable?("ip")
+          network = default_ipv4_network_from_ip
+          return network if network
+        end
+
+        if executable?("route") && executable?("ipconfig")
+          network = default_ipv4_network_from_macos
+          return network if network
+        end
+
+        fallback_ipv4_network
+      end
+
+      def network_addresses(network)
+        ipaddr = IPAddr.new(network)
+        raise DiscoveryError, "scan only supports IPv4 networks" unless ipaddr.ipv4?
+
+        range = ipaddr.to_range.to_a
+        range = range[1...-1] if network.to_s.include?("/") && range.length > 2
+        range.map(&:to_s)
+      rescue ArgumentError => e
+        raise DiscoveryError, "invalid network #{network.inspect}: #{e.message}"
+      end
+
+      private
+
+      def scan_addresses(addresses, timeout:, concurrency:, client_options:)
+        queue = Queue.new
+        addresses.each { |address| queue << address }
+        results = Queue.new
+        worker_count = [[concurrency.to_i, 1].max, addresses.length].min
+
+        workers = Array.new(worker_count) do
+          Thread.new do
+            loop do
+              address = queue.pop(true)
+              client = Client.new(address, **client_options.merge(timeout: timeout))
+              results << client.normalized_info.merge("discovery" => { "source" => "ip-scan" })
+            rescue ThreadError
+              break
+            rescue Error, URI::InvalidURIError, JSON::ParserError
+              next
+            end
+          end
+        end
+        workers.each(&:join)
+
+        found = []
+        found << results.pop(true) until results.empty?
+        found
+      end
+
+      def verify_records(records, timeout:, concurrency:, client_options:)
+        queue = Queue.new
+        records.each { |record| queue << record }
+        results = Queue.new
+        worker_count = [[concurrency.to_i, 1].max, records.length].min
+
+        workers = Array.new(worker_count) do
+          Thread.new do
+            loop do
+              record = queue.pop(true)
+              client = Client.new(record[:ip], **client_options.merge(timeout: timeout))
+              results << client.normalized_info.merge("discovery" => stringify_keys(record))
+            rescue ThreadError
+              break
+            rescue Error, URI::InvalidURIError, JSON::ParserError
+              next
+            end
+          end
+        end
+        workers.each(&:join)
+
+        found = []
+        found << results.pop(true) until results.empty?
+        found.sort_by do |device|
+          [0, IPAddr.new(device["ip"]).to_i]
+        rescue ArgumentError
+          [1, device["ip"].to_s]
+        end
+      end
+
+      def default_ipv4_network_from_ip
+        route_output = capture_command("ip", "-o", "route", "show", "default")
+        iface = route_output[/\bdev\s+(\S+)/, 1]
+
+        addr_output = capture_command("ip", "-o", "-f", "inet", "addr", "show", "scope", "global")
+        candidates = addr_output.lines.filter_map do |line|
+          fields = line.split
+          next unless fields[2] == "inet"
+          next if iface && fields[1] != iface
+
+          cidr = fields[3]
+          prefix = cidr.split("/", 2).last.to_i
+          "#{IPAddr.new(cidr).mask(prefix)}/#{prefix}"
+        rescue ArgumentError
+          nil
+        end
+
+        candidates.first
+      end
+
+      def default_ipv4_network_from_macos
+        route_output = capture_command("route", "-n", "get", "default")
+        iface = route_output[/interface:\s+(\S+)/, 1]
+        return nil unless iface
+
+        address = capture_command("ipconfig", "getifaddr", iface).strip
+        mask = capture_command("ipconfig", "getoption", iface, "subnet_mask").strip
+        return nil if address.empty? || mask.empty?
+
+        prefix = IPAddr.new(mask).to_i.to_s(2).count("1")
+        "#{IPAddr.new(address).mask(prefix)}/#{prefix}"
+      rescue ArgumentError
+        nil
+      end
+
+      def fallback_ipv4_network
+        addr = Socket.ip_address_list.find { |info| info.ipv4_private? && !info.ipv4_loopback? }
+        return nil unless addr
+
+        "#{IPAddr.new(addr.ip_address).mask(24)}/24"
+      end
+
+      def executable?(name)
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+          path = File.join(dir, name)
+          File.executable?(path) && !File.directory?(path)
+        end
+      end
+
+      def capture_for(seconds, *cmd)
+        output, = run_command_for(seconds, *cmd, timeout_error: false)
+        output
+      end
+
+      def capture_command_for(seconds, *cmd)
+        run_command_for(seconds, *cmd, timeout_error: true)
+      end
+
+      def run_command_for(seconds, *cmd, timeout_error:)
+        output = +""
+        status = nil
+        timed_out = false
+        Open3.popen2e(*cmd) do |_stdin, stdout_err, wait_thr|
+          begin
+            Timeout.timeout(seconds) do
+              until stdout_err.eof?
+                output << stdout_err.readpartial(4096)
+              end
+              status = wait_thr.value
+            end
+          rescue Timeout::Error
+            timed_out = true
+            terminate_process(wait_thr)
+          ensure
+            status ||= wait_thr.value rescue nil
+          end
+        end
+
+        if timed_out && timeout_error
+          raise DiscoveryError, "#{cmd.shelljoin} timed out after #{seconds} seconds"
+        end
+
+        [output, status]
+      rescue Errno::ENOENT
+        raise
+      rescue DiscoveryError
+        raise
+      rescue => e
+        raise DiscoveryError, "#{cmd.shelljoin} failed: #{e.message}"
+      end
+
+      def terminate_process(wait_thr)
+        Process.kill("TERM", wait_thr.pid)
+        return if wait_thr.join(1)
+
+        Process.kill("KILL", wait_thr.pid)
+        wait_thr.join
+      rescue Errno::ESRCH, Errno::ECHILD
+        nil
+      end
+
+      def stringify_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, item), result|
+            result[key.to_s] = stringify_keys(item)
+          end
+        when Array
+          value.map { |item| stringify_keys(item) }
+        else
+          value
+        end
+      end
+
+      def capture_command(*cmd)
+        stdout, _stderr, status = Open3.capture3(*cmd)
+        status.success? ? stdout : ""
+      rescue Errno::ENOENT
+        ""
+      end
+    end
+  end
+end

data/lib/rshelly/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Shelly
+  Error = Class.new(StandardError)
+  HttpError = Class.new(Error)
+  RpcError = Class.new(Error)
+  UnsupportedDeviceError = Class.new(Error)
+  DiscoveryError = Class.new(Error)
+end

data/lib/rshelly/version.rb

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

data/lib/rshelly.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "rshelly/version"
+require_relative "rshelly/error"
+require_relative "rshelly/client"
+require_relative "rshelly/discovery"
+
+module Shelly
+  def self.client(host, **options)
+    Client.new(host, **options)
+  end
+
+  def self.discover(**options)
+    Discovery.discover(**options)
+  end
+
+  def self.scan(**options)
+    Discovery.scan(**options)
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: rshelly
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jonas Tehler
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: The rshelly Ruby library and shelly command for discovery, inspection,
+  control, metering, and firmware management of Shelly Gen1 and Gen2+ devices.
+email:
+- jonas@tehler.se
+executables:
+- shelly
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/shelly
+- lib/rshelly.rb
+- lib/rshelly/cli.rb
+- lib/rshelly/client.rb
+- lib/rshelly/discovery.rb
+- lib/rshelly/error.rb
+- lib/rshelly/version.rb
+homepage: https://github.com/jegt/rshelly
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jegt/rshelly
+  source_code_uri: https://github.com/jegt/rshelly/tree/main
+  documentation_uri: https://github.com/jegt/rshelly/blob/main/README.md
+  bug_tracker_uri: https://github.com/jegt/rshelly/issues
+  changelog_uri: https://github.com/jegt/rshelly/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  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: 4.0.7
+specification_version: 4
+summary: Ruby library and CLI for managing Shelly Gen1 and Gen2 devices
+test_files: []