[tor-commits] [snowflake/master] Add a build step / documentation for code reuse

[arlo at torproject.org]

commit af4cc52dc2eb46585d5f0da3ecc285c914e22414
Author: Arlo Breault <arlolra at gmail.com>
Date:   Fri Nov 22 17:17:22 2019 -0500

    Add a build step / documentation for code reuse
    
    Trac: 32499
---
 .gitignore             |  1 +
 proxy/.eslintignore    |  1 +
 proxy/README.md        | 64 +++++++++++++++++++++++++++++++++++++++++++++++++-
 proxy/make.js          | 10 +++++++-
 proxy/package.json     |  1 +
 proxy/webext/README.md | 11 ---------
 6 files changed, 75 insertions(+), 13 deletions(-)

diff --git a/.gitignore b/.gitignore
index 1bae622..2d31939 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,6 +13,7 @@ snowflake.log
 proxy/test
 proxy/build
 proxy/node_modules
+proxy/snowflake-library.js
 proxy/spec/support
 proxy/webext/snowflake.js
 proxy/webext/popup.js
diff --git a/proxy/.eslintignore b/proxy/.eslintignore
index f580632..c249199 100644
--- a/proxy/.eslintignore
+++ b/proxy/.eslintignore
@@ -1,6 +1,7 @@
 build/
 test/
 webext/snowflake.js
+snowflake-library.js
 
 # FIXME: Whittle these away
 spec/
diff --git a/proxy/README.md b/proxy/README.md
index 61468c0..fedfa20 100644
--- a/proxy/README.md
+++ b/proxy/README.md
@@ -7,12 +7,26 @@ See https://snowflake.torproject.org/ for more info:
 <iframe src="https://snowflake.torproject.org/embed.html" width="88" height="16" frameborder="0" scrolling="no"></iframe>
 ```
 
-### Building
+### Building the badge / snowflake.torproject.org
 
 ```
+npm install
 npm run build
 ```
 
+which outputs to the `build/` directory.
+
+### Building the webextension
+
+```
+npm install
+npm run webext
+```
+
+and then load the `webext/` directory as an unpacked extension.
+ * https://developer.mozilla.org/en-US/docs/Tools/about:debugging#Loading_a_temporary_extension
+ * https://developer.chrome.com/extensions/getstarted#manifest
+
 ### Testing
 
 Unit testing with Jasmine are available with:
@@ -44,6 +58,7 @@ IdentityFile ~/.ssh/tor
 ### Deploying
 
 ```
+npm install
 npm run build
 ```
 
@@ -73,3 +88,50 @@ With no parameters,
 snowflake uses the default relay `snowflake.freehaven.net:443` and
 uses automatic signaling with the default broker at
 `https://snowflake-broker.freehaven.net/`.
+
+### Reuse as a library
+
+The badge and the webextension make use of the same underlying library and
+only differ in their UI.  That same library can be produced for use with other
+interfaces, such as [Cupcake][1], by running,
+
+```
+npm install
+npm run library
+```
+
+which outputs a `./snowflake-library.js`.
+
+You'd then want to create a subclass of `UI` to perform various actions as
+the state of the snowflake changes,
+
+```
+class MyUI extends UI {
+    ...
+}
+```
+
+See `WebExtUI` in `init-webext.js` and `BadgeUI` in `init-badge.js` for
+examples.
+
+Finally, initialize the snowflake with,
+
+```
+var log = function(msg) {
+  return console.log('Snowflake: ' + msg);
+};
+var dbg = log;
+
+var config = new Config();
+var ui = new MyUI();  // NOTE: Using the class defined above
+var broker = new Broker(config.brokerUrl);
+
+var snowflake = new Snowflake(config, ui, broker);
+
+snowflake.setRelayAddr(config.relayAddr);
+snowflake.beginWebRTC();
+```
+
+This minimal setup is pretty much what's currently in `init-node.js`.
+
+[1]: https://chrome.google.com/webstore/detail/cupcake/dajjbehmbnbppjkcnpdkaniapgdppdnc
diff --git a/proxy/make.js b/proxy/make.js
index c7be058..f8b2192 100755
--- a/proxy/make.js
+++ b/proxy/make.js
@@ -39,7 +39,10 @@ var SHARED_FILES = [
 ];
 
 var concatJS = function(outDir, init, outFile, pre) {
-  var files = FILES.concat(`init-${init}.js`);
+  var files = FILES;
+  if (init) {
+    files = files.concat(`init-${init}.js`);
+  }
   var outPath = `${outDir}/${outFile}`;
   writeFileSync(outPath, pre, 'utf8');
   execSync(`cat ${files.join(' ')} >> ${outPath}`);
@@ -176,6 +179,11 @@ task('clean', 'remove all built files', function() {
   execSync('rm -rf build test spec/support');
 });
 
+task('library', 'build the library', function() {
+  concatJS('.', '', 'snowflake-library.js', '');
+  console.log('Library prepared.');
+});
+
 var cmd = process.argv[2];
 
 if (tasks.has(cmd)) {
diff --git a/proxy/package.json b/proxy/package.json
index 6946691..772746e 100644
--- a/proxy/package.json
+++ b/proxy/package.json
@@ -10,6 +10,7 @@
     "test": "node make.js test",
     "build": "node make.js build",
     "webext": "node make.js webext",
+    "library": "node make.js library",
     "pack-webext": "node make.js pack-webext",
     "clean": "node make.js clean",
     "prepublish": "node make.js node",
diff --git a/proxy/webext/README.md b/proxy/webext/README.md
deleted file mode 100644
index cd53ff1..0000000
--- a/proxy/webext/README.md
+++ /dev/null
@@ -1,11 +0,0 @@
-Build it,
-
-```
-cd ..
-npm install
-npm run webext
-```
-
-and then load this directory as an unpacked extension.
- * https://developer.mozilla.org/en-US/docs/Tools/about:debugging#Loading_a_temporary_extension
- * https://developer.chrome.com/extensions/getstarted#manifest