/* This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ #include "nsISupports.idl" /** * nsIClassOfService.idl * * Used to express class dependencies and characteristics - complimentary to * nsISupportsPriority which is used to express weight * * Channels that implement this interface may make use of this * information in different ways. */ // convenience class for passing around the class of service %{C++ namespace mozilla::net { class ClassOfService; } %} native ClassOfService(mozilla::net::ClassOfService); [scriptable, uuid(1ccb58ec-5e07-4cf9-a30d-ac5490d23b41)] interface nsIClassOfService : nsISupports { attribute unsigned long classFlags; attribute boolean incremental; void clearClassFlags(in unsigned long flags); void addClassFlags(in unsigned long flags); void setClassOfService(in ClassOfService s); // All these flags have a (de)prioritization effect. // In the HTTP/1 world the priority is considered for all requests inside a so // called 'Request Context' which is a context common to all sub-resources // belonging to a single top level window (RequestContextService). Requests // marked with the Leader flag are blocking (preventing from being sent to the // server) all other resource loads except those marked with the Unblocked // flag. Other classes run in parallel - neither being blocked no ;r blocking. // The Leader flag is used only for blocking resources (sync and // defer javascript resources and stylesheets.) Purpose is to deliver these // first-paint and domcontentloaded blocking resources as soon as possbile. // In the HTTP/2 world it's different. Priorities are done only per HTTP/2 // session, normally we have one session per one origin (including origin // attributes!) Requests are dispatched (sent) immediately on an HTTP/2 // session. Each session has artificial streams (groups) relating to the class // of service flags (Leader, Other, Background, Speculative, Follower, // UrgentStart), each such a stream is given a different weight (only way to // give a stream a priority in HTTP/2) reflecting the desired request group // priority. Actual request streams are then dependent on these artificial // streams (groups). nsISupportsPriority of each request is passed as a weight // on the HTTP/2 stream to prioritize streams in the same group. A stream can // also be dependent on other stream. We have dependency of Followers on // Leaders, hence everything set the Follower flag should be processed by the // server after Leaders. Same for Speculative being dependent on Background. The // tree is created and used here: // https://searchfox.org/mozilla-central/rev/cc280c4be94ff8cf64a27cc9b3d6831ffa49fa45/netwerk/protocol/http/Http2Session.cpp#1053-1070 // https://searchfox.org/mozilla-central/rev/cc280c4be94ff8cf64a27cc9b3d6831ffa49fa45/netwerk/protocol/http/Http2Stream.cpp#1338 // For detailed description of how HTTP/2 server should handle the priorities // and dependencies see: // https://developers.google.com/web/fundamentals/performance/http2/#stream_prioritization // Please note that the dependecies and weights we are sending to the server // are only suggestions, the server may completely ignore it. // Leaders (should) block all other resources except Unblocked. This flag // also priortizes HTTP cache reading queue by blocking all other cache // requests. const unsigned long Leader = 1 << 0; // The Follower flag is currently unused! const unsigned long Follower = 1 << 1; // The Speculative flag is currently unused! const unsigned long Speculative = 1 << 2; // The Background flag is currently only used for Beacon. const unsigned long Background = 1 << 3; // Requests marked with this flag are not blocked by Leaders. This is mainly // used for probing-like XMLHttpRequests that may block delivery of head // blocking resources, e.g. CSS files tailored for the UA. const unsigned long Unblocked = 1 << 4; // Throttleable flag allows response throttling of the resource load. Note // that this functionality is currently disabled. const unsigned long Throttleable = 1 << 5; // UrgentStart makes the request temporarily extend HTTP/1 connection // parallelism limits. Used mainly for navigational requests (top level html) // and any request considered coming from a user interaction to make reaction // of the browser as fast as possible and not blocked. const unsigned long UrgentStart = 1 << 6; // Specifically disables throttling under any circumstances, used for media // responses mainly. const unsigned long DontThrottle = 1 << 7; // Enforce tailing on this load; any of Leader, Unblocked, UrgentStart, // TailForbidden overrule this flag (disable tailing.) const unsigned long Tail = 1 << 8; // Tailing may be engaged regardless if the load is marked Unblocked when some // other conditions are met later, like when the load is found to be a // tracker. const unsigned long TailAllowed = 1 << 9; // Tailing not allowed under any circumstances or combination of flags. const unsigned long TailForbidden = 1 << 10; };