Mozilla Source Tree Docs Release 50.0A1
Total Page:16
File Type:pdf, Size:1020Kb
Mozilla Source Tree Docs Release 50.0a1 August 02, 2016 Contents 1 SSL Error Reporting 1 2 Firefox 3 3 Telemetry Experiments 11 4 Build System 17 5 WebIDL 83 6 Graphics 85 7 Firefox for Android 87 8 Indices and tables 99 9 Localization 101 10 mach 105 11 CloudSync 113 12 TaskCluster Task-Graph Generation 119 13 Crash Manager 133 14 Telemetry 137 15 Crash Reporter 207 16 Supbrocess Module 211 17 Toolkit modules 215 18 Add-on Manager 221 19 Linting 227 20 Indices and tables 233 21 Mozilla ESLint Plugin 235 i 22 Python Packages 239 23 Managing Documentation 375 24 Indices and tables 377 Python Module Index 379 ii CHAPTER 1 SSL Error Reporting With the introduction of HPKP, it becomes useful to be able to capture data on pin violations. SSL Error Reporting is an opt-in mechanism to allow users to send data on such violations to mozilla. 1.1 Payload Format An example report: { "hostname":"example.com", "port":443, "timestamp":1413490449, "errorCode":-16384, "failedCertChain":[ ], "userAgent":"Mozilla/5.0 (X11; Linux x86_64; rv:36.0) Gecko/20100101 Firefox/36.0", "version":1, "build":"20141022164419", "product":"Firefox", "channel":"default" } Where the data represents the following: “hostname” The name of the host the connection was being made to. “port” The TCP port the connection was being made to. “timestamp” The (local) time at which the report was generated. Seconds since 1 Jan 1970, UTC. “errorCode” The error code. This is the error code from certificate veri- fication. Here’s a small list of the most commonly-encountered errors: https://wiki.mozilla.org/SecurityEngineering/x509Certs#Error_Codes_in_Firefox In theory many of the errors from sslerr.h, secerr.h, and pkixnss.h could be encountered. We’re starting with just MOZILLA_PKIX_ERROR_KEY_PINNING_FAILURE, which means that key pinning failed (i.e. there wasn’t an intersection between the keys in any computed trusted certificate chain and the expected list of keys for the domain the user is attempting to connect to). “failedCertChain” The certificate chain which caused the pinning violation (array of base64 encoded PEM) “user agent” The user agent string of the browser sending the report “build” The build ID 1 Mozilla Source Tree Docs, Release 50.0a1 “product” The product name “channel” The user’s release channel 1.2 Preferences The following preferences are used by SSL Error reporting: “security.ssl.errorReporting.enabled” Should the SSL Error Reporting UI be shown on pin violations? Default value: true “security.ssl.errorReporting.url” Where should SSL error reports be sent? Default value: https://incoming.telemetry.mozilla.org/submit/sslreports/ “security.ssl.errorReporting.automatic” Should error reports be sent without user interaction. Default value: false. Note: this pref is overridden by the value of security.ssl.errorReporting.enabled This is only set when specifically requested by the user. The user can set this value (or unset it) by checking the “Automatically report errors in the future” checkbox when about:neterror is displayed for SSL Errors. 2 Chapter 1. SSL Error Reporting CHAPTER 2 Firefox This is the nascent documentation of the Firefox front-end code. 2.1 Directory Links Architecture and Data Formats Directory links are enhancements to the new tab experience that combine content Firefox already knows about from user browsing with external content. There are 3 kinds of links: • directory links fill in additional tiles on the new tab page if there would have been empty tiles because the user has a clean profile or cleared history • suggested links are shown if certain triggering criteria matches the user’s browsing behavior, i.e., if the user has a top site that matches one of several possible sites. E.g., only show a sports suggestion if the user has a sport site as a top site • enhanced links replace a matching user’s visible history tile from the same site but only the visual aspects: title, image, and rollover image To power the above features, DirectoryLinksProvider module downloads, at most once per 24 hours, the directory source links as JSON with enough data for Firefox to determine what should be shown or not. This module also handles reporting back data about the tiles via asynchronous pings that don’t return data from the server. For the directory source and ping endpoints, the default preference values point to Mozilla key-pinned servers with encryption. No cookies are set by the servers and Firefox enforces this by making anonymous requests. • default directory source endpoint: https://tiles.services.mozilla.com/v3/links/fetch/%LOCALE%/%CHANNEL% • default directory ping endpoint: https://tiles.services.mozilla.com/v3/links/ 2.1.1 Preferences There are two main preferences that control downloading links and reporting metrics. browser.newtabpage.directory.source This endpoint tells Firefox where to download directory source file as a GET request. It should return JSON of the appropriate format containing the relevant links data. The value can be a data URI, e.g., an empty JSON object effectively turns off remote downloading: data:text/plain,{} The preference value will have %LOCALE% and %CHANNEL% replaced by the appropriate values for the build of Firefox, e.g., 3 Mozilla Source Tree Docs, Release 50.0a1 • directory source endpoint: https://tiles.services.mozilla.com/v3/links/fetch/en-US/release browser.newtabpage.directory.ping This endpoint tells Firefox where to report Tiles metrics as a POST request. The data is sent as a JSON blob. Setting it to empty effectively turns off reporting of Tiles data. A path segment will be appended to the endpoint of “view” or “click” depending on the type of ping, e.g., • view ping endpoint: https://tiles.services.mozilla.com/v3/links/view • click ping endpoint: https://tiles.services.mozilla.com/v3/links/click 2.1.2 Data Flow When Firefox starts, it checks for a cached directory source file. If one exists, it checks for its timestamp to determine if a new file should be downloaded. If a directory source file needs to be downloaded, a GET request is made then cacheed and unpacked the JSON into the different types of links. Various checks filter out invalid links, e.g., those with http-hosted images or those that don’t fit the allowed suggestions. When a new tab page is built, DirectoryLinksProvider module provides additional link data that is combined with history link data to determine which links can be displayed or not. When a new tab page is shown, a view ping is sent with relevant tiles data. Similarly, when the user clicks on various parts of tiles (to load the page, pin, block, etc.), a click ping is sent with similar data. Both of these can trigger downloading of fresh directory source links if 24 hours have elapsed since last download. Users can turn off the ping with in-new-tab-page controls. As the new tab page is rendered, any images for tiles are downloaded if not already cached. The default servers hosting the images are Mozilla CDN that don’t use cookies: https://tiles.cdn.mozilla.net/ and Firefox enforces that the images come from mozilla.net or data URIs when using the default directory source. 2.1.3 Source JSON Format Firefox expects links data in a JSON object with top level keys each providing an array of tile objects. The keys correspond to the different types of links: directory, suggested, and enhanced. Example Below is an example directory source file: { "directory":[ { "bgColor":"", "directoryId": 498, "enhancedImageURI":"https://tiles.cdn.mozilla.net/images/d11ba0b3095bb19d8092cd29be9cbb9e197671ea.28088.png", "imageURI":"https://tiles.cdn.mozilla.net/images/1332a68badf11e3f7f69bf7364e79c0a7e2753bc.5316.png", "title":"Mozilla Community", "type":"affiliate", "url":"http://contribute.mozilla.org/" } ], 4 Chapter 2. Firefox Mozilla Source Tree Docs, Release 50.0a1 "enhanced":[ { "bgColor":"", "directoryId": 776, "enhancedImageURI":"https://tiles.cdn.mozilla.net/images/44a14fc405cebc299ead86514dff0e3735c8cf65.10814.png", "imageURI":"https://tiles.cdn.mozilla.net/images/20e24aa2219ec7542cc8cf0fd79f0c81e16ebeac.11859.png", "title":"TurboTax", "type":"sponsored", "url":"https://turbotax.intuit.com/" } ], "suggested":[ { "adgroup_name":"open-source browser", "bgColor":"#cae1f4", "check_inadjacency": true, "directoryId": 702, "explanation":"Suggested for%1$S enthusiasts who visit sites like%2$S", "frecent_sites":[ "addons.mozilla.org", "air.mozilla.org", "blog.mozilla.org", "bugzilla.mozilla.org", "developer.mozilla.org", "etherpad.mozilla.org", "hacks.mozilla.org", "hg.mozilla.org", "mozilla.org", "planet.mozilla.org", "quality.mozilla.org", "support.mozilla.org", "treeherder.mozilla.org", "wiki.mozilla.org" ], "frequency_caps":{"daily":3,"total": 10}, "imageURI":"https://tiles.cdn.mozilla.net/images/9ee2b265678f2775de2e4bf680df600b502e6038.3875.png", "time_limits":{"start":"2014-01-01T00:00:00.000Z","end":"2014-02-01T00:00:00.000Z"}, "title":"Thanks for testing!", "type":"affiliate", "url":"https://www.mozilla.com/firefox/tiles" } ] } Link Object Each link object has various values that Firefox uses to display a tile: • url - string url for the page to be loaded when the tile is clicked. Only https and http URLs are allowed. • title - string that appears below the tile. • type - string relationship of the link to Mozilla. Expected values: affiliate, organic, sponsored. • imageURI - string url for the tile image to show. Only https and data URIs are allowed. • enhancedImageURI - string url for the image to be shown before the user hovers. Only https and data URIs are allowed. 2.1. Directory Links Architecture and Data Formats 5 Mozilla Source Tree Docs, Release 50.0a1 • bgColor - string css color for additional fill background color. • directoryId - id of the tile to be used during ping reporting Suggested Link Object Extras A suggested link has additional values: • adgroup_name - string to override the hardcoded display name of the triggering set of sites in Firefox. • check_inadjacency - boolean if true prevents the suggested link from being shown if the new tab page is showing a site from an inadjacency list. • explanation - string to override the default explanation that appears below a Suggested Tile.