keenetic 0.1.0

data/lib/keenetic/resources/policies.rb

@@ -0,0 +1,171 @@
+module Keenetic
+  module Resources
+    # Manages routing policies (VPN policies, traffic routing rules).
+    #
+    # Policies allow routing specific devices through VPN tunnels or other interfaces.
+    #
+    # == API Endpoints Used
+    #
+    # === Reading Policies
+    #   POST /rci/ (batch request)
+    #   Body: [{"show":{"sc":{"ip":{"policy":{}}}}}]
+    #
+    # === Reading Device-Policy Assignments
+    #   POST /rci/ (batch request)
+    #   Body: [{"show":{"sc":{"ip":{"hotspot":{"host":{}}}}}}]
+    #
+    # == Policy Structure
+    # Policies are identified by IDs like "Policy0", "Policy1", etc.
+    # Each policy has:
+    #   - description: Name prefixed with "!" (e.g., "!Latvia VPN")
+    #   - permit: Array of interfaces this policy routes through
+    #
+    # == Example Response from API
+    #   {
+    #     "show": {
+    #       "sc": {
+    #         "ip": {
+    #           "policy": {
+    #             "Policy0": {
+    #               "description": "!Latvia",
+    #               "permit": [
+    #                 { "interface": "Wireguard0", "enabled": true },
+    #                 { "interface": "ISP", "enabled": false }
+    #               ]
+    #             }
+    #           }
+    #         }
+    #       }
+    #     }
+    #   }
+    #
+    class Policies < Base
+      # Fetch all routing policies.
+      #
+      # == Keenetic API Request
+      #   POST /rci/
+      #   Body: [{"show":{"sc":{"ip":{"policy":{}}}}}]
+      #
+      # == Response Processing
+      # - Extracts policy data from nested response structure
+      # - Filters permit list to only enabled interfaces (enabled: true, no: not true)
+      # - Removes "!" prefix from description for clean policy name
+      #
+      # @return [Array<Hash>] List of policies with :id, :description, :name, :interfaces
+      # @example
+      #   policies = client.policies.all
+      #   # => [{ id: "Policy0", description: "!Latvia", name: "Latvia",
+      #   #       interfaces: ["Wireguard0"], interface_count: 1 }]
+      #
+      def all
+        response = client.batch([
+          { 'show' => { 'sc' => { 'ip' => { 'policy' => {} } } } }
+        ])
+
+        normalize_policies(response&.first)
+      end
+
+      # Get policy assignments for all devices.
+      #
+      # == Keenetic API Request
+      #   POST /rci/
+      #   Body: [{"show":{"sc":{"ip":{"hotspot":{"host":{}}}}}}]
+      #
+      # == Response Structure
+      #   {
+      #     "show": {
+      #       "sc": {
+      #         "ip": {
+      #           "hotspot": {
+      #             "host": [
+      #               { "mac": "00:11:22:33:44:55", "policy": "Policy0" },
+      #               { "mac": "AA:BB:CC:DD:EE:FF", "policy": "Policy1" }
+      #             ]
+      #           }
+      #         }
+      #       }
+      #     }
+      #   }
+      #
+      # @return [Hash] MAC address (lowercase) => policy ID mapping
+      # @example
+      #   assignments = client.policies.device_assignments
+      #   # => { "00:11:22:33:44:55" => "Policy0", "aa:bb:cc:dd:ee:ff" => "Policy1" }
+      #
+      def device_assignments
+        response = client.batch([
+          { 'show' => { 'sc' => { 'ip' => { 'hotspot' => { 'host' => {} } } } } }
+        ])
+
+        extract_device_policies(response&.first)
+      end
+
+      # Find a specific policy by ID.
+      #
+      # @param id [String] Policy ID (e.g., "Policy0")
+      # @return [Hash] Policy data
+      # @raise [NotFoundError] if policy not found
+      # @example
+      #   policy = client.policies.find(id: 'Policy0')
+      #   # => { id: "Policy0", name: "Latvia", interfaces: ["Wireguard0"], ... }
+      #
+      def find(id:)
+        policies = all
+        policy = policies.find { |p| p[:id] == id }
+        raise NotFoundError, "Policy #{id} not found" unless policy
+        policy
+      end
+
+      private
+
+      def normalize_policies(response)
+        return [] unless response.is_a?(Hash)
+
+        policies_data = response.dig('show', 'sc', 'ip', 'policy')
+        return [] unless policies_data.is_a?(Hash)
+
+        policies_data.map do |id, data|
+          normalize_policy(id, data)
+        end
+      end
+
+      def normalize_policy(id, data)
+        return nil unless data.is_a?(Hash)
+
+        # Extract active interfaces from permit list
+        permits = data['permit'] || []
+        active_interfaces = permits
+          .select { |p| p.is_a?(Hash) && p['enabled'] == true && p['no'] != true }
+          .map { |p| p['interface'] }
+          .compact
+
+        {
+          id: id,
+          description: data['description'] || id,
+          name: extract_policy_name(data['description'] || id),
+          interfaces: active_interfaces,
+          interface_count: active_interfaces.size
+        }
+      end
+
+      def extract_policy_name(description)
+        # Remove leading "!" and clean up the name
+        name = description.to_s.sub(/^!/, '').strip
+        name.empty? ? 'Unnamed Policy' : name
+      end
+
+      def extract_device_policies(response)
+        return {} unless response.is_a?(Hash)
+
+        hosts = response.dig('show', 'sc', 'ip', 'hotspot', 'host')
+        return {} unless hosts.is_a?(Array)
+
+        hosts.each_with_object({}) do |host, mapping|
+          next unless host.is_a?(Hash) && host['policy']
+          mapping[host['mac']&.downcase] = host['policy']
+        end
+      end
+    end
+  end
+end
+

