[asterisk-bugs] [JIRA] (ASTERISK-23692) ARI: Add a Messaging Capability

[Matt Jordan (JIRA)]

     [ https://issues.asterisk.org/jira/browse/ASTERISK-23692?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Matt Jordan updated ASTERISK-23692:
-----------------------------------

    Description: 
This improvement to ARI would extend Asterisk's technology agnostic messaging capabilities to ARI. This entails doing a few improvements to the core, followed by some extensions to some existing resources.

# Add a new API to {{message.h}} that registers a callback function (or an observer) that can be notified when a message is received. When a message is enqueued (but before it goes to the dialplan), the message can be handed off to the observers to let them 'deal' with the message if they so choose.
{noformat}
static int ast_msg_register_observer(const char *id, void (*msg_cb)(struct ast_msg *msg));
 
static int ast_msg_unregister_observer(const char *id);
{noformat}
** *NOTE*: technically, the act of enqueuing the message could be an observer as well. Don't get crazy with this, but it may be worthwhile making the act of handling a message somewhat generic.
# Modify {{chan_sip}} to not bail if {{get_destination}} fails *and* an observer is present that can handle the message.
# Implement an observer in ARI that emits received message as a new websocket event.
# Implement the following in the existing ARI resources:
## A method on endpoints that lets you send a message to the endpoint ({{ POST /endpoints/PJSIP/alice/message}})
## A method on technology that lets you specify the destination in the To:
{noformat}
POST /endpoints/PJSIP/message
{
    "from": "xmpp:bob at jabber.org",
    "to": "pjsip:generic/sip:alice at mysipserver.org"
    "body": "No, *I* am the very model of a major general"
}
{noformat}
## Update subscriptions on endpoints such that subscribing to an endpoint subscribes for the WebSocket events of messages sent from/to the endpoint.

Add tests for the following:

|| Test || Level || Description ||
| applications/subscribe-endpoint | Asterisk Test Suite | Basic subscription to an endpoint. Test should verify that a message sent from the subscribed endpoint is received; message sent to the subscribed endpoint is received; message sent to an unsubscribed endpoint is not received. Verify that an application not subscribed does not receive messages. |
| applications/subscribe-technology | Asterisk Test Suite | Subscribe to all messages associated with a technology. Verify that any message sent to an endpoint of the technology type is received. Verify that an application not subscribed does not receive messages. |
| message/basic | Asterisk Test Suite | Test sending a message through ARI to an endpoint, a generic URI; from an endpoint, from a sip URI. |
| message/off_nominal | Asterisk Test Suite | Test off nominal scenarios:
* Badly formatted request body
* Bad from endpoint (for a technology that requires it)
* Bad to endpoint (for a technology that requires it) |
| message/headers | Asterisk Test Suite | Test adding technology specific headers to a message through ARI |

For more detailed information, see the wiki page.

  was:
This improvement to ARI would extend Asterisk's technology agnostic messaging capabilities to ARI. This entails doing a few improvements to the core, followed by some extensions to some existing resources.

# Add a new API to {{message.h}} that registers a callback function (or an observer) that can be notified when a message is received. When a message is enqueued (but before it goes to the dialplan), the message can be handed off to the observers to let them 'deal' with the message if they so choose.
{noformat}
static int ast_msg_register_observer(const char *id, void (*msg_cb)(struct ast_msg *msg));
 
static int ast_msg_unregister_observer(const char *id);
{noformat}
** *NOTE*: technically, the act of enqueuing the message could be an observer as well. Don't get crazy with this, but it may be worthwhile making the act of handling a message somewhat generic.
# Modify {{chan_sip}} to not bail if {{get_destination}} fails *and* an observer is present that can handle the message.
# Implement an observer in ARI that emits received message as a new websocket event.
# Implement the following in the existing ARI resources:
## A method on endpoints that lets you send a message to the endpoint ({{ POST /endpoints/PJSIP/alice/message}})
## A method on technology that lets you specify the destination in the To:
{noformat}
POST /endpoints/PJSIP/message
{
    "from": "xmpp:bob at jabber.org",
    "to": "pjsip:generic/sip:alice at mysipserver.org"
    "body": "No, *I* am the very model of a major general"
}
{noformat}
## Update subscriptions on endpoints such that subscribing to an endpoint subscribes for the WebSocket events of messages sent from/to the endpoint.

Add tests for the following:

<table>
  <tbody>
    <tr>
      <th>
        <p>Test</p>
      </th>
      <th>
        <p>Level</p>
      </th>
      <th>
        <p>Description</p>
      </th>
    </tr>
    <tr>
      <td>
        <p>applications/subscribe-endpoint</p>
      </td>
      <td>
        <p>Asterisk Test Suite</p>
      </td>
      <td>
        <p>Basic subscription to an endpoint. Test should verify that a message sent from the subscribed endpoint is received; message sent to the subscribed endpoint is received; message sent to an unsubscribed endpoint is not received. Verify that an application not subscribed does not receive messages.</p>
      </td>
    </tr>
    <tr>
      <td colspan="1">applications/subscribe-technology</td>
      <td colspan="1">Asterisk Test Suite</td>
      <td colspan="1">Subscribe to all messages associated with a technology. Verify that any message sent to an endpoint of the technology type is received. Verify that an application not subscribed does not receive messages.</td>
    </tr>
    <tr>
      <td>
        <p>message/basic</p>
      </td>
      <td>
        <p>Asterisk Test Suite</p>
      </td>
      <td>
        <p>Test sending a message through ARI to an endpoint, a generic URI; from an endpoint, from a sip URI.</p>
      </td>
    </tr>
    <tr>
      <td>
        <p>message/off_nominal</p>
      </td>
      <td>
        <p>Asterisk Test Suite</p>
      </td>
      <td>
        <p>Test off nominal scenarios:</p>
        <ul>
          <li>Badly formatted request body</li>
          <li>Bad from endpoint (for a technology that requires it)</li>
          <li>Bad to endpoint (for a technology that requires it)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td>
        <p>message/headers</p>
      </td>
      <td>
        <p>Asterisk Test Suite</p>
      </td>
      <td>
        <p>Test adding technology specific headers to a message through ARI</p>
      </td>
    </tr>
  </tbody>
</table>

For more detailed information, see the wiki page.


> ARI: Add a Messaging Capability
> -------------------------------
>
>                 Key: ASTERISK-23692
>                 URL: https://issues.asterisk.org/jira/browse/ASTERISK-23692
>             Project: Asterisk
>          Issue Type: Improvement
>      Security Level: None
>            Reporter: Matt Jordan
>
> This improvement to ARI would extend Asterisk's technology agnostic messaging capabilities to ARI. This entails doing a few improvements to the core, followed by some extensions to some existing resources.
> # Add a new API to {{message.h}} that registers a callback function (or an observer) that can be notified when a message is received. When a message is enqueued (but before it goes to the dialplan), the message can be handed off to the observers to let them 'deal' with the message if they so choose.
> {noformat}
> static int ast_msg_register_observer(const char *id, void (*msg_cb)(struct ast_msg *msg));
>  
> static int ast_msg_unregister_observer(const char *id);
> {noformat}
> ** *NOTE*: technically, the act of enqueuing the message could be an observer as well. Don't get crazy with this, but it may be worthwhile making the act of handling a message somewhat generic.
> # Modify {{chan_sip}} to not bail if {{get_destination}} fails *and* an observer is present that can handle the message.
> # Implement an observer in ARI that emits received message as a new websocket event.
> # Implement the following in the existing ARI resources:
> ## A method on endpoints that lets you send a message to the endpoint ({{ POST /endpoints/PJSIP/alice/message}})
> ## A method on technology that lets you specify the destination in the To:
> {noformat}
> POST /endpoints/PJSIP/message
> {
>     "from": "xmpp:bob at jabber.org",
>     "to": "pjsip:generic/sip:alice at mysipserver.org"
>     "body": "No, *I* am the very model of a major general"
> }
> {noformat}
> ## Update subscriptions on endpoints such that subscribing to an endpoint subscribes for the WebSocket events of messages sent from/to the endpoint.
> Add tests for the following:
> || Test || Level || Description ||
> | applications/subscribe-endpoint | Asterisk Test Suite | Basic subscription to an endpoint. Test should verify that a message sent from the subscribed endpoint is received; message sent to the subscribed endpoint is received; message sent to an unsubscribed endpoint is not received. Verify that an application not subscribed does not receive messages. |
> | applications/subscribe-technology | Asterisk Test Suite | Subscribe to all messages associated with a technology. Verify that any message sent to an endpoint of the technology type is received. Verify that an application not subscribed does not receive messages. |
> | message/basic | Asterisk Test Suite | Test sending a message through ARI to an endpoint, a generic URI; from an endpoint, from a sip URI. |
> | message/off_nominal | Asterisk Test Suite | Test off nominal scenarios:
> * Badly formatted request body
> * Bad from endpoint (for a technology that requires it)
> * Bad to endpoint (for a technology that requires it) |
> | message/headers | Asterisk Test Suite | Test adding technology specific headers to a message through ARI |
> For more detailed information, see the wiki page.



--
This message was sent by Atlassian JIRA
(v6.2#6252)