opensips-mi 0.0.10 → 1.0.0

data/lib/opensips/mi/command.rb

@@ -1,45 +1,61 @@
+# frozen_string_literal: true
+
 module Opensips
   module MI
+    # core class to send command to MI
+    # and return responses
     class Command
+      attr_reader :transp
+
       EVENTNOTIFY = {
         # Aastra
-        aastra_check_cfg:       'check-sync',
-        aastra_xml:             'aastra-xml',
+        aastra_check_cfg: "check-sync",
+        aastra_xml: "aastra-xml",
         # Digium
-        digium_check_cfg:       'check-sync',
+        digium_check_cfg: "check-sync",
         # Linksys
-        linksys_cold_restart:   'reboot_now',
-        linksys_warm_restart:   'restart_now',
+        linksys_cold_restart: "reboot_now",
+        linksys_warm_restart: "restart_now",
         # Polycom
-        polycom_check_cfg:      'check-sync',
+        polycom_check_cfg: "check-sync",
         # Sipura
-        sipura_check_cfg:       'resync',
-        sipura_get_report:      'report',
+        sipura_check_cfg: "resync",
+        sipura_get_report: "report",
         # Snom
-        snom_check_cfg:         'check-sync;reboot=false',
-        snom_reboot:            'check-sync;reboot=true',
+        snom_check_cfg: "check-sync;reboot=false",
+        snom_reboot: "check-sync;reboot=true",
         # Cisco
-        cisco_check_cfg:        'check-sync',
+        cisco_check_cfg: "check-sync",
         # Avaya
-        avaya_check_cfg:        'check-sync',
-      }
-
-      # Interface to mi methods direct call
-      def method_missing(md, *params, &block)  
-        response = command md.to_s, params
-        # return special helper output if exists
-        return response unless response.success
-        if response.respond_to?(md)
-          response.send md
-        else
-          response
-        end
+        avaya_check_cfg: "check-sync"
+      }.freeze
+
+      def initialize(transp)
+        @transp = transp
+      end
+
+      # prepare args, pipe them to send to MI using transport
+      # and finally format response
+      def command(*params)
+        raise ErrorParams, "command missing method name" if params.empty?
+
+        transp.adapter_request(*params)
+              .then { |args| transp.send(*args) }
+              .then { |resp| transp.adapter_response(resp) }
+      end
+
+      # meta methods call directly
+      def method_missing(cmd, *args)
+        command(cmd.to_s, *args)
       end
 
+      def respond_to_missing?(_name, _include_private = false) = true
+
       # = Interface to t_uac_dlg function of transaction (tm) module
       # Very cool method from OpenSIPs. Can generate and send SIP request method to destination.
       # Example of usage:
-      #   - Send NOTIFY with special Event header to force restart SIP phone (equivalent of ASterisk's "sip notify peer")
+      #   - Send NOTIFY with special Event header to force restart SIP phone
+      #     (equivalent of ASterisk's "sip notify peer")
       #   - Send PUBLISH to trigger device state change notification
       #   - Send REFER to transfer call
       #   - etc., etc., etc.
@@ -50,10 +66,6 @@ module Opensips
       # Example:
       #   hf["From"] => "Alice Liddell <sip:alice@wanderland.com>;tag=843887163"
       #
-      # Special "nl" header with any value is used to input additional "\r\n". This is
-      # useful, for example, for message-summary event to separate application body. This is
-      # because t_uac_dlg expect body parameter as xml only.
-      #
       # Thus, using multiple headers with same header-name is not possible with header hash.
       # However, it is possible to use multiple header-values comma separated (rfc3261, section 7.3.1):
       #   hf["Route"] => "<sip:alice@atlanta.com>, <sip:bob@biloxi.com>"
@@ -67,60 +79,52 @@ module Opensips
       # == Parameters
       #   method:     SIP request method (NOTIFY, PUBLISH etc)
       #   ruri:       Request URI, ex.: sip:555@10.0.0.55:5060
-      #   hf:         Headers array. Additional headers will be added to request. 
+      #   hf:         Headers array. Additional headers will be added to request.
       #               At least "From" and "To" headers must be specify
       #   nhop:       Next hop SIP URI (OBP); use "." if no value.
