1// Copyright 2013 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef EXTENSIONS_COMMON_USER_SCRIPT_H_
6#define EXTENSIONS_COMMON_USER_SCRIPT_H_
7
8#include <memory>
9#include <string>
10#include <vector>
11
12#include "base/files/file_path.h"
13#include "base/strings/string_piece.h"
14#include "extensions/common/host_id.h"
15#include "extensions/common/url_pattern.h"
16#include "extensions/common/url_pattern_set.h"
17#include "url/gurl.h"
18
19namespace base {
20class Pickle;
21class PickleIterator;
22}
23
24namespace extensions {
25
26// Represents a user script, either a standalone one, or one that is part of an
27// extension.
28class UserScript {
29 public:
30 // The file extension for standalone user scripts.
31 static const char kFileExtension[];
32
33 static int GenerateUserScriptID();
34
35 // Check if a URL should be treated as a user script and converted to an
36 // extension.
37 static bool IsURLUserScript(const GURL& url, const std::string& mime_type);
38
39 // Get the valid user script schemes for the current process. If
40 // canExecuteScriptEverywhere is true, this will return ALL_SCHEMES.
41 static int ValidUserScriptSchemes(bool canExecuteScriptEverywhere = false);
42
43 // TODO(rdevlin.cronin) This and RunLocation don't really belong here, since
44 // they are used for more than UserScripts (e.g., tabs.executeScript()).
45 // The type of injected script.
46 enum InjectionType {
47 // A content script specified in the extension's manifest.
48 CONTENT_SCRIPT,
49 // A script injected via, e.g. tabs.executeScript().
50 PROGRAMMATIC_SCRIPT
51 };
52 // The last type of injected script; used for enum verification in IPC.
53 // Update this if you add more injected script types!
54 static const InjectionType INJECTION_TYPE_LAST = PROGRAMMATIC_SCRIPT;
55
56 // Locations that user scripts can be run inside the document.
57 // The three run locations must strictly follow each other in both load order
58 // (i.e., start *always* comes before end) and numerically, as we use
59 // arithmetic checking (e.g., curr == last + 1). So, no bitmasks here!!
60 enum RunLocation {
61 UNDEFINED,
62 DOCUMENT_START, // After the documentElement is created, but before
63 // anything else happens.
64 DOCUMENT_END, // After the entire document is parsed. Same as
65 // DOMContentLoaded.
66 DOCUMENT_IDLE, // Sometime after DOMContentLoaded, as soon as the document
67 // is "idle". Currently this uses the simple heuristic of:
68 // min(DOM_CONTENT_LOADED + TIMEOUT, ONLOAD), but no
69 // particular injection point is guaranteed.
70 RUN_DEFERRED, // The user script's injection was deferred for permissions
71 // reasons, and was executed at a later time.
72 BROWSER_DRIVEN, // The user script will be injected when triggered by an
73 // IPC in the browser process.
74 RUN_LOCATION_LAST // Leave this as the last item.
75 };
76
77 // Holds script file info.
78 class File {
79 public:
80 File(const base::FilePath& extension_root,
81 const base::FilePath& relative_path,
82 const GURL& url);
83 File();
84 File(const File& other);
85 ~File();
86
87 const base::FilePath& extension_root() const { return extension_root_; }
88 const base::FilePath& relative_path() const { return relative_path_; }
89
90 const GURL& url() const { return url_; }
91 void set_url(const GURL& url) { url_ = url; }
92
93 // If external_content_ is set returns it as content otherwise it returns
94 // content_
95 const base::StringPiece GetContent() const {
96 if (external_content_.data())
97 return external_content_;
98 else
99 return content_;
100 }
101 void set_external_content(const base::StringPiece& content) {
102 external_content_ = content;
103 }
104 void set_content(const base::StringPiece& content) {
105 content_.assign(content.begin(), content.end());
106 }
107
108 // Serialization support. The content and FilePath members will not be
109 // serialized!
110 void Pickle(base::Pickle* pickle) const;
111 void Unpickle(const base::Pickle& pickle, base::PickleIterator* iter);
112
113 private:
114 // Where the script file lives on the disk. We keep the path split so that
115 // it can be localized at will.
116 base::FilePath extension_root_;
117 base::FilePath relative_path_;
118
119 // The url to this script file.
120 GURL url_;
121
122 // The script content. It can be set to either loaded_content_ or
123 // externally allocated string.
124 base::StringPiece external_content_;
125
126 // Set when the content is loaded by LoadContent
127 std::string content_;
128 };
129
130 using FileList = std::vector<std::unique_ptr<File>>;
131
132 // Type of a API consumer instance that user scripts will be injected on.
133 enum ConsumerInstanceType { TAB, WEBVIEW };
134
135 // Constructor. Default the run location to document end, which is like
136 // Greasemonkey and probably more useful for typical scripts.
137 UserScript();
138 ~UserScript();
139
140 // Performs a copy of all fields except file contents.
141 static std::unique_ptr<UserScript> CopyMetadataFrom(const UserScript& other);
142
143 const std::string& name_space() const { return name_space_; }
144 void set_name_space(const std::string& name_space) {
145 name_space_ = name_space;
146 }
147
148 const std::string& name() const { return name_; }
149 void set_name(const std::string& name) { name_ = name; }
150
151 const std::string& version() const { return version_; }
152 void set_version(const std::string& version) {
153 version_ = version;
154 }
155
156 const std::string& description() const { return description_; }
157 void set_description(const std::string& description) {
158 description_ = description;
159 }
160
161 // The place in the document to run the script.
162 RunLocation run_location() const { return run_location_; }
163 void set_run_location(RunLocation location) { run_location_ = location; }
164
165 // Whether to emulate greasemonkey when running this script.
166 bool emulate_greasemonkey() const { return emulate_greasemonkey_; }
167 void set_emulate_greasemonkey(bool val) { emulate_greasemonkey_ = val; }
168
169 // Whether to match all frames, or only the top one.
170 bool match_all_frames() const { return match_all_frames_; }
171 void set_match_all_frames(bool val) { match_all_frames_ = val; }
172
173 // Whether to match about:blank and about:srcdoc.
174 bool match_about_blank() const { return match_about_blank_; }
175 void set_match_about_blank(bool val) { match_about_blank_ = val; }
176
177 // The globs, if any, that determine which pages this script runs against.
178 // These are only used with "standalone" Greasemonkey-like user scripts.
179 const std::vector<std::string>& globs() const { return globs_; }
180 void add_glob(const std::string& glob) { globs_.push_back(glob); }
181 void clear_globs() { globs_.clear(); }
182 const std::vector<std::string>& exclude_globs() const {
183 return exclude_globs_;
184 }
185 void add_exclude_glob(const std::string& glob) {
186 exclude_globs_.push_back(glob);
187 }
188 void clear_exclude_globs() { exclude_globs_.clear(); }
189
190 // The URLPatterns, if any, that determine which pages this script runs
191 // against.
192 const URLPatternSet& url_patterns() const { return url_set_; }
193 void add_url_pattern(const URLPattern& pattern);
194 const URLPatternSet& exclude_url_patterns() const {
195 return exclude_url_set_;
196 }
197 void add_exclude_url_pattern(const URLPattern& pattern);
198
199 // List of js scripts for this user script
200 FileList& js_scripts() { return js_scripts_; }
201 const FileList& js_scripts() const { return js_scripts_; }
202
203 // List of css scripts for this user script
204 FileList& css_scripts() { return css_scripts_; }
205 const FileList& css_scripts() const { return css_scripts_; }
206
207 const std::string& extension_id() const { return host_id_.id(); }
208
209 const HostID& host_id() const { return host_id_; }
210 void set_host_id(const HostID& host_id) { host_id_ = host_id; }
211
212 const ConsumerInstanceType& consumer_instance_type() const {
213 return consumer_instance_type_;
214 }
215 void set_consumer_instance_type(
216 const ConsumerInstanceType& consumer_instance_type) {
217 consumer_instance_type_ = consumer_instance_type;
218 }
219
220 int id() const { return user_script_id_; }
221 void set_id(int id) { user_script_id_ = id; }
222
223 // TODO(lazyboy): Incognito information is extension specific, it doesn't
224 // belong here. We should be able to determine this in the renderer/ where it
225 // is used.
226 bool is_incognito_enabled() const { return incognito_enabled_; }
227 void set_incognito_enabled(bool enabled) { incognito_enabled_ = enabled; }
228
229 // Returns true if the script should be applied to the specified URL, false
230 // otherwise.
231 bool MatchesURL(const GURL& url) const;
232
233 // Returns true if the script should be applied to the given
234 // |effective_document_url| (calculated by the caller based on
235 // match_about_blank()| while also taking into account whether the document's
236 // frame |is_subframe| and what the |top_level_origin| is.
237 bool MatchesDocument(const GURL& effective_document_url,
238 bool is_subframe) const;
239
240 // Serializes the UserScript into a pickle. The content of the scripts and
241 // paths to UserScript::Files will not be serialized!
242 void Pickle(base::Pickle* pickle) const;
243
244 // Deserializes the script from a pickle. Note that this always succeeds
245 // because presumably we were the one that pickled it, and we did it
246 // correctly.
247 void Unpickle(const base::Pickle& pickle, base::PickleIterator* iter);
248
249 private:
250 // base::Pickle helper functions used to pickle the individual types of
251 // components.
252 void PickleGlobs(base::Pickle* pickle,
253 const std::vector<std::string>& globs) const;
254 void PickleHostID(base::Pickle* pickle, const HostID& host_id) const;
255 void PickleURLPatternSet(base::Pickle* pickle,
256 const URLPatternSet& pattern_list) const;
257 void PickleScripts(base::Pickle* pickle, const FileList& scripts) const;
258
259 // Unpickle helper functions used to unpickle individual types of components.
260 void UnpickleGlobs(const base::Pickle& pickle,
261 base::PickleIterator* iter,
262 std::vector<std::string>* globs);
263 void UnpickleHostID(const base::Pickle& pickle,
264 base::PickleIterator* iter,
265 HostID* host_id);
266 void UnpickleURLPatternSet(const base::Pickle& pickle,
267 base::PickleIterator* iter,
268 URLPatternSet* pattern_list);
269 void UnpickleScripts(const base::Pickle& pickle,
270 base::PickleIterator* iter,
271 FileList* scripts);
272
273 // The location to run the script inside the document.
274 RunLocation run_location_;
275
276 // The namespace of the script. This is used by Greasemonkey in the same way
277 // as XML namespaces. Only used when parsing Greasemonkey-style scripts.
278 std::string name_space_;
279
280 // The script's name. Only used when parsing Greasemonkey-style scripts.
281 std::string name_;
282
283 // A longer description. Only used when parsing Greasemonkey-style scripts.
284 std::string description_;
285
286 // A version number of the script. Only used when parsing Greasemonkey-style
287 // scripts.
288 std::string version_;
289
290 // Greasemonkey-style globs that determine pages to inject the script into.
291 // These are only used with standalone scripts.
292 std::vector<std::string> globs_;
293 std::vector<std::string> exclude_globs_;
294
295 // URLPatterns that determine pages to inject the script into. These are
296 // only used with scripts that are part of extensions.
297 URLPatternSet url_set_;
298 URLPatternSet exclude_url_set_;
299
300 // List of js scripts defined in content_scripts
301 FileList js_scripts_;
302
303 // List of css scripts defined in content_scripts
304 FileList css_scripts_;
305
306 // The ID of the host this script is a part of. The |ID| of the
307 // |host_id| can be empty if the script is a "standlone" user script.
308 HostID host_id_;
309
310 // The type of the consumer instance that the script will be injected.
311 ConsumerInstanceType consumer_instance_type_;
312
313 // The globally-unique id associated with this user script. Defaults to
314 // -1 for invalid.
315 int user_script_id_;
316
317 // Whether we should try to emulate Greasemonkey's APIs when running this
318 // script.
319 bool emulate_greasemonkey_;
320
321 // Whether the user script should run in all frames, or only just the top one.
322 // Defaults to false.
323 bool match_all_frames_;
324
325 // Whether the user script should run in about:blank and about:srcdoc as well.
326 // Defaults to false.
327 bool match_about_blank_;
328
329 // True if the script should be injected into an incognito tab.
330 bool incognito_enabled_;
331
332 DISALLOW_COPY_AND_ASSIGN(UserScript);
333};
334
335// Information we need while removing scripts from a UserScriptLoader.
336struct UserScriptIDPair {
337 UserScriptIDPair(int id, const HostID& host_id);
338 explicit UserScriptIDPair(int id);
339
340 int id;
341 HostID host_id;
342};
343
344bool operator<(const UserScriptIDPair& a, const UserScriptIDPair& b);
345
346using UserScriptList = std::vector<std::unique_ptr<UserScript>>;
347
348} // namespace extensions
349
350#endif // EXTENSIONS_COMMON_USER_SCRIPT_H_
351