@itslanguage/api

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>communication/websocket.js - ITSLanguage JavaScript SDK</title> <meta name="description" content="Speech technology for language education. JSDoc 3 website for the JavaScript SDK." /> <meta name="keywords" content="itslangauge, jsdoc, documentation, speech, speech technology" /> <meta name="keyword" content="itslangauge, jsdoc, documentation, speech, speech technology" /> <meta property="og:title" content="ITSLanguage JavaScript SDK"/> <meta property="og:type" content="website"/> <meta property="og:image" content="https://avatars0.githubusercontent.com/u/20972344?s=400&u=73936e7fa2d2a1e5c180a11675bf9166d3717a6d&v=4"/> <meta property="og:site_name" content="ITSLanguage JavaScript SDK"/> <meta property="og:url" content="http://itslanguage.github.io/itslanguage-js/"/> <script src="scripts/prettify/prettify.js"></script> <script src="scripts/prettify/lang-css.js"></script>  <link type="text/css" rel="stylesheet" href="styles/prettify.css"> <link type="text/css" rel="stylesheet" href="styles/jsdoc.css"> <script src="scripts/nav.js" defer></script> <meta name="viewport" content="width=device-width, initial-scale=1.0"> </head> <body> <input type="checkbox" id="nav-trigger" class="nav-trigger" /> <label for="nav-trigger" class="navicon-button x"> <div class="navicon"></div> </label> <label for="nav-trigger" class="overlay"></label> <nav > <input type="text" id="nav-search" placeholder="Search" /> <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/itslanguage/itslanguage-js" target="_blank" class="menu-item" id="repository" >Github repo</a></h2><h3>Modules</h3><ul><li><a href="module-api.html">api</a><ul class='members'><li data-type='member'><a href="module-api.html#.version">version</a></li></ul><ul class='methods'><li data-type='method'><a href="module-api.html#.createItslApi">createItslApi</a></li></ul></li><li><a href="module-api_authentication.html">api/authentication</a><ul class='methods'><li data-type='method'><a href="module-api_authentication.html#.assembleScope">assembleScope</a></li><li data-type='method'><a href="module-api_authentication.html#.authenticate">authenticate</a></li><li data-type='method'><a href="module-api_authentication.html#.impersonate">impersonate</a></li></ul></li><li><a href="module-api_basicauth.html">api/basicauth</a><ul class='methods'><li data-type='method'><a href="module-api_basicauth.html#.create">create</a></li></ul></li><li><a href="module-api_broadcaster.html">api/broadcaster</a></li><li><a href="module-api_categories.html">api/categories</a><ul class='methods'><li data-type='method'><a href="module-api_categories.html#.create">create</a></li><li data-type='method'><a href="module-api_categories.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_categories.html#.getAllWithParentId">getAllWithParentId</a></li><li data-type='method'><a href="module-api_categories.html#.getById">getById</a></li><li data-type='method'><a href="module-api_categories.html#.update">update</a></li></ul></li><li><a href="module-api_challenges.html">api/challenges</a><ul class='members'><li data-type='member'><a href="module-api_challenges.html#.choice">choice</a></li><li data-type='member'><a href="module-api_challenges.html#.choiceRecognition">choiceRecognition</a></li><li data-type='member'><a href="module-api_challenges.html#.feedback">feedback</a></li><li data-type='member'><a href="module-api_challenges.html#.feedbackSpeech">feedbackSpeech</a></li><li data-type='member'><a href="module-api_challenges.html#.pronunciation">pronunciation</a></li><li data-type='member'><a href="module-api_challenges.html#.pronunciationAnalysis">pronunciationAnalysis</a></li><li data-type='member'><a href="module-api_challenges.html#.speech">speech</a></li><li data-type='member'><a href="module-api_challenges.html#.speechRecording">speechRecording</a></li></ul></li><li><a href="module-api_challenges_choice.html">api/challenges/choice</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_choice.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_choice.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_choice.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_choice_recognition.html">api/challenges/choice/recognition</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.getById">getById</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.prepare">prepare</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.prepareChallenge">prepareChallenge</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.recognise">recognise</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.recogniseAudioStream">recogniseAudioStream</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.recogniseNonStreaming">recogniseNonStreaming</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#~url">url</a></li></ul></li><li><a href="module-api_challenges_feedback.html">api/challenges/feedback</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_feedback.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_feedback.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_feedback.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_feedback_speech.html">api/challenges/feedback/speech</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.feedback">feedback</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.listenAndReply">listenAndReply</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.pause">pause</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.prepare">prepare</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.resume">resume</a></li></ul></li><li><a href="module-api_challenges_pronunciation.html">api/challenges/pronunciation</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_pronunciation.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_pronunciation.html#.deleteChallenge">deleteChallenge</a></li><li data-type='method'><a href="module-api_challenges_pronunciation.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_pronunciation.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_pronunciation_analysis.html">api/challenges/pronunciation/analysis</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.alignChallenge">alignChallenge</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.endStreamAudio">endStreamAudio</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.getById">getById</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.prepare">prepare</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.prepareAudio">prepareAudio</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.prepareChallenge">prepareChallenge</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.streamAudio">streamAudio</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#~url">url</a></li></ul></li><li><a href="module-api_challenges_speech.html">api/challenges/speech</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_speech.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_speech.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_speech.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_speech_recordings.html">api/challenges/speech/recordings</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.getById">getById</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.record">record</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#~url">url</a></li></ul></li><li><a href="module-api_communication.html">api/communication</a><ul class='members'><li data-type='member'><a href="module-api_communication.html#.settings">settings</a></li><li data-type='member'><a href="module-api_communication.html#~APPLICATION_JSON">APPLICATION_JSON</a></li><li data-type='member'><a href="module-api_communication.html#~AUTHORIZATION">AUTHORIZATION</a></li><li data-type='member'><a href="module-api_communication.html#~CONTENT_TYPE">CONTENT_TYPE</a></li><li data-type='member'><a href="module-api_communication.html#~LINK">LINK</a></li></ul><ul class='methods'><li data-type='method'><a href="module-api_communication.html#.addAccessToken">addAccessToken</a></li><li data-type='method'><a href="module-api_communication.html#.authorisedRequest">authorisedRequest</a></li><li data-type='method'><a href="module-api_communication.html#.request">request</a></li><li data-type='method'><a href="module-api_communication.html#.updateSettings">updateSettings</a></li><li data-type='method'><a href="module-api_communication.html#~getBearerToken">getBearerToken</a></li><li data-type='method'><a href="module-api_communication.html#~handleResponse">handleResponse</a></li></ul></li><li><a href="module-api_communication_websocket.html">api/communication/websocket</a><ul class='methods'><li data-type='method'><a href="module-api_communication_websocket.html#.closeWebsocketConnection">closeWebsocketConnection</a></li><li data-type='method'><a href="module-api_communication_websocket.html#.getWebsocketConnection">getWebsocketConnection</a></li><li data-type='method'><a href="module-api_communication_websocket.html#.makeWebsocketCall">makeWebsocketCall</a></li><li data-type='method'><a href="module-api_communication_websocket.html#.openWebsocketConnection">openWebsocketConnection</a></li><li data-type='method'><a href="module-api_communication_websocket.html#~establishNewBundesbahn">establishNewBundesbahn</a></li><li data-type='method'><a href="module-api_communication_websocket.html#~handleWebsocketAuthorisationChallenge">handleWebsocketAuthorisationChallenge</a></li></ul></li><li><a href="module-api_emailauth.html">api/emailauth</a><ul class='methods'><li data-type='method'><a href="module-api_emailauth.html#.create">create</a></li><li data-type='method'><a href="module-api_emailauth.html#~url">url</a></li></ul></li><li><a href="module-api_groups.html">api/groups</a><ul class='methods'><li data-type='method'><a href="module-api_groups.html#.create">create</a></li><li data-type='method'><a href="module-api_groups.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_groups.html#.getById">getById</a></li></ul></li><li><a href="module-api_organisations.html">api/organisations</a><ul class='methods'><li data-type='method'><a href="module-api_organisations.html#.create">create</a></li><li data-type='method'><a href="module-api_organisations.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_organisations.html#.getById">getById</a></li></ul></li><li><a href="module-api_profile.html">api/profile</a><ul class='methods'><li data-type='method'><a href="module-api_profile.html#.create">create</a></li><li data-type='method'><a href="module-api_profile.html#.getById">getById</a></li><li data-type='method'><a href="module-api_profile.html#.getCurrent">getCurrent</a></li><li data-type='method'><a href="module-api_profile.html#~url">url</a></li></ul></li><li><a href="module-api_progress.html">api/progress</a><ul class='methods'><li data-type='method'><a href="module-api_progress.html#.getById">getById</a></li></ul></li><li><a href="module-api_roles.html">api/roles</a><ul class='methods'><li data-type='method'><a href="module-api_roles.html#.create">create</a></li><li data-type='method'><a href="module-api_roles.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_roles.html#.getById">getById</a></li></ul></li><li><a href="module-api_tenants.html">api/tenants</a><ul class='methods'><li data-type='method'><a href="module-api_tenants.html#.create">create</a></li><li data-type='method'><a href="module-api_tenants.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_tenants.html#.getById">getById</a></li></ul></li><li><a href="module-api_users.html">api/users</a><ul class='methods'><li data-type='method'><a href="module-api_users.html#.create">create</a></li><li data-type='method'><a href="module-api_users.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_users.html#.getById">getById</a></li><li data-type='method'><a href="module-api_users.html#.getCurrent">getCurrent</a></li></ul></li><li><a href="module-api_utils.html">api/utils</a><ul class='methods'><li data-type='method'><a href="module-api_utils.html#.asyncBlobToArrayBuffer">asyncBlobToArrayBuffer</a></li><li data-type='method'><a href="module-api_utils.html#.checkAudioIsNotEmpty">checkAudioIsNotEmpty</a></li><li data-type='method'><a href="module-api_utils.html#.dataToBase64">dataToBase64</a></li></ul></li><li><a href="module-api_utils_audio-over-socket.html">api/utils/audio-over-socket</a><ul class='methods'><li data-type='method'><a href="module-api_utils_audio-over-socket.html#.encodeAndSendAudioOnDataAvailable">encodeAndSendAudioOnDataAvailable</a></li><li data-type='method'><a href="module-api_utils_audio-over-socket.html#.prepareServerForAudio">prepareServerForAudio</a></li><li data-type='method'><a href="module-api_utils_audio-over-socket.html#.registerStreamForRecorder">registerStreamForRecorder</a></li></ul></li></ul><h3>Classes</h3><ul><li><a href="module-api.Itslanguage.html">Itslanguage</a></li></ul><h3>Events</h3><ul><li><a href="broadcaster.html#event:websocketserverreadyforaudio">websocketserverreadyforaudio</a></li></ul> </nav> <div id="main"> <h1 class="page-title">communication/websocket.js</h1> <section> <article> <pre class="prettyprint source linenums"><code>/** * @module api/communication/websocket */ import autobahn from 'autobahn'; import debug from 'debug'; import { settings } from './index'; const log = debug('its-sdk:WebSocket'); const error = debug('its-sdk:WebSocket'); log.log = console.log.bind(console); /** * Keep hold of the currently open autobahn connection. * * @type {Promise<autobahn.Connection>} */ let bundesautobahn; /** * Allow the `autobahn.Connection` to challenge the provided authentication. * * @param {autobahn.Session} session - The session of the current {@link autobahn.Connection}. * @param {string} method - The authentication method it tries to use. * * @throws {Error} - When the given `method` is unknown to the SDK. */ function handleWebsocketAuthorisationChallenge(session, method) { switch (method) { case 'ticket': return settings.authorizationToken; default: throw new Error( 'The websocket server tried to use the unknown ' + `authentication challenge: "${method}"`, ); } } /** * Set {@link bundesautobahn} to a new Promise which resolves into a `autobahn.Connection` object * when a connection was successfully established. * * @returns {Promise<autobahn.Connection>} - A promise which resolves when the connection was * successfully created and opened. */ function establishNewBundesbahn() { bundesautobahn = new Promise((resolve, reject) => { const bahn = new autobahn.Connection({ url: settings.wsUrl, realm: 'default', // Of course we want to use es6 promises if they are available. // But, the backend sometimes spits out progress. For that we need // a When.JS promise.. use_es6_promises: false, // eslint-disable-line camelcase // The following options are required in order to authorise the // connection. authmethods: ['ticket'], authid: 'oauth2', details: { ticket: settings.authorizationToken, }, max_retries: 0, onchallenge: handleWebsocketAuthorisationChallenge, }); // The connection close callback is fired when the connection has been // closed explicitly, was lost or could not be established in the first // place. For more information on the connection callbacks go to // https://github.com/crossbario/autobahn-js/blob/master/doc/reference.md#connection-callbacks bahn.onclose = (reason, details) => { if (reason === 'closed' && details.reason === 'wamp.close.normal') { // A normal disconnect! No need to error out here; resolve(reason); } else { // Several errors might be true here // closed, lost, unreachable or unsupported reject(reason); } }; // Connection got established; lets us it. bahn.onopen = () => { log('Successfully established a websocket connection.'); resolve(bahn); }; bahn.open(); }); // Return the promise to make it this function chainable. In case the // `bundesautobahn` is rejected; remove the reference so we can use simple // falsy checks to determine if there is a connection. return bundesautobahn.catch(reason => { bundesautobahn = null; return Promise.reject(reason); }); } /** * Close the current websocket connection. * * @returns {Promise<string>} - A promise which will resolve as soon as the connection was * successfully closed. */ export function closeWebsocketConnection() { if (!bundesautobahn) { return Promise.resolve('There is no websocket connection to close.'); } return bundesautobahn.then(bahn => { try { bahn.close(); bundesautobahn = null; const message = 'The websocket connection has been closed successfully.'; log(message); return message; } catch (reason) { // `autobahn.Connection.close()` throws a string when the connection is // already closed. The connection is not exposed and therefore cannot be // closed by anyone using the SDK. Regardless, when it happens just // return a resolved promise. bundesautobahn = null; const message = 'The websocket connection has already been closed.'; error(message); return message; } }); } /** * Open a new websocket connection. * * There there currently is a open connection, close it and open a new connection. * * @returns {Promise<string>} - A resolved promise which resolves when the connection was * successfully created and opened. */ export function openWebsocketConnection() { return ( closeWebsocketConnection() .then(() => establishNewBundesbahn()) // `bundesautobahn` actually resolved with the `autobahn.Connection` // object. This is only meant for internal usage and therefore should not // be exposed to the users of the SDK. .then(() => 'Successfully established a websocket connection.') ); } /** * Get the current websocket connection, or open a new one. * * If there is no current connection, open one and return that in stead. * * @returns {Promise<autobahn.Connection>} - The current websocket connection. */ export function getWebsocketConnection() { if (!bundesautobahn) { return establishNewBundesbahn(); } return bundesautobahn; } /** * Make a rpc call to the ITSLanguage websocket server. * * This method will try to establish a websocket connection if there isn't one already. * * @param {string} rpc - The RPC to make. This be prepended by `nl.itslanguage` as the websocket * server only handles websocket calls when the RPC starts with that prefix. * @param {Object} [options] - Destructed object with options to pass to the websocket server. * @param {Array} [options.args] - An array with arguments to pass to the RPC. * @param {Object} [options.kwargs] - An object (dictionary) with arguments to pass to the RPC. * @param {Object} [options.options] - The options to pass to the RPC. * @param {Function} [options.progressCb] - Optional callback to receive progressed results. * * @returns {Promise<*>} - The response of the websocket call. */ export function makeWebsocketCall( rpc, { args, kwargs, options, progressCb } = {}, ) { let mergedOptions = options; if (progressCb) { mergedOptions = { ...options, receive_progress: true, // eslint-disable-line camelcase }; } return getWebsocketConnection() .then(connection => connection.session .call(`nl.itslanguage.${rpc}`, args, kwargs, mergedOptions) .progress(progressCb), ) .catch(result => { const { error: wssError, kwargs: wssKwargs, args: wssArgs } = result; // Log the error to stderr error(result); const customError = new Error(wssError); customError.data = { args: wssArgs || [], kwargs: wssKwargs || {}, }; // Return a slightly simplistic version of the error that occurred return Promise.reject(customError); }); } </code></pre> </article> </section> </div> <br class="clear"> <footer> Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Mon Oct 12 2020 12:26:34 GMT+0000 (Coordinated Universal Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme. </footer> <script>prettyPrint();</script> <script src="scripts/polyfill.js"></script> <script src="scripts/linenumber.js"></script> <script src="scripts/search.js" defer></script> </body> </html>