vnstat-ruby 1.0.0

data/lib/vnstat/interface.rb

@@ -0,0 +1,161 @@
+module Vnstat
+  ##
+  # A class encapsulating traffic information for a specific network interface.
+  #
+  # @attr_reader [String] id The network interface identifier.
+  class Interface < Document
+    attr_reader :id
+
+    ##
+    # Initializes the {Interface}.
+    #
+    # @param [String] id The network interface identifier.
+    # @param [String] data The raw XML data.
+    def initialize(id, data)
+      super(data)
+      @id = id
+    end
+
+    ##
+    # Retrieves the raw XML data for the given interface identifier.
+    #
+    # @param [String] id The network interface identifier.
+    # @return [String]
+    def self.load_data(id)
+      Utils.call_executable('-i', id, '--xml')
+    end
+
+    ##
+    # Determines whether the interface is the same as another.
+    #
+    # @param [Interface] other The compared object.
+    # @return [true, false]
+    def ==(other)
+      return false unless other.respond_to?(:id)
+      id == other.id
+    end
+
+    ##
+    # Refreshes data cached in the current instance.
+    #
+    # @return [Interface]
+    def reload
+      self.data = self.class.load_data(id)
+      @nick = nil
+      self
+    end
+
+    ##
+    # Deletes the traffic database for the interface.
+    #
+    # @return [true, false]
+    def delete
+      Utils.call_executable_returning_status('--delete', '-i', id)
+    end
+
+    ##
+    # Reset the internal counters in the database for the selected interface.
+    # Use this if the interface goes down and back up, otherwise that interface
+    # will get some extra traffic to its database. Not needed when the daemon is
+    # used.
+    #
+    # @return [Interface]
+    def reset
+      Utils.call_executable_returning_status('--reset', '-i', id)
+      reload
+    end
+
+    ##
+    # Returns the alias name for the interface.
+    #
+    # @return [String]
+    def nick
+      @nick ||= interface_data.xpath('nick').text
+    end
+
+    #
+    # Sets the alias name for the interface.
+    #
+    # @param [String] nick The alias name for the interface.
+    def nick=(nick)
+      Utils.call_executable_returning_status(
+        '-i', id, '--nick', nick, '--update'
+      )
+      @nick = nick
+    end
+
+    alias_method :name, :nick
+    alias_method :name=, :nick=
+
+    ##
+    # The date on which tracking of the interface began.
+    # @return [Date]
+    #
+    def created_on
+      Parser.extract_date_from_xml_element(interface_data.xpath('created'))
+    end
+
+    ##
+    # The date and time on which the tracking information for the interface
+    # were updated.
+    #
+    # @return [DateTime]
+    def updated_at
+      Parser.extract_datetime_from_xml_element(interface_data.xpath('updated'))
+    end
+
+    ##
+    # Returns information about the total traffic.
+    #
+    # @return [Result]
+    def total
+      Result.extract_from_xml_element(interface_data.xpath('traffic/total'))
+    end
+
+    ##
+    # Returns information about the hourly traffic.
+    #
+    # @return [Traffic::Hourly]
+    def hours
+      @hours ||= Traffic::Hourly.new(self)
+    end
+
+    ##
+    # Returns information about the daily traffic.
+    #
+    # @return [Traffic::Daily]
+    def days
+      @days ||= Traffic::Daily.new(self)
+    end
+
+    ##
+    # Returns information about the monthly traffic.
+    #
+    # @return [Traffic::Monthly]
+    def months
+      @months ||= Traffic::Monthly.new(self)
+    end
+
+    ##
+    # Returns information about the traffic tops.
+    #
+    # @return [Traffic::Tops]
+    def tops
+      @tops ||= Traffic::Tops.new(self)
+    end
+
+    ##
+    # A human readable representation of the {Interface}.
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} id: #{id.inspect}>"
+    end
+
+    private
+
+    def interface_data
+      data.xpath("//interface[@id='#{id}']")
+    end
+  end
+end

data/lib/vnstat/interface_collection.rb

