opensips-mi 0.0.10 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 135298241a7da04c8011bdc51fd903c62b04dbfb05de49cce7610544fee9f274
-  data.tar.gz: 25a7bede110b7b35b121baddb04c2da6588d6fb8de3d9914cc84f6fd79041ef2
+  metadata.gz: 4c1a5116b4c5981ca39236ffe7f8595e6d2b7c493c648fcaae5c05ba2f698e05
+  data.tar.gz: d2f9b66b04887bc02412e225b0119f7d437ffd875207eaefbad9b2446e304536
 SHA512:
-  metadata.gz: 273474a444d49d471180eb7051cd57dc34e1c8c21146429cb649fab1134c5b4c6f604c0762a3a97005c4f340c7c4d379e95a0e89935d7511a1f5c1654c7edbc6
-  data.tar.gz: 7aca0cdf36610f3f4db77864d215ec9b214acaebfcac25345e2f8042997614f62e44f47e8914f06717f0d1cb9186e62df391524a2ae5bcef7246f7c3adb278c4
+  metadata.gz: 037cdb3d26bfb7b85424f352330c8660723f09f4af1cb9f6a3e880a71ca6383c62643ce89eddbda15a598649432a73324f2ee9ab8ee7cd13b640f874956f385e
+  data.tar.gz: 673d02eb93d30b4b43eeaa9ce19b1204ec0dc09efd1362e2cc1d24cb6a76e438240a58ca0161f4542116b298a2d2a8ff92261ec11f9d7d3761ae3c6d3359e3fc

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+staskobzar@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

data/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Gemfile

@@ -1,7 +1,12 @@
-source "https://rubygems.org"
-
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+# frozen_string_literal: true
 
-gem 'simplecov', require: false, group: :test
+source "https://rubygems.org"
 
+# Specify your gem's dependencies in opensips-mi.gemspec
 gemspec
+
+gem "rake", "~> 13.0", group: :development
+gem "rspec", "~> 3.0", group: :development
+gem "rubocop", "~> 1.21", group: :development
+gem "simplecov", require: false, group: :test
+gem "webmock", group: :test

data/README.md

@@ -1,15 +1,20 @@
 # Opensips::Mi
