From 0407826057a5615a76aff68b543fb9b1a3f3e97c Mon Sep 17 00:00:00 2001 From: JC Brand Date: Sun, 8 Feb 2015 19:35:58 +0100 Subject: [PATCH] Two websocket related changes. updates #204 * Handle case where no websocket url is specified. * Update the documentation w.r.t. websockets --- converse.js | 6 +++-- docs/source/configuration.rst | 51 +++++++++++++++++++++++++++++++++-- docs/source/setup.rst | 20 +++++++++----- 3 files changed, 66 insertions(+), 11 deletions(-) diff --git a/converse.js b/converse.js index 1cf9650ff..e8c1bd8f0 100644 --- a/converse.js +++ b/converse.js @@ -5100,10 +5100,12 @@ if (!this.bosh_service_url && ! this.websocket_url) { throw("Error: you must supply a value for the bosh_service_url or websocket_url"); } - if ('WebSocket' in window || 'MozWebSocket' in window) { + if (('WebSocket' in window || 'MozWebSocket' in window) && this.websocket_url) { this.connection = new Strophe.Connection(this.websocket_url); - } else { + } else if (this.bosh_service_url) { this.connection = new Strophe.Connection(this.bosh_service_url); + } else { + throw("Error: this browser does not support websockets and no bosh_service_url specified."); } this.setUpXMLLogging(); diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 992124aa8..c4e65c207 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -103,11 +103,20 @@ If true, the user will automatically subscribe back to any contact requests. bosh_service_url ---------------- -Connections to an XMPP server depend on a BOSH connection manager which acts as -a middle man between HTTP and XMPP. +Default: ``undefined`` +To connect to an XMPP server over HTTP you need a `BOSH `_ +connection manager which acts as a middle man between the HTTP and XMPP +protocols. + +The bosh_service_url setting takes the URL of a BOSH connection manager. + +Please refer to your XMPP server's documentation on how to enable BOSH. For more information, read this blog post: `Which BOSH server do you need? `_ +A more modern alternative to BOSH is to use `websockets `_. +Please see the :ref:`websocket-url` configuration setting. + cache_otr_key ------------- @@ -145,6 +154,8 @@ Default: ``e.g. conversejs.org`` The placeholder text shown in the domain input on the registration form. +.. _`keepalive`: + keepalive --------- @@ -158,6 +169,13 @@ See also: * :ref:`session-support` * `Using prebind in connection with keepalive`_ +.. note:: + Currently the "keepalive" setting only works with BOSH and not with + websockets. This is because XMPP over websocket does not use the same + session token as with BOSH. A possible solution for this is to implement + `XEP-0198 `_, specifically + with regards to "stream resumption". + message_carbons --------------- @@ -257,6 +275,8 @@ it in both formats as ``http://yoursite.com/sounds/msg_received.mp3`` and ``http://yoursite.com`` should of course be your site's URL. +.. _`prebind`: + prebind -------- @@ -452,6 +472,33 @@ Allows you to show or hide buttons on the chat boxes' toolbars. * toggle_participants: Shows a button for toggling (i.e. showing/hiding) the list of participants in a chat room. +.. _`websocket-url`: + +websocket_url +------------- + +Default: ``undefined`` + +This option is used to specify a +`websocket `_ URI to which +converse.js can connect to. + +Websockets provide a more modern and effective two-way communication protocol +between the browser and a server, effectively emulating TCP at the application +layer and therefore overcoming many of the problems with existing long-polling +techniques for bidirectional HTTP (such as `BOSH `_). + +Please refer to your XMPP server's documentation on how to enable websocket +support. + +.. note:: + Please note that not older browsers do not support websockets. For older + browsers you'll want to specify a BOSH URL. See the :ref:`bosh-service-url` + configuration setting). + +.. note:: + Converse.js does not yet support "keepalive" with websockets. + xhr_custom_status ----------------- diff --git a/docs/source/setup.rst b/docs/source/setup.rst index a81905a1c..d336779f6 100644 --- a/docs/source/setup.rst +++ b/docs/source/setup.rst @@ -120,15 +120,15 @@ Apache Single Session Support ---------------------- -Server-side authentication -========================== +Server-side authentication (prebind) +==================================== -It's possible to enable single-site login, whereby users already -authenticated in your website will also automatically be logged in on the chat server, +It's possible to enable shared sessions whereby users already +authenticated in your website will also automatically be logged in on the XMPP server, -This session should also persist across page loads. In other words, we don't -want the user to have to give their chat credentials every time they reload the -page. +This session can be made to persist across page loads. In other words, we want +a user to automatically be logged in to chat when they log in to the website, +and we want their chat session to persist across page loads. To do this you will require a `BOSH server `_ for converse.js to connect to (see the :ref:`bosh-service-url` under :ref:`configuration-variables`) @@ -193,6 +193,12 @@ These values are then passed to converse.js's ``initialize`` method. Additionally you need to pass in valid **jid**, **sid**, **rid** and **bosh_service_url** values. + The :ref:`prebind` configuration setting can be used together with the + :ref:`keepalive` setting. This means you only have to prebind once for the + first page the user loads and not anymore for subsequent pages. + + For more info, please refer to the :ref:`configuration-variables` section. + Example code for server-side prebinding =======================================