chrome service

Service Development Guidelines

[TOC]

Overview

The top-level //services directory contains the sources, public Mojo interface definitions, and public client libraries for a number of essential services, designated as Chrome Foundation Services. If you think of Chrome as a "portable OS," Chrome Foundation Services can be thought of as the core system services of that OS.

Each subdirectory here corresponds to a service that:

• generally focuses on a subset of functionality or features which are thematically or functionally related in a way that makes sense given the name of the service
• could logically run in an isolated process for security or performance isolation, depending on the constraints of the host OS

*** aside Note that there are other parts of the tree which aggregate slightly-less-than-foundational service definitions, such as services specific to the Chrome browser defined in //chrome/services or reusable services for Content or its embedders, defined in //components/services. The motivations, advice, and standards discussed in this document apply to all service definitions in the Chromium tree.

---

One of the main motivations for expressing Chromium as a collection of services is long-term maintainability and code health. Because service API boundaries are strictly limited to Mojo interfaces, state owned and managed by each service is strongly isolated from other components in the system.

Another key motivation is general modularity and reusability: in the past there have been a number of missed opportunities for potential new features or Chromium-based products due to the browser's generally monolothic and inflexible system design. With the services providing scaffolding for system components, it becomes progressively easier to build out newer use cases with e.g. a smaller resource footprint, or a different process model, or even a more granular binary distribution.

Service Standards

As outlined above, individual services are intended for graceful reusability across a broad variety of use cases. To enable this goal, we have rigorous standards on services' structure and public API design. Before doing significant work in //services (or other places where services are defined), please internalize these standards. All Chromium developers are responsible for upholding them!

Public Service APIs

In creating and maintaining a service's public API, please respect the following principles:

• The purpose of a service should be readily apparent.
• The supported client use cases of the service should be easy for a new consumer to understand.
• The service should use idioms and design patterns consistent with other services.
• From the service's public API documentation and tests, it should be feasible to develop a new implementation of the service which satisfies existing clients and doesn't require mimicking internal implementation details of the existing service.
• Perhaps most important of all, a service's public API should be designed with multiple hypothetical clients in mind, not focused on supporting only a single narrow use known at development time. Always be thinking about the future!

If you're working on a new service and have concerns or doubts about API design, please post to services-dev@chromium.org and ask for help. The list is generally quite responsive, and it's loaded with people who have done a lot of work on services.

Service API Design Tips

Using Interface Factories to Establish Context

One common pitfall when designing service APIs is to write something like:

interface GoatTeleporter {
  // Sets the client interface pipe for this teleporter. Must be called before
  // other interface methods.
  SetClient(GoatTeleporterClient client);

  TeleportGoat(string name);
};

interface GoatTeleporterClient {
  TeleporterReady();
};

The problem with this approach is that a client may easily fail to call SetClient before calling TeleportGoat. When such ordering requirements are necessary, the service can benefit clients by designing an API that is harder to fail at. For example:

interface GoatTeleporterFactory {
  GetGoatTeleporter(GoatTeleporter& request, GoatTeleporterClient client);
};

interface GoatTeleporter {
  TeleportGoat(string name);
};

Instead of exposing GoatTeleporter directly to other services, the service can expose GoatTeleporterFactory instead. Now it's impossible for a client to acquire a functioning GoatTeleporter pipe without also providing a corresponding client pipe to complement it.

Interface Naming

Just some basic tips for service and interface naming:

• Strive to give your service's main interface a name that directly conveys the general purpose of the service (e.g., NetworkService, StorageService) rather than a meaningless codename like Cromulator.

• Strive to avoid conceptual layering violations in naming and documentation -- e.g., avoid referencing Blink or Content concepts like "renderers" or "frame hosts".

• Use the names FooClient and FooObserver consistently in interfaces. If there is an expected 1:1 correspondence between a Foo and its client interface counterpart, that counterpart should most likely be called FooClient. If there is expected to be 1-to-many correspondence between a Foo and its counterpart clients, the client interface may be better named FooObserver.

Service Directory & Dependency Structure

Services typically follow a canonical directory structure:

//services/service_name/               # Private implementation
                        public/
                               mojom/  # Mojom interfaces
                               cpp/    # C++ client libraries (optional)
                               java/   # Java client libararies (optional, rare)
                               js/     # JS client libraries (optional, rare)

As a general rule, nothing below /public can depend on the private service implementation (i.e. things above /public). Enforcing this principle makes it much easier to keep the service's state well-isolated from the rest of the system.

Generally the language-specific client libraries are built against only the public mojom API of the service (and usually few other common dependencies like //base and //mojo).

Even in the private service implementation, services should not depend on very large components like Content, Chrome, or Blink.

*** aside NOTE: Exceptions to the above rule are made in rare cases where Blink or V8 is actually required as part of the service implementation. For example "data_decoder" uses Blink implementation to decode common image formats, and "proxy_resolver" uses V8 to execute proxy autoconfig scripts.

---

Service Documentation

• Every service should have a top-level README.md that explains the purpose and supported usage models of the service.

• Every public interface should be documented within its Mojom file at both the interface level and indivudal message level.

• Interface documentation should be complete enough to serve as test specifications. If the method returns information of a user's accounts, what should happen if the user is not signed in? If the method makes a request for an access token, what happens if a client makes a second method call before the first one has completed? If the method returns a nullable object, under which conditions will it be null?

• Avoid writing interface documentation which is unnecessarily prescriptive about implementation details. Keep in mind that these are interface definitions, not implementations thereof.

• Avoid writing documentation which is tailored to a specific client.

Service Testing

• Try to cover service implementation details with unit tests tied as closely as possible to the private implementation object or method being tested, rather than exercising implementation details through public API surface.

• For integration tests, try to have tests cover as much of the public API surface as possible while mocking out as little of the underlying service as possible.

• Treat the public API tests as "conformance tests" which clearly demonstrate what expectations and guarantees are supposed to be upheld by any implementation of the service's APIs.

Adding a New Service

Please start a thread on services-dev@chromium.org if you want to propose the introduction of a new service.

If you are servicifying an existing Chromium feature, please check out Servicifying Chromium Features.

Other Docs

Here are some other external documents that aren't quite fully captured by any documents in the Chromium tree. Beware of obsolete information:

• High-level Design Doc
• Servicification Homepage

Additional Support

You can always post to services-dev@chromium.org with questions or concerns about anything related to service development.

---

Servicifying Chromium Features

Contents

• Overview
• Setting Up The Service
• Where in the Tree?
• Launching Service Processes
• Hooking Up the Service Implementation
• Incremental Servicification
• Platform-Specific Issues: Android
• Platform-Specific Issues: iOS
• Client-Specific Issues
• Strategies for Challenges to Decoupling from //content
• Coupling to UI
• Shutdown of Singletons
• Additional Support

Overview

Much to the dismay of Chromium developers, practicing linguists, and keyboard operators everywhere, the term servicificificification [sic] has been egregiously smuggled into the Chromium parlance.

Lots of Chromium code is contained in reasonably well-isolated component libraries with some occasionally fuzzy boundaries and often a surprising number of gnarly runtime interdependencies among a complex graph of components. Y implements one of Z‘s delegate interfaces, while X implements one of Y’s delegate interfaces, and now it's possible for some ridiculous bug to creep in where W calls into Z at the wrong time and causes a crash in X. Yikes.

Servicification embodies the ongoing process of servicifying Chromium features and subsystems, or refactoring these collections of library code into services with well-defined public API boundaries and very strong runtime isolation via Mojo interfaces.

The primary goals are to improve maintainability and extensibility of the system over time, while also allowing for more flexible runtime configuration. For example, with the Network Service in place we can now run the entire network stack either inside or outside of the browser process with the flip of a command-line switch. Client code using the Network Service stays the same, independent of that switch.

This document focuses on helpful guidelines and patterns for servicifying parts of Chromium.

Also see general Mojo & Services documentation for other introductory guides, API references, etc.

Setting Up The Service

This section briefly covers early decisions and implementation concerns when introducing a new service.

Where in the Tree?

Based on the service development guidelines, any service which could be reasonably justified as a core system service in a hypothetical, well-designed operating system may belong in the top-level //services directory. If that sounds super hand-wavy and unclear, that‘s because it is! There isn’t really a great universal policy here, so when in doubt, contact your favorite local services-dev@chromium.org mailing list and start a friendly discussion.

Other common places where developers place services, and why:

• //components/services for services which haven't yet made the cut for //services but which are either used by Content directly or by multiple Content embedders.
• //chrome/services for services which are used exclusively within Chrome and not shared with other Content embedders.
• //chromeos/services for services which are used on Chrome OS by more than just Chrome itself (for example, if the ash service must also connect to them for use in system UI).

Launching Service Processes

Content provides a simple ServiceProcessHost API to launch a new Service Process. The Mojo Remote corresponding to each process launch is effectively a lifetime control for the launched process.

You may choose to maintain only a single concurrent instance of your service at a time, similar to the Network or Storage services. In this case, typically you will have some browser code maintain a lazy Mojo Remote to the service process, and any clients of the service will have their connections brokered through this interface.

In other cases you may want to manage multiple independent service processes. The Data Decoder service, for example, allows for arbitrary browser code to launch a unique isolated instance to process a single decode operation or a batch of related operations (e.g. to decode a bunch of different objects from the same untrusted origin).

Insofar as the browser can use ServiceProcessLauncher however it likes, and the corresponding Mojo Remotes can be owned just like any other object, developers are free to manage their service instances however they like.

Hooking Up the Service Implementation

For out-of-process service launching, Content uses its “utility” process type.

For services known to content, this is accomplished by adding an appropriate factory function to //content/utility/services.cc

For other services known only to Chrome, we have a similar file at //chrome/utility/services.cc.

Once an appropriate service factory is registered for your main service interface in one of these places, ServiceProcessHost::Launch can be used to acquire a new isolated instance from within the browser process.

To run a service in-process, you can simply instantiate your service implementation (e.g. on a background thread) like you would any other object, and you can then bind a Mojo Remote which is connected to that instance.

This is useful if you want to avoid the overhead of extra processes in some scenarios, and it allows the detail of where and how the service runs to be fully hidden behind management of the main interface's Mojo Remote.

Incremental Servicification

For large Chromium features it is not feasible to convert an entire subsystem to a service all at once. As a result, it may be necessary for the subsystem to spend a considerable amount of time (weeks or months) split between the old implementation and your beautiful, sparkling new service implementation.

In creating your service, you likely have two goals:

• Making the service available to its consumers
• Making the service self-contained

Those two goals are not the same, and to some extent are at tension:

• To satisfy the first, you need to build out the API surface of the service to a sufficient degree for the anticipated use cases.

• To satisfy the second, you need to convert all clients of the code that you are servicifying to instead use the service, and then fold that code into the internal implementation of the service.

Whatever your goals, you will need to proceed incrementally if your project is at all non-trivial (as they basically all are given the nature of the effort). You should explicitly decide what your approach to incremental bringup and conversion will be. Here are some approaches that have been taken for various services:

• Build out your service depending directly on existing code, convert the clients of that code 1-by-1, and fold the existing code into the service implementation when complete (Identity Service).
• Build out the service with new code and make the existing code into a client library of the service. In that fashion, all consumers of the existing code get converted transparently (Preferences Service).
• Build out the new service piece-by-piece by picking a given bite-size piece of functionality and entirely servicifying that functionality (Device Service).

These all have tradeoffs:

• The first lets you incrementally validate your API and implementation, but leaves the service depending on external code for a long period of time.
• The second can create a self-contained service more quickly, but leaves all the existing clients in place as potential cleanup work.
• The third ensures that you're being honest as you go, but delays having the breadth of the service API up and going.

Which makes sense depends both on the nature of the existing code and on the priorities for doing the servicification. The first two enable making the service available for new use cases sooner at the cost of leaving legacy code in place longer, while the last is most suitable when you want to be very exacting about doing the servicification cleanly as you go.

Platform-Specific Issues: Android

As you servicify code running on Android, you might find that you need to port interfaces that are served in Java. Here is an example CL that gives a basic pattern to follow in doing this.

You also might need to register JNI in your service. That is simple to set up, as illustrated in this CL. (Note that that CL is doing more than just enabling the Device Service to register JNI; you should take the register_jni.cc file added there as your starting point to examine the pattern to follow).

Finally, it is possible that your feature will have coupling to UI process state (e.g., the Activity) via Android system APIs. To handle this challenging issue, see the section on Coupling to UI.

Platform-Specific Issues: iOS

WARNING: Some of this content is obsolete and needs to be updated. When in doubt, look approximately near the recommended bits of code and try to find relevant prior art.

Services are supported on iOS insofar as Mojo is supported. However, Chrome on iOS is strictly single-process, and all services thus must run in-process on iOS.

If you have a use case or need for services on iOS, contact blundell@chromium.org. For general information on the motivations and vision for supporting services on iOS, see the high-level servicification design doc. In particular, search for the mentions of iOS within the doc.

Client-Specific Issues

Mocking Interface Impls in JS

It is a common pattern in Blink's web tests to mock a remote Mojo interface in JS so that native Blink code requests interfaces from the test JS rather than whatever would normally service them in the browser process.

The current way to set up that sort of thing looks like this.

Feature Impls That Depend on Blink Headers

In the course of servicifying a feature that has Blink as a client, you might encounter cases where the feature implementation has dependencies on Blink public headers (e.g., defining POD structs that are used both by the client and by the feature implementation). These dependencies pose a challenge:

• Services should not depend on Blink, as this is a dependency inversion (Blink is a client of services).
• However, Blink is very careful about accepting dependencies from Chromium.

To meet this challenge, you have two options:

1. Move the code in question from C++ to mojom (e.g., if it is simple structs).
2. Move the code into the service's C++ client library, being very explicit about its usage by Blink. See this CL for a basic pattern to follow.

Frame-Scoped Connections

You must think carefully about the scoping of the connection being made from Blink. In particular, some feature requests are necessarily scoped to a frame in the context of Blink (e.g., geolocation, where permission to access the interface is origin-scoped). Servicifying these features is then challenging, as Blink has no frame-scoped connection to arbitrary services (by design, as arbitrary services have no knowledge of frames or even a notion of what a frame is).

After a long discussion, the policy that we have adopted for this challenge is the following:

CURRENT

• The renderer makes a request through its frame-scoped connection to the browser.
• The browser obtains the necessary permissions before directly servicing the request.

AFTER SERVICIFYING THE FEATURE IN QUESTION

• The renderer makes a request through its frame-scoped connection to the browser.
• The browser obtains the necessary permissions before forwarding the request on to the underlying service that hosts the feature.

Notably, from the renderer's POV essentially nothing changes here.

Strategies for Challenges to Decoupling from //content

Coupling to UI

Some feature implementations have hard constraints on coupling to UI on various platforms. An example is NFC on Android, which requires the Activity of the view in which the requesting client is hosted in order to access the NFC platform APIs. This coupling is at odds with the vision of servicification, which is to make the service physically isolatable. However, when it occurs, we need to accommodate it.

The high-level decision that we have reached is to scope the coupling to the feature and platform in question (rather than e.g. introducing a general-purpose FooServiceDelegate), in order to make it completely explicit what requires the coupling and to avoid the coupling creeping in scope.

The basic strategy to support this coupling while still servicifying the feature in question is to inject a mechanism of mapping from an opaque “context ID” to the required context. The embedder (e.g., //content) maintains this map, and the service makes use of it. The embedder also serves as an intermediary: it provides a connection that is appropriately context-scoped to clients. When clients request the feature in question, the embedder forwards the request on along with the appropriate context ID. The service impl can then map that context ID back to the needed context on-demand using the mapping functionality injected into the service impl.

To make this more concrete, see this CL.

Shutdown of Singletons

You might find that your feature includes singletons that are shut down as part of //content's shutdown process. As part of decoupling the feature implementation entirely from //content, the shutdown of these singletons must be either ported into your service or eliminated:

• In general, as Chromium is moving away from graceful shutdown, the first question to analyze is: Do the singletons actually need to be shut down at all?
• If you need to preserve shutdown of the singleton, the naive approach is to move the shutdown of the singleton to the destructor of your service
• However, you should carefully examine when your service is destroyed compared to when the previous code was executing, and ensure that any differences introduced do not impact correctness.

See this thread for more discussion of this issue.

Additional Support

If this document was not helpful in some way, please post a message to your friendly local chromium-mojo@chromium.org or services-dev@chromium.org mailing list.

Powered by Gitiles| Privacy

---

Mandoline Project Summary

Ben Goodger (1/29/2016)

What is Mandoline?

Mandoline was an experiment a group of us conducted in 2015 to explore an alternative to the Content layer in Chrome, using Mojo for IPC and the Mojo Shell as the process launcher. The origin of the experiment was a feeling that the Chrome codebase had not scaled to support the myriad features and platforms it had to support. The intent was to stand up a functional shell alongside Chrome using this new approach to identify some ways in which a browser constructed today would be different. By the end of 2015 we had wound down the experiment and begun to develop a plan for implementing the findings in Chrome.

How is Mandoline different?

Expressivity

Mandoline uses Mojo for communication between services. Mojo provides a collection of tools for developing services. The base layer offers APIs for creating message pipes that allow two endpoints to communicate. The endpoints may be in the same or different processes. Endpoints may be passed over message pipes to other endpoints. On top of this system is an expressive binding layer that provides an IDL (“mojom”) that allows service APIs to be defined in a human readable manner and language bindings that translate the mojom into idiomatic C++, JS, etc. Mojom interfaces are bound to interface pointers on the client side and interface implementations on the server side. At the mojom layer, interface implementations and requests for implementations can be passed via mojom method calls, which translates to passing Mojo message pipe endpoints. If a Mojo message pipe is considered a conceptual “capability”, this is how delegation is implemented. This facility is used extensively in Mandoline services.

Modularity

The Mandoline design is component based, built of a number of different applications and services in a “system services” model resembling that of a modern OS with the Mojo Shell acting as the microkernel. The main idea is that there is a layer cake of services starting with those providing low level networking, file system, device and UI/rendering with higher level services layered on top. Service APIs are asynchronous, expressed in mojom. Services are run either in dedicated processes or in service threads in unified processes.

In the Mojo Shell, application components are referenced by URL. Components are physically packaged as DLLs with .mojo extensions. Components living at a specific location on the file system can be loaded with special “mojo://” URLs. The long term intent was to develop a single unified component manager that would encompass the baseline application, experimental features, market/platform/user-specific features as well as third party applications (e.g. extensions). The idea is that some components are delivered and updated with the core Chrome install, and some others are lazily loaded on demand as the product is used, and others are only installed upon user demand.

Coherency

The service and component based model supported by Mojo and the Mojo Shell provides some opportunities to improve component coherency. By this I mean all of the code required to implement a service can live with that service and be run in that service’s process. Contrast to Chrome/Content, where parts of the web platform are scattered outside of Blink across content/renderer, content/browser, and Chrome. Coherency is achieved by designing a suite of more powerful lower level system services.

In Mandoline, we designed (or at least stubbed) new system services for UI/rendering, network, file system access, a navigable frame tree (“web view”), as well as a variety of others. These services reuse low level library code from Chrome (e.g. CC, net, blink, etc) providing well considered APIs, avoiding the spaghetti of higher level modules.

Security

With Mandoline’s component-based architecture, further optimization per principle of least privilege is possible. Compared to Chrome, most application code can be run in the tightest possible sandbox. A “pure” Mojo component interacts with its environment exclusively via capabilities delegated to it. For example file system access is brokered via a privileged file system service which can read the native file system, allowing components consuming the file system service to be aggressively sandboxed. Furthermore, the Mojo Shell API makes it possible to restrict both the set of applications a component can connect to, and the set of capabilities a component can acquire from each application. (Note that while this restriction applies to capabilities obtained via the core Shell APIs, it does not extend to capabilities acquired from services obtained from those APIs. As such it is important to consider the total tree of capabilities granted by granting a capability via the Shell).

Flexibility

A big theme for Mandoline was flexibility. With a system comprised of well defined low level services, it becomes possible to build a variety of high level applications, including the web platform itself, the browser UI, and others. For example, a combination of APIs from the display, network, navigation and shell APIs supports the concept of an abstract application renderer that can consume content loaded off the web and displayed in a viewport. This was used to implement Blink and PDF without significant special casing for either, and would allow for other renderers to be explored in the future.

Furthermore, such a system would give the team the ability to experiment with new ideas across the stack without bloating the baseline executable as components can be ephemerally loaded & run as need arises.

What did we build?

Over the course of the Mandoline effort we built many of the system services described above, and a shell that could traverse a 20 page telemetry cycler, suitable for gathering performance stats. We were able to mostly stabilize this to the point we could trust the performance data it would generate. We found the performance numbers promising but inconclusive. While the numbers posted were better than those achieved in a production content_shell, there were some configuration differences, and the architecture of our system (e.g. site isolated by default, so more cores in use) may have accounted for the improvements.

We did make various improvements to Mojo & its bindings and the set of base APIs and services, and over the course of this effort Mojo became a lot more pleasant to use. Similarly we felt like several of the objectives stated in the previous section were more than adequately achieved. The system design felt very clean and rational.

What next?

It’s one thing to produce a shell, it’s another thing to build a browser. At this point the team is looking at ways to migrate Chrome to this model. We believe it’s possible to do this incrementally, in a few stages:

1. Mass migration of Chrome to Mojo for IPC.
   This has the effect of exposing the whole Chrome team to Mojo & shaking out any last issues that may be present with the Mojo infrastructure. The current Mojo-in-Chrome team is tasked with this project. See announcement.
   
   

Gradual refactoring of code in src/content into the array of system services we described in Mandoline.
In the limit, this amounts to the gradual teardown of src/content, moving things out into separate services, e.g. components/mus for the display service, src/net for the network service and so on. What will probably remain is the tab abstraction/navigable frame tree. Most of this work should be possible behind various runtime flags. This document describes this effort and enumerates some specific sub-projects. This is a multi-year effort spanning many teams. The Mandoline team will be reformulated into a Chrome system architecture team that will provide central organization and some staffing for these tasks.