Skip to content

Commit 4a77b26

Browse files
jcbrandjcbrand
committed
Make sure ConnectionOptions type is exportable
1 parent ca86312 commit 4a77b26

File tree

8 files changed

+290
-556
lines changed

8 files changed

+290
-556
lines changed

‎src/connection.js

+128-128
Original file line numberDiff line numberDiff line change
@@ -28,18 +28,141 @@ import Bosh from './bosh.js';
2828
import WorkerWebsocket from './worker-websocket.js';
2929
import Websocket from './websocket.js';
3030

31+
/**
32+
* @typedef {import("./sasl.js").default} SASLMechanism
33+
* @typedef {import("./request.js").default} Request
34+
*
35+
* @typedef {Object} ConnectionOptions
36+
* @property {Cookies} [cookies]
37+
* Allows you to pass in cookies that will be included in HTTP requests.
38+
* Relevant to both the BOSH and Websocket transports.
39+
*
40+
* The passed in value must be a map of cookie names and string values.
41+
*
42+
* > { "myCookie": {
43+
* > "value": "1234",
44+
* > "domain": ".example.org",
45+
* > "path": "/",
46+
* > "expires": expirationDate
47+
* > }
48+
* > }
49+
*
50+
* Note that cookies can't be set in this way for domains other than the one
51+
* that's hosting Strophe (i.e. cross-domain).
52+
* Those cookies need to be set under those domains, for example they can be
53+
* set server-side by making a XHR call to that domain to ask it to set any
54+
* necessary cookies.
55+
* @property {SASLMechanism[]} [mechanisms]
56+
* Allows you to specify the SASL authentication mechanisms that this
57+
* instance of Connection (and therefore your XMPP client) will support.
58+
*
59+
* The value must be an array of objects with {@link SASLMechanism}
60+
* prototypes.
61+
*
62+
* If nothing is specified, then the following mechanisms (and their
63+
* priorities) are registered:
64+
*
65+
* Mechanism Priority
66+
* ------------------------
67+
* SCRAM-SHA-512 72
68+
* SCRAM-SHA-384 71
69+
* SCRAM-SHA-256 70
70+
* SCRAM-SHA-1 60
71+
* PLAIN 50
72+
* OAUTHBEARER 40
73+
* X-OAUTH2 30
74+
* ANONYMOUS 20
75+
* EXTERNAL 10
76+
*
77+
* @property {boolean} [explicitResourceBinding]
78+
* If `explicitResourceBinding` is set to `true`, then the XMPP client
79+
* needs to explicitly call {@link Connection.bind} once the XMPP
80+
* server has advertised the `urn:ietf:propertys:xml:ns:xmpp-bind` feature.
81+
*
82+
* Making this step explicit allows client authors to first finish other
83+
* stream related tasks, such as setting up an XEP-0198 Stream Management
84+
* session, before binding the JID resource for this session.
85+
*
86+
* @property {'ws'|'wss'} [protocol]
87+
* _Note: This option is only relevant to Websocket connections, and not BOSH_
88+
*
89+
* If you want to connect to the current host with a WebSocket connection you
90+
* can tell Strophe to use WebSockets through the "protocol" option.
91+
* Valid values are `ws` for WebSocket and `wss` for Secure WebSocket.
92+
* So to connect to "wss://CURRENT_HOSTNAME/xmpp-websocket" you would call
93+
*
94+
* const conn = new Strophe.Connection(
95+
* "/xmpp-websocket/",
96+
* {protocol: "wss"}
97+
* );
98+
*
99+
* Note that relative URLs _NOT_ starting with a "/" will also include the path
100+
* of the current site.
101+
*
102+
* Also because downgrading security is not permitted by browsers, when using
103+
* relative URLs both BOSH and WebSocket connections will use their secure
104+
* variants if the current connection to the site is also secure (https).
105+
*
106+
* @property {string} [worker]
107+
* _Note: This option is only relevant to Websocket connections, and not BOSH_
108+
*
109+
* Set this option to URL from where the shared worker script should be loaded.
110+
*
111+
* To run the websocket connection inside a shared worker.
112+
* This allows you to share a single websocket-based connection between
113+
* multiple Connection instances, for example one per browser tab.
114+
*
115+
* The script to use is the one in `src/shared-connection-worker.js`.
116+
*
117+
* @property {boolean} [sync]
118+
* Used to control whether BOSH HTTP requests will be made synchronously or not.
119+
* The default behaviour is asynchronous. If you want to make requests
120+
* synchronous, make "sync" evaluate to true.
121+
*
122+
* > const conn = new Strophe.Connection("/http-bind/", {sync: true});
123+
*
124+
* You can also toggle this on an already established connection.
125+
*
126+
* > conn.options.sync = true;
127+
*
128+
* @property {string[]} [customHeaders]
129+
* Used to provide custom HTTP headers to be included in the BOSH HTTP requests.
130+
*
131+
* @property {boolean} [keepalive]
132+
* Used to instruct Strophe to maintain the current BOSH session across
133+
* interruptions such as webpage reloads.
134+
*
135+
* It will do this by caching the sessions tokens in sessionStorage, and when
136+
* "restore" is called it will check whether there are cached tokens with
137+
* which it can resume an existing session.
138+
*
139+
* @property {boolean} [withCredentials]
140+
* Used to indicate wether cookies should be included in HTTP requests (by default
141+
* they're not).
142+
* Set this value to `true` if you are connecting to a BOSH service
143+
* and for some reason need to send cookies to it.
144+
* In order for this to work cross-domain, the server must also enable
145+
* credentials by setting the `Access-Control-Allow-Credentials` response header
146+
* to "true". For most usecases however this setting should be false (which
147+
* is the default).
148+
* Additionally, when using `Access-Control-Allow-Credentials`, the
149+
* `Access-Control-Allow-Origin` header can't be set to the wildcard "*", but
150+
* instead must be restricted to actual domains.
151+
*
152+
* @property {string} [contentType]
153+
* Used to change the default Content-Type, which is "text/xml; charset=utf-8".
154+
* Can be useful to reduce the amount of CORS preflight requests that are sent
155+
* to the server.
156+
*/
157+
158+
31159
/**
32160
* _Private_ variable Used to store plugin names that need
33161
* initialization during Connection construction.
34162
* @type {Object.<string, Object>}
35163
*/
36164
const connectionPlugins = {};
37165

38-
/**
39-
* @typedef {import("./sasl.js").default} SASLMechanism
40-
* @typedef {import("./request.js").default} Request
41-
*/
42-
43166
/**
44167
* **XMPP Connection manager**
45168
*
@@ -73,129 +196,6 @@ class Connection {
73196
* @typedef {Cookie|Object.<string, Cookie>} Cookies
74197
*/
75198

76-
/**
77-
* @typedef {Object} ConnectionOptions
78-
* @property {Cookies} [cookies]
79-
* Allows you to pass in cookies that will be included in HTTP requests.
80-
* Relevant to both the BOSH and Websocket transports.
81-
*
82-
* The passed in value must be a map of cookie names and string values.
83-
*
84-
* > { "myCookie": {
85-
* > "value": "1234",
86-
* > "domain": ".example.org",
87-
* > "path": "/",
88-
* > "expires": expirationDate
89-
* > }
90-
* > }
91-
*
92-
* Note that cookies can't be set in this way for domains other than the one
93-
* that's hosting Strophe (i.e. cross-domain).
94-
* Those cookies need to be set under those domains, for example they can be
95-
* set server-side by making a XHR call to that domain to ask it to set any
96-
* necessary cookies.
97-
* @property {SASLMechanism[]} [mechanisms]
98-
* Allows you to specify the SASL authentication mechanisms that this
99-
* instance of Connection (and therefore your XMPP client) will support.
100-
*
101-
* The value must be an array of objects with {@link SASLMechanism}
102-
* prototypes.
103-
*
104-
* If nothing is specified, then the following mechanisms (and their
105-
* priorities) are registered:
106-
*
107-
* Mechanism Priority
108-
* ------------------------
109-
* SCRAM-SHA-512 72
110-
* SCRAM-SHA-384 71
111-
* SCRAM-SHA-256 70
112-
* SCRAM-SHA-1 60
113-
* PLAIN 50
114-
* OAUTHBEARER 40
115-
* X-OAUTH2 30
116-
* ANONYMOUS 20
117-
* EXTERNAL 10
118-
*
119-
* @property {boolean} [explicitResourceBinding]
120-
* If `explicitResourceBinding` is set to `true`, then the XMPP client
121-
* needs to explicitly call {@link Connection.bind} once the XMPP
122-
* server has advertised the `urn:ietf:propertys:xml:ns:xmpp-bind` feature.
123-
*
124-
* Making this step explicit allows client authors to first finish other
125-
* stream related tasks, such as setting up an XEP-0198 Stream Management
126-
* session, before binding the JID resource for this session.
127-
*
128-
* @property {'ws'|'wss'} [protocol]
129-
* _Note: This option is only relevant to Websocket connections, and not BOSH_
130-
*
131-
* If you want to connect to the current host with a WebSocket connection you
132-
* can tell Strophe to use WebSockets through the "protocol" option.
133-
* Valid values are `ws` for WebSocket and `wss` for Secure WebSocket.
134-
* So to connect to "wss://CURRENT_HOSTNAME/xmpp-websocket" you would call
135-
*
136-
* const conn = new Strophe.Connection(
137-
* "/xmpp-websocket/",
138-
* {protocol: "wss"}
139-
* );
140-
*
141-
* Note that relative URLs _NOT_ starting with a "/" will also include the path
142-
* of the current site.
143-
*
144-
* Also because downgrading security is not permitted by browsers, when using
145-
* relative URLs both BOSH and WebSocket connections will use their secure
146-
* variants if the current connection to the site is also secure (https).
147-
*
148-
* @property {string} [worker]
149-
* _Note: This option is only relevant to Websocket connections, and not BOSH_
150-
*
151-
* Set this option to URL from where the shared worker script should be loaded.
152-
*
153-
* To run the websocket connection inside a shared worker.
154-
* This allows you to share a single websocket-based connection between
155-
* multiple Connection instances, for example one per browser tab.
156-
*
157-
* The script to use is the one in `src/shared-connection-worker.js`.
158-
*
159-
* @property {boolean} [sync]
160-
* Used to control whether BOSH HTTP requests will be made synchronously or not.
161-
* The default behaviour is asynchronous. If you want to make requests
162-
* synchronous, make "sync" evaluate to true.
163-
*
164-
* > const conn = new Strophe.Connection("/http-bind/", {sync: true});
165-
*
166-
* You can also toggle this on an already established connection.
167-
*
168-
* > conn.options.sync = true;
169-
*
170-
* @property {string[]} [customHeaders]
171-
* Used to provide custom HTTP headers to be included in the BOSH HTTP requests.
172-
*
173-
* @property {boolean} [keepalive]
174-
* Used to instruct Strophe to maintain the current BOSH session across
175-
* interruptions such as webpage reloads.
176-
*
177-
* It will do this by caching the sessions tokens in sessionStorage, and when
178-
* "restore" is called it will check whether there are cached tokens with
179-
* which it can resume an existing session.
180-
*
181-
* @property {boolean} [withCredentials]
182-
* Used to indicate wether cookies should be included in HTTP requests (by default
183-
* they're not).
184-
* Set this value to `true` if you are connecting to a BOSH service
185-
* and for some reason need to send cookies to it.
186-
* In order for this to work cross-domain, the server must also enable
187-
* credentials by setting the `Access-Control-Allow-Credentials` response header
188-
* to "true". For most usecases however this setting should be false (which
189-
* is the default).
190-
* Additionally, when using `Access-Control-Allow-Credentials`, the
191-
* `Access-Control-Allow-Origin` header can't be set to the wildcard "*", but
192-
* instead must be restricted to actual domains.
193-
*
194-
* @property {string} [contentType]
195-
* Used to change the default Content-Type, which is "text/xml; charset=utf-8".
196-
* Can be useful to reduce the amount of CORS preflight requests that are sent
197-
* to the server.
198-
*/
199199

200200
/**
201201
* Create and initialize a {@link Connection} object.

‎src/index.js

+1
Original file line numberDiff line numberDiff line change
@@ -184,5 +184,6 @@ globalThis.$iq = $iq;
184184
globalThis.$msg = $msg;
185185
globalThis.$pres = $pres;
186186
globalThis.Strophe = Strophe;
187+
globalThis.toStanza = toStanza;
187188

188189
export { Builder, $build, $iq, $msg, $pres, Strophe, Stanza, stx, toStanza, Request };

‎src/stanza.js

+7-9
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@ export function toStanza(string, throwErrorIfInvalidNS) {
1616
}
1717

1818
const node = doc.firstElementChild;
19-
2019
if (
2120
['message', 'iq', 'presence'].includes(node.nodeName.toLowerCase()) &&
2221
node.namespaceURI !== 'jabber:client' &&
@@ -33,21 +32,20 @@ export function toStanza(string, throwErrorIfInvalidNS) {
3332
}
3433

3534
/**
36-
* A Stanza represents a XML element used in XMPP (commonly referred to as
37-
* stanzas).
35+
* A Stanza represents a XML element used in XMPP (commonly referred to as stanzas).
3836
*/
3937
export class Stanza {
4038
/**
41-
* @param { string[] } strings
42-
* @param { any[] } values
39+
* @param {string[]} strings
40+
* @param {any[]} values
4341
*/
4442
constructor(strings, values) {
4543
this.strings = strings;
4644
this.values = values;
4745
}
4846

4947
/**
50-
* @return { string }
48+
* @return {string}
5149
*/
5250
toString() {
5351
this.string =
@@ -61,7 +59,7 @@ export class Stanza {
6159
}
6260

6361
/**
64-
* @return { Element }
62+
* @return {Element}
6563
*/
6664
tree() {
6765
this.node = this.node ?? toStanza(this.toString(), true);
@@ -73,8 +71,8 @@ export class Stanza {
7371
* Tagged template literal function which generates {@link Stanza } objects
7472
* @example stx`<presence type="${type}" xmlns="jabber:client"><show>${show}</show></presence>`
7573
*
76-
* @param { string[] } strings
77-
* @param { ...any } values
74+
* @param {string[]} strings
75+
* @param {...any} values
7876
*/
7977
export function stx(strings, ...values) {
8078
return new Stanza(strings, values);

0 commit comments

Comments
 (0)