keenetic 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 150b29909b27e3c0c7704dead364af88b95152e02c48ad237dd2bbdaf5d6471e
+  data.tar.gz: dde2d8a08098c812502fb07cb3cad0262d004ff6c431be3b8d11b21f2216491a
+SHA512:
+  metadata.gz: 12e93dc8b6b71b665fd88994236ef984c042dc2cbf16b3108456f9615e55c5751a76b657adaf7ff970c4a83ffd3d4aa49ade8800b772666abc27c23e082bc630
+  data.tar.gz: 7921327abfc55e5f1d2c4846602ecad522fe69478b8d78ddf2a3519ebe9b15aff87950618eeef2a8fe4a6e889c08e8b350931bfe2bc430549bb12a36668e8d95

data/README.md

@@ -0,0 +1,83 @@
+# Keenetic
+
+Ruby wrapper for the Keenetic router RCI (Remote Command Interface) — the same API that powers the Keenetic web UI.
+
+## Installation
+
+```ruby
+gem 'keenetic'
+```
+
+## Configuration
+
+```ruby
+Keenetic.configure do |config|
+  config.host = '192.168.1.1'
+  config.login = 'admin'
+  config.password = 'your_password'
+  config.timeout = 30               # optional
+  config.logger = Logger.new($stdout) # optional
+end
+```
+
+## Usage
+
+```ruby
+client = Keenetic.client
+
+# Connected devices
+client.devices.all
+client.devices.active
+client.devices.find(mac: 'AA:BB:CC:DD:EE:FF')
+client.devices.update(mac: 'AA:BB:CC:DD:EE:FF', name: 'My Phone')
+
+# System info
+client.system.info       # model, firmware
+client.system.resources  # CPU, memory, uptime
+
+# Network
+client.network.interfaces
+
+# WiFi
+client.wifi.access_points
+client.wifi.clients
+
+# Internet
+client.internet.status
+client.internet.speed
+
+# Ports
+client.ports.all
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.devices.all
+rescue Keenetic::AuthenticationError
+  # invalid credentials
+rescue Keenetic::ConnectionError
+  # router unreachable
+rescue Keenetic::TimeoutError
+  # request timed out
+rescue Keenetic::NotFoundError
+  # resource not found
+rescue Keenetic::ApiError => e
+  # Other API errors
+  e.status_code
+  e.response_body
+end
+```
+
+## API Reference
+
+See [KEENETIC_API.md](KEENETIC_API.md) for complete API documentation.
+
+## Requirements
+
+- Ruby >= 3.0
+
+## License
+
+MIT

data/lib/keenetic/client.rb