-      #   socket:     Local socket to be used for sending the request; use "." if no value. Ex.: udp:10.130.8.21:5060
-      #   body:       (optional, may not be present) request body (if present, requires the "Content-Type" and "Content-length" headers)
-      #
-      def uac_dlg method, ruri, hf, next_hop = ?., socket = ?., body = nil
-        mandatory_hf = Array['To', 'From']
-        mandatory_hf += ['Content-Type'] unless body.nil?
-        mandatory_hf.map{|h|h.downcase}.each do |n|
-          raise ArgumentError, 
-            "Missing mandatory header #{n.capitalize}" unless hf.keys.map{|h| h.downcase}.include?(n)
-        end
-        # compile headers to string
-        headers = hf.map{|name,val| name.eql?("nl") ? "" : "#{name}: #{val}"}.join "\r\n"
+      #   socket:     Local socket to be used for sending the request; use "." if no value.
+      #               Ex.: udp:10.130.8.21:5060
+      #   body:       (optional, may not be present) request body (if present, requires the "Content-Type"
+      #               and "Content-length" headers)
+      def uac_dlg(method, ruri, hdrs, next_hop = ".", socket = ".", body = nil)
+        validate_hf(hdrs)
+
+        headers = hdrs.map { |name, val| "#{name}: #{val}" }.join("\r\n")
         headers << "\r\n\r\n"
 
-        # set_header is a hack for xmlrpc which fails if headers are quoted
-        params = [method, ruri, next_hop, socket, set_header(headers)]
+        params = [method, ruri, next_hop, socket, headers]
         params << body unless body.nil?
-        # send it and return Response
-        command 't_uac_dlg', params
+        command "t_uac_dlg", params
       end
 
       # = NOTIFY check-sync like event
-      # NOTIFY Events to restart phone, force configuration reload or 
-      # report for some SIP IP phone models. 
+      # NOTIFY Events to restart phone, force configuration reload or
+      # report for some SIP IP phone models.
       # The events list was taken from Asterisk configuration file (sip_notify.conf)
       # Note that SIP IP phones usually should be configured to accept special notify
       # event to reboot. For example, Polycom configuration option to enable special
       # event would be:
       #   voIpProt.SIP.specialEvent.checkSync.alwaysReboot="1"
       #
-      # This function will generate To/From/Event headers. Will use random tag for 
-      # From header. 
+      # This function will generate To/From/Event headers. Will use random tag for
+      # From header.
       # *NOTE*: This function will not generate To header tag. This is not complying with
-      # SIP protocol specification (rfc3265). NOTIFY must be part of a subscription 
+      # SIP protocol specification (rfc3265). NOTIFY must be part of a subscription
       # dialog. However, it works for the most of the SIP IP phone models.
       # == Parameters
-      #   - uri:    Valid client contact URI (sip:alice@10.0.0.100:5060). 
+      #   - uri:    Valid client contact URI (sip:alice@10.0.0.100:5060).
       #             To get client URI use *ul_show_contact => contact* function
       #   - event:  One of the events from EVENTNOTIFY constant hash
-      #   - hf:     Header fields. Add To/From header fields here if you do not want them 
+      #   - hf:     Header fields. Add To/From header fields here if you do not want them
       #             to be auto-generated. Header field example:
       #             hf['To'] => '<sip:alice@wanderland.com>'
-      #
-      def event_notify uri, event, hf = {}
-        raise ArgumentError,
-          "Invalid notify event: #{event.to_s}" unless EVENTNOTIFY.keys.include?(event)
-        hf['To'] = "<#{uri}>" unless hf.keys.map{|k|k.downcase}.include?('to')
-        hf['From'] = "<#{uri}>;tag=#{SecureRandom.hex}" unless hf.keys.map{|k|k.downcase}.include?('from')
-        hf['Event'] = EVENTNOTIFY[event]
-
-        uac_dlg "NOTIFY", uri, hf
+      def event_notify(uri, event, hdrs = {})
+        hnames = hdrs.keys.map { |k| k.to_s.downcase } || []
+        hdrs["To"] = "<#{uri}>" unless hnames.include?("to")
+        hdrs["From"] = "<#{uri}>;tag=#{rand(1 << 32)}" unless hnames.include?("from")
+        hdrs["Event"] = EVENTNOTIFY[event] || event.to_s
+
+        uac_dlg "NOTIFY", uri, hdrs
       end
 
       # = Presence MWI
