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