keenetic 0.2.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fa7552177bec3d537db352ed748bcd24e07bee6156272569a121b7cb18c6a2f
-  data.tar.gz: e48b1c10d4cc62466ebd5e34b200f399e28e8261e0e1a83a1a4b1ee86efc4ee3
+  metadata.gz: 55da30f5dcac15dad86d5d93cd6dd35cd8d9f63ee2dfb63f73a8e8b32d66a4bb
+  data.tar.gz: 7be5b4c51ca2b764c7bc2cc68e1bb69402377d3c19106f0e288a15103847bbcd
 SHA512:
-  metadata.gz: f801f8df36437d0f2ea76f6765beaeee3a68750b2974b8b3fc4eed9145be5a5c123940245b56566c690ef906d791eaf8223ae3f016b4bb0472c1a2a3476f77df
-  data.tar.gz: 984b84f49fb83117ab0c9c89b60a0b88718ccbbd92258c69987be8103bec4d2fd66554c4413c001e45167396735c634a578e839c35cce74b0124d2d3c829f930
+  metadata.gz: 655fd847b64bec33b24534d23d8f7459cad8cede50af9e78b5289f615612e334b8bf53e74990569d52e3ee6276ac49e01e83894b35c4fd64c8a8418668fd17da
+  data.tar.gz: 14e3d21ee47872269d4a13bb0794e06d9926eb111e919788122cc76f6d2a6f7cb9af225c39cb9e397883c1194b3e32faa53e7fc58f8619f2bf2314c2052c0f13

data/README.md

@@ -20,62 +20,48 @@ Keenetic.configure do |config|
 end
 ```
 
-## Usage
+## Quick Start
 
 ```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
+client.system.info              # model, firmware
+client.system.resources         # CPU, memory, uptime
+
+# Connected devices
+client.devices.all              # all registered devices
+client.devices.active           # currently connected
 
 # Network
-client.network.interfaces
-
-# WiFi
-client.wifi.access_points
-client.wifi.clients
-
-# Internet
-client.internet.status
-client.internet.speed
-
-# Ports
-client.ports.all
-
-# Static Routes
-client.routes.all
-client.routes.add(host: '1.2.3.4', interface: 'Wireguard0', comment: 'VPN host')
-client.routes.add(network: '10.0.0.0/24', interface: 'Wireguard0', comment: 'VPN network')
-client.routes.add_batch([
-  { host: '1.2.3.4', interface: 'Wireguard0', comment: 'Host 1' },
-  { network: '10.0.0.0/24', interface: 'Wireguard0', comment: 'Network 1' }
-])
-client.routes.delete(host: '1.2.3.4')
-client.routes.delete(network: '10.0.0.0/24')
-
-# Hotspot / Policies
-client.hotspot.policies                                         # all IP policies
-client.hotspot.hosts                                            # all registered hosts
-client.hotspot.set_host_policy(mac: 'AA:BB:CC:DD:EE:FF', policy: 'Policy0')
-client.hotspot.set_host_policy(mac: 'AA:BB:CC:DD:EE:FF', policy: nil)  # remove policy
+client.network.interfaces       # all interfaces
+client.wifi.access_points       # Wi-Fi networks
+client.internet.status          # internet connectivity
+
+# Static routes
+client.routes.all               # configured static routes
+client.routes.add(network: '10.0.0.0/24', interface: 'Wireguard0', comment: 'VPN')
+
+# DNS-based routes
+client.dns_routes.domain_groups # FQDN domain groups
+client.dns_routes.routes        # DNS-based route mappings
+client.dns_routes.create_domain_group(name: 'domain-list0', description: 'YouTube',
+                                      domains: ['youtube.com', 'googlevideo.com'])
+client.dns_routes.add_route(group: 'domain-list0', interface: 'Wireguard0')
+client.dns_routes.delete_route(index: 'abc123...')
+
+# Port forwarding
+client.nat.rules                # NAT rules
+client.nat.add_forward(index: 1, protocol: 'tcp', port: 8080,
+                       to_host: '192.168.1.100', to_port: 80)
+
+# VPN
+client.vpn.status               # VPN server status
+client.vpn.clients              # connected VPN clients
 
 # Configuration
 client.system_config.save       # save to flash