@@ -0,0 +1,106 @@
+module Vnstat
+  ##
+  # A class encapsulating traffic information for all known network interfaces.
+  class InterfaceCollection < Document
+    include Enumerable
+
+    ##
+    # Retrieves the raw XML data for all interfaces.
+    #
+    # @return [String]
+    def self.load_data
+      Utils.call_executable('--xml')
+    end
+
+    ##
+    # Sets the raw XML data for the {InterfaceCollection}.
+    #
+    # @param [String] data A string representing the document.
+    def data=(data)
+      super
+      each { |interface| interface.data = data }
+    end
+
+    ##
+    # Refreshes data cached in the current instance.
+    #
+    # @return [InterfaceCollection]
+    def reload
+      self.data = self.class.load_data
+      self
+    end
+
+    ##
+    # Returns the names of known interfaces.
+    #
+    # @return [Array<String>]
+    def ids
+      interfaces_hash.keys
+    end
+
+    ##
+    # Returns traffic information for a certain interface.
+    #
+    # @param [String] id The name of the interface.
+    # @raise [UnknownInterface] An error that is raised if the
+    #   specified interface is not tracked.
+    # @return [Interface]
+    def [](id)
+      interfaces_hash.fetch(id.to_s) do
+        fail UnknownInterface.new(id.to_s),
+             "Unknown interface: #{id}"
+      end
+    end
+
+    ##
+    # Iterates over each interface.
+    #
+    # @yieldparam [Interface] interface
+    def each(&block)
+      interfaces_hash.each_value(&block)
+    end
+
+    ##
+    # Creates the traffic database for the given interface.
+    #
+    # @param [String] id The network interface identifier
+    # @return [Interface, nil] The interface that has justed been added to
+    #   tracking.
+    def create(id)
+      success = Utils.call_executable_returning_status('--create', '-i', id)
+      return nil unless success
+      reload
+      self[id]
+    end
+
+    ##
+    # Reset the total traffic counters and recount those using recorded months.
+    #
+    # @return [InterfaceCollection]
+    def rebuild
+      success = Utils.call_executable_returning_status('--rebuildtotal')
+      reload if success
+      self
+    end
+
+    ##
+    # A human readable representation of the {InterfaceCollection}.
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} ids: #{ids.inspect}>"
+    end
+
+    private
+
+    def interfaces_hash
+      @interfaces_hash ||= begin
+        elements = data.xpath('//interface')
+        elements.each_with_object({}) do |node, hash|
+          id = node[:id]
+          hash[id] = Interface.new(id, data)
+        end
+      end
+    end
+  end
+end

data/lib/vnstat/parser.rb

@@ -0,0 +1,54 @@
+module Vnstat
+  ##
+  # A module containing several utility methods responsible for document
+  # parsing.
+  module Parser
+    module_function
+
+    ##
+    # Extracts the year and month from the given XML element.
+    #
+    # @param [Nokogiri::XML::Element] element The XML element.
+    # @return [Array<Integer, Integer>] An Array consisting of year and month.
+    def extract_month_from_xml_element(element)
+      month = element.xpath('date/month').text.to_i
+      year = element.xpath('date/year').text.to_i
+      [year, month]
+    end
+
+    ##
+    # Extracts the date from the given XML element.
+    #
+    # @param [Nokogiri::XML::Element] element The XML element.
+    # @return [Date]
+    def extract_date_from_xml_element(element)
+      day = element.xpath('date/day').text.to_i
+      year, month = extract_month_from_xml_element(element)
+      Date.new(year, month, day)
+    end
+
+    ##
+    # Extracts the date and time from the given XML element.
+    #
+    # @param [Nokogiri::XML::Element] element The XML element.
+    # @return [DateTime]
+    def extract_datetime_from_xml_element(element)
+      date = extract_date_from_xml_element(element)
+      hour = element.xpath('time/hour').text.to_i
+      minute = element.xpath('time/minute').text.to_i
+      DateTime.new(date.year, date.month, date.day, hour, minute)
+    end
+
+    ##
+    # Extracts the bytes received and sent from the given XML element.
+    #
+    # @param [Nokogiri::XML::Element] element The XML element.
+    # @return [Array<Integer, Integer>] An Array consisting of bytes received
+    #   and bytes sent.
+    def extract_transmitted_bytes_from_xml_element(element)
+      bytes_received = element.xpath('rx').text.to_i * 1024
+      bytes_sent = element.xpath('tx').text.to_i * 1024
+      [bytes_received, bytes_sent]
+    end
+  end
+end