-[![Build Status](https://travis-ci.org/staskobzar/opensips-mi.png?branch=master)](https://travis-ci.org/staskobzar/opensips-mi)
+
+[![Ruby Build](https://github.com/staskobzar/opensips-mi/actions/workflows/main.yml/badge.svg)](https://github.com/staskobzar/opensips-mi/actions/workflows/main.yml)
 [![Code Climate](https://codeclimate.com/github/staskobzar/opensips-mi.png)](https://codeclimate.com/github/staskobzar/opensips-mi)
 [![Gem Version](https://badge.fury.io/rb/opensips-mi.png)](http://badge.fury.io/rb/opensips-mi)
 [![Coverage Status](https://coveralls.io/repos/staskobzar/opensips-mi/badge.png?branch=master)](https://coveralls.io/r/staskobzar/opensips-mi)
 
-OpenSIPs management interface library. 
+OpenSIPs management interface library.
 This library supports following management interfaces OpenSIPs modules:
 
-* mi_fifo
-* mi_datagram
-* mi_xmlrpc
+- mi_datagram
+- mi_http
+- mi_xmlrpc
+
+> version 1+ supports only new MI jsonrpc used by opensips v3+.
+> if you need older version with a plain text MI protocol install
+> this library version 0.0.11
 
 ## Installation
 
@@ -30,142 +35,162 @@ Or install it yourself as:
 ### Generic function to connect mi
 
 Using generic function to connect management interface:
+
 ```ruby
 require 'opensips/mi'
 Opensips::MI.connect INTERFACE, PARAMS
 ```
+
 Parameters:
 
-*INTRFACE* - interface name. One of the following:
+_INTRFACE_ - interface name. One of the following:
 
-* :fifo
-* :datagram
-* :xmlrpc
+- :datagram
+- :http
+- :xmlrpc
 
-*PARAMS* - connection parameters. Depends on interface. See below.
+_PARAMS_ - connection parameters. Depends on interface. See below.
 
 This function will raise exceptions if there are parameters' or environment errors.
 Function returns instance of one of the following classes:
 
-* Opensips::MI::Transport::Fifo
-* Opensips::MI::Transport::Datagram
-* Opensips::MI::Transport::Xmlrpc
+- Opensips::MI::Transport::Datagram
+- Opensips::MI::Transport::HTTP
+- Opensips::MI::Transport::Xmlrpc
 
-### FIFO
+### Datagram
 
 ```ruby
 require 'opensips/mi'
-opensips = Opensips::MI.connect :fifo, 
-                                :fifo_name => '/tmp/opensips_fifo',
-                                :reply_fifo => 'opensips_reply' . $$,
-                                :reply_dir => '/tmp'
-
+opensips = Opensips::MI.connect :datagram,
+                                :host => "199.188.10.100",
+                                :port => 8809,
+                                :timeout => 3
 ```
 
-**Parameters hash:** 
+**Parameters hash:**
 
-* fifo_name: OpenSIPs fifo file. See mi_fifo module parameter: `modparam("mi_fifo", "fifo_name", "/tmp/opensips_fifo")`.
-* reply_fifo: (OPTIONAL) Name of the reply fifo file. If not used, will generate random file in *reply_dir* and delete after use.
-* reply_dir:  (OPTIONAL) Path to directory of reply fifo file.
+- host: Hostname or IP address of OpenSIPs server
+- port: Datagram port. See mi_datagram module configuration parameter: `modparam("mi_datagram", "socket_name", "udp:192.168.2.133:8080")`
+- timeout: Timeout in seconds to wait send/recv commands. Optional. Default 5 seconds.
+
+### HTTP
 
-### Datagram
 ```ruby
 require 'opensips/mi'
-opensips = Opensips::MI.connect :datagram, 
-                                :host => "sipproxy.com", 
-                                :port => 8809,
+opensips = Opensips::MI.connect :http,
+                                :url => "http://192.168.0.1:8000/mi",
                                 :timeout => 5
 ```
+
 **Parameters hash:**
 
-* host: Hostname or IP address of OpenSIPs server
-* port: Datagram port. See mi_datagram module configuration parameter: `modparam("mi_datagram", "socket_name", "udp:192.168.2.133:8080")`
-* timeout: Timeout in seconds to wait send/recv commands. Optional. Default 3 seconds.
+- url: HTTP MI url. Check OpenSIPS module mi_http for setting of IP, port and root path.
+- timeout: Timeout in seconds to wait send/recv commands. Optional. Default 5 seconds.
 
 ### XMLRPC
+
 ```ruby
 require 'opensips/mi'
-opensips = Opensips::MI.connect :xmlrpc, 
-                                :host => "192.168.2.133", 
-                                :port => 8080
+opensips = Opensips::MI.connect :xmlrpc,
+                                :url => "http://192.168.0.1/rpc",
+                                :timeout => 5
 ```
+
 **Parameters hash:**
 
-* host: Hostname or IP address of OpenSIPs server
-* port: Datagram port. See mi_xmlrpc module configuration parameter: `modparam("mi_xmlrpc", "port", 8080)`
+- url: HTTP MI url. Check OpenSIPS module mi_http for setting of IP, port and root path.
+- timeout: Timeout in seconds to wait send/recv commands. Optional. Default 5 seconds.
 
 ### Command function
 
-Function "*command*" expects fifo command as a first argument, followed by command parameters.
-Command parameters' description can be found in module documentation. For example: http://www.opensips.org/html/docs/modules/1.8.x/dialog.html#id295450
-Usage example:
+Function "_command_" expects fifo command as a first argument, followed by command parameters.
+Command parameters' description can be found in module documentation. For example:
 
 ```ruby
 require 'opensips/mi'
-opensips = Opensips::MI.connect :fifo, 
-                                :fifo_name => '/tmp/opensips_fifo'
-                                
+opensips = Opensips::MI.connect :http,
+                                :url => 'http://10.0.0.1/mi'
+
 opensips.command('which')
 opensips.command('get_statistics', 'dialog','tm')
 ```
 
 ### Command method interface
 
-It is also possible to use command names as a method interface:
+It is also possible to use command names as a method interface. Parameters can be passed as array or hash too.
+Library will automatically fit it to defined protocol.
+
 ```ruby
 require 'opensips/mi'
-opensips = Opensips::MI.connect :datagram, 
-                                :host => "192.168.122.128", 
+opensips = Opensips::MI.connect :datagram,
+                                :host => "192.168.122.128",
                                 :port => 8809
-                                
+
 opensips.which
 opensips.get_statistics('dialog','tm')
 opensips.uptime
 opensips.ul_show_contact('location', 'alice')
-```
+opensips.lb_status([1, 0])
 
-Those methods first of all verify if mi function exists using `which` mi command. 
+# NOTE: named parametters can be used in hash.
+# Make sure you are using correct names
+opensips.log_level({level: 3, pid: 1})
+```
 
 ### Response
 
-Command function returns `Opensips::MI::Response` class. This class containe following class members which can be used to process responses:
+Command function returns hash with root key `:result` and hash/array of respons data
+or root key `:error` with message or more data.
+
+Example of response of "uptime" command:
+
+```ruby
+{:result=>{
+    "Now"=>"Wed Aug  9 19:41:28 2023",
+    "Up since"=>"Wed Aug  9 18:44:18 2023",
+    "Up time"=>"3430 [sec]"
+    }
+}
+```
 
-* code: *Integer* Response code: 200, 404 etc
-* message: *String* Response messages: "OK", "Bad headers" etc.
-* rawdata: *Array* Raw response data as array
-* result: *Mixed* Struct/Hash/Array/Nil. This member is used by helper response methods for pretty formatted result. See below.
- 
-### Response helpers methods
+Error response example:
 
-There are several helper methods which return conveniently formatted data:
-* ul_dump
-* uptime
-* cache_fetch
-* ul_show_contact
-* dlg_list
-* ps
+```ruby
+{:error=>{
+    "code"=>-32602,
+    "message"=>"Invalid params",
+    "data"=>"Bad PID"
+    }
+}
+```
 
-See example files for details.
+### Helper methods
 
 ## Dialog methods
 
-Dialog methods are interface to `t_uac_dlg` function of OpenSIPs' *tm* (transactions) module. 
+Dialog methods are interface to `t_uac_dlg` function of OpenSIPs' _tm_ (transactions) module.
 
 ### Interface to t_uac_dlg function of transaction (tm) module
+
 Very cool method from OpenSIPs. Can generate and send SIP request method to a destination UAC.
 Example of usage:
-* Send NOTIFY with special Event header to force restart SIP phone (equivalent of Asterisk's "sip notify peer")
-* Send PUBLISH to trigger notification which changes device state
-* Send REFER to transfer call
-* etc., etc., etc.
+
+- Send NOTIFY with special Event header to force restart SIP phone (equivalent of Asterisk's "sip notify peer")
+- Send PUBLISH to trigger notification which changes device state
+- Send REFER to transfer call
+- etc., etc., etc.
 
 **Headers**
 
 Headers parameter "hf" is a hash of headers of format:
+
 ```
 header-name => header-value
 ```
+
 Example:
+
 ```
 hf["From"] => "Alice Liddell <sip:alice@wanderland.com>;tag=843887163"
 ```
@@ -176,29 +201,34 @@ because t_uac_dlg expects body parameter as an xml only.
 
 Thus, using multiple headers with same header-name is not possible.
 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>"
 ```
+
 Which is equivalent to:
+
 ```
 Route: <sip:alice@atlanta.com>
 Route: <sip:bob@biloxi.com>
 ```
+
 If there are no To and From headers found, then exception ArgumentError is raised. Also when
 body part is present, Content-Type and Content-length fields are required.
 
 **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. At least "From" and "To" headers must be present. Headers' names are case-insensitive.
-* 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)
+- 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. At least "From" and "To" headers must be present. Headers' names are case-insensitive.
+- 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)
 
 **Example of usage**
+
 ```ruby
-opensips.uac_dlg "NOTIFY", "sip:alice@127.0.0.1:5066", 
+opensips.uac_dlg "NOTIFY", "sip:alice@127.0.0.1:5066",
                   {
                     "From"  => "<sip:alice@wanderland.com>;tag=8755a8d01a12f7e903a6f4ccaf393f04",
                     "To"    => "<sip:alice@wanderland.com>",
@@ -207,47 +237,50 @@ opensips.uac_dlg "NOTIFY", "sip:alice@127.0.0.1:5066",
 ```
 
 ### 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.
 Wrapper to `uac_dlg` function.
 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. 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 
+_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
 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). 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 to be auto-generated. Header field example: `hf['To'] => '<sip:alice@wanderland.com>'`
+- 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 to be auto-generated. Header field example: `hf['To'] => '<sip:alice@wanderland.com>'`
 
 **Example of usage**
 Will reboot Polycom phone:
+
 ```ruby
 opensips.event_notify 'sip:alice@127.0.0.1:5060', :polycom_check_cfg
 ```
 
 **List of available events' keys:**
 
-* :astra_check_cfg
-* :aastra_xml
-* :digium_check_cfg
-* :linksys_cold_restart
-* :linksys_warm_restart
-* :polycom_check_cfg
-* :sipura_check_cfg
-* :sipura_get_report
-* :snom_check_cfg
-* :snom_reboot
-* :cisco_check_cfg
-* :avaya_check_cfg
+- :astra_check_cfg
+- :aastra_xml
+- :digium_check_cfg
+- :linksys_cold_restart
+- :linksys_warm_restart
+- :polycom_check_cfg
+- :sipura_check_cfg
+- :sipura_get_report
+- :snom_check_cfg
+- :snom_reboot
+- :cisco_check_cfg
+- :avaya_check_cfg
 
 ### Presence MWI
 
@@ -255,32 +288,15 @@ Send message-summary NOTIFY Event to update phone voicemail status.
 
 **Parameters**
 
-* uri:      Request URI (sip:alice@wanderland.com:5060). To get client URI use `ul_show_contact` function, *contact* value
-* vmaccount:Message Account value. Ex.: sip:*97@asterisk.com
-* new:      Number of new messages. If more than 0 then Messages-Waiting header will be "yes". Set to 0 to clear phone MWI
-* old:      (optional) Old messages
-* urg_new:  (optional) New urgent messages
-* urg_old:  (optional) Old urgent messages
+- uri: Request URI (sip:alice@wanderland.com:5060). To get client URI use `ul_show_contact` function, _contact_ value
+- vmaccount:Message Account value. Ex.: sip:\*97@asterisk.com
+- new: Number of new messages. If more than 0 then Messages-Waiting header will be "yes". Set to 0 to clear phone MWI
+- old: (optional) Old messages
+- urg_new: (optional) New urgent messages
+- urg_old: (optional) Old urgent messages
 
 **Example of usage**
+
 ```ruby
 opensips.mwi_update 'sip:alice@wanderland.com:5060', 'sip:*97@voicemail.pbx.com', 5
 ```
-
-## Examples
-
-There are some sample files in *examples* directory.
-
-## TODO:
-
-Support for mi_xmlrpc_ng
-
-----
-## Contributing
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
-

data/Rakefile

@@ -1,16 +1,12 @@
-require "bundler/gem_tasks"
-require "rake/clean"
-require 'opensips/mi/version'
-require 'rspec/core/rake_task'
+# frozen_string_literal: true
 
-require "rdoc/task"
-Rake::RDocTask.new do |rd|
-  rd.rdoc_dir = 'rdoc'
-  rd.main = "README.md"
-  rd.rdoc_files.include("README.md","lib/**/*.rb")
-  rd.title = "OpenSIPs management interface " << Opensips::MI::VERSION
-end
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]