-client.system_config.download   # download startup-config.txt
-
-# Raw RCI Access (for custom commands)
-client.rci({ 'show' => { 'system' => {} } })
-client.rci([
-  { 'show' => { 'system' => {} } },
-  { 'show' => { 'version' => {} } }
-])
+client.system_config.download   # backup config
 ```
 
 ## Error Handling
@@ -89,18 +75,18 @@ rescue Keenetic::ConnectionError
   # router unreachable
 rescue Keenetic::TimeoutError
   # request timed out
-rescue Keenetic::NotFoundError
-  # resource not found
 rescue Keenetic::ApiError => e
-  # Other API errors
+  # other API errors
   e.status_code
   e.response_body
 end
 ```
 
-## API Reference
+## Documentation
 
-See [KEENETIC_API.md](KEENETIC_API.md) for complete API documentation.
+- [Complete API Reference](docs/API_REFERENCE.md) - All features with detailed examples
+- [API Coverage](API_PROGRESS.md) - Implementation status
+- [Keenetic API Specification](KEENETIC_API.md) - Raw API documentation
 
 ## Requirements
 

data/lib/keenetic/client.rb

@@ -117,6 +117,76 @@ module Keenetic
       @system_config ||= Resources::Config.new(self)
     end
 
+    # @return [Resources::Nat] NAT and port forwarding resource
+    def nat
+      @nat ||= Resources::Nat.new(self)
+    end
+
+    # @return [Resources::Vpn] VPN server resource
+    def vpn
+      @vpn ||= Resources::Vpn.new(self)
+    end
+
+    # @return [Resources::Diagnostics] Network diagnostics resource
+    def diagnostics
+      @diagnostics ||= Resources::Diagnostics.new(self)
+    end
+
+    # @return [Resources::Firewall] Firewall resource
+    def firewall
+      @firewall ||= Resources::Firewall.new(self)
+    end
+
+    # @return [Resources::Mesh] Mesh Wi-Fi system resource
+    def mesh
+      @mesh ||= Resources::Mesh.new(self)
+    end
+
+    # @return [Resources::Usb] USB devices and storage resource
+    def usb
+      @usb ||= Resources::Usb.new(self)
+    end
+
+    # @return [Resources::Dns] DNS settings and cache resource
+    def dns
+      @dns ||= Resources::Dns.new(self)
+    end
+
+    # @return [Resources::Dyndns] Dynamic DNS resource
+    def dyndns
+      @dyndns ||= Resources::Dyndns.new(self)
+    end
+
+    # @return [Resources::Schedule] Access schedules resource
+    def schedule
+      @schedule ||= Resources::Schedule.new(self)
+    end
+
+    # @return [Resources::Users] User accounts resource
+    def users
+      @users ||= Resources::Users.new(self)
+    end
+
+    # @return [Resources::Components] System components resource
+    def components
+      @components ||= Resources::Components.new(self)
+    end
+
+    # @return [Resources::Qos] QoS and traffic control resource
+    def qos
+      @qos ||= Resources::Qos.new(self)
+    end
+
+    # @return [Resources::Ipv6] IPv6 network resource
+    def ipv6
+      @ipv6 ||= Resources::Ipv6.new(self)
+    end
+
+    # @return [Resources::DnsRoutes] DNS-based routes and FQDN domain groups resource
+    def dns_routes
+      @dns_routes ||= Resources::DnsRoutes.new(self)
+    end
+
     # Execute arbitrary RCI command(s).
     #
     # Provides raw access to the Keenetic RCI (Remote Command Interface).
@@ -211,6 +281,19 @@ module Keenetic
       request(:post, '/rci/', body: commands)
     end
 
+    # Make a POST request with raw body content (non-JSON).
+    #
+    # Used for file uploads like configuration restore.
+    #
+    # @param path [String] API path
+    # @param content [String] Raw content to send
+    # @param content_type [String] Content-Type header (default: text/plain)
+    # @return [String, nil] Response body
+    #
+    def post_raw(path, content, content_type: 'text/plain')
+      request(:post, path, raw_body: content, content_type: content_type)
+    end
+
     # Check if client is authenticated.
     # @return [Boolean]
     def authenticated?
@@ -240,6 +323,25 @@ module Keenetic
     def request(method, path, options = {})
       authenticate! unless @authenticated || path == '/auth'
 
+      response = execute_request(method, path, options)
+
+      # Handle 401 by re-authenticating and retrying once
+      if response.code == 401 && path != '/auth'
+        config.logger.debug { "Keenetic: Got 401, re-authenticating..." }
+        @authenticated = false
+        @mutex.synchronize { perform_authentication }
+        
+        response = execute_request(method, path, options)
+        
+        if response.code == 401
+          raise AuthenticationError, "Request unauthorized after re-authentication (HTTP 401)"
+        end
+      end
+
+      handle_response(response)
+    end
+
+    def execute_request(method, path, options)
       url = "#{config.base_url}#{path}"
       
       request_options = {
@@ -254,16 +356,17 @@ module Keenetic
         url += "?#{URI.encode_www_form(options[:params])}"
       end
 
-      if options[:body]
+      if options[:raw_body]
+        request_options[:body] = options[:raw_body]
+        request_options[:headers]['Content-Type'] = options[:content_type] || 'text/plain'
+      elsif 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)
+      Typhoeus::Request.new(url, request_options).run
     end
 
     def build_headers
@@ -297,7 +400,7 @@ module Keenetic
       end
     end
 
-    def handle_response(response)
+    def handle_response(response, allow_401: false)
       parse_cookies(response)
 
       if response.timed_out?
@@ -308,7 +411,7 @@ module Keenetic
         raise ConnectionError, "Connection failed: #{response.return_message}"
       end
 
-      unless response.success? || response.code == 401
+      unless response.success? || (allow_401 && response.code == 401)
         if response.code == 404
           raise NotFoundError, "Resource not found"
         end

data/lib/keenetic/resources/base.rb

@@ -17,6 +17,10 @@ module Keenetic
         client.post(path, body)
       end
 
+      def post_raw(path, content, content_type: 'text/plain')
+        client.post_raw(path, content, content_type: content_type)
+      end
+
       # Convert kebab-case keys to snake_case symbols
       # @param hash [Hash] Hash with string keys
       # @return [Hash] Hash with symbolized snake_case keys

data/lib/keenetic/resources/components.rb

@@ -0,0 +1,88 @@
+module Keenetic
+  module Resources
+    # Components resource for managing installable router components.
+    #
+    # == API Endpoints Used
+    #
+    # === Installed Components
+    #   GET /rci/show/components
+    #
+    # === Available Components
+    #   GET /rci/show/components/available
+    #
+    # === Install Component
+    #   POST /rci/components/install
+    #
+    # === Remove Component
+    #   POST /rci/components/remove
+    #
+    class Components < Base
+      # Get installed components.
+      #
+      # @return [Array<Hash>] List of installed components
+      # @example
+      #   installed = client.components.installed
+      #
+      def installed
+        response = get('/rci/show/components')
+        normalize_components(response)
+      end
+
+      # Get available components for installation.
+      #
+      # @return [Array<Hash>] List of available components
+      # @example
+      #   available = client.components.available
+      #
+      def available
+        response = get('/rci/show/components/available')
+        normalize_components(response)
+      end
+
+      # Install a component.
+      #
+      # @param name [String] Component name
+      # @return [Hash, nil] API response
+      # @example
+      #   client.components.install(name: 'transmission')
+      #
+      def install(name:)
+        post('/rci/components/install', { 'name' => name })
+      end
+
+      # Remove a component.
+      #
+      # @param name [String] Component name
+      # @return [Hash, nil] API response
+      # @example
+      #   client.components.remove(name: 'transmission')
+      #
+      def remove(name:)
+        post('/rci/components/remove', { 'name' => name })
+      end
+
+      private
+
+      def normalize_components(response)
+        components_data = case response
+                          when Array
+                            response
+                          when Hash
+                            response['component'] || response['components'] || []
+                          else
+                            []
+                          end
+
+        return [] unless components_data.is_a?(Array)
+
+        components_data.map { |component| normalize_component(component) }.compact
+      end
+
+      def normalize_component(data)
+        return nil unless data.is_a?(Hash)
+
+        deep_normalize_keys(data)
+      end
+    end
+  end
+end

data/lib/keenetic/resources/config.rb

@@ -13,6 +13,11 @@ module Keenetic
     #   GET /ci/startup-config.txt
     #   Returns: Plain text configuration file
     #
+    # === Upload Configuration
+    #   POST /ci/startup-config.txt
+    #   Body: Plain text configuration file
+    #   Restores configuration from backup
+    #
     class Config < Base
       # Save current configuration to persistent storage.
       #
@@ -42,12 +47,43 @@ module Keenetic
       #
       # @return [String] Configuration file content
       # @example
-      #   config_text = client.config.download
+      #   config_text = client.system_config.download
       #   File.write('router-backup.txt', config_text)
       #
       def download
         get('/ci/startup-config.txt')
       end
+
+      # Upload and restore a configuration file.
+      #
+      # == Keenetic API Request
+      #   POST /ci/startup-config.txt
+      #   Content-Type: text/plain
+      #   Body: Configuration file content
+      #
+      # Uploads a configuration file to the router. The configuration
+      # will be applied after a reboot.
+      #
+      # == Warning
+      # This is a potentially destructive operation. Uploading an
+      # invalid or incompatible configuration may make the router
+      # inaccessible. Always ensure you have physical access to the
+      # router before restoring configuration.
+      #
+      # @param content [String] Configuration file content
+      # @return [String, nil] Response from the router
+      # @example Upload from string
+      #   client.system_config.upload(config_text)
+      #
+      # @example Upload from file
+      #   config_text = File.read('router-backup.txt')
+      #   client.system_config.upload(config_text)
+      #
+      def upload(content)
+        raise ArgumentError, 'Configuration content cannot be empty' if content.nil? || content.strip.empty?
+
+        post_raw('/ci/startup-config.txt', content)
+      end
     end
   end
 end

data/lib/keenetic/resources/diagnostics.rb

@@ -0,0 +1,102 @@
+module Keenetic
+  module Resources
+    # Diagnostics resource for network troubleshooting tools.
+    #
+    # == API Endpoints Used
+    #
+    # === Ping
+    #   POST /rci/tools/ping
+    #   Body: { host, count }
+    #
+    # === Traceroute
+    #   POST /rci/tools/traceroute
+    #   Body: { host }
+    #
+    # === DNS Lookup
+    #   POST /rci/tools/nslookup
+    #   Body: { host }
+    #
+    class Diagnostics < Base
+      # Ping a host from the router.
+      #
+      # == Keenetic API Request
+      #   POST /rci/tools/ping
+      #   Body: { "host": "8.8.8.8", "count": 4 }
+      #
+      # @param host [String] Hostname or IP address to ping
+      # @param count [Integer] Number of ping packets (default: 4)
+      # @return [Hash] Ping results
+      #
+      # @example Ping Google DNS
+      #   result = client.diagnostics.ping('8.8.8.8')
+      #   # => { host: "8.8.8.8", transmitted: 4, received: 4, loss: 0, ... }
+      #
+      # @example Ping with custom count
+      #   result = client.diagnostics.ping('google.com', count: 10)
+      #
+      def ping(host, count: 4)
+        response = post('/rci/tools/ping', { 'host' => host, 'count' => count })
+        normalize_ping_result(response)
+      end
+
+      # Trace route to a host from the router.
+      #
+      # == Keenetic API Request
+      #   POST /rci/tools/traceroute
+      #   Body: { "host": "google.com" }
+      #
+      # @param host [String] Hostname or IP address to trace
+      # @return [Hash] Traceroute results with hops
+      #
+      # @example Trace route to Google
+      #   result = client.diagnostics.traceroute('google.com')
+      #   # => { host: "google.com", hops: [{ hop: 1, ip: "192.168.1.1", time: 1 }, ...] }
+      #
+      def traceroute(host)
+        response = post('/rci/tools/traceroute', { 'host' => host })
+        normalize_traceroute_result(response)
+      end
+
+      # Perform DNS lookup from the router.
+      #
+      # == Keenetic API Request
+      #   POST /rci/tools/nslookup
+      #   Body: { "host": "google.com" }
+      #
+      # @param host [String] Hostname to resolve
+      # @return [Hash] DNS lookup results
+      #
+      # @example Lookup Google
+      #   result = client.diagnostics.nslookup('google.com')
+      #   # => { host: "google.com", addresses: ["142.250.185.46", ...], ... }
+      #
+      def nslookup(host)
+        response = post('/rci/tools/nslookup', { 'host' => host })
+        normalize_nslookup_result(response)
+      end
+
+      # Alias for nslookup
+      alias dns_lookup nslookup
+
+      private
+
+      def normalize_ping_result(response)
+        return {} unless response.is_a?(Hash)
+
+        deep_normalize_keys(response)
+      end
+
+      def normalize_traceroute_result(response)
+        return {} unless response.is_a?(Hash)
+
+        deep_normalize_keys(response)
+      end
+
+      def normalize_nslookup_result(response)
+        return {} unless response.is_a?(Hash)
+
+        deep_normalize_keys(response)
+      end
+    end
+  end
+end

data/lib/keenetic/resources/dns.rb

@@ -0,0 +1,95 @@
+module Keenetic
+  module Resources
+    # DNS resource for managing DNS settings and cache.
+    #
+    # == API Endpoints Used
+    #
+    # === Reading DNS Servers
+    #   GET /rci/show/ip/name-server
+    #   Returns: Configured DNS servers
+    #
+    # === Reading DNS Cache
+    #   GET /rci/show/dns/cache
+    #   Returns: DNS cache entries
+    #
+    # === Reading DNS Proxy Settings
+    #   GET /rci/show/dns/proxy
+    #   Returns: DNS proxy configuration
+    #
+    # === Clear DNS Cache
+    #   POST /rci/dns/cache/clear
+    #   Body: {}
+    #
+    class Dns < Base
+      # Get configured DNS servers.
+      #
+      # == Keenetic API Request
+      #   GET /rci/show/ip/name-server
+      #
+      # @return [Hash] DNS servers configuration
+      # @example
+      #   servers = client.dns.servers
+      #
+      def servers
+        response = get('/rci/show/ip/name-server')
+        normalize_response(response)
+      end
+
+      # Alias for servers
+      alias name_servers servers
+
+      # Get DNS cache entries.
+      #
+      # == Keenetic API Request
+      #   GET /rci/show/dns/cache
+      #
+      # @return [Hash] DNS cache data
+      # @example
+      #   cache = client.dns.cache
+      #
+      def cache
+        response = get('/rci/show/dns/cache')
+        normalize_response(response)
+      end
+
+      # Get DNS proxy settings.
+      #
+      # == Keenetic API Request
+      #   GET /rci/show/dns/proxy
+      #
+      # @return [Hash] DNS proxy configuration
+      # @example
+      #   proxy = client.dns.proxy
+      #
+      def proxy
+        response = get('/rci/show/dns/proxy')
+        normalize_response(response)
+      end
+
+      # Alias for proxy
+      alias proxy_settings proxy
+
+      # Clear DNS cache.
+      #
+      # == Keenetic API Request
+      #   POST /rci/dns/cache/clear
+      #   Body: {}
+      #
+      # @return [Hash, nil] API response
+      # @example
+      #   client.dns.clear_cache
+      #
+      def clear_cache
+        post('/rci/dns/cache/clear', {})
+      end
+
+      private
+
+      def normalize_response(response)
+        return {} unless response.is_a?(Hash)
+
+        deep_normalize_keys(response)
+      end
+    end
+  end
+end