@@ -0,0 +1,361 @@
+require 'typhoeus'
+require 'json'
+require 'digest'
+
+module Keenetic
+  # HTTP client for Keenetic router API.
+  #
+  # == Authentication Flow
+  # Keenetic uses a challenge-response authentication mechanism:
+  #
+  #   Step 1: GET /auth
+  #           Response: HTTP 401 with headers X-NDM-Challenge and X-NDM-Realm
+  #           Also sets session cookie
+  #
+  #   Step 2: Calculate authentication hash
+  #           md5_hash = MD5(login + ":" + realm + ":" + password)
+  #           auth_hash = SHA256(challenge + md5_hash)
+  #
+  #   Step 3: POST /auth
+  #           Body: {"login": "admin", "password": "<auth_hash>"}
+  #           Response: HTTP 200 on success
+  #           Session maintained via cookies
+  #
+  # == Request Types
+  #
+  # === Reading Data (GET)
+  #   GET /rci/show/<path>
+  #   Example: GET /rci/show/system, GET /rci/show/ip/hotspot
+  #
+  # === Writing Data (POST - Batch Format)
+  #   POST /rci/
+  #   Body: Array of commands (MUST be array, even for single command)
+  #   Example: [{"ip":{"hotspot":{"host":{"mac":"aa:bb:cc:dd:ee:ff","permit":true}}}}]
+  #
+  # == Thread Safety
+  # The client uses a mutex to prevent concurrent authentication attempts.
+  # Resource instances are memoized and thread-safe for reading.
+  #
+  class Client
+    attr_reader :config
+
+    # Create a new client instance.
+    #
+    # @param config [Configuration, nil] Optional configuration (uses global if nil)
+    # @raise [ConfigurationError] if configuration is invalid
+    #
+    def initialize(config = nil)
+      @config = config || Keenetic.configuration
+      @config.validate!
+      @cookies = {}
+      @authenticated = false
+      @mutex = Mutex.new
+    end
+
+    # @return [Resources::Devices] Device management resource
+    def devices
+      @devices ||= Resources::Devices.new(self)
+    end
+
+    # @return [Resources::System] System information resource
+    def system
+      @system ||= Resources::System.new(self)
+    end
+
+    # @return [Resources::Network] Network interfaces resource
+    def network
+      @network ||= Resources::Network.new(self)
+    end
+
+    # @return [Resources::WiFi] Wi-Fi resource
+    def wifi
+      @wifi ||= Resources::WiFi.new(self)
+    end
+
+    # @return [Resources::Internet] Internet status resource
+    def internet
+      @internet ||= Resources::Internet.new(self)
+    end
+
+    # @return [Resources::Ports] Physical ports resource
+    def ports
+      @ports ||= Resources::Ports.new(self)
+    end
+
+    # @return [Resources::Policies] Routing policies resource
+    def policies
+      @policies ||= Resources::Policies.new(self)
+    end
+
+    # @return [Resources::DHCP] DHCP resource
+    def dhcp
+      @dhcp ||= Resources::DHCP.new(self)
+    end
+
+    # @return [Resources::Routing] Routing resource
+    def routing
+      @routing ||= Resources::Routing.new(self)
+    end
+
+    # @return [Resources::Logs] System logs resource
+    def logs
+      @logs ||= Resources::Logs.new(self)
+    end
+
+    # Make a GET request to the router API.
+    #
+    # == Keenetic API
+    #   GET http://<host>/rci/show/<path>
+    #
+    # @param path [String] API path (e.g., '/rci/show/system')
+    # @param params [Hash] Optional query parameters
+    # @return [Hash, Array, nil] Parsed JSON response
+    #
+    def get(path, params = {})
+      request(:get, path, params: params)
+    end
+
+    # Make a POST request to the router API.
+    #
+    # == Keenetic API
+    #   POST http://<host>/rci/<path>
+    #   Content-Type: application/json
+    #
+    # @param path [String] API path
+    # @param body [Hash] Request body (will be JSON encoded)
+    # @return [Hash, Array, nil] Parsed JSON response
+    #
+    def post(path, body = {})
+      request(:post, path, body: body)
+    end
+
+    # Execute multiple commands in a single batch request.
+    #
+    # == Keenetic API
+    #   POST http://<host>/rci/
+    #   Content-Type: application/json
+    #   Body: Array of command objects
+    #
+    # == Important
+    # All write operations to Keenetic MUST use batch format (array).
+    # Even single commands must be wrapped in an array.
+    #
+    # @param commands [Array<Hash>] Array of command hashes
+    # @return [Array] Array of responses in the same order as commands
+    # @raise [ArgumentError] if commands is not a non-empty array
+    #
+    # @example Read multiple values
+    #   client.batch([
+    #     { 'show' => { 'system' => {} } },
+    #     { 'show' => { 'version' => {} } }
+    #   ])
+    #
+    # @example Write command (update device)
+    #   client.batch([
+    #     { 'known' => { 'host' => { 'mac' => 'aa:bb:cc:dd:ee:ff', 'name' => 'My Device' } } }
+    #   ])
+    #
+    def batch(commands)
+      raise ArgumentError, 'Commands must be an array' unless commands.is_a?(Array)
+      raise ArgumentError, 'Commands array cannot be empty' if commands.empty?
+
+      request(:post, '/rci/', body: commands)
+    end
+
+    # Check if client is authenticated.
+    # @return [Boolean]
+    def authenticated?
+      @authenticated
+    end
+
+    # Perform authentication (thread-safe).
+    #
+    # Called automatically before first request.
+    # Uses mutex to prevent concurrent authentication attempts.
+    #
+    # @return [Boolean] true on success
+    # @raise [AuthenticationError] on failure
+    # @raise [TimeoutError] if connection times out
+    # @raise [ConnectionError] if router is unreachable
+    #
+    def authenticate!
+      @mutex.synchronize do
+        return true if @authenticated
+
+        perform_authentication
+      end
+    end
+
+    private
+
+    def request(method, path, options = {})
+      authenticate! unless @authenticated || path == '/auth'
+
+      url = "#{config.base_url}#{path}"
+      
+      request_options = {
+        method: method,
+        timeout: config.timeout,
+        connecttimeout: config.open_timeout,
+        headers: build_headers,
+        accept_encoding: 'gzip'
+      }
+
+      if options[:params] && !options[:params].empty?
+        url += "?#{URI.encode_www_form(options[:params])}"
+      end
+
+      if options[:body]
+        request_options[:body] = options[:body].to_json
+        request_options[:headers]['Content-Type'] = 'application/json'
+      end
+
+      config.logger.debug { "Keenetic: #{method.upcase} #{url}" }
+
+      response = Typhoeus::Request.new(url, request_options).run
+
+      handle_response(response)
+    end
+
+    def build_headers
+      headers = {
+        'Accept' => 'application/json',
+        'User-Agent' => "Keenetic Ruby Client/#{VERSION}"
+      }
+      
+      headers['Cookie'] = format_cookies unless @cookies.empty?
+      headers
+    end
+
+    def format_cookies
+      @cookies.map { |k, v| "#{k}=#{v}" }.join('; ')
+    end
+
+    def parse_cookies(response)
+      return unless response.headers
+
+      set_cookie_headers = response.headers['Set-Cookie']
+      return unless set_cookie_headers
+
+      cookies = set_cookie_headers.is_a?(Array) ? set_cookie_headers : [set_cookie_headers]
+      
+      cookies.each do |cookie|
+        parts = cookie.split(';').first
+        next unless parts
+
+        name, value = parts.split('=', 2)
+        @cookies[name.strip] = value&.strip if name
+      end
+    end
+
+    def handle_response(response)
+      parse_cookies(response)
+
+      if response.timed_out?
+        raise TimeoutError, "Request timed out after #{config.timeout}s"
+      end
+
+      if response.code == 0
+        raise ConnectionError, "Connection failed: #{response.return_message}"
+      end
+
+      unless response.success? || response.code == 401
+        if response.code == 404
+          raise NotFoundError, "Resource not found"
+        end
+        raise ApiError.new(
+          "API request failed with status #{response.code}",
+          status_code: response.code,
+          response_body: response.body
+        )
+      end
+
+      return nil if response.body.nil? || response.body.empty?
+
+      begin
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        response.body
+      end
+    end
+
+    def perform_authentication
+      # Step 1: Get challenge from router
+      url = "#{config.base_url}/auth"
+      
+      challenge_response = Typhoeus::Request.new(url, {
+        method: :get,
+        timeout: config.timeout,
+        connecttimeout: config.open_timeout,
+        headers: { 'Accept' => 'application/json' }
+      }).run
+
+      if challenge_response.timed_out?
+        raise TimeoutError, auth_error_context("Authentication timed out after #{config.timeout}s")
+      end
+
+      if challenge_response.code == 0
+        raise ConnectionError, auth_error_context("Connection failed: #{challenge_response.return_message}")
+      end
+
+      parse_cookies(challenge_response)
+
+      # If already authenticated (returns 200), we're done
+      if challenge_response.code == 200
+        @authenticated = true
+        config.logger.info { "Keenetic: Already authenticated" }
+        return true
+      end
+
+      unless challenge_response.code == 401
+        raise AuthenticationError, auth_error_context("Unexpected response: HTTP #{challenge_response.code}")
+      end
+
+      headers = challenge_response.headers || {}
+      challenge = headers['X-NDM-Challenge']
+      realm = headers['X-NDM-Realm']
+
+      unless challenge && realm
+        raise AuthenticationError, auth_error_context("Missing challenge headers from router")
+      end
+
+      config.logger.debug { "Keenetic: Got challenge, realm=#{realm}" }
+
+      # Step 2: Calculate authentication hash
+      # MD5(login:realm:password) -> then SHA256(challenge + md5_hash)
+      md5_hash = Digest::MD5.hexdigest("#{config.login}:#{realm}:#{config.password}")
+      auth_hash = Digest::SHA256.hexdigest("#{challenge}#{md5_hash}")
+
+      # Step 3: Send authentication request
+      auth_response = Typhoeus::Request.new(url, {
+        method: :post,
+        timeout: config.timeout,
+        connecttimeout: config.open_timeout,
+        headers: build_headers.merge('Content-Type' => 'application/json'),
+        body: { login: config.login, password: auth_hash }.to_json
+      }).run
+
+      parse_cookies(auth_response)
+
+      if auth_response.code == 200
+        @authenticated = true
+        config.logger.info { "Keenetic: Authentication successful" }
+        true
+      else
+        raise AuthenticationError, auth_error_context("Authentication failed: HTTP #{auth_response.code}")
+      end
+    end
+
+    def auth_error_context(message)
+      details = [
+        message,
+        "host=#{config.host}",
+        "login=#{config.login}",
+        "timeout=#{config.timeout}s",
+        "connect_timeout=#{config.open_timeout}s"
+      ]
+      details.join(' | ')
+    end
+  end
+end
+

