summaryrefslogtreecommitdiffstats
path: root/netwerk/base/nsIClassOfService.idl
blob: 2d5fa03dc1a12983e56ee117f95159ee4d875c6a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
/* 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, builtinclass, 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);
  [noscript] 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 <head> 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;
};