Web App Origin Association Design

Web App Origin Association Design

This Document is Public

Authors: [email protected], [email protected] 

Contributors/Reviewers: [email protected] 

Last Updated: March 2021

Table of Contents

Main Design Document

Overview

Folder Structure

Mojom Definitions

Web App Origin Association Parser Implementation

WebAppOriginAssociationParserService

WebAppOriginAssociationManager

WebAppOriginAssociationFetcher

When To Fetch Association Files

On PWA Installation

On Manifest Update

On DevTools

Main Design Document

PWA as URL Handlers

Overview

Following the suggestion from Add parser for web app origin association files (Id02648f1) · Gerrit Code Review (googlesource.com), this design document explains briefly the plan of implementing web app origin association parsing in a utility process and other association related work.

Utility process is a sandboxed, low-privilege, short-lived process that is used to do a specific task. Existing services that leverage utility processes can be found in chrome/utility/services.h.

Folder Structure

Add a new folder components/webapps/web_app_origin_association for new files. This is where the main implementation lives.

components/webapps/services/web_app_origin_association

|--public

|     |--mojom

| |--BUILD.gn

|            |--web_app_origin_association_parser.mojom

|

|--BUILD.gn

|--DEPS

|--web_app_origin_association_parser_impl.h

|--web_app_origin_association_parser_impl.cc

|--web_app_origin_association_fetcher.h

|--web_app_origin_association_fetcher.cc

|--web_app_origin_association_parser_service.h

|--web_app_origin_association_parser_service.cc

 

chrome/browser/web_applications/components

|--web_app_origin_association_manager.h

|--web_app_origin_association_manager.cc

Mojom Definitions

Set up utility process to parse web app origin association files (I04cec826) · Gerrit Code Review (googlesource.com)

components/webapps/services/web_app_origin_association/public/mojom/web_app_origin_association_parser.mojom

module web_app.mojom;

 

// The web app origin association structure is an internal representation of the

// web app origin association file described in the "PWAs as URL Handlers"

// explainer: https://github.com/WICG/pwa-url-handler/blob/master/explainer.md

struct WebAppOriginAssociation {

  array<AssociatedWebApp> apps;

};

 

struct AssociatedWebApp {

  url.mojom.Url manifest_url;

  array<mojo_base.mojom.String16> paths;

  array<mojo_base.mojom.String16> exclude_paths;

};

 

interface WebAppOriginAssociationParser {

  ParseWebAppOriginAssociation(string file_content) => (WebAppOriginAssociation association);

};

 

Web App Origin Association Parser Implementation

Set up utility process to parse web app origin association files (I04cec826) · Gerrit Code Review (googlesource.com)

We parse the file content into WebAppOriginAssociation here in the utility process, if possible, and return the data structure to the browser process.

namespace webapps {

 

class WebAppOriginAssociationParserImpl : public mojom::WebAppOriginAssociationParser {

 public:

  // web_app_origin_association::mojom::WebAppOriginAssociationParser:

  ParseWebAppOriginAssociation(const std::string& file_content, ParseWebAppOriginAssociationsCallback callback);

 

};

}

WebAppOriginAssociationParserService

Set up utility process to parse web app origin association files (I04cec826) · Gerrit Code Review (googlesource.com)

Defines a function to launch the parser utility process.

namespace webapps {

 

mojo::Remote<mojom::WebAppOriginAssociationParser> LaunchWebAppOriginAssociationParser() {

   return content::ServiceProcessHost::Launch<mojom:: WebAppOriginAssociationParser >(

      content::ServiceProcessHost::Options()

          .WithDisplayName(

               IDS_WEB_APP_ORIGIN_ASSOCIATION_PARSE_DISPLAY_NAME)

          .Pass());

}

 

}

WebAppOriginAssociationManager

Add Web App Origin Association Manager to fetch, parse, and validate associations (I43d26560) · Gerrit Code Review (googlesource.com)

