Issue #303 Part 1: Move basilisk files from /browser to /application/basilisk

4 files changed, 460 insertions, 0 deletions

diff --git a/application/basilisk/docs/BrowserUsageTelemetry.rst b/application/basilisk/docs/BrowserUsageTelemetry.rst
new file mode 100644
index 000000000..c49cf7a3a
--- /dev/null
+++ b/application/basilisk/docs/BrowserUsageTelemetry.rst
@@ -0,0 +1,28 @@
+.. _browserusagetelemetry:
+
+=======================
+Browser Usage Telemetry
+=======================
+
+The `BrowserUsageTelemetry.jsm <https://dxr.mozilla.org/mozilla-central/source/browser/modules/BrowserUsageTelemetry.jsm>`_ module is the main module for measurements regarding the browser usage (e.g. tab and window counts, search counts, ...).
+
+The measurements recording begins right after the ``SessionStore`` has finished restoring the session (i.e. restoring tabs/windows after Firefox starts).
+
+Search telemetry
+================
+This module exposes the ``recordSearch`` method, which serves as the main entry point for recording search related Telemetry. It records only the search *counts* per engine and the origin of the search, but nothing pertaining the search contents themselves.
+
+As the transition to the ``BrowserUsageTelemetry`` happens, the ``recordSearch`` calls are dispatched through `BrowserSearch.recordSearchInTelemetry <https://dxr.mozilla.org/mozilla-central/rev/3e73fd638e687a4d7f46613586e5156b8e2af846/browser/base/content/browser.js#3752>`_, that is called by all the search related UI components (urlbar, searchbar, context menu and about\:\* pages).
+
+A list of the components recording search Telemetry can be found using the following `DXR search <https://dxr.mozilla.org/mozilla-central/search?q=recordSearchInTelemetry>`_.
+
+Measured interactions
+=====================
+The usage telemetry module currently measures these interactions with the browser:
+
+- *tab and window engagement*: counts the number of non-private tabs and windows opened in a subsession, after the session is restored (see e.g. ``browser.engagement.max_concurrent_tab_count``);
+- *URI loads*: counts the number of page loads (doesn't track and send the addresses, just the counts) directly triggered by the users (see ``browser.engagement.total_uri_count``);
+- *navigation events*: at this time, this only counts the number of time a page load is triggered by a particular UI interaction (e.g. by searching through the URL bar, see ``browser.engagement.navigation.urlbar``).
+
+
+Please see `Scalars.yaml <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/Scalars.yaml>`_ for the full list of tracked interactions.
diff --git a/application/basilisk/docs/DirectoryLinksProvider.rst b/application/basilisk/docs/DirectoryLinksProvider.rst
new file mode 100644
index 000000000..c6f55c3d4
--- /dev/null
+++ b/application/basilisk/docs/DirectoryLinksProvider.rst
@@ -0,0 +1,278 @@
+=============================================
+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/
+
+
+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.,
+
+- 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
+
+
+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.
+
+
+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/"
+          }
+      ],
+      "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.
+- ``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. %1$S is replaced by the triggering adgroup name and
+  %2$S is replaced by the triggering site.
+- ``frecent_sites`` - array of strings of the sites that can trigger showing a
+  Suggested Tile if the user has the site in one of the top 100 most-frecent
+  pages.
+- ``frequency_caps`` - an object consisting of daily and total frequency caps
+  that limit the number of times a Suggested Tile can be shown in the new tab
+  per day and overall.
+- ``time_limits`` - an object consisting of start and end timestamps specifying
+  when a Suggested Tile may start and has to stop showing in the newtab.
+  The timestamp is expected in ISO_8601 format: '2014-01-10T20:00:00.000Z'
+
+The inadjacency list is packaged with Firefox as base64-encoded 1-way-hashed
+sites that tend to have adult, gambling, alcohol, drug, and similar content.
+Its location: chrome://browser/content/newtab/newTab.inadjacent.json
+
+The preapproved arrays follow a policy for determining what topic grouping is
+allowed as well as the composition of a grouping. The topics are broad
+uncontroversial categories, e.g., Mobile Phone, News, Technology, Video Game,
+Web Development. There are at least 5 sites within a grouping, and as many
+popular sites relevant to the topic are included to avoid having one site be
+clearly dominant. These requirements provide some deniability of which site
+actually triggered a suggestion during ping reporting, so it's more difficult to
+determine if a user has gone to a specific site.
+
+
+Ping JSON Format
+================
+
+Firefox reports back an action and the state of tiles on the new tab page based
+on the user opening a new tab or clicking a tile. The top level keys of the
+ping:
+
+- ``locale`` - string locale of the Firefox build
+- ``tiles`` - array of tiles ping objects
+
+An additional key at the top level indicates which action triggered the ping.
+The value associated to the action key is the 0-based index into the tiles array
+of which tile triggered the action. Valid actions: block, click, pin, sponsored,
+sponsored_link, unpin, view. E.g., if the second tile is being clicked, the ping
+will have ``"click": 1``
+
+Example
+-------
+
+Below is an example ``click`` ping with 3 tiles: a pinned suggested tile
+followed by a history tile and a directory tile. The first tile is being
+blocked::
+
+  {
+      "locale": "en-US",
+      "tiles": [
+          {
+              "id": 702,
+              "pin": 1,
+              "past_impressions": {"total": 5, "daily": 1},
+          },
+          {},
+          {
+              "id": 498,
+          }
+      ],
+      "block": 0
+  }
+
+Tiles Ping Object
+-----------------
+
+Each tile of the new tab page is reported back as part of the ping with some or
+none of the following optional values:
+
+- ``id`` - id that was provided as part of the downloaded link object (for all
+  types of links: directory, suggested, enhanced); not present if the tile was
+  created from user behavior, e.g., visiting pages
+- ``past_impressions`` - number of impressions (new tab "views") a suggested
+  tile was shown before it was clicked, pinned or blocked. Where the "total"
+  counter is the overall number of impressions accumulated prior to a click action,
+  and "daily" counter is the number impressions occurred on same calendar day of
+  a click. This infomration is submitted once per a suggested tile upon click,
+  pin or block
+- ``pinned`` - 1 if the tile is pinned; not present otherwise
+- ``pos`` - integer position if the tile is not in the natural order, e.g., a
+  pinned tile after an empty slot; not present otherwise
+- ``score`` - integer truncated score based on the tile's frecency; not present
+  if 0
+- ``url`` - empty string if it's an enhanced tile; not present otherwise
diff --git a/application/basilisk/docs/UITelemetry.rst b/application/basilisk/docs/UITelemetry.rst
new file mode 100644
index 000000000..1a9213359
--- /dev/null
+++ b/application/basilisk/docs/UITelemetry.rst
@@ -0,0 +1,142 @@
+.. _uitelemetry:
+
+=======================
+UITelemetry data format
+=======================
+
+UI Telemetry sends its data as a JSON blob. This document describes the different parts
+of the JSON blob.
+
+``toolbars``
+============
+
+This tracks the state of the user's UI customizations. It has the following properties:
+
+- ``sizemode`` - string indicating whether the window is in maximized, normal (restored) or
+  fullscreen mode;
+- ``bookmarksBarEnabled`` - boolean indicating whether the bookmarks bar is visible;
+- ``menuBarEnabled`` - boolean indicating whether the menu bar is visible (always false on OS X);
+- ``titleBarEnabled`` - boolean indicating whether the (real) titlebar is visible (rather than
+  having tabs in the titlebar);
+- ``defaultKept`` - list of strings identifying toolbar buttons and items that are still in their
+  default position. Only the IDs of builtin widgets are sent (ie not add-on widgets);
+- ``defaultMoved`` - list of strings identifying toolbar buttons and items that are no longer in
+  their default position, but have not been removed to the palette. Only the IDs of builtin widgets
+  are sent (ie not add-on widgets);
+- ``nondefaultAdded`` - list of strings identifying toolbar buttons and items that have been added
+  from the palette. Only the IDs of builtin widgets are sent (ie not add-on widgets);
+- ``defaultRemoved`` - list of strings identifying toolbar buttons and items that are in the
+  palette that are elsewhere by default. Only the IDs of builtin widgets are sent
+  (ie not add-on widgets);
+- ``addonToolbars`` - the number of non-default toolbars that are customizable. 1 by default
+  because it counts the add-on bar shim;
+- ``visibleTabs`` - array of the number of visible tabs per window;
+- ``hiddenTabs`` - array of the number of hidden tabs per window (ie tabs in panorama groups which
+  are not the current group);
+- ``countableEvents`` - please refer to the next section.
+- ``durations`` - an object mapping descriptions to duration records, which records the amount of
+  time a user spent doing something. Currently only has one property:
+
+  - ``customization`` - how long a user spent customizing the browser. This is an array of
+    objects, where each object has a ``duration`` property indicating the time in milliseconds,
+    and a ``bucket`` property indicating a bucket in which the duration info falls.
+
+
+.. _UITelemetry_countableEvents:
+
+``countableEvents``
+===================
+
+Countable events are stored under the ``toolbars`` section. They count the number of times certain
+events happen. No timing or other correlating information is stored - purely the number of times
+things happen.
+
+``countableEvents`` contains a list of buckets as its properties. A bucket represents the state the browser was in when these events occurred, such as currently running an interactive tour. There are 3 types of buckets:
+
+- ``__DEFAULT__`` - No bucket, for times when the browser is not in any special state.
+- ``bucket_<NAME>`` - Normal buckets, for when the browser is in a special state. The ``<NAME>`` in the bucket ID is the name associated with the bucket and may be further broken down into parts by the ``|`` character.
+- ``bucket_<NAME>|<INTERVAL>`` - Expiring buckets, which are similar to a countdown timer. The ``<INTERVAL>`` in the bucket ID describes the time interval the recorded event happened in. The intervals are ``1m`` (one minute), ``3m`` (three minutes), ``10m`` (ten minutes), and ``1h`` (one hour). After one hour, the ``__DEFAULT__`` bucket is automatically used again.
+
+Each bucket is an object with the following properties:
+
+- ``click-builtin-item`` is an object tracking clicks on builtin customizable toolbar items, keyed
+  off the item IDs, with an object for each item with keys ``left``, ``middle`` and ``right`` each
+  storing a number indicating how often the respective type of click has happened.
+- ``click-menu-button`` is the same, except the item ID is always 'button'.
+- ``click-bookmarks-bar`` is the same, with the item IDs being replaced by either ``container`` for
+  clicks on bookmark or livemark folders, and ``item`` for individual bookmarks.
+- ``click-menubar`` is similar, with the item IDs being replaced by one of ``menu``, ``menuitem``
+  or ``other``, depending on the kind of item clicked. Note that this is not tracked on OS X, where
+  we can't listen for these events because of the global menubar.
+- ``click-bookmarks-menu-button`` is also similar, with the item IDs being replaced by:
+
+  - ``menu`` for clicks on the 'menu' part of the item;
+  - ``add`` for clicks that add a bookmark;
+  - ``edit`` for clicks that open the panel to edit an existing bookmark;
+  - ``in-panel`` for clicks when the button is in the menu panel, and clicking it does none of the
+     above;
+- ``customize`` tracks different types of customization events without the ``left``, ``middle`` and
+  ``right`` distinctions. The different events are the following, with each storing a count of the
+  number of times they occurred:
+
+  - ``start`` counts the number of times the user starts customizing;
+  - ``add`` counts the number of times an item is added somewhere from the palette;
+  - ``move`` counts the number of times an item is moved somewhere else (but not to the palette);
+  - ``remove`` counts the number of times an item is removed to the palette;
+  - ``reset`` counts the number of times the 'restore defaults' button is used;
+- ``search`` is an object tracking searches of various types, keyed off the search
+    location, storing a number indicating how often the respective type of search
+    has happened.
+
+  - There are also two special keys that mean slightly different things.
+
+    - ``urlbar-keyword`` records searches that would have been an invalid-protocol
+      error, but are now keyword searches.  They are also counted in the ``urlbar``
+      keyword (along with all the other urlbar searches).
+    - ``selection`` searches records selections of search suggestions.  They include
+      the source, the index of the selection, and the kind of selection (mouse or
+      enter key).  Selection searches are also counted in their sources.
+
+
+
+``UITour``
+==========
+
+The UITour API provides ways for pages on trusted domains to safely interact with the browser UI and request it to perform actions such as opening menus and showing highlights over the browser chrome - for the purposes of interactive tours. We track some usage of this API via the ``UITour`` object in the UI Telemetry output.
+
+Each page is able to register itself with an identifier, a ``Page ID``. A list of Page IDs that have been seen over the last 8 weeks is available via ``seenPageIDs``.
+
+Page IDs are also used to identify buckets for :ref:`UITelemetry_countableEvents`, in the following circumstances:
+
+- The current tab is a tour page. This will be a normal bucket with the name ``UITour|<PAGEID>``, where ``<PAGEID>`` is the page's registered ID. This will result in bucket IDs such as ``bucket_UITour|australis-tour``.
+- A tour tab is open but another tab is active. This will be an expiring bucket with the name ``UITour|<PAGEID>|inactive``. This will result in bucket IDs such as ``bucket_UITour|australis-tour|inactive|1m``.
+- A tour tab has recently been open but has been closed. This will be an expiring bucket with the name ``UITour|<PAGEID>|closed``. This will result in bucket IDs such as ``bucket_UITour|australis-tour|closed|10m``.
+
+
+
+``contextmenu``
+===============
+
+We track context menu interactions to figure out which ones are most often used and/or how
+effective they are. In the ``contextmenu`` object, we first store things per-bucket. Next, we
+divide the following different context menu situations:
+
+- ``selection`` if there is content on the page that's selected on which the user clicks;
+- ``link`` if the user opened the context menu for a link
+- ``image-link`` if the user opened the context menu on an image or canvas that's a link;
+- ``image`` if the user opened the context menu on an image (that isn't a link);
+- ``canvas`` if the user opened the context menu on a canvas (that isn't a link);
+- ``media`` if the user opened the context menu on an HTML video or audio element;
+- ``input`` if the user opened the context menu on a text input element;
+- ``other`` for all other openings of the content menu;
+
+Each of these objects (if they exist) then gets a "withcustom" and/or a "withoutcustom" property
+for context menus opened with custom page-created items and without them, and each of those
+properties holds an object with IDs corresponding to a count of how often an item with that ID was
+activated in the context menu. Only builtin context menu items are tracked, and besides those items
+there are four special items which get counts:
+
+- ``close-without-interaction`` is incremented when the user closes the context menu without interacting with it;
+- ``custom-page-item`` is incremented when the user clicks an item that was created by the page;
+- ``unknown`` is incremented when an item without an ID was clicked;
+- ``other-item`` is incremented when an add-on-provided menuitem is clicked.
diff --git a/application/basilisk/docs/index.rst b/application/basilisk/docs/index.rst
new file mode 100644
index 000000000..bfdd78e04
--- /dev/null
+++ b/application/basilisk/docs/index.rst
@@ -0,0 +1,12 @@
+=======
+Firefox
+=======
+
+This is the nascent documentation of the Firefox front-end code.
+
+.. toctree::
+   :maxdepth: 1
+
+   DirectoryLinksProvider
+   UITelemetry
+   BrowserUsageTelemetry