commit af4cc52dc2eb46585d5f0da3ecc285c914e22414 Author: Arlo Breault <arlolra@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_tem... + * 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/dajjbehmbnbppjkcnpdkaniapg... 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_tem... - * https://developer.chrome.com/extensions/getstarted#manifest