[tor-commits] [pluggable-transports/snowflake-webext] 04/08: refactor: convert some comments to JSDoc, improve types
gitolite role
git at cupani.torproject.org
Wed Jul 6 09:01:43 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 17168c1f57c177e74ade038d1394476b2c740e3c
Author: WofWca <wofwca at protonmail.com>
AuthorDate: Sat Jun 18 18:23:12 2022 +0300
refactor: convert some comments to JSDoc, improve types
---
broker.js | 36 +++++++++++++++++++------------
proxypair.js | 25 +++++++++++-----------
snowflake.js | 31 +++++++++++++++++----------
ui.js | 2 +-
util.js | 70 +++++++++++++++++++++++++++++++++++++-----------------------
websocket.js | 6 ++++--
6 files changed, 102 insertions(+), 68 deletions(-)
diff --git a/broker.js b/broker.js
index 8d084e0..128eda7 100644
--- a/broker.js
+++ b/broker.js
@@ -1,6 +1,6 @@
/* global log, dbg, snowflake */
-/*
+/**
Communication with the snowflake broker.
Browser snowflakes must register with the broker in order
@@ -10,10 +10,12 @@ to get assigned to clients.
// Represents a broker running remotely.
class Broker {
- // When interacting with the Broker, snowflake must generate a unique session
- // 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.
+ /**
+ * When interacting with the Broker, snowflake must generate a unique session
+ * 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.
+ */
constructor(config) {
this.getClientOffer = this.getClientOffer.bind(this);
this._postRequest = this._postRequest.bind(this);
@@ -34,11 +36,13 @@ class Broker {
}
}
- // Promises some client SDP Offer.
- // Registers this Snowflake with the broker using an HTTP POST request, and
- // waits for a response containing some client offer that the Broker chooses
- // for this proxy..
- // TODO: Actually support multiple clients.
+ /**
+ * Promises some client SDP Offer.
+ * Registers this Snowflake with the broker using an HTTP POST request, and
+ * waits for a response containing some client offer that the Broker chooses
+ * for this proxy..
+ * TODO: Actually support multiple clients.
+ */
getClientOffer(id, numClientsConnected) {
return new Promise((fulfill, reject) => {
const xhr = new XMLHttpRequest();
@@ -77,8 +81,10 @@ 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.
+ /**
+ * 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.
+ */
sendAnswer(id, answer) {
dbg(id + ' - Sending answer back to broker...\n');
dbg(answer.sdp);
@@ -104,8 +110,10 @@ class Broker {
this.natType = natType;
}
- // urlSuffix for the broker is different depending on what action
- // is desired.
+ /**
+ * urlSuffix for the broker is different depending on what action
+ * is desired.
+ */
_postRequest(xhr, urlSuffix, payload) {
try {
xhr.open('POST', this.url + urlSuffix);
diff --git a/proxypair.js b/proxypair.js
index e423b59..880f202 100644
--- a/proxypair.js
+++ b/proxypair.js
@@ -1,6 +1,6 @@
/* global snowflake, log, dbg, Util, Parse, WS */
-/*
+/**
Represents a single:
client <-- webrtc --> snowflake <-- websocket --> relay
@@ -11,11 +11,10 @@ Broker with an WebRTC answer.
class ProxyPair {
- /*
- Constructs a ProxyPair where:
- - @relayAddr is the destination relay
- - @rateLimit specifies a rate limit on traffic
- */
+ /**
+ * @param relayAddr the destination relay
+ * @param {*} rateLimit specifies a rate limit on traffic
+ */
constructor(relayAddr, rateLimit, config) {
this.prepareDataChannel = this.prepareDataChannel.bind(this);
this.connectRelay = this.connectRelay.bind(this);
@@ -35,7 +34,7 @@ class ProxyPair {
this.counted = false;
}
- // Prepare a WebRTC PeerConnection and await for an SDP offer.
+ /** Prepare a WebRTC PeerConnection and await for an SDP offer. */
begin() {
this.pc = new RTCPeerConnection(this.pcConfig);
this.pc.onicecandidate = (evt) => {
@@ -69,7 +68,7 @@ class ProxyPair {
return true;
}
- // Given a WebRTC DataChannel, prepare callbacks.
+ /** Given a WebRTC DataChannel, prepare callbacks. */
prepareDataChannel(channel) {
channel.onopen = () => {
log('WebRTC DataChannel opened!');
@@ -96,7 +95,7 @@ class ProxyPair {
return channel.onmessage = this.onClientToRelayMessage;
}
- // Assumes WebRTC datachannel is connected.
+ /** Assumes WebRTC datachannel is connected. */
connectRelay() {
dbg('Connecting to relay...');
// Get a remote IP address from the PeerConnection, if possible. Add it to
@@ -147,7 +146,7 @@ class ProxyPair {
}), 5000);
}
- // WebRTC --> websocket
+ /** WebRTC --> websocket */
onClientToRelayMessage(msg) {
if (this.messageTimer) {
clearTimeout(this.messageTimer);
@@ -165,7 +164,7 @@ class ProxyPair {
return this.flush();
}
- // websocket --> WebRTC
+ /** websocket --> WebRTC */
onRelayToClientMessage(event) {
dbg('websocket --> WebRTC data: ' + event.data.byteLength + ' bytes');
this.r2cSchedule.push(event.data);
@@ -178,7 +177,7 @@ class ProxyPair {
return this.close();
}
- // Close both WebRTC and websocket.
+ /** Close both WebRTC and websocket. */
close() {
if (this.timer) {
clearTimeout(this.timer);
@@ -200,7 +199,7 @@ class ProxyPair {
this.onCleanup();
}
- // Send as much data in both directions as the rate limit currently allows.
+ /** Send as much data in both directions as the rate limit currently allows. */
flush() {
if (this.flush_timeout_id) {
clearTimeout(this.flush_timeout_id);
diff --git a/snowflake.js b/snowflake.js
index 7354b97..2c94cf8 100644
--- a/snowflake.js
+++ b/snowflake.js
@@ -1,6 +1,6 @@
/* global log, dbg, DummyRateLimit, BucketRateLimit, ProxyPair */
-/*
+/**
A JavaScript WebRTC snowflake proxy
Uses WebRTC from the client, and Websocket to the server.
@@ -32,16 +32,20 @@ class Snowflake {
this.retries = 0;
}
- // 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.
+ /**
+ * 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.
+ */
setRelayAddr(relayAddr) {
this.relayAddr = relayAddr;
log('Using ' + relayAddr.host + ':' + relayAddr.port + ' as Relay.');
}
- // Initialize WebRTC PeerConnection, which requires beginning the signalling
- // process. |pollBroker| automatically arranges signalling.
+ /**
+ * Initialize WebRTC PeerConnection, which requires beginning the signalling
+ * process. `pollBroker` automatically arranges signalling.
+ */
beginWebRTC() {
this.pollBroker();
this.pollTimeoutId = setTimeout((() => {
@@ -49,8 +53,10 @@ class Snowflake {
}), this.pollInterval);
}
- // Regularly poll Broker for clients to serve until this snowflake is
- // serving at capacity, at which point stop polling.
+ /**
+ * Regularly poll Broker for clients to serve until this snowflake is
+ * serving at capacity, at which point stop polling.
+ */
pollBroker() {
// Poll broker for clients.
const pair = this.makeProxyPair();
@@ -110,8 +116,11 @@ class Snowflake {
this.retries++;
}
- // Receive an SDP offer from some client assigned by the Broker,
- // |pair| - an available ProxyPair.
+ /**
+ * Receive an SDP offer from some client assigned by the Broker
+ * @param {ProxyPair} pair an available ProxyPair.
+ * @returns {boolean} `true` on success, `false` on fail.
+ */
receiveOffer(pair, desc, relayURL) {
try {
if (relayURL !== undefined) {
@@ -180,7 +189,7 @@ class Snowflake {
return pair;
}
- // Stop all proxypairs.
+ /** Stop all proxypairs. */
disable() {
log('Disabling Snowflake.');
clearTimeout(this.pollTimeoutId);
diff --git a/ui.js b/ui.js
index de8670d..6358758 100644
--- a/ui.js
+++ b/ui.js
@@ -1,4 +1,4 @@
-/*
+/**
All of Snowflake's DOM manipulation and inputs.
*/
diff --git a/util.js b/util.js
index 9a7673b..bf73571 100644
--- a/util.js
+++ b/util.js
@@ -1,7 +1,7 @@
/* exported Util, Params, DummyRateLimit */
/* global Config */
-/*
+/**
A JavaScript WebRTC snowflake proxy
Contains helpers for parsing query strings and other utilities.
@@ -21,10 +21,12 @@ class Util {
return navigator.cookieEnabled;
}
- // returns a promise that 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
+ /**
+ * returns a promise that 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
+ */
static checkNATType(timeout) {
let pc = new RTCPeerConnection({iceServers: [
{urls: 'stun:stun1.l.google.com:19302'}
@@ -65,8 +67,10 @@ 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.
+ /**
+ * 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.
+ */
static sendOffer(offer) {
return new Promise((fulfill, reject) => {
const xhr = new XMLHttpRequest();
@@ -99,9 +103,11 @@ class Util {
class Parse {
- // 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
+ /**
+ * 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
+ */
static cookie(cookies) {
const result = {};
const strings = cookies ? cookies.split(';') : [];
@@ -120,8 +126,10 @@ class Parse {
return result;
}
- // Parse an address in the form 'host:port'. Returns an Object with keys 'host'
- // (String) and 'port' (int). Returns null on error.
+ /**
+ * Parse an address in the form 'host:port'. Returns an Object with keys 'host'
+ * (String) and 'port' (int). Returns null on error.
+ */
static address(spec) {
let m = null;
if (!m) {
@@ -147,8 +155,10 @@ class Parse {
};
}
- // Parse a count of bytes. A suffix of 'k', 'm', or 'g' (or uppercase)
- // does what you would think. Returns null on error.
+ /**
+ * Parse a count of bytes. A suffix of 'k', 'm', or 'g' (or uppercase)
+ * does what you would think. Returns null on error.
+ */
static byteCount(spec) {
let matches = spec.match(/^(\d+(?:\.\d*)?)(\w*)$/);
if (matches === null) {
@@ -172,11 +182,13 @@ class Parse {
return count * multiplier;
}
- //Parse a remote connection-address out of the "c=" Connection Data field
- // or the "a=" attribute fields of the session description.
- // Return undefined if none is found.
- // https://tools.ietf.org/html/rfc4566#section-5.7
- // https://tools.ietf.org/html/rfc5245#section-15
+ /**
+ * Parse a remote connection-address out of the "c=" Connection Data field
+ * or the "a=" attribute fields of the session description.
+ * Return undefined if none is found.
+ * https://tools.ietf.org/html/rfc4566#section-5.7
+ * https://tools.ietf.org/html/rfc5245#section-15
+ */
static ipFromSDP(sdp) {
console.log(sdp);
const ref = [
@@ -195,8 +207,10 @@ class Parse {
}
}
- // Parse the mapped port out of an ice candidate returned from the
- // onicecandidate callback
+ /**
+ * Parse the mapped port out of an ice candidate returned from the
+ * onicecandidate callback
+ */
static portFromCandidate(c) {
const pattern = /(?:[\d.]+|[0-9A-Fa-f:.]+) (\d+) typ srflx/m;
const m = pattern.exec(c);
@@ -206,7 +220,7 @@ class Parse {
return null;
}
- // Determine whether an IP address is a local, unspecified, or loopback address
+ /** Determine whether an IP address is a local, unspecified, or loopback address */
static isRemoteIP(ip) {
if (ip.includes(":")) {
var ip6 = ip.split(':');
@@ -249,9 +263,11 @@ class Params {
return null;
}
- // Get an object value and parse it as a byte count. Example byte counts are
- // '100' and '1.3m'. Returns |defaultValue| if param is not a key. Return null
- // on a parsing error.
+ /**
+ * Get an object value and parse it as a byte count. Example byte counts are
+ * '100' and '1.3m'. Returns |defaultValue| if param is not a key. Return null
+ * on a parsing error.
+ */
static getByteCount(query, param, defaultValue) {
if (!query.has(param)) {
return defaultValue;
@@ -285,7 +301,7 @@ class BucketRateLimit {
return this.amount <= this.capacity;
}
- // How many seconds in the future will the limit expire?
+ /** How many seconds in the future will the limit expire? */
when() {
this.age();
return (this.amount - this.capacity) / (this.capacity / this.time);
@@ -303,7 +319,7 @@ BucketRateLimit.prototype.amount = 0.0;
BucketRateLimit.prototype.lastUpdate = new Date();
-// A rate limiter that never limits.
+/** A rate limiter that never limits. */
class DummyRateLimit {
constructor(capacity, time) {
diff --git a/websocket.js b/websocket.js
index fdf470c..b2d509a 100644
--- a/websocket.js
+++ b/websocket.js
@@ -4,8 +4,10 @@ Only websocket-specific stuff.
class WS {
- // Build an escaped URL string from unescaped components. Only scheme and host
- // are required. See RFC 3986, section 3.
+ /**
+ * Build an escaped URL string from unescaped components. Only scheme and host
+ * are required. See RFC 3986, section 3.
+ */
static buildUrl(scheme, host, port, path, params) {
var parts;
parts = [];
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
More information about the tor-commits
mailing list