Add a new configuration setting: `connection_options`

Allows you to pass in options for the `Strophe.Connection` constructor.

docs/CHANGES.md

@@ -8,6 +8,7 @@
 - HTML templates are now loaded in the respective modules/plugins. [jcbrand]
 - Start improving Content-Security-Policy compatibility by removing inline CSS. [mathiasertl]
 - Add support for XEP-0048, chat room bookmarks [jcbrand]
+- New configuration setting [connection_options](https://conversejs.org/docs/html/configuration.html#connection_options) [jcbrand]
 
 ## 2.0.0 (2016-09-16)
 - #656 Online users count not shown initially [amanzur]
@@ -15,7 +16,7 @@
 - Backwards incompatible change: the `_super` attribute in plugins is now named `__super__`. [jcbrand]
 - Continuously attempt to resurrect dead connections when `auto_reconnect` is `true`. [jcbrand]
 - Update the 'rooms' API to allow user to pass in room attributes. [jcbrand]
-- Add new configuration setting [message_storage](https://conversejs.org/docs/html/configuration.html#message_storage) [jcbrand]
+- New configuration setting [message_storage](https://conversejs.org/docs/html/configuration.html#message_storage) [jcbrand]
 - Hardcode the storage for roster contacts and chatroom occupants to `sessionStorage`. [jcbrand]
 - Fixed wrong chat state value, should be `chat`, not `chatty`.
   See [RFC 3921](https://xmpp.org/rfcs/rfc3921.html#rfc.section.2.1.2.2). [jcbrand]
@@ -31,8 +32,8 @@
 - Typing (i.e. chat state) notifications are now also sent out from MUC rooms. [jcbrand]
 - `ChatRoomView.onChatRoomMessageSubmitted` has been renamed to
   `onMessageSubmitted`, to make it the same as the method on `ChatBoxView`. [jcbrand]
-- New config option [muc_nickname_from_jid](https://conversejs.org/docs/html/configuration.html#muc_nickname_from_jid) [jcbrand]
-- New config option [muc_instant_rooms](https://conversejs.org/docs/html/configuration.html#muc_instant_rooms) [jcbrand]
+- New configuration setting [muc_nickname_from_jid](https://conversejs.org/docs/html/configuration.html#muc_nickname_from_jid) [jcbrand]
+- New configuration setting [muc_instant_rooms](https://conversejs.org/docs/html/configuration.html#muc_instant_rooms) [jcbrand]
 
 ## 1.0.5 (2016-07-28)
 - In case of nickname conflict when joining a room, allow the user to choose a new one.

docs/source/configuration.rst

@@ -368,6 +368,34 @@ then you'll receive notification messages each time this happens.
 Receiving constant notifications that a user's client is connecting and disconnecting
 is annoying, so this option allows you to ignore those JIDs.
 
+connection_options
+------------------
+
+* Default:  ``{}``
+* Type:  Object
+
+Converse.js relies on `Strophe.js <http://strophe.im>`_ to establish and
+maintain a connection to the XMPP server.
+
+This option allows you to pass a map of configuration options to be passed into
+the ``Strophe.Connection`` constructor.
+
+For documentation on the configuration options that ``Strophe.Connection``
+accepts, refer to the
+`Strophe.Connection documentation <http://strophe.im/strophejs/doc/1.2.8/files/strophe-js.html#Strophe.Connection.Strophe.Connection>`_.
+
+As an example, suppose you want to restrict the supported SASL authentication
+mechanisms, then you'd pass in the ``mechanisms`` as a ``connection_options``
+``key:value`` pair::
+
+        converse.initialize({
+            connection_options: {
+                'mechanisms': [
+                    converse.env.Strophe.SASLMD5,
+                ]
+            },
+        });
+
 credentials_url
 ---------------
 

src/converse-core.js

@@ -233,6 +233,7 @@
             auto_subscribe: false,
             auto_xa: 0, // Seconds after which user status is set to 'xa'
             bosh_service_url: undefined, // The BOSH connection manager URL.
+            connection_options: {},
             credentials_url: null, // URL from where login credentials can be fetched
             csi_waiting_time: 0, // Support for XEP-0352. Seconds before client is considered idle and CSI is sent out.
             debug: false,
@@ -1916,9 +1917,12 @@
                 throw new Error("initConnection: you must supply a value for either the bosh_service_url or websocket_url or both.");
             }
             if (('WebSocket' in window || 'MozWebSocket' in window) && this.websocket_url) {
-                this.connection = new Strophe.Connection(this.websocket_url);
+                this.connection = new Strophe.Connection(this.websocket_url, this.connection_options);
             } else if (this.bosh_service_url) {
-                this.connection = new Strophe.Connection(this.bosh_service_url, {'keepalive': this.keepalive});
+                this.connection = new Strophe.Connection(
+                    this.bosh_service_url,
+                    _.extend(this.connection_options, {'keepalive': this.keepalive})
+                );
             } else {
                 throw new Error("initConnection: this browser does not support websockets and bosh_service_url wasn't specified.");
             }