Add documentation for Origin Trials integration

docs/origin_trials_integration.md

Index: docs/origin_trials_integration.md
diff --git a/docs/origin_trials_integration.md b/docs/origin_trials_integration.md
new file mode 100644
index 0000000000000000000000000000000000000000..79da2454595d910e84dc5d5192d3242c9f16462e
--- /dev/null
+++ b/docs/origin_trials_integration.md
@@ -0,0 +1,161 @@
+# Integrating a feature with the Origin Trials framework
+
+To expose your feature via the origin trials framework, there are a few code
+changes required.
+
+[TOC]
+
+## Code Changes
+
+### Runtime Enabled Features
+
+First, you’ll need to configure [RuntimeEnabledFeatures.json5]. This is
+explained in the file, but you use `origin_trial_feature_name` to associate your
+runtime feature flag with a name for your origin trial.  The name can be the
+same as your runtime feature flag, or different.  Eventually, this configured
+name will be used in the Origin Trials developer console (still under
+development). You can have both `status: experimental` and
+`origin_trial_feature_name` if you want your feature to be enabled either by
+using the `--enable-experimental-web-platform-features` flag **or** the origin
+trial.
+
+You may have a feature that is not available on all platforms, or need to limit
+the trial to specific platforms. Use `origin_trial_os: [list]` to specify which
+platforms will allow the trial to be enabled.

[iclelland, 2017/02/10 19:41:28]

Can we list the valid values for that list here? "android" and "linux" are easy
(modulo case-sensitivity), but I can never remember whether its "mac" or "macos"
or "osx". Is "win7" a thing, or just "windows"? etc.

[chasej, 2017/02/10 20:24:41]

I intentionally omitted the list of valid values. If the supported values
change, the odds of someone updating this doc are approximately zero.

Instead, I added a link to the file where the corresponding macros are defined.

+
+#### Examples
+
+Flag name and trial name are the same:
+```
+{
+  name: "MyFeature",
+  origin_trial_feature_name: "MyFeature",
+  status: "experimental",
+},
+```
+Flag name and trial name are different:
+```
+{
+  name: "MyFeature",
+  origin_trial_feature_name: "MyFeatureTrial",
+  status: "experimental",
+},
+```
+Trial limited to specific platform:
+``` json
+{
+  name: "MyFeature",
+  origin_trial_feature_name: "MyFeature",
+  origin_trial_os: ["android"],
+  status: "experimental",
+},
+```
+
+### Gating Access
+
+Once configured, there are two mechanisms to gate access to your feature behind
+an origin trial. You can use either mechanism, or both, as appropriate to your
+feature implementation.
+
+1. A native C++ method that you can call in Blink code at runtime to expose your
+    feature: `bool OriginTrials::myFeatureEnabled()`
+2. An IDL attribute \[[OriginTrialEnabled]\] that you can use to automatically
+    expose and hide JavaScript methods/attributes/objects. This attribute works
+    very similar to \[RuntimeEnabled\].
+```
+[OriginTrialEnabled=MyFeature]
+partial interface Navigator {
+     readonly attribute MyFeatureManager myFeature;
+}
+```
+
+**NOTE:** Your feature implementation must not persist the result of the enabled
+check. Your code should simply call `OriginTrials::myFeatureEnabled()` as often
+as necessary to gate access to your feature.
+
+### IDL Bindings
+
+When using the \[OriginTrialEnabled\] IDL attribute, you'll need to manually
+install the appropriate methods in the V8 bindings code. Based on the
+\[OriginTrialEnabled\] attribute, there will be one or more `installMyFeature`
+methods generated in the bindings code. These methods must be manually
+installed:
+
+- Find the relevant methods by doing a code search for `installMyFeature`:

[iclelland, 2017/02/10 19:41:27]

I didn't realise this was best practise :) I suppose you could do a more
targeted search if you include 'f:gen/blink/bindings' as a term as well.

[chasej, 2017/02/10 20:24:41]

You could do that. I had tested with a few examples (e.g. installWebUSB) and
the results were just the generated bindings. I suppose it's always possible
that could be other, hand-written code for "installMyFeature".

Added more explicit guidance.

