Bug 1525245 - Stabilize cookiePolicy/cookiePermission for live documents - part 15 - Comments, r=asuth

Differential Revision: https://phabricator.services.mozilla.com/D21906

--HG--
extra : moz-landing-system : lando

netwerk/cookie/CookieSettings.h

@@ -17,6 +17,88 @@ namespace net {
 
 class CookieSettingsArgs;
 
+/**
+ * CookieSettings
+ * ~~~~~~~~~~~~~~
+ *
+ * CookieSettings is a snapshot of cookie policy and cookie permissions in a
+ * precise moment of time. This object is used by top-level documents to have a
+ * consistent cookie configuration also in case the user changes it. New cookie
+ * configurations will apply only to new top-level documents.
+ *
+ * CookieSettings creation
+ * ~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * CookieSettings is created when the top-level document's nsIChannel's
+ * nsILoadInfo is constructed. Any sub-resource and any sub-document inherits it
+ * from that nsILoadInfo. Also dedicated workers and their resources inherit it
+ * from the parent document.
+ *
+ * SharedWorkers and ServiceWorkers have their own CookieSettings because they
+ * don't have a single parent document (SharedWorkers could have more than one,
+ * ServiceWorkers have none).
+ *
+ * In Chrome code, we have a new CookieSettings when we download resources via
+ * 'Save-as...' and we also have a new CookieSettings for favicon downloading.
+ *
+ * Content-scripts WebExtensions also have their own CookieSettings because they
+ * don't have a direct access to the document they are running into.
+ *
+ * Anything else will have a special CookieSettings which blocks everything
+ * (CookieSettings::CreateBlockingAll()) by forcing BEHAVIOR_REJECT as policy.
+ * When this happens, that context will not have access to the cookie jar and no
+ * cookies are sent or received.
+ *
+ * Propagation of CookieSettings
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * CookieSettings are shared inside the same top-level document via its
+ * nsIChannel's nsILoadInfo.  This is done automatically if you pass a nsINode
+ * to NS_NewChannel(), and it must be done manually if you use a different
+ * channel constructor. For instance, this happens for any worker networking
+ * operation.
+ *
+ * We use the same CookieSettings for any resource belonging to the top-level
+ * document even if cross-origin. This makes the browser behave consistently a
+ * scenario where A loads B which loads A again, and cookie policy/permission
+ * changes in the meantime.
+ *
+ * Cookie Permissions propagation
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * CookieSettings populates the known cookie permissions only when required.
+ * Initially the list is empty, but when CookieSettings::CookiePermission() is
+ * called, the requested permission is stored in the internal list if it doesn't
+ * exist yet.
+ *
+ * This is actually nice because it relies on the permission propagation from
+ * parent to content process. No extra IPC is required.
+ *
+ * Note that we store permissions with UNKNOWN_ACTION values too because they
+ * can be set after the loading of the top-level document and we don't want to
+ * return a different value when this happens.
+ *
+ * Use of CookieSettings
+ * ~~~~~~~~~~~~~~~~~~~~~
+ *
+ * In theory, there should not be direct access to cookie permissions or
+ * cookieBehavior pref. Everything should pass through CookieSettings.
+ *
+ * A reference to CookieSettings can be obtained from
+ * nsILoadInfo::GetCookieSettings(), from Document::CookieSettings() and from
+ * the WorkerPrivate::CookieSettings().
+ *
+ * CookieSettings is thread-safe, but the permission list must be touched only
+ * on the main-thread.
+ *
+ * Testing
+ * ~~~~~~~
+ *
+ * If you need to test the changing of cookie policy or a cookie permission, you
+ * need to workaround CookieSettings. This can be done opening a new window and
+ * running the test into that new global.
+ */
+
 /**
  * Class that provides an nsICookieSettings implementation.
  */