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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
// Copyright 2024 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef NET_DEVICE_BOUND_SESSIONS_SESSION_INCLUSION_RULES_H_
#define NET_DEVICE_BOUND_SESSIONS_SESSION_INCLUSION_RULES_H_
#include <memory>
#include <optional>
#include <vector>
#include "net/base/net_export.h"
#include "net/base/scheme_host_port_matcher_rule.h"
#include "net/base/schemeful_site.h"
#include "url/origin.h"
namespace net::device_bound_sessions {
namespace proto {
class SessionInclusionRules;
}
// This class represents a set of rules that define which network requests may
// potentially be deferred on account of an active DBSC session. It is derived
// from parameters specified in the session config. Note that this scope is a
// distinct concept from the "scope" of a cookie (or CookieCraving), which is
// the set of requests for which that cookie should be included.
//
// The SessionInclusionRules consists of a basic include rule and a number of
// specific include/exclude rules.
// 1. The basic include rule defaults to including the origin that created/set
// this session's config, but can be expanded to include the whole site
// (eTLD+1) if allowed.
// 2. A session is allowed to include requests beyond its setting origin if the
// setting origin's host is the root eTLD+1 (not a subdomain).
// 3. Specific include and exclude rules specify URL patterns that are included
// or excluded from deferral by the session.
//
// A request URL is evaluated for inclusion by matching with the specific rules
// in reverse order of addition, and then following the basic include rule if no
// specific rules match. Once established, a SessionInclusionRules only cares
// about the request URL, not any other properties of the request.
class NET_EXPORT SessionInclusionRules final {
public:
enum InclusionResult {
// Definitely do not defer a request on behalf of this DBSC session.
kExclude,
// Consider a request eligible for deferral on behalf of this session, if
// other conditions are met.
kInclude,
};
// Initializes a default rule for the given origin. Does not do any checks
// on the origin; caller should enforce semantic checks on the origin such as
// desired schemes.
explicit SessionInclusionRules(const url::Origin& origin);
// Default, matches nothing.
SessionInclusionRules();
SessionInclusionRules(const SessionInclusionRules& other) = delete;
SessionInclusionRules& operator=(const SessionInclusionRules& other) = delete;
SessionInclusionRules(SessionInclusionRules&& other);
SessionInclusionRules& operator=(SessionInclusionRules&& other);
~SessionInclusionRules();
bool operator==(const SessionInclusionRules& other) const;
// Sets the basic include rule underlying the more specific URL rules. This
// should be derived from the "include_site" param in the config. If not set
// explicitly, the default is false (meaning an origin-scoped session). If
// called with true: expands the basic include rule to include the whole site
// of the setting origin, if allowed. If called with false: restricts the
// basic rule to the setting origin only (any specific URL rules that are
// present will still apply).
void SetIncludeSite(bool include_site);
// Adds a specific URL rule that includes/excludes certain URLs based on their
// host part matching `host_pattern` and the path matching `path_prefix`. Any
// matching rule takes precedence over the basic scope. Does some validity
// checks on the inputs first. The `host_pattern` must either be a full domain
// (host piece) or a pattern containing a wildcard ('*' character) in the
// most-specific (leftmost) label position followed by a dot and a non-eTLD.
// The `path_prefix` must begin with '/' and cannot contain wildcards, and
// will match paths that start with the same path components. Returns whether
// the specified rule was added.
bool AddUrlRuleIfValid(InclusionResult rule_type,
const std::string& host_pattern,
const std::string& path_prefix);
// Evaluates `url` to determine whether a request to `url` may be included
// (i.e. potentially deferred on account of this DBSC session, if other
// conditions are met).
InclusionResult EvaluateRequestUrl(const GURL& url) const;
bool may_include_site_for_testing() const { return may_include_site_; }
const url::Origin& origin() const { return origin_; }
size_t num_url_rules_for_testing() const;
proto::SessionInclusionRules ToProto() const;
static std::unique_ptr<SessionInclusionRules> CreateFromProto(
const proto::SessionInclusionRules& proto);
std::string DebugString() const;
private:
struct UrlRule;
// The origin that created/set the session that this applies to. By default,
// sessions are origin-scoped unless specified otherwise.
url::Origin origin_;
// Whether the setting origin is allowed to include the whole site in its
// rules. This is equivalent to whether the origin's domain is the root eTLD+1
// (not a subdomain). It is cached here to avoid repeated eTLD lookups.
bool may_include_site_ = false;
// If non-nullopt: The site of `origin_`, when the config has specified
// "include_site" to make the session include any request URL on the setting
// origin's whole eTLD+1. This is only allowed if the origin's host is the
// root eTLD+1 (not a subdomain). We cache it here for efficiency rather than
// repeatedly constructing it from the `origin_` from which it's derived.
// If nullopt: Either the config has not specified "include_site", or the
// `origin_` is not allowed to include anything outside its origin.
// Invariant: If `may_include_site_` is false, then this must also be nullopt.
// This shouldn't ever be an opaque site.
std::optional<SchemefulSite> include_site_;
// A list of rules that modify the basic include rule (specified by `origin_`
// or `include_site_`), which may specify inclusion or exclusion for URLs that
// match. If any rules overlap, the latest rule takes precedence over earlier
// rules.
std::vector<UrlRule> url_rules_;
};
} // namespace net::device_bound_sessions
#endif // NET_DEVICE_BOUND_SESSIONS_SESSION_INCLUSION_RULES_H_
|
