Bug 31329

This is one of the speculative problems that ChannelBundle was meant to solve.

_`dis5`: Incoming 1-1 text chat thread related to a VoIP call
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Juliet is talking to Romeo over VoIP; there is no text channel open between
them. Romeo sends Juliet a text chat message (e.g. to send her a URI instead of
having to spell it out verbally), which should appear in the same
UI as the VoIP call if possible.

Current implementation: impossible, we have no representation for related
channels

Sub-cases exist, some of which are more problematic:

_`dis5a`: Juliet's VoIP UI also supports Text
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Proposed implementation:

* The new Text channel is announced with the same bundle ID as the old
  VoIP channel; observers are invoked

* The channel dispatcher notices that Juliet's UI (which is the
  handler for this bundle) supports Text channels, and tells it to handle
  the new Text channel too. Approvers are not invoked

Problems:

* How do we ensure that approvers are not invoked in this case, but are
  invoked in case dis10_?

_`dis5b`: Juliet's VoIP UI does not support Text
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Proposed implementation:

* The new Text channel is announced with the same bundle ID as the old
  VoIP channel; observers are invoked

* The channel dispatcher notices that Juliet's UI (which is the
  handler for this bundle) does not support Text channels, and falls back
  to splitting the channel bundle: the new channel goes to approvers and to
  a channel handler

_`dis5c`: "the same UI" is not unique
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Suppose Juliet has two channel handlers:

* Empathy: supports text and VoIP, currently in use for VoIP
* TChat: supports text and file transfers

Suppose that Romeo sends Juliet a file transfer offer, then a Text message.
Juliet's channel dispatcher sees the following:

* initially, there is a VoIP channel C1 in a bundle B, handled by Empathy
* next, there is a FT channel C2 in a bundle B. Empathy cannot handle it,
  so according to `dis5b`_, only TChat is offered to approvers.
  Juliet accepts the file transfer and it is handled by TChat
* now the Text channel, C3, appears. What happens to it? Is it handled by
  Empathy or by TChat without running approvers, or are they both offered to
  approvers?

_`dis5d`: not a channel handler
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Suppose that Juliet's UI got the channel via use-case req1_. No approver
or handler was ever invoked, so how does Juliet's channel dispatcher
know that that UI should get subsequent channels?

(The same issue exists in the proposed API if an approver calls Claim().)

Proposed solution: you're not allowed to handle a channel yourself unless
either you're a channel handler, or you're bypassing the channel dispatcher
completely

.. _req1: request.html#req1

_`dis6`: Incoming 1-1 text chat thread related to a collaborative app
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Mercutio is collaborating on a document with Romeo using AbiWord and Tubes;
there is no text channel open between them. Romeo sends Mercutio some review
comments, which should appear in a chat UI embedded inside AbiWord.

Current implementation: impossible, we have no representation for related
channels

Proposed implementation: the same as dis5_, with the same problems

_`dis10`: Incoming VoIP call related to some other channel
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Juliet is talking to Romeo over text chat. Romeo decides that he can't bear
to not hear her voice, and starts a VoIP call. Juliet wants controls for the
VoIP call to appear in the same UI that she's already using.

Current implementation: the call is indistinguishable from dis8_

Problems: Juliet can't get the UI she wants

Proposed implementation: the reverse of dis5_, with the same issues

Problems with proposed implementation:

* How do we ensure that approvers are invoked here, if they're not
  in case dis5a_?

File transfers
--------------

_`dis18`: Receiving a file in the context of a conversation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Juliet is talking to Romeo using a text or VoIP UI when he sends her
a file in the context of that conversation. If it implements file transfer
functionality, the text or VoIP UI should handle the file transfer; otherwise,
the channel dispatcher should fall back to launching a standalone file
transfer handler.

Proposed implementation and problems: same as dis5_

_`req3`: collaborative app
~~~~~~~~~~~~~~~~~~~~~~~~~~

Romeo is collaborating on a document with Mercutio, and wants to have a chat
embedded in his AbiWord instance, separate from any other chat with Mercutio
that may be ongoing.

:New vs. existing:
    New channel required [#]_
:Definition of channel identity:
    ChannelType is Text, TargetHandleType is CONTACT, TargetHandle is
    mercutio, Bundle is the same as the AbiWord Tube channel

.. [#] If the collaborative app already has a suitable channel, it is expected
    to work this out without the channel dispatcher's help.
    Stealing a channel from another UI is likely to fail (e.g. in the Text
    interface, they'll both try to acknowledge messages) so we should
    forbid this for sanity's sake

Current implementation: impossible, even in protocols supporting
conversation threads, because the spec can't represent them

Proposed implementation::

    let bundle_id = ...Bundle property of AbiWord Tube channel

    if a channel with TargetHandleType == CONTACT, TargetHandle == mercutio
    and Bundle == bundle_id is being handled by AbiWord:
        nothing to do, we already have a Text channel: stop

    AbiWord calls ChannelDispatcher.CreateChannel(
        account,
        {
            '...ChannelType': '...Text',
            '...TargetHandleType': CONTACT,
            '...TargetHandle': mercutio,
            '...Bundle': bundle_id,
        },
        timestamp,
        abiword_client_bus_name
    )
    AbiWord calls ChannelRequest.Proceed()

    ChannelDispatcher calls AddRequest on AbiWord, AbiWord ignores it as
        the request is already known to it

    try:
        ChannelDispatcher calls CreateChannel ({same dictionary as above})
    on success:
        channel observers run
        ChannelRequest emits Succeeded
        channel approvers do not run
        CD calls HandleChannels on AbiWord
        AbiWord handles channel
    on failure:
        ChannelDispatcher calls RemoveFailedRequest on AbiWord, and
            ChannelRequest emits Failed
        AbiWord displays failure
        if the error is the EEXIST equivalent, the message might be
            "Already talking to Mercutio in another app, and multiple threads
            are not possible in this protocol"

(Fallback behaviour if the CM is pre-Requests: the request is made with
suppress_handler = TRUE.)