data/lib/keenetic/resources/ports.rb

@@ -0,0 +1,115 @@
+module Keenetic
+  module Resources
+    # Ports resource for accessing physical Ethernet port status.
+    #
+    # == API Endpoints Used
+    #
+    # === Reading Port Statistics
+    #   GET /rci/show/interface/stat
+    #   Filters: Physical ports only (GigabitEthernet*, FastEthernet*, SFP*, USB*)
+    #
+    # == Port Naming Convention
+    #   - GigabitEthernet0, GigabitEthernet1, etc.: Gigabit Ethernet ports
+    #   - FastEthernet0, etc.: Fast Ethernet ports (100Mbps)
+    #   - SFP0: SFP port (if available)
+    #
+    # == Link Status
+    #   - link: true = cable connected, false = no cable
+    #   - speed: Current negotiated speed (1000, 100, 10 Mbps)
+    #   - duplex: "full" or "half"
+    #
+    class Ports < Base
+      # Get all physical port statuses.
+      #
+      # == Keenetic API Request
+      #   GET /rci/show/interface/stat
+      #   Internally filters for physical ports only
+      #
+      # == Response Fields
+      #   - id: Interface ID (e.g., "GigabitEthernet0")
+      #   - port: Port number extracted from ID
+      #   - type: "gigabit", "fast", "sfp", or "usb"
+      #   - link: true if cable connected
+      #   - speed: Negotiated speed in Mbps
+      #   - duplex: "full" or "half"
+      #   - rxbytes/txbytes: Traffic counters
+      #   - rxerrors/txerrors: Error counters
+      #   - media: Media type string
+      #
+      # @return [Array<Hash>] List of physical ports with status
+      # @example
+      #   ports = client.ports.all
+      #   # => [{ id: "GigabitEthernet0", port: 0, type: "gigabit", link: true, speed: 1000, ... }]
+      #
+      def all
+        response = get('/rci/show/interface/stat')
+        normalize_ports(response)
+      end
+
+      # Get specific port by ID.
+      #
+      # @param id [String] Port interface ID (e.g., "GigabitEthernet0")
+      # @return [Hash, nil] Port data or nil if not found
+      # @example
+      #   port = client.ports.find('GigabitEthernet0')
+      #   # => { id: "GigabitEthernet0", port: 0, link: true, speed: 1000, ... }
+      #
+      def find(id)
+        all.find { |p| p[:id] == id }
+      end
+
+      private
+
+      def normalize_ports(response)
+        return [] unless response.is_a?(Hash)
+
+        response.filter_map do |id, data|
+          next unless physical_port?(id, data)
+          normalize_port(id, data)
+        end
+      end
+
+      def physical_port?(id, data)
+        return false unless data.is_a?(Hash)
+        
+        # Physical ports are typically named GigabitEthernet0, GigabitEthernet1, etc.
+        # or SFP ports, or USB ports
+        id.match?(/^(Gigabit|Fast)?Ethernet\d+|SFP|USB/)
+      end
+
+      def normalize_port(id, data)
+        {
+          id: id,
+          port: extract_port_number(id),
+          type: extract_port_type(id),
+          link: data['link'] == true,
+          speed: data['speed'],
+          duplex: data['duplex'],
+          rxbytes: data['rxbytes'],
+          txbytes: data['txbytes'],
+          rxpackets: data['rxpackets'],
+          txpackets: data['txpackets'],
+          rxerrors: data['rxerrors'],
+          txerrors: data['txerrors'],
+          media: data['media']
+        }
+      end
+
+      def extract_port_number(id)
+        match = id.match(/(\d+)$/)
+        match ? match[1].to_i : nil
+      end
+
+      def extract_port_type(id)
+        case id
+        when /GigabitEthernet/ then 'gigabit'
+        when /FastEthernet/ then 'fast'
+        when /SFP/ then 'sfp'
+        when /USB/ then 'usb'
+        else 'unknown'
+        end
+      end
+    end
+  end
+end
+

