nsIClassOfService.idl (5807B)
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 };