data/lib/vnstat/result.rb

@@ -0,0 +1,55 @@
+module Vnstat
+  ##
+  # A class representing a tracking result.
+  #
+  # @attr_reader [Integer] bytes_received The received bytes.
+  # @attr_reader [Integer] bytes_sent The sent bytes.
+  class Result
+    autoload :Minute, 'vnstat/result/minute'
+    autoload :Day, 'vnstat/result/day'
+    autoload :Hour, 'vnstat/result/hour'
+    autoload :Month, 'vnstat/result/month'
+
+    autoload :DateDelegation, 'vnstat/result/date_delegation'
+    autoload :TimeComparable, 'vnstat/result/time_comparable'
+
+    include Comparable
+
+    attr_reader :bytes_received, :bytes_sent
+
+    ##
+    # Initializes the {Result}.
+    #
+    # @param [Integer] bytes_received The received bytes.
+    # @param [Integer] bytes_sent The sent bytes.
+    def initialize(bytes_received, bytes_sent)
+      @bytes_received = bytes_received
+      @bytes_sent = bytes_sent
+    end
+
+    ##
+    # Initializes a {Result} using the the data contained in the given XML
+    # element.
+    #
+    # @param [Nokogiri::XML::Element] element The XML element.
+    # @return [Result]
+    def self.extract_from_xml_element(element)
+      new(*Parser.extract_transmitted_bytes_from_xml_element(element))
+    end
+
+    ##
+    # The transmitted bytes (both sent and received).
+    #
+    # @return [Integer]
+    def bytes_transmitted
+      bytes_received + bytes_sent
+    end
+
+    ##
+    # @return [Integer, nil]
+    def <=>(other)
+      return nil unless other.respond_to?(:bytes_transmitted)
+      bytes_transmitted <=> other.bytes_transmitted
+    end
+  end
+end

data/lib/vnstat/result/date_delegation.rb

@@ -0,0 +1,31 @@
+module Vnstat
+  class Result
+    ##
+    # A module that is included by result types that contain date information.
+    module DateDelegation
+      ##
+      # The year the result was captured in.
+      #
+      # @return [Integer]
+      def year
+        date.year
+      end
+
+      ##
+      # The month the result was captured in.
+      #
+      # @return [Integer]
+      def month
+        date.month
+      end
+
+      ##
+      # The day the result was captured on.
+      #
+      # @return [Integer]
+      def day
+        date.day
+      end
+    end
+  end
+end

data/lib/vnstat/result/day.rb

@@ -0,0 +1,45 @@
+module Vnstat
+  class Result
+    ##
+    # A class representing a tracking result for a specific day.
+    #
+    # @attr_reader [Date] date The date the result was captured on.
+    class Day < Result
+      include DateDelegation
+
+      attr_reader :date
+
+      ##
+      # Initializes the {Day}.
+      #
+      # @param [Date] date The date the result was captured on.
+      # @param [Integer] bytes_received The received bytes.
+      # @param [Integer] bytes_sent The sent bytes.
+      def initialize(date, bytes_received, bytes_sent)
+        @date = date
+        super(bytes_received, bytes_sent)
+      end
+
+      ##
+      # Initializes a {Day} using the the data contained in the given XML
+      # element.
+      #
+      # @param [Nokogiri::XML::Element] element The XML element.
+      # @return [Day]
+      def self.extract_from_xml_element(element)
+        new(
+          Parser.extract_date_from_xml_element(element),
+          *Parser.extract_transmitted_bytes_from_xml_element(element)
+        )
+      end
+
+      ##
+      # @return [Integer, nil]
+      def <=>(other)
+        return nil unless other.respond_to?(:bytes_transmitted)
+        return nil unless other.respond_to?(:date)
+        [date, bytes_transmitted] <=> [other.date, other.bytes_transmitted]
+      end
+    end
+  end
+end