@@ -135,39 +139,28 @@ module Opensips
       #   - old:      (optional) Old messages
       #   - urg_new:  (optional) New urgent messages
       #   - urg_old:  (optional) Old urgent messages
-      #
-      def mwi_update uri, vmaccount, new, old = 0, urg_new = 0, urg_old = 0
-        mbody = Hash[
-          'Messages-Waiting'  => (new > 0 ? "yes" : "no"),
-          'Message-Account'   => vmaccount,
-          'Voice-Message'     => "#{new}/#{old} (#{urg_new}/#{urg_old})",
-        ]
-        hf = Hash[
-          'To'                => "<#{uri}>",
-          'From'              => "<#{uri}>;tag=#{SecureRandom.hex}",
-          'Event'             => "message-summary",
-          'Subscription-State'=> "active",
-          'Content-Type'      => "application/simple-message-summary",
-          'nl'                => "",
-        ]
-
-        uac_dlg "NOTIFY", uri, hf.merge(mbody)
+      def mwi_update(uri, vmaccount, newmsgs, old = 0, urg_new = 0, urg_old = 0)
+        hbody = { "Messages-Waiting" => (newmsgs.positive? ? "yes" : "no"),
+                  "Message-Account" => vmaccount,
+                  "Voice-Message" => "#{newmsgs}/#{old} (#{urg_new}/#{urg_old})" }
+        hdrs = { "To" => "<#{uri}>",
+                 "From" => "<#{uri}>;tag=#{rand(1 << 32)}",
+                 "Event" => "message-summary",
+                 "Subscription-State" => "active",
+                 "Content-Type" => "application/simple-message-summary" }
+
+        body = hbody.map { |k, v| "#{k}: #{v}" }.join("\r\n") << "\r\n\r\n"
+        uac_dlg "NOTIFY", uri, hdrs, ".", ".", body
       end
 
       private
-        def set_header(header);"\"#{header}\"";end
-
-        def host_valid? params
-          raise ArgumentError,
-            'Missing socket host' if params[:host].nil?
-          raise ArgumentError,
-            'Missing socket port' if params[:port].nil?
-          Socket.getaddrinfo(params[:host], nil) rescue 
-            raise SocketError, "Invalid host #{params[:host]}" 
-          raise SocketError, 
-            "Invalid port #{params[:port]}" unless (1..(2**16-1)).include?(params[:port])
-          true
-        end
+
+      def validate_hf(headers)
+        names = headers&.keys&.map { |k| k.to_s.downcase } || []
+        return if names.include?("to") && names.include?("from")
+
+        raise ArgumentError, "invalid headers value. must be a hash and have 'To' and 'From' headers"
+      end
     end
   end
 end