This class manages Web App Origin Association related work. It creates a Task for each batch of url handlers to call WebAppOriginAssociationFetcher to make network requests for association files, and feeds the file content into WebAppOriginAssociationParser. Once the association files are parsed, it validates the associations. It handles starting a mojo remote connection to the utility process and communicating with it, as well as task management to make sure batches of url handlers are handled in order.

This class also enforces limits on the number of url_handler entries per web app manifest (10), and limits on the lengths of each path and each exclude_path (2000 characters).

// web_app_origin_association_manager.cc

namespace web_app {

 

WebAppOriginAssociationManager::WebAppOriginAssociationManager() = default;

 

WebAppOriginAssociationManager::~WebAppOriginAssociationManager() = default;

 

const mojo::Remote<web_app::mojom::WebAppOriginAssociationParser>&

WebAppOriginAssociationManager::GetParser() {

  if (!parser_ || !parser_.is_bound()) {

    mojo::Remote<web_app::mojom::WebAppOriginAssociationParser> parser(

        LaunchWebAppOriginAssociationParser());

 

    parser_ = std::move(parser);

    parser_.reset_on_disconnect();

  }

 

  return parser_;

}

 

}

WebAppOriginAssociationFetcher

Add a fetcher for web app origin association files (Iba5dd6ec) · Gerrit Code Review (googlesource.com)

This class makes network requests for Web App Origin Association files in the browser process. It will use net libraries such as network::SimpleURLLoader to do so.

When To Fetch Association Files

There are several scenarios where we would need to fetch the web app origin association files and validate the information.

  1. When we install a PWA, so that we can store the associated app info in browser prefs.

  2. When we update a PWA (i.e. manifest is updated), so that we can update the relevant info in browser prefs.

  3. When a user opens the Application pane (or some other appropriate tool) in DevTools against a PWA page, we would want to fetch, parse, and validate the associated app information and display it to the user.

On PWA Installation

Get web app origin associations at app install (If59356fc) · Gerrit Code Review (googlesource.com)

Web app origin association info should be fetched post-installation, since it won’t be used until after app installation. To minimize the impact on web app installation user experience, we will start fetching and processing web app origin association files after app installation is finalized, as part of an OsInstallHook. Origin association fetching is done asynchronously to ensure the next steps of installation are not blocked.

We will check the url handler information and if necessary, launch a utility process to fetch the appropriate association files and validate the information. The validated info will be persisted to local state browser preferences after.

On Manifest Update

Update URL handlers at manifest update (Iba427da0) · Gerrit Code Review (googlesource.com)

Currently, manifest updates are throttled to once a day or longer. When we navigate to an installed PWA page, we will check if an update should happen. If so, a manifest update task is created to fetch the manifest and check the new content against what’s been installed. If updateable changes are detected, we will update the app after all app windows are closed. The call stack: 

ManifestUpdateTask::IsUpdateNeededForManifest

ManifestUpdateTask::OnDidGetInstallableData

InstallableManager::GetData

ManifestUpdateTask::DidFinishLoad

ManifestUpdateManager::MaybeUpdate

WebAppTabHelper::DidFinishNavigation

When checking if manifest update is needed, we will check if url handlers have changed, and schedule an update if they have. If a manifest update isn’t needed, we will check if url handlers exist. If so, associations need to be fetched and validated.

Once we have the updated associations, we need to update browser preferences accordingly. If a url handler changed (i.e. paths or exclude_paths changed), needs explicit user permission again to be enabled. Any url handlers that don’t exist anymore will be removed from prefs. If a url handler already exists in prefs, we will keep the user permission unchanged.

Since associations are updated as part of the manifest update, the update frequency is once a day as well.

On DevTools

The Application Panel currently has support for PWAs through CDP methods under the Page domain: Page.getAppManifest, Page.getInstallabilityErrors, Page.getManifestIcons. A new CDP method can be added to fetch web app origin association files.

Leave a Comment

Your email address will not be published.