updated docs

Author: dannycoates

README.md

@@ -3,7 +3,7 @@
 [![CircleCI](https://img.shields.io/circleci/project/github/mozilla/send.svg)](https://circleci.com/gh/mozilla/send)
 [![Available on Test Pilot](https://img.shields.io/badge/available_on-Test_Pilot-0996F8.svg)](https://testpilot.firefox.com/experiments/send)
 
-**Docs:** [Docker](docs/docker.md), [Metrics](docs/metrics.md)
+**Docs:** [FAQ](docs/faq.md), [Encryption](docs/encryption.md), [Build](docs/build.md), [Docker](docs/docker.md), [Metrics](docs/metrics.md), [More](docs/)
 
 ---
 
@@ -71,6 +71,8 @@ The server is configured with environment variables. See [server/config.js](serv
 
 Firefox Send localization is managed via [Pontoon](https://pontoon.mozilla.org/projects/test-pilot-firefox-send/), not direct pull requests to the repository. If you want to fix a typo, add a new language, or simply know more about localization, please get in touch with the [existing localization team](https://pontoon.mozilla.org/teams/) for your language or Mozilla’s [l10n-drivers](https://wiki.mozilla.org/L10n:Mozilla_Team#Mozilla_Corporation) for guidance.
 
+see also [docs/localization.md](docs/localization.md)
+
 ---
 
 ## Contributing

app/fileManager.js

@@ -104,8 +104,10 @@ export default function(state, emitter) {
       metrics.completedUpload(ownedFile);
 
       state.storage.addFile(ownedFile);
-
-      document.getElementById('cancel-upload').hidden = 'hidden';
+      const cancelBtn = document.getElementById('cancel-upload');
+      if (cancelBtn) {
+        cancelBtn.hidden = 'hidden';
+      }
       await delay(1000);
       await fadeOut('.page');
       openLinksInNewTab(links, false);

app/readme.md

@@ -0,0 +1,9 @@
+# Application Code
+
+`app/` contains the browser code that gets bundled into `app.[hash].js`. It's got all the logic, crypto, and UI. All of it gets used in the browser, and some of it by the server for server side rendering.
+
+The main entrypoint for the browser is [main.js](./main.js) and on the server [routes/index.js](./routes/index.js) gets imported by [/server/routes/pages.js](../server/routes/pages.js)
+
+- `pages` contains display logic an markup for pages
+- `routes` contains route definitions and logic
+- `templates` contains ui elements smaller than pages

build/generate_asset_map.js

@@ -1,3 +1,14 @@
+/*
+  This code is included by both the server and frontend via
+  common/assets.js
+
+  When included from the server the export will be the function.
+
+  When included from the frontend (via webpack) the export will
+  be an object mapping file names to hashed file names. Example:
+  "send_logo.svg": "send_logo.5fcfdf0e.svg"
+*/
+
 const fs = require('fs');
 const path = require('path');
 

build/generate_l10n_map.js

@@ -1,3 +1,14 @@
+/*
+  This code is included by both the server and frontend via
+  common/locales.js
+
+  When included from the server the export will be the function.
+
+  When included from the frontend (via webpack) the export will
+  be an object mapping ftl files to js files. Example:
+  "public/locales/en-US/send.ftl":"public/locales/en-US/send.6b4f8354.js"
+*/
+
 const fs = require('fs');
 const path = require('path');
 

build/readme.md

@@ -0,0 +1,26 @@
+# Custom Loaders
+
+## Fluent Loader
+
+The fluent loader "compiles" `.ftl` files into `.js` files directly usable by both the frontend and server for localization.
+
+## Generate Asset Map
+
+This loader enumerates all the files in `assets/` so that `common/assets.js` can provide mappings from the source filename to the hashed filename used on the site.
+
+## Generate L10N Map
+
+This loader enumerates all the ftl files in `public/locales` so that the fluent loader can create it's js files.
+
+## Package.json Loader
+
+This loader creates a `version.json` file that gets exposed by the `/__version__` route from the `package.json` file and current git commit hash.
+
+## Version Loader
+
+This loader substitutes the string "VERSION" for the version string specified in `package.json`. This is a workaround because `package.json` already uses the `package_json_loader`. See [app/templates/header/index.js](../app/templates/header/index.js) for more info.
+
+# See Also
+
+- [docs/build.md](../docs/build.md)
+- [webpack.config.js](../webpack.config.js)

common/readme.md

@@ -0,0 +1,3 @@
+# Common Code
+
+This directory contains code loaded by both the frontend `app` and backend `server`. The code here can be challenging to understand at first because the contexts for the two (three counting the dev server) environments that include them are quite different, but the purpose of these modules are quite simple, to provide mappings from the source assets (`copy-16.png`) to the concrete production assets (`copy-16.db66e0bf.svg`), similarly for localizations.

docs/build.md

@@ -0,0 +1,22 @@
+Send has two build configurations, development and production. Both can be run via `npm` scripts, `npm start` for development and `npm run build` for production. Webpack is our only build tool and all configuration lives in [webpack.config.js](../webpack.config.js).
+
+# Development
+
+`npm start` launches a `webpack-dev-server` on port 8080 that compiles the assets and watches files for changes. It also serves the backend API and frontend unit tests via the `server/dev.js` entrypoint. The frontend tests can be run in the browser by navigating to http://localhost:8080/test and will rerun automatically as the watched files are saved with changes.
+
+# Production
+
+`npm run build` compiles the assets and writes the files to the `dist/` directory. `npm run prod` launches an Express server on port 1443 that serves the backend API and frontend static assets from `dist/` via the `server/prod.js` entrypoint.
+
+# Notable differences
+
+- Development compiles assets in memory, so no `dist/` directory is generated
+- Development does not enable CSP headers
+- Development frontend source is instrumented for code coverage
+- Only development includes sourcemaps
+- Only development exposes the `/test` route
+- Production sets Cache-Control immutable headers on the hashed static assets
+
+# Custom Loaders
+
+The `build/` directory contains custom webpack loaders specific to Send. See [build/readme.md](../build/readme.md) for details on each loader.

docs/encryption.md

@@ -0,0 +1,46 @@
+# File Encryption
+
+Send use 128-bit AES-GCM encryption via the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) to encrypt files in the browser before uploading them to the server. The code is in [app/keychain.js](../app/keychain.js).
+
+## Steps
+
+### Uploading
+
+1. A new secret key is generated with `crypto.getRandomValues`
+2. The secret key is used to derive 3 more keys via HKDF SHA-256
+    - an encryption key for the file (AES-GCM)
+    - an encryption key for the file metadata (AES-GCM)
+    - a signing key for request authentication (HMAC SHA-256)
+3. The file and metadata are encrypted with their corresponding keys
+4. The encrypted data and signing key are uploaded to the server
+5. An owner token and the share url are returned by the server and stored in local storage
+6. The secret key is appended to the share url as a [#fragment](https://en.wikipedia.org/wiki/Fragment_identifier) and presented to the UI
+
+### Downloading
+
+1. The browser loads the share url page, which includes an authentication nonce
+2. The browser imports the secret key from the url fragment
+3. The same 3 keys as above are derived
+4. The browser signs the nonce with it's signing key and requests the metadata
+5. The encrypted metadata is decrypted and presented on the page
+6. The browser makes another authenticated request to download the encrypted file
+7. The browser downloads and decrypts the file
+8. The file prompts the save dialog or automatically saves depending on the browser settings
+
+### Passwords
+
+A password may optionally be set to authenticate the download request. When a password is set the following steps occur.
+
+#### Sender
+
+1. The original signing key derived from the secret key is discarded
+2. A new signing key is generated via PBKDF2 from the user entered password and the full share url (including secret key fragment)
+3. The new key is sent to the server, authenticated by the owner token
+4. The server stores the new key and marks the record as needing a password
+
+#### Downloader
+
+1. The browser loads the share url page, which includes an authentication nonce and indicator that the file requires a password
+2. The user is prompted for the password and the signing key is derived
+3. The browser requests the metadata using the key to sign the nonce
+4. If the password was correct the metadata is returned, otherwise a 401

docs/experiments.md

@@ -0,0 +1,84 @@
+# A/B experiment testing
+
+We're using Google Analytics Experiments for A/B testing.
+
+## Creating an experiment
+
+Navigate to the Behavior > Experiments section of Google Analytics and click the "Create experiment" button.
+
+The "Objective for this experiment" is the most complicated part. See the "Promo click (Goal ID 4 / Goal Set 1)" for an example.
+
+In step 2 add as many variants as you plan to test. The urls are not important since we aren't using their js library to choose the variants. The name will show up in the report so choose good ones. "Original page" becomes variant 0 and each variant increments by one. We'll use the numbers in our `app/experiments.js` code.
+
+Step 3 contains some script that we'll ignore. The important thing here is the **Experiment ID**. This is the value we need to name our experiment in `app/experiments.js`. Save the changes so far and wait until the code containing the experiment has been deployed to production **before** starting the experiment.
+
+## Experiment code
+
+Code for experiments live in [app/experiments.js](../app/experiments.js). There's an `experiments` object that contains the logic for deciding whether an experiment should run, which variant to use, and what to do. Each object needs to have these functions:
+
+### `eligible` function
+
+This function returns a boolean of whether this experiment should be active for this session. Any data available to the page can be used determine the result.
+
+### `variant` function
+
+This function returns which experimental group this session is placed in. The variant values need to match the values set up in Google Analytics, usually 0 thru N-1. This value is usually picked at random based on what percentage of each variant is desired.
+
+### `run` function
+
+This function gets the `variant` value chosen by the variant function and the `state` and `emitter` objects from the app. This function can do anything needed to change the app based on the experiment. A common pattern is to set or change a value on `state` that will be picked up by other parts of the app, like ui templates, to change how it looks or behaves.
+
+### Example
+
+Here's a full example of the experiment object:
+
+```js
+const experiments = {
+  S9wqVl2SQ4ab2yZtqDI3Dw: { // The Experiment ID from Google Analytics
+    id: 'S9wqVl2SQ4ab2yZtqDI3Dw',
+    run: function(variant, state, emitter) {
+      switch (variant) {
+        case 1:
+          state.promo = 'blue';
+          break;
+        case 2:
+          state.promo = 'pink';
+          break;
+        default:
+          state.promo = 'grey';
+      }
+      emitter.emit('render');
+    },
+    eligible: function() {
+      return (
+        !/firefox|fxios/i.test(navigator.userAgent) &&
+        document.querySelector('html').lang === 'en-US'
+      );
+    },
+    variant: function(state) {
+      const n = this.luckyNumber(state);
+      if (n < 0.33) {
+        return 0;
+      }
+      return n < 0.66 ? 1 : 2;
+    },
+    luckyNumber: function(state) {
+      return luckyNumber(
+        `${this.id}:${state.storage.get('testpilot_ga__cid')}`
+      );
+    }
+  }
+};
+```
+
+## Reporting results
+
+All metrics pings will include the variant and experiment id, but it's usually important to trigger a specific event to be counted as the experiment goal (the "Objective for this experiment" part from setup). Use an 'experiment' event to do this. For example:
+
+```js
+emit('experiment', { cd3: 'promo' });
+```
+
+where `emit` is the app emitter function passed to the [route handler](https://github.com/choojs/choo#approuteroutename-handlerstate-emit)
+
+The second argument can be an object with any additional parameters. It  usually includes a custom dimension that we chose to filter on while creating the experiment in Google Analytics.