data/lib/opensips/mi/transport/abstract.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Opensips
+  module MI
+    module Transport
+      # abstruct class for transport protocols
+      class Abstract
+        # send a command to connection and return response
+        def send(_command)
+          raise NotImplementedError
+        end
+
+        # request adapter method
+        # by default if does jsonrpc v2 as string
+        # xmlrpc overload this message
+        def adapter_request(cmd, *args)
+          rpc = {
+            jsonrpc: "2.0",
+            id: rand(1 << 16),
+            method: cmd
+          }
+
+          unless args.empty?
+            params = args.flatten
+            rpc[:params] = params[0].is_a?(Hash) ? params[0] : params
+          end
+
+          JSON.generate(rpc)
+        end
+
+        # response adapter by default parses jsonrpc response
+        # to an object. xmlrp overloads this method
+        def adapter_response(body)
+          resp = JSON.parse(body)
+          if resp["result"]
+            { result: resp["result"] }
+          elsif resp["error"]
+            { error: resp["error"] }
+          else
+            { error: { "message" => "invalid response: #{body}" } }
+          end
+        rescue JSON::ParserError => e
+          { error: { "message" => %(JSON::ParserError: #{e}) } }
+        end
+
+        protected
+
+        def raise_invalid_params
+          raise Opensips::MI::ErrorParams,
+                "invalid params. Expecting a hash with :url and optional :timeout"
+        end
+
+        def seturi(url)
+          @uri = URI(url)
+        rescue URI::InvalidURIError
+          raise Opensips::MI::ErrorParams,
+                "invalid http host url: #{url}"
+        end
+      end
+    end
+  end
+end

data/lib/opensips/mi/transport/datagram.rb

@@ -1,44 +1,57 @@
-require 'timeout'
+# frozen_string_literal: true
+
+require_relative "abstract"
+require "socket"
+require "timeout"
 
 module Opensips
   module MI
     module Transport
-      class Datagram < Opensips::MI::Command
-        RECVMAXLEN = 2**16 - 1
-        TIMEOUT = 3
+      # datagram UDP transport to communicate with MI
+      class Datagram < Abstract
+        def initialize(args)
+          super()
+          raise_invalid_params unless args.is_a?(Hash)
+          @host, @port, @timeout = args.values_at(:host, :port, :timeout)
+          raise_invalid_params if @host.nil? || @port.nil?
+          raise_invalid_port unless @port.to_i.between?(1, 1 << 16)
+          @timeout ||= 5
+          connect
+        end
 
-        class << self
-          def init(params)
-            Datagram.new params
+        def send(command)
+          Timeout.timeout(
+            @timeout,
+            Opensips::MI::ErrorSendTimeout,
+            "timeout send command to #{@host}:#{@port} within #{@timeout} sec"
+          ) do
+            @sock.send command, 0
+            msg, = @sock.recvfrom(1500)
+            msg
           end
         end
 
-        def initialize(params)
-          host_valid? params
-          @sock = UDPSocket.new
-          @sock.connect params[:host], params[:port]
-          @timeout = params[:timeout].to_i
-        end
+        protected
 
-        def command(cmd, params = [])
-          request = ":#{cmd}:\n"
-          params.each do |c|
-            request << "#{c}\n"
-          end
-          Timeout::timeout(tout, nil, "Timeout send request to datagram MI") {
-            @sock.send request, 0
-          }
-          # will raise Errno::ECONNREFUSED if failed to connect
-          Timeout::timeout(tout,nil,"Timeout receive respond from datagram MI") {
-            response, = @sock.recvfrom RECVMAXLEN
-          }
-          Opensips::MI::Response.new response.split(?\n)
+        def raise_invalid_params
+          raise Opensips::MI::ErrorParams,
+                "invalid params. Expecting a hash with :host, :port and optional :timeout"
         end
 
-        def tout
-          @timeout > 0 ? @timeout : TIMEOUT
+        def raise_invalid_port
+          raise Opensips::MI::ErrorParams, "invalid port '#{@port}'"
         end
 
+        private
+
+        def connect
+          @sock = UDPSocket.new
+          Timeout.timeout(
+            @timeout,
+            Opensips::MI::ErrorResolveTimeout,
+            "failed to resolve address #{@host}:#{@port} within #{@timeout} sec"
+          ) { @sock.connect(@host, @port) }
+        end
       end
     end
   end

data/lib/opensips/mi/transport/http.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "net/http"
+require_relative "abstract"
+
+module Opensips
+  module MI
+    module Transport
+      # HTTP transport to communicate with MI
+      class HTTP < Abstract
+        def initialize(args)
+          super()
+          raise_invalid_params unless args.is_a?(Hash)
+          url, @timeout = args.values_at(:url, :timeout)
+          raise_invalid_params if url.nil?
+          seturi(url)
+          @timeout ||= 5
+          connect
+        end
+
+        def send(cmd)
+          resp = @client.post(@uri.path, cmd, { "Content-Type" => "application/json" })
+          unless resp.code.eql? "200"
+            raise Opensips::MI::ErrorHTTPReq,
+                  "invalid MI HTTP response: #{resp.message}"
+          end
+          resp.body
+        end
+
+        private
+
+        def connect
+          @client = Net::HTTP.new(@uri.host, @uri.port)
+          @client.read_timeout = @timeout
+          @client.write_timeout = @timeout
+        end
+      end
+    end
+  end
+end

data/lib/opensips/mi/transport/xmlrpc.rb

@@ -1,35 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "abstract"
+require "xmlrpc/client"
+
 module Opensips
   module MI
     module Transport
-      class Xmlrpc < Opensips::MI::Command
-        RPCSEG = 'RPC2'
-        class << self
-          def init(params)
-            Xmlrpc.new params
-          end
+      # XML-RPC protocol for MI
+      class Xmlrpc < Abstract
+        def initialize(args)
+          super()
+          raise_invalid_params unless args.is_a?(Hash)
+          url, @timeout = args.values_at(:url, :timeout)
+          raise_invalid_params if url.nil?
+          seturi(url)
+          @client = XMLRPC::Client.new2(@uri.to_s, nil, @timeout)
         end
 
-        def initialize(params)
-          host_valid? params
-          uri = "http://#{params[:host]}:#{params[:port]}/#{RPCSEG}"
-          @client = XMLRPC::Client.new_from_uri(uri, nil, 3)
-        rescue => e
-          raise e.class,
-            "Can not connect OpenSIPs server.\n#{e.message}"
+        def send(*cmd)
+          @client.call(*cmd)
+        rescue XMLRPC::FaultException => e
+          { error: { "message" => e.message } }
+        rescue StandardError => e
+          raise Opensips::MI::ErrorHTTPReq, e
         end
 
-        def command(cmd, params = [])
-          response = ["200 OK"]
-          response += @client.call(cmd, *params).split(?\n)
-          response << ""
-        rescue => e
-          response = ["600 " << e.message]
-        ensure
-          return Opensips::MI::Response.new response
+        # overload resonse adapter for xmlrpc
+        def adapter_response(resp)
+          if resp[:error]
+            resp
+          else
+            { result: resp }
+          end
         end
 
-        def set_header(header);header;end
+        # overload request adapter for xmlrpc
+        def adapter_request(*args)
+          args.flatten => [cmd, *rest]
+          return [cmd] if rest.empty?
+
+          rest = rest.flatten
+          return [cmd, rest.first.map { |_, v| v }].flatten if rest.first.is_a?(Hash)
 
+          [cmd, rest].flatten
+        end
       end
     end
   end

data/lib/opensips/mi/transport.rb

@@ -1,9 +1,12 @@
-require_relative "transport/fifo"
+# frozen_string_literal: true
+
 require_relative "transport/datagram"
+require_relative "transport/http"
 require_relative "transport/xmlrpc"
 
 module Opensips
   module MI
+    # module transport protocols implementation
     module Transport
     end
   end

data/lib/opensips/mi/version.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module Opensips
   module MI
-    VERSION = "0.0.10"
+    VERSION = "1.0.0"
   end
 end

data/lib/opensips/mi.rb

@@ -1,22 +1,27 @@
-require 'ostruct'
-require 'fcntl'
-require 'securerandom'
-require 'socket'
-require 'xmlrpc/client'
+# frozen_string_literal: true
 
 require "opensips/mi/version"
-require "opensips/mi/response"
 require "opensips/mi/command"
 require "opensips/mi/transport"
 
 module Opensips
+  # OpenSIPS Managemen Interface core module
   module MI
-    def self.connect(transport, params)
-      # send to transport class
-      Transport.const_get(transport.to_s.capitalize).init params
-    rescue NameError
-      raise NameError, "Unknown transport method: " << transport.to_s
+    class Error < StandardError; end
+    class ErrorParams < Error; end
+    class ErrorResolveTimeout < Error; end
+    class ErrorSendTimeout < Error; end
+    class ErrorHTTPReq < Error; end
+
+    def self.connect(transport_proto, params = {})
+      transp = case transport_proto
+               when :datagram then Transport::Datagram.new(params)
+               when :http then Transport::HTTP.new(params)
+               when :xmlrpc then Transport::Xmlrpc.new(params)
+               else
+                 raise Error, "Unknown transport method: #{transport_proto}"
+               end
+      Command.new(transp)
     end
   end
 end
-

data/lib/opensips.rb

@@ -1,4 +1,8 @@
+# frozen_string_literal: true
+
 require "opensips/mi"
 
+# Ruby module to connect OpenSIPS Management Interface
+# to send commands and read responses
 module Opensips
 end

data/sig/opensips/mi.rbs

@@ -0,0 +1,6 @@
+module Opensips
+  module Mi
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end