data/lib/keenetic/resources/routing.rb

@@ -0,0 +1,200 @@
+module Keenetic
+  module Resources
+    # Routing resource for managing IP routes and ARP table.
+    #
+    # == API Endpoints Used
+    #
+    # === Reading Routing Table
+    #   GET /rci/show/ip/route
+    #   Returns: Array of IP routes
+    #
+    # === Reading ARP Table
+    #   GET /rci/show/ip/arp
+    #   Returns: Array of ARP entries
+    #
+    # === Adding Static Route
+    #   POST /rci/ip/route
+    #   Body: { "destination": "10.0.0.0", "mask": "255.0.0.0", "gateway": "192.168.1.1", "interface": "ISP" }
+    #
+    # === Deleting Static Route
+    #   POST /rci/ip/route
+    #   Body: { "destination": "10.0.0.0", "mask": "255.0.0.0", "no": true }
+    #
+    class Routing < Base
+      # Get IP routing table.
+      #
+      # == Keenetic API Request
+      #   GET /rci/show/ip/route
+      #
+      # == Response Structure from API
+      #   [
+      #     {
+      #       "destination": "0.0.0.0",
+      #       "mask": "0.0.0.0",
+      #       "gateway": "192.168.1.1",
+      #       "interface": "ISP",
+      #       "metric": 0,
+      #       "flags": "G",
+      #       "auto": true
+      #     }
+      #   ]
+      #
+      # @return [Array<Hash>] List of normalized route hashes
+      # @example
+      #   routes = client.routing.routes
+      #   # => [{ destination: "0.0.0.0", mask: "0.0.0.0", gateway: "192.168.1.1", ... }]
+      #
+      def routes
+        response = get('/rci/show/ip/route')
+        normalize_routes(response)
+      end
+
+      # Get ARP table (IP to MAC address mappings).
+      #
+      # == Keenetic API Request
+      #   GET /rci/show/ip/arp
+      #
+      # == Response Structure from API
+      #   [
+      #     {
+      #       "ip": "192.168.1.100",
+      #       "mac": "AA:BB:CC:DD:EE:FF",
+      #       "interface": "Bridge0",
+      #       "state": "reachable"
+      #     }
+      #   ]
+      #
+      # @return [Array<Hash>] List of normalized ARP entries
+      # @example
+      #   arp_table = client.routing.arp_table
+      #   # => [{ ip: "192.168.1.100", mac: "AA:BB:CC:DD:EE:FF", interface: "Bridge0", state: "reachable" }]
+      #
+      def arp_table
+        response = get('/rci/show/ip/arp')
+        normalize_arp_entries(response)
+      end
+
+      # Find a specific route by destination and mask.
+      #
+      # @param destination [String] Destination network (e.g., "10.0.0.0")
+      # @param mask [String] Network mask (e.g., "255.0.0.0")
+      # @return [Hash, nil] Route data or nil if not found
+      # @example
+      #   route = client.routing.find_route(destination: "10.0.0.0", mask: "255.0.0.0")
+      #   # => { destination: "10.0.0.0", mask: "255.0.0.0", gateway: "192.168.1.1", ... }
+      #
+      def find_route(destination:, mask:)
+        routes.find { |r| r[:destination] == destination && r[:mask] == mask }
+      end
+
+      # Find ARP entry by IP address.
+      #
+      # @param ip [String] IP address to look up
+      # @return [Hash, nil] ARP entry or nil if not found
+      # @example
+      #   entry = client.routing.find_arp_entry(ip: "192.168.1.100")
+      #   # => { ip: "192.168.1.100", mac: "AA:BB:CC:DD:EE:FF", ... }
+      #
+      def find_arp_entry(ip:)
+        arp_table.find { |e| e[:ip] == ip }
+      end
+
+      # Add a static route.
+      #
+      # == Keenetic API Request
+      #   POST /rci/ (batch format)
+      #   Body: [{"ip": {"route": {"destination": "...", "mask": "...", "gateway": "...", "interface": "..."}}}]
+      #
+      # @param destination [String] Destination network (e.g., "10.0.0.0")
+      # @param mask [String] Network mask (e.g., "255.0.0.0")
+      # @param gateway [String, nil] Next hop gateway IP address
+      # @param interface [String, nil] Output interface name
+      # @param metric [Integer, nil] Route metric (optional)
+      # @return [Array<Hash>] API response
+      #
+      # @example Add route via gateway
+      #   client.routing.create_route(destination: "10.0.0.0", mask: "255.0.0.0", gateway: "192.168.1.1")
+      #
+      # @example Add route via interface
+      #   client.routing.create_route(destination: "10.0.0.0", mask: "255.0.0.0", interface: "ISP")
+      #
+      def create_route(destination:, mask:, gateway: nil, interface: nil, metric: nil)
+        params = {
+          'destination' => destination,
+          'mask' => mask
+        }
+        params['gateway'] = gateway if gateway
+        params['interface'] = interface if interface
+        params['metric'] = metric if metric
+
+        client.batch([{ 'ip' => { 'route' => params } }])
+      end
+
+      # Delete a static route.
+      #
+      # == Keenetic API Request
+      #   POST /rci/ (batch format)
+      #   Body: [{"ip": {"route": {"destination": "...", "mask": "...", "no": true}}}]
+      #
+      # @param destination [String] Destination network
+      # @param mask [String] Network mask
+      # @return [Array<Hash>] API response
+      #
+      # @example
+      #   client.routing.delete_route(destination: "10.0.0.0", mask: "255.0.0.0")
+      #
+      def delete_route(destination:, mask:)
+        client.batch([{
+          'ip' => {
+            'route' => {
+              'destination' => destination,
+              'mask' => mask,
+              'no' => true
+            }
+          }
+        }])
+      end
+
+      private
+
+      def normalize_routes(response)
+        return [] unless response.is_a?(Array)
+
+        response.map { |route| normalize_route(route) }.compact
+      end
+
+      def normalize_route(data)
+        return nil unless data.is_a?(Hash)
+
+        {
+          destination: data['destination'],
+          mask: data['mask'],
+          gateway: data['gateway'],
+          interface: data['interface'],
+          metric: data['metric'],
+          flags: data['flags'],
+          auto: data['auto'],
+          comment: data['comment']
+        }
+      end
+
+      def normalize_arp_entries(response)
+        return [] unless response.is_a?(Array)
+
+        response.map { |entry| normalize_arp_entry(entry) }.compact
+      end
+
+      def normalize_arp_entry(data)
+        return nil unless data.is_a?(Hash)
+
+        {
+          ip: data['ip'],
+          mac: data['mac'],
+          interface: data['interface'],
+          state: data['state']
+        }
+      end
+    end
+  end
+end
+