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
|
# Internal URLs
Firefox and other Gecko applications use several URL schemes (protocols) for
internal or "special" resources.
The main ones are:
<!-- no toc -->
- [`moz-src` URLs](#moz-src-urls)
- [`resource` URLs](#resource-urls)
- [`chrome` URLs](#chrome-urls)
There are other special protocols like `moz-icon` and various places URLs,
but at the moment they are not covered here.
## `moz-src` URLs
URLs look like: `moz-src:///browser/components/BrowserGlue.sys.mjs`.
Note that there is no "host" component (nothing between the second and third
slash). In future we may support non-empty hosts with specific meanings. For
now, always use a triple slash.
Everything after this is the full source path of the file you are referencing.
Of course this is an abstraction: the URL will only work if the file is actually
packaged.
### Packaging
To package a file for use via `moz-src`, include it in a
[`moz.build` file][mozbuild-files] inside a `MOZ_SRC_FILES` instruction.
All files are packaged in the toolkit `omni.ja` file. Internally, the URL is
translated into a `jar:file` URL into the toolkit (`gre`) `omni.ja` file.
### Security considerations
Only privileged (system principal / "chrome" privileged) code can load
or link to `moz-src` URLs.
The intention is that in future we make it possible to have more fine-grained
restrictions for `moz-src` URLs with non-empty "host" portions
(e.g. `moz-src://about/` for content only accessible to about: pages), but this
has not yet been implemented.
## `resource` URLs
URLs look like `resource://mapping/optional/path/components/file.txt`.
Here, `mapping` is an arbitrary identifier chosen elsewhere. There are
3 builtin mappings of note:
- `gre` ("Gecko Runtime Environment") for some of the content inside the
"toolkit" omni.ja file
- `app`, for some of the content inside the "browser" (or other
application-specific) omni.ja file.
- `android`, on Android, for APK contents.
The `app` mapping is the default, which means that if you use a resource URL
without a host component (`resource:///whatever`), it is equivalent to the
`app` URL: `resource://app/whatever`.
Each mapping is resolved to a URL in the resource URL protocol handler, after
which any subsequent path/file components are resolved relative to that URL.
Additional mappings can be added via a
[chrome.manifest instruction][resource-map]. Builtin extensions make use of
this, as do [some components][searchfox-res-reg].
### Packaging
The builtin `app` and `gre` mappings, as well as any additional mappings from
`jar.mn` files and other non-extension parts of the build, always resolve into
the app-specific and toolkit `omni.ja` file, respectively.
To package files for access via `resource` URLs, use
[jar manifest file instructions][jar-manifest-files] to package files into
the mapped directory inside `omni.ja` .
### Security considerations
By default `resource` URLs cannot be accessed by web content and are restricted
to privileged (system principal / "chrome" privileged) code. However, you can
register a `resource` mapping with `contentaccessible=yes` in order to
"holepunch" this restriction. Note that this means _everything_ packaged under
that path becomes linkable and loadable by all web content. With few exceptions
(like user agent stylesheets), that is not what you want.
Unfortunately more fine-grained restrictions are not available for `resource`
URLs.
## `chrome` URLs
`chrome` URLs take one of three forms:
- `chrome://browser/content/browser.xhtml`
- `chrome://browser/skin/browser.css`
- `chrome://browser/locale/browser.properties`
The first ("host") component after `chrome://` is the **package name**. Common
ones are `browser` (for front-end Desktop Firefox files) and `global` (for
content used by Gecko/toolkit code), but different parts of the codebase can and
do register their own packages.
The second component after `chrome://{packagename}/` is always one of `content`,
`skin` or `locale`, known as "providers". They cater to JS and HTML (`content`),
style information (`skin`) and old-style `.properties` localization files
(`locale`).
Any path portions after the provider are relative paths to where that particular
package & provider combination is pointing.
More information is available in
[the build system's chrome registration docs][chrome-registration].
### Packaging
To package files for access via `chrome` URLs, use
[jar manifest file instructions][jar-manifest-files] to package files into
the mapped directory inside `omni.ja` .
Depending on how and where [the chrome is registered][chrome-registration],
the files are typically packaged into either the app or toolkit `omni.ja` file,
though it is possible to use `chrome` URLs inside builtin extensions as well.
### Security considerations
By default `chrome` URLs cannot be accessed by web content and are restricted
to privileged (system principal / "chrome" privileged) code. However, you can
register a chrome `content` mapping with `contentaccessible=yes` in order to
"holepunch" this restriction. Note that this means _everything_ packaged under
**the content, skin and locale packages for that identifier** becomes linkable
and loadable by all web content. Please do not use this functionality going
forward.
Unfortunately more fine-grained restrictions are not available for `chrome`
URLs.
[chrome-registration]: ../build/buildsystem/chrome-registration
[resource-map]: ../build/buildsystem/chrome-registration#resource
[mozbuild-files]: ../build/buildsystem/mozbuild-files
[searchfox-res-reg]: https://searchfox.org/mozilla-central/search?q=%25+resource&path=jar.mn&case=false®exp=false
[jar-manifest-files]: ../build/buildsystem/jar-manifests
|