data/lib/keenetic/configuration.rb

@@ -0,0 +1,27 @@
+require 'logger'
+
+module Keenetic
+  class Configuration
+    attr_accessor :host, :login, :password, :timeout, :open_timeout, :logger
+
+    def initialize
+      @host = nil
+      @login = nil
+      @password = nil
+      @timeout = 30
+      @open_timeout = 10
+      @logger = Logger.new(nil)
+    end
+
+    def base_url
+      "http://#{host}"
+    end
+
+    def validate!
+      raise ConfigurationError, 'Host is required' if host.nil? || host.empty?
+      raise ConfigurationError, 'Login is required' if login.nil? || login.empty?
+      raise ConfigurationError, 'Password is required' if password.nil? || password.empty?
+    end
+  end
+end
+

data/lib/keenetic/errors.rb

@@ -0,0 +1,19 @@
+module Keenetic
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+  class AuthenticationError < Error; end
+  class ConnectionError < Error; end
+  class TimeoutError < Error; end
+  class NotFoundError < Error; end
+  class ApiError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code: nil, response_body: nil)
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+    end
+  end
+end
+

data/lib/keenetic/resources/base.rb

@@ -0,0 +1,76 @@
+module Keenetic
+  module Resources
+    class Base
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      protected
+
+      def get(path, params = {})
+        client.get(path, params)
+      end
+
+      def post(path, body = {})
+        client.post(path, body)
+      end
+
+      # Convert kebab-case keys to snake_case symbols
+      # @param hash [Hash] Hash with string keys
+      # @return [Hash] Hash with symbolized snake_case keys
+      def normalize_keys(hash)
+        return {} unless hash.is_a?(Hash)
+
+        hash.transform_keys { |key| key.to_s.tr('-', '_').to_sym }
+      end
+
+      # Deep normalize keys in a hash (recursive)
+      # @param obj [Hash, Array, Object] Object to normalize
+      # @return [Hash, Array, Object] Normalized object
+      def deep_normalize_keys(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(key, value), result|
+            new_key = key.to_s.tr('-', '_').to_sym
+            result[new_key] = deep_normalize_keys(value)
+          end
+        when Array
+          obj.map { |item| deep_normalize_keys(item) }
+        else
+          obj
+        end
+      end
+
+      # Normalize boolean values from various formats
+      # API may return true/false or "true"/"false" strings
+      # @param value [Object] Value to normalize
+      # @return [Boolean, Object] Normalized boolean or original value
+      def normalize_boolean(value)
+        case value
+        when true, 'true', 'yes', '1', 1
+          true
+        when false, 'false', 'no', '0', 0
+          false
+        else
+          value
+        end
+      end
+
+      # Normalize all boolean values in a hash
+      # @param hash [Hash] Hash with potential boolean values
+      # @param keys [Array<Symbol>] Keys to normalize as booleans
+      # @return [Hash] Hash with normalized boolean values
+      def normalize_booleans(hash, keys)
+        return hash unless hash.is_a?(Hash)
+
+        keys.each do |key|
+          hash[key] = normalize_boolean(hash[key]) if hash.key?(key)
+        end
+        hash
+      end
+    end
+  end
+end
+