request API
authorRobin Berjon <robin@berjon.com>
Fri, 27 May 2011 11:06:40 +0200
changeset 21 fdd8a2141c4c
parent 20 89bcc8506c00
child 22 e3e3bf71a7e5
request API
proposals/request-feature/Overview.html
--- a/proposals/request-feature/Overview.html	Thu May 26 18:53:35 2011 +0200
+++ b/proposals/request-feature/Overview.html	Fri May 27 11:06:40 2011 +0200
@@ -32,6 +32,9 @@
         only once, and encapsulates the resulting access permission in a secure container in order to protect
         the increased privileges granted to a web application from cross-site scripting (XSS) attacks.
       </p>
+      <p class='note'>
+        This document is currently more of a sketch of a proposal than a properly defined specification.
+      </p>
     </section>
     <section id='sotd'>
       <p>
@@ -101,9 +104,9 @@
           live on a different server.
         </p>
         <p>
-          You can look at <a href='xss-pwnd/index.html' target='_blank' title='muahahaha'>the example in action</a>.
-          It requires Geolocation and IndexedDB support (though you can still read the source if your browser
-          does not support those).
+          You can look at <a href='xss-pwnd/index.html' target='_blank' title='muahahaha'>the example in action</a>
+          (<a href='xss-pwnd.zip'>download</a>). It requires Geolocation and IndexedDB support (though you can still 
+          read the source if your browser does not support those).
         </p>
         <p>
           Two things can be noted: there are too many permission prompts for a smooth experience, and simply because
@@ -116,8 +119,9 @@
         <h2>Example: FRAC</h2>
         <p>
           We will now show how to implement the very same functionality using FRAC. You can 
-          <a href='frac-unicorner/index.html'>try the example</a> but it will only work in a FRAC-enabled browser and
-          as of this writing those are few and far apart. We can look at the code however to see how it has been modified.
+          <a href='frac-unicorner/index.html' target='_blank'>try the example</a> (<a href='frac-unicorner.zip'>download</a>) 
+          but it will only work in a FRAC-enabled browser and as of this writing those are few and far apart. We can look at 
+          the code however to see how it has been modified.
         </p>
         <p>
           The first thing to note is that the changes required to the entire code are extremely minimal:
@@ -242,40 +246,71 @@
           <dl class='parameters'>
             <dt>DOMString[] features</dt>
             <dd>
-              A list of feature strings (e.g. <code>geolocation</code>, <code>contacts</code>, <code>indexeddb</code>)
-              that the author is requesting access to. Individual feature strings are defined by their respective
-              specifications. A user agent MUST ignore feature strings which it does not know. Vendor-specific
-              features are expected to be identified using vendor-prefixed strings. Mechanisms to obtain user
-              agreement for access to these features are left up to implementations. If this list is empty, no
-              user agreement is necessary and the modules are loaded immediately.
+              <p>
+                A list of feature strings (e.g. <code>geolocation</code>, <code>contacts</code>, <code>indexeddb</code>)
+                that the author is requesting access to. Individual feature strings are defined by their respective
+                specifications. A user agent MUST ignore feature strings which it does not know. Vendor-specific
+                features are expected to be identified using vendor-prefixed strings. Mechanisms to obtain user
+                agreement for access to these features are left up to implementations. If this list is empty, no
+                user agreement is necessary and the modules are loaded immediately.
+              </p>
+              <p>
+                While the user agent is expect to make it easy to accept all or none of the requested features in
+                bulk, such outcomes are not required. Any number of features can be accepted or rejected in the set,
+                and the scripts will still load. They will simply have access to only those features which were
+                accepted. Likewise, irrespective of the user decision made for these, all privileged features in
+                the main scope are expected to be declined.
+              </p>
+              <p class='note'>
+                An API to discover which features have been granted and which haven't would prove useful in this
+                context. That is indeed part of what the 
+                <a href='http://dev.w3.org/2009/dap/perms/FeaturePermissions.html'>Feature Permissions</a>
+                specification proposes.
+              </p>
             </dd>
             <dt>DOMString[] modules</dt>
             <dd>
-              A list of paths to scripts to be loaded.
-              <!-- XXX -->
+              A list of paths to scripts to be loaded. These can only be loaded from the same origin. Scripts that
+              for whatever reason fail to load produce an <code>undefined</code> object in the callback. Each of
+              the script is loaded as a contained module, as described in section <a href='#modules'></a>.
             </dd>
             <dt>RequestFeaturesCB successCB</dt>
             <dd>
-              
+              A callback called when the permission decision has been made (positive or negative) and the module
+              scripts have been loaded.
             </dd>
           </dl>
         </dd>
       </dl>
-      <!-- 
-        XXX
-          - scripts that don't load produce an undefined object
-          - features aren't necessarily accepted in bulk, those that aren't are simply
-            automatically declined
-          - features in the main scope are automatically declined
-          - zip links
-          - need API to know which accesses were granted
-      -->
+      <section>
+        <h2>The <a>RequestFeaturesCB</a> Callback</h2>
+        <p>
+          This is the wrapper interface for <code>requestFeatures()</code> completion callbacks.
+        </p>
+        <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface RequestFeaturesCB' class='idl'>
+          <dt>void onsuccess ()</dt>
+          <dd>
+            <dl class='parameters'>
+              <dt>Object[] moduleObjects</dt>
+              <dd>
+                An array of objects that expose the scripts' interfaces.
+              </dd>
+            </dl>
+          </dd>
+        </dl>
+      </section>
     </section>
     <section id='modules'>
       <h2>Containing Access</h2>
       <p>
         
       </p>
+      <!-- 
+          XXX
+          - mostly reference
+          - can't write to these from the main scope
+          - can always shoot yourself in the foot, but it's harder
+      -->
     </section>
     <section class='appendix'>
       <h2>Acknowledgements</h2>