+    - e.g. V8WindowPartial::installMyFeature,
+      V8NavigatorPartial::installMyFeature
+- Determine which bindings code needs to be updated:
+    - [ConditionalFeatures.cpp]: Your feature lives in `core` (i.e. generated
+      methods are found under .../bindings/core/...)
+    - [ConditionalFeaturesForModules.cpp]: Your feature lives under `modules`
+      (i.e. generated methods are found under .../bindings/modules/...)
+- Update `installConditionalFeatures[Core|ForModules]()`:
+    - These methods are broken down by type.
+    - Add/update the logic for each type to call the corresponding
+      `<type>::installMyFeature()` methods.
+- Update `installPendingConditionalFeature[Core|ForModules]()`:
+    - These methods are broken down by trial/feature.
+    - Add/update the logic for each feature to call all of the
+     `installMyFeature()` methods.
+
+Eventually, the V8 bindings code will be generated automatically (See
+[crbug.com/615060]).
+
+
+## Limitations
+
+What you can't do, because of the nature of these Origin Trials, is know at
+either browser or renderer startup time whether your feature is going to be used
+in the current page/context. This means that if you require lots of expensive
+processing to begin (say you index the user's hard drive, or scan an entire city
+for interesting weather patterns,) that you will have to either do it on browser
+startup for *all* users, just in case it's used, or do it on first access. (If
+you go with first access, then only people trying the experiment will notice the
+delay, and hopefully only the first time they use it.). We are investigating
+providing a method like `OriginTrials::myFeatureShouldInitialize()` that will
+hint if you should do startup initialization.  For example, this could include
+checks for trials that have been revoked (or throttled) due to usage, if the
+entire origin trials framework has been disabled, etc.  The method would be
+conservative and assume initialization is required, but it could avoid expensive
+startup in some known scenarios.
+
+Similarly, if you need to know in the browser process whether a feature should
+be enabled, then you will have to either have the renderer inform it at runtime,
+or else just assume that it's always enabled, and gate access to the feature
+from the renderer.
+
+## Testing
+
+If you want to test your code's interactions with the framework, you'll need to
+generate some tokens of your own. To generate your own tokens, use
+[/tools/origin_trials/generate_token.py]. You can generate signed tokens for

[iclelland, 2017/02/10 19:41:27]

Why is this reference using the complete path as its text, when the others are
all just the filename?

[chasej, 2017/02/10 20:24:41]

The source document had the complete path as its text, so I kept it the same.
That, and I thought it made sense to highlight that it's a tool, not some other
source file. That said, the following example has the full path, so probably
don't need it in the text too.

Removed the path.

+localhost, or for 127.0.0.1, or for any origin that you need to help you test.
+For example:
+
+```
+tools/origin_trials/generate_token.py http://localhost:8000 MyFeature
+```
+
+The file `tools/origin_trials/eftest.key` is used by default as the private key
+for the test keypair used by Origin Trials unit tests (tokens generated with
+this key will **not** work in the browser by default; see the [Developer Guide]

[iclelland, 2017/02/10 19:41:27]

We could mention that they *do* work in content shell, just not in Chrome.

[chasej, 2017/02/10 20:24:41]

Done.

+for instructions on creating real tokens). To use a test token with the browser,
+run Chrome with the command-line flag:
+
+```
+--origin-trial-public-key=dRCs+TocuKkocNKa0AtZ4awrt9XKH2SQCI6o4FY6BNA=
+```
+
+This is the public key associated with `eftest.key`. If it doesn't work, see

[iclelland, 2017/02/10 19:41:28]

...is the base64 encoding of the public key...

[chasej, 2017/02/10 20:24:41]

Done.

+[trial_token_unittest.cc]. If you cannot set command-line switches (e.g., on
+Chrome OS), you can also directly modify [chrome_origin_trial_policy.cc].
+
+[chrome_origin_trial_policy.cc]: /chrome/common/origin_trials/chrome_origin_trial_policy.cc
+[crbug.com/615060]: https://bugs.chromium.org/p/chromium/issues/detail?id=615060
+[ConditionalFeatures.cpp]: /third_party/WebKit/Source/bindings/core/v8/ConditionalFeatures.cpp
+[ConditionalFeaturesForModules.cpp]: /third_party/WebKit/Source/bindings/modules/v8/ConditionalFeaturesForModules.cpp
+[Developer Guide]: https://github.com/jpchase/OriginTrials/blob/gh-pages/developer-guide.md
+[OriginTrialEnabled]: /third_party/WebKit/Source/bindings/IDLExtendedAttributes.md#_OriginTrialEnabled_i_m_a_c_
+[RuntimeEnabledFeatures.json5]: /third_party/WebKit/Source/platform/RuntimeEnabledFeatures.json5
+[/tools/origin_trials/generate_token.py]: /tools/origin_trials/generate_token.py
+[trial_token_unittest.cc]: /content/common/origin_trials/trial_token_unittest.cc