netwerk/base/nsIClassOfService.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 /**
   8  * nsIClassOfService.idl
   9  *
  10  * Used to express class dependencies and characteristics - complimentary to
  11  * nsISupportsPriority which is used to express weight
  12  *
  13  * Channels that implement this interface may make use of this
  14  * information in different ways.
  15  */
  16
  17 // convenience class for passing around the class of service
  18 %{C++
  19 namespace mozilla::net {
  20 class ClassOfService;
  21 }
  22
  23 namespace mozilla::dom {
  24 enum class FetchPriority: uint8_t;
  25 }
  26 %}
  27 native ClassOfService(mozilla::net::ClassOfService);
  28 native FetchPriorityDOM(mozilla::dom::FetchPriority);
  29
  30 [scriptable, builtinclass, uuid(1ccb58ec-5e07-4cf9-a30d-ac5490d23b41)]
  31 interface nsIClassOfService : nsISupports
  32 {
  33   attribute unsigned long classFlags;
  34   attribute boolean incremental;
  35
  36   void clearClassFlags(in unsigned long flags);
  37   void addClassFlags(in unsigned long flags);
  38   [noscript] void setClassOfService(in ClassOfService s);
  39
  40   cenum FetchPriority: 8 {
  41     FETCHPRIORITY_UNSET = 0,
  42     FETCHPRIORITY_LOW = 1,
  43     FETCHPRIORITY_AUTO = 2,
  44     FETCHPRIORITY_HIGH = 3,
  45   };
  46   // Reflects the fetchPriority attribute set on the request.
  47   attribute nsIClassOfService_FetchPriority fetchPriority;
  48
  49   [notxpcom, nostdcall] void setFetchPriorityDOM(in FetchPriorityDOM aPriority);
  50
  51   // All these flags have a (de)prioritization effect.
  52
  53   // In the HTTP/1 world the priority is considered for all requests inside a so
  54   // called 'Request Context' which is a context common to all sub-resources
  55   // belonging to a single top level window (RequestContextService). Requests
  56   // marked with the Leader flag are blocking (preventing from being sent to the
  57   // server) all other resource loads except those marked with the Unblocked
  58   // flag.  Other classes run in parallel - neither being blocked no ;r blocking.
  59   // The Leader flag is used only for <head> blocking resources (sync and
  60   // defer javascript resources and stylesheets.) Purpose is to deliver these
  61   // first-paint and domcontentloaded blocking resources as soon as possbile.
  62
  63   // In the HTTP/2 world it's different. Priorities are done only per HTTP/2
  64   // session, normally we have one session per one origin (including origin
  65   // attributes!) Requests are dispatched (sent) immediately on an HTTP/2
  66   // session. Each session has artificial streams (groups) relating to the class
  67   // of service flags (Leader, Other, Background, Speculative, Follower,
  68   // UrgentStart), each such a stream is given a different weight (only way to
  69   // give a stream a priority in HTTP/2) reflecting the desired request group
  70   // priority.  Actual request streams are then dependent on these artificial
  71   // streams (groups). nsISupportsPriority of each request is passed as a weight
  72   // on the HTTP/2 stream to prioritize streams in the same group. A stream can
  73   // also be dependent on other stream. We have dependency of Followers on
  74   // Leaders, hence everything set the Follower flag should be processed by the
  75   // server after Leaders. Same for Speculative being dependent on Background. The
  76   // tree is created and used here:
  77   // https://searchfox.org/mozilla-central/rev/cc280c4be94ff8cf64a27cc9b3d6831ffa49fa45/netwerk/protocol/http/Http2Session.cpp#1053-1070
  78   // https://searchfox.org/mozilla-central/rev/cc280c4be94ff8cf64a27cc9b3d6831ffa49fa45/netwerk/protocol/http/Http2Stream.cpp#1338
  79   // For detailed description of how HTTP/2 server should handle the priorities
  80   // and dependencies see:
  81   // https://developers.google.com/web/fundamentals/performance/http2/#stream_prioritization
  82   // Please note that the dependecies and weights we are sending to the server
  83   // are only suggestions, the server may completely ignore it.
  84
  85   // Leaders (should) block all other resources except Unblocked.  This flag
  86   // also priortizes HTTP cache reading queue by blocking all other cache
  87   // requests.
  88   const unsigned long Leader = 1 << 0;
  89   // The Follower flag is currently unused!
  90   const unsigned long Follower = 1 << 1;
  91   // The Speculative flag is currently unused!
  92   const unsigned long Speculative = 1 << 2;
  93   // The Background flag is currently only used for Beacon.
  94   const unsigned long Background = 1 << 3;
  95   // Requests marked with this flag are not blocked by Leaders.  This is mainly
  96   // used for probing-like XMLHttpRequests that may block delivery of head
  97   // blocking resources, e.g. CSS files tailored for the UA.
  98   const unsigned long Unblocked = 1 << 4;
  99   // Throttleable flag allows response throttling of the resource load. Note
 100   // that this functionality is currently disabled.
 101   const unsigned long Throttleable = 1 << 5;
 102   // UrgentStart makes the request temporarily extend HTTP/1 connection
 103   // parallelism limits.  Used mainly for navigational requests (top level html)
 104   // and any request considered coming from a user interaction to make reaction
 105   // of the browser as fast as possible and not blocked.
 106   const unsigned long UrgentStart = 1 << 6;
 107   // Specifically disables throttling under any circumstances, used for media
 108   // responses mainly.
 109   const unsigned long DontThrottle = 1 << 7;
 110   // Enforce tailing on this load; any of Leader, Unblocked, UrgentStart,
 111   // TailForbidden overrule this flag (disable tailing.)
 112   const unsigned long Tail = 1 << 8;
 113   // Tailing may be engaged regardless if the load is marked Unblocked when some
 114   // other conditions are met later, like when the load is found to be a
 115   // tracker.
 116   const unsigned long TailAllowed = 1 << 9;
 117   // Tailing not allowed under any circumstances or combination of flags.
 118   const unsigned long TailForbidden = 1 << 10;
 119 };