# 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
[[email protected]](https://groups.google.com/a/chromium.org/forum#!forum/services-dev)
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:
``` cpp
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:
``` cpp
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
[[email protected]](https://groups.google.com/a/chromium.org/g/services-dev)
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](/docs/servicification.md).
## 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](https://docs.google.com/document/d/15I7sQyQo6zsqXVNAlVd520tdGaS8FCicZHrN0yRu-oU)
- [Servicification Homepage](https://www.chromium.org/servicification/)
## Additional Support
You can always post to
[[email protected]](https://groups.google.com/a/chromium.org/g/services-dev)
with questions or concerns about anything related to service development.
Codebase Browser
chromium