[tor-commits] [pluggable-transports/snowflake-webext] 02/02: refactor: add some more JSDoc
gitolite role
git at cupani.torproject.org
Fri Jul 15 11:17:34 UTC 2022
This is an automated email from the git hooks/post-receive script.
meskio pushed a commit to branch main
in repository pluggable-transports/snowflake-webext.
commit 4b56f7a350ef78ac2f8888cdd15d529dada30f72
Author: WofWca <wofwca at protonmail.com>
AuthorDate: Wed Jul 13 15:34:22 2022 +0300
refactor: add some more JSDoc
---
broker.js | 7 ++++++-
init-badge.js | 27 ++++++++++++++++++++++++++-
init-testing.js | 20 +++++++++++++++++++-
init-webext.js | 26 +++++++++++++++++++++++++-
proxypair.js | 27 ++++++++++++++++++++++++---
snowflake.js | 15 ++++++++++++++-
util.js | 7 ++++++-
websocket.js | 4 ++--
8 files changed, 122 insertions(+), 11 deletions(-)
diff --git a/broker.js b/broker.js
index 36ca3f8..761efcf 100644
--- a/broker.js
+++ b/broker.js
@@ -15,6 +15,7 @@ class Broker {
* ID so the Broker can keep track of each proxy's signalling channels.
* On construction, this Broker object does not do anything until
* `getClientOffer` is called.
+ * @param {Config} config
*/
constructor(config) {
this.getClientOffer = this.getClientOffer.bind(this);
@@ -85,6 +86,8 @@ class Broker {
/**
* Assumes getClientOffer happened, and a WebRTC SDP answer has been generated.
* Sends it back to the broker, which passes it to back to the original client.
+ * @param {string} id
+ * @param {RTCSessionDescription} answer
*/
sendAnswer(id, answer) {
dbg(id + ' - Sending answer back to broker...\n');
@@ -114,8 +117,10 @@ class Broker {
}
/**
- * urlSuffix for the broker is different depending on what action
+ * @param {XMLHttpRequest} xhr
+ * @param {string} urlSuffix for the broker is different depending on what action
* is desired.
+ * @param {string} payload
*/
_postRequest(xhr, urlSuffix, payload) {
try {
diff --git a/init-badge.js b/init-badge.js
index ec62b5d..a4305a2 100644
--- a/init-badge.js
+++ b/init-badge.js
@@ -122,7 +122,32 @@ function getLang() {
return defaultLang;
}
-var debug, snowflake, config, broker, ui, log, dbg, init, update, silenceNotifications, query, tryProbe;
+/** @typedef {BadgeUI} UIOfThisContext */
+var
+ /** @type {boolean} */
+ debug,
+ /** @type {Snowflake | null} */
+ snowflake,
+ /** @type {Config | null} */
+ config,
+ /** @type {Broker | null} */
+ broker,
+ /** @type {UIOfThisContext | null} */
+ ui,
+ /** @type {(msg: unknown) => void} */
+ log,
+ /** @type {(msg: unknown) => void} */
+ dbg,
+ /** @type {() => void} */
+ init,
+ /** @type {() => void} */
+ update,
+ /** @type {boolean} */
+ silenceNotifications,
+ /** @type {URLSearchParams} */
+ query,
+ /** @type {() => void} */
+ tryProbe;
(function() {
diff --git a/init-testing.js b/init-testing.js
index 6bc86ef..8333065 100644
--- a/init-testing.js
+++ b/init-testing.js
@@ -50,7 +50,25 @@ DebugUI.prototype.$status = null;
Entry point.
*/
-var snowflake, query, debug, ui, silenceNotifications, log, dbg, init;
+/** @typedef {DebugUI | UI} UIOfThisContext */
+var
+ /** @type {boolean} */
+ debug,
+ /** @type {Snowflake | null} */
+ snowflake,
+ /** @type {URLSearchParams} */
+ query,
+ /** @type {UIOfThisContext} */
+ ui,
+ /** @type {(msg: unknown) => void} */
+ log,
+ /** @type {(msg: unknown) => void} */
+ dbg,
+ /** @type {() => void} */
+ init,
+ /** @type {boolean} */
+ silenceNotifications;
+
(function() {
diff --git a/init-webext.js b/init-webext.js
index 0bba740..cde7d5f 100644
--- a/init-webext.js
+++ b/init-webext.js
@@ -109,6 +109,9 @@ class WebExtUI extends UI {
this.port = null;
}
+ /**
+ * @param {boolean} enabled
+ */
setEnabled(enabled) {
this.enabled = enabled;
this.postActive();
@@ -148,7 +151,28 @@ WebExtUI.prototype.enabled = true;
Entry point.
*/
-var debug, snowflake, config, broker, ui, log, dbg, init, update, silenceNotifications;
+/** @typedef {WebExtUI} UIOfThisContext */
+var
+ /** @type {boolean} */
+ debug,
+ /** @type {Snowflake | null} */
+ snowflake,
+ /** @type {Config | null} */
+ config,
+ /** @type {Broker | null} */
+ broker,
+ /** @type {UIOfThisContext | null} */
+ ui,
+ /** @type {(msg: unknown) => void} */
+ log,
+ /** @type {(msg: unknown) => void} */
+ dbg,
+ /** @type {() => void} */
+ init,
+ /** @type {() => void} */
+ update,
+ /** @type {boolean} */
+ silenceNotifications;
(function () {
diff --git a/proxypair.js b/proxypair.js
index a5b7823..41e6291 100644
--- a/proxypair.js
+++ b/proxypair.js
@@ -14,6 +14,7 @@ class ProxyPair {
/**
* @param relayAddr the destination relay
* @param {*} rateLimit specifies a rate limit on traffic
+ * @param {Config} config
*/
constructor(relayAddr, rateLimit, config) {
this.prepareDataChannel = this.prepareDataChannel.bind(this);
@@ -23,6 +24,7 @@ class ProxyPair {
this.onError = this.onError.bind(this);
this.flush = this.flush.bind(this);
+ /** @type {string | undefined} */
this.relayURL = undefined;
this.relayAddr = relayAddr;
this.rateLimit = rateLimit;
@@ -53,6 +55,10 @@ class ProxyPair {
};
}
+ /**
+ * @param {RTCSessionDescription} offer
+ * @returns {boolean} `true` on success, `false` on fail.
+ */
receiveWebRTCOffer(offer) {
if ('offer' !== offer.type) {
log('Invalid SDP received -- was not an offer.');
@@ -68,7 +74,10 @@ class ProxyPair {
return true;
}
- /** Given a WebRTC DataChannel, prepare callbacks. */
+ /**
+ * Given a WebRTC DataChannel, prepare callbacks.
+ * @param {RTCDataChannel} channel
+ */
prepareDataChannel(channel) {
channel.onopen = () => {
log('WebRTC DataChannel opened!');
@@ -146,7 +155,10 @@ class ProxyPair {
}), 5000);
}
- /** WebRTC --> websocket */
+ /**
+ * WebRTC --> websocket
+ * @param {MessageEvent} msg
+ */
onClientToRelayMessage(msg) {
if (this.messageTimer) {
clearTimeout(this.messageTimer);
@@ -164,7 +176,10 @@ class ProxyPair {
this.flush();
}
- /** websocket --> WebRTC */
+ /**
+ * websocket --> WebRTC
+ * @param {MessageEvent} event
+ */
onRelayToClientMessage(event) {
dbg('websocket --> WebRTC data: ' + event.data.byteLength + ' bytes');
this.r2cSchedule.push(event.data);
@@ -239,6 +254,9 @@ class ProxyPair {
return (null !== this.relay) && (WebSocket.OPEN === this.relay.readyState);
}
+ /**
+ * @param {WebSocket} ws
+ */
isClosed(ws) {
return undefined === ws || WebSocket.CLOSED === ws.readyState;
}
@@ -247,6 +265,9 @@ class ProxyPair {
return (null !== this.pc) && ('closed' !== this.pc.connectionState);
}
+ /**
+ * @param {typeof this.relayURL} relayURL
+ */
setRelayURL(relayURL) {
this.relayURL = relayURL;
}
diff --git a/snowflake.js b/snowflake.js
index 19d8992..b55a3bd 100644
--- a/snowflake.js
+++ b/snowflake.js
@@ -13,7 +13,12 @@ TODO: More documentation
class Snowflake {
- // Prepare the Snowflake with a Broker (to find clients) and optional UI.
+ /**
+ * Prepare the Snowflake with a Broker (to find clients) and optional UI.
+ * @param {Config} config
+ * @param {WebExtUI | BadgeUI | DebugUI} ui
+ * @param {Broker} broker
+ */
constructor(config, ui, broker) {
this.receiveOffer = this.receiveOffer.bind(this);
@@ -36,6 +41,7 @@ class Snowflake {
* Set the target relay address spec, which is expected to be websocket.
* TODO: Should potentially fetch the target from broker later, or modify
* entirely for the Tor-independent version.
+ * @param {{ host: string; port: string; }} relayAddr
*/
setRelayAddr(relayAddr) {
this.relayAddr = relayAddr;
@@ -119,6 +125,8 @@ class Snowflake {
/**
* Receive an SDP offer from some client assigned by the Broker
* @param {ProxyPair} pair an available ProxyPair.
+ * @param {string} desc
+ * @param {string | undefined} relayURL
* @returns {boolean} `true` on success, `false` on fail.
*/
receiveOffer(pair, desc, relayURL) {
@@ -137,6 +145,7 @@ class Snowflake {
}
pair.setRelayURL(relayURL);
}
+ /** @type {RTCSessionDescriptionInit} */
const offer = JSON.parse(desc);
dbg('Received:\n\n' + offer.sdp + '\n');
const sdp = new RTCSessionDescription(offer);
@@ -152,7 +161,11 @@ class Snowflake {
}
}
+ /**
+ * @param {ProxyPair} pair
+ */
sendAnswer(pair) {
+ /** @param {RTCLocalSessionDescriptionInit} sdp */
const next = function (sdp) {
dbg('webrtc: Answer ready.');
pair.pc.setLocalDescription(sdp).catch(fail);
diff --git a/util.js b/util.js
index 73d67be..7c865e8 100644
--- a/util.js
+++ b/util.js
@@ -22,10 +22,12 @@ class Util {
}
/**
- * returns a promise that resolves to "restricted" if we
+ * @returns {Promise<"restricted" | "unrestricted">}
+ * resolves to "restricted" if we
* fail to make a test connection to a known restricted
* NAT, "unrestricted" if the test connection succeeds, and
* "unknown" if we fail to reach the probe test server
+ * @param {number} timeout
*/
static checkNATType(timeout) {
let pc = new RTCPeerConnection({iceServers: [
@@ -70,6 +72,7 @@ class Util {
/**
* Assumes getClientOffer happened, and a WebRTC SDP answer has been generated.
* Sends it back to the broker, which passes it back to the original client.
+ * @param {RTCSessionDescription} offer
*/
static sendOffer(offer) {
return new Promise((fulfill, reject) => {
@@ -105,6 +108,7 @@ class Util {
class Parse {
/**
+ * @param {typeof document.cookie} cookies
* Parse a cookie data string (usually document.cookie). The return type is an
* object mapping cookies names to values. Returns null on error.
* http://www.w3.org/TR/DOM-Level-2-HTML/html.html#ID-8747038
@@ -128,6 +132,7 @@ class Parse {
}
/**
+ * @param {string} spec
* Parse an address in the form 'host:port'. Returns an Object with keys 'host'
* (String) and 'port' (int). Returns null on error.
*/
diff --git a/websocket.js b/websocket.js
index 4a27ef4..ed236c3 100644
--- a/websocket.js
+++ b/websocket.js
@@ -79,7 +79,7 @@ class WS {
}
static probeWebsocket(addr) {
- return new Promise((resolve, reject) => {
+ return /** @type {Promise<void>} */(new Promise((resolve, reject) => {
const ws = WS.makeWebsocket(addr);
ws.onopen = () => {
resolve();
@@ -89,7 +89,7 @@ class WS {
reject();
ws.close();
};
- });
+ }));
}
}
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
More information about the tor-commits
mailing list