keenetic 0.1.0 → 1.0.0

checksums.yaml

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Anton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -20,34 +20,36 @@ 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
-
-# Network
-client.network.interfaces
+client.system.info              # model, firmware
+client.system.resources         # CPU, memory, uptime
 
-# WiFi
-client.wifi.access_points
-client.wifi.clients
-
-# Internet
-client.internet.status
-client.internet.speed
+# Connected devices
+client.devices.all              # all registered devices
+client.devices.active           # currently connected
 
-# Ports
-client.ports.all
+# Network
+client.network.interfaces       # all interfaces
+client.wifi.access_points       # Wi-Fi networks
+client.internet.status          # internet connectivity
+
+# 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   # backup config
 ```
 
 ## Error Handling
@@ -61,18 +63,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

@@ -102,6 +102,120 @@ module Keenetic
       @logs ||= Resources::Logs.new(self)
     end
 
+    # @return [Resources::Routes] Static routes resource
+    def routes
+      @routes ||= Resources::Routes.new(self)
+    end
+
+    # @return [Resources::Hotspot] Hotspot hosts and policies resource
+    def hotspot
+      @hotspot ||= Resources::Hotspot.new(self)
+    end
+
+    # @return [Resources::Config] Configuration management resource
+    def system_config
+      @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
+
+    # Execute arbitrary RCI command(s).
+    #
+    # Provides raw access to the Keenetic RCI (Remote Command Interface).
+    # Use this for custom commands not covered by the gem's resources.
+    #
+    # == Keenetic API
+    #   POST http://<host>/rci/
+    #   Content-Type: application/json
+    #   Body: Array or Hash of RCI commands
+    #
+    # @param body [Hash, Array<Hash>] RCI command(s) to execute
+    # @return [Hash, Array, nil] Parsed JSON response
+    #
+    # @example Execute single command
+    #   client.rci({ 'show' => { 'system' => {} } })
+    #   # => { "show" => { "system" => { ... } } }
+    #
+    # @example Execute batch commands
+    #   client.rci([
+    #     { 'show' => { 'system' => {} } },
+    #     { 'show' => { 'version' => {} } }
+    #   ])
+    #   # => [{ "show" => { "system" => { ... } } }, { "show" => { "version" => { ... } } }]
+    #
+    # @example Execute write command
+    #   client.rci([
+    #     { 'ip' => { 'hotspot' => { 'host' => { 'mac' => 'aa:bb:cc:dd:ee:ff', 'permit' => true } } } }
+    #   ])
+    #
+    def rci(body)
+      commands = body.is_a?(Array) ? body : [body]
+      batch(commands)
+    end
+
     # Make a GET request to the router API.
     #
     # == Keenetic API
@@ -162,6 +276,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?
@@ -205,7 +332,10 @@ 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

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

@@ -0,0 +1,89 @@
+module Keenetic
+  module Resources
+    # Manages router configuration operations.
+    #
+    # == API Endpoints Used
+    #
+    # === Save Configuration
+    #   POST /rci/ (batch format)
+    #   Body: [{"system": {"configuration": {"save": {}}}}]
+    #   Saves current configuration to persistent storage
+    #
+    # === Download Configuration
+    #   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.
+      #
+      # == Keenetic API Request
+      #   POST /rci/ (batch format)
+      #   Body: [{"system": {"configuration": {"save": {}}}}]
+      #
+      # Configuration changes are typically auto-saved, but this method
+      # forces an immediate save to flash storage.
+      #
+      # @return [Array<Hash>] API response
+      # @example
+      #   client.config.save
+      #   # => [{ "system" => { "configuration" => { "save" => {} } } }]
+      #
+      def save
+        client.batch([{ 'system' => { 'configuration' => { 'save' => {} } } }])
+      end
+
+      # Download the startup configuration file.
+      #
+      # == Keenetic API Request
+      #   GET /ci/startup-config.txt
+      #
+      # Returns the full router configuration as a text file.
+      # This is the same format used for backup/restore operations.
+      #
+      # @return [String] Configuration file content
+      # @example
+      #   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