Sylvestre Ledru
2f607401b6
The Sphinx configuration already supports both RST and Markdown via
myst-parser. Converting these docs to Markdown for consistency with
the rest of the tree.
Done with rst-to-myst plus manual fixups: replace eval-rst tables that
relied on RST substitutions with Markdown tables using inline HTML for
strikethrough/line-break, fix :ref: cross-references to use explicit
slug labels, and update the cross-doc link in index.md to use {doc}.
docs/config.yml warning patterns updated from .rst to .md.
Differential Revision: https://phabricator.services.mozilla.com/D304196
3.5 KiB
Utility Process
:::{warning} Please reach out to #ipc on https://chat.mozilla.org/ if you intent to add a new utility. :::
The utility process is used to provide a simple way to implement IPC actor with some more specific sandboxing properties, in case where you don't need or want to deal with the extra complexity of adding a whole new process type but you just want to apply different sandboxing policies. To implement such an actor, you will have to follow a few steps like for implementing the trivial example visible in EmptyUtil:
-
Define a new IPC actor, e.g.,
PEmptyUtilthat allows to get some string viaGetSomeString()from the child to the parent -
In the
PUtilityProcessdefinition, expose a new child-level method, e.g.,StartEmptyUtilService(Endpoint<PEmptyUtilChild>) -
Implement
EmptyUtilChildandEmptyUtilParentclasses both deriving from theirPEmptyUtilXX. If you want or need to run things from a different thread, you can have a look atUtilityProcessGenericActor -
Make sure both are refcounted
-
Expose your new service on
UtilityProcessManagerwith a method performing the heavy lifting of starting your process, you can take inspiration fromStartEmptyUtil()in the sample. -
Ideally, this starting method should rely on {searchfox}
StartUtility() <mozilla-central/rev/f9f9b422f685244dcd3f6826b70d34a496ce5853:ipc/glue/UtilityProcessManager.cpp#238-318,347> -
To use
StartUtility()mentioned above, please ensure that you provide ansresult BindToUtilityProcess(RefPtr<UtilityProcessParent> aUtilityParent). Usually, it should be in charge of creating a set of endpoints and performingBind()to setup the IPC. You can see some example for {searchfox}UtilityMediaService <mozilla-central/rev/0fe32133f12ed0f20d5fde8fe970157f04817982:ipc/glue/UtilityMediaServiceChild.cpp#60-92> -
For proper user-facing exposition in
about:processesyou will have to also provide an actor name via a methodUtilityActorName GetActorName() { return UtilityActorName::EmptyUtil; }- Add member within {searchfox}
enum WebIDLUtilityActorName in <mozilla-central/rev/f9f9b422f685244dcd3f6826b70d34a496ce5853:dom/chrome-webidl/ChromeUtils.webidl#852-866>
- Add member within {searchfox}
-
Handle reception of
StartEmptyUtilServiceon the child side ofUtilityProcesswithinRecvStartEmptyUtilService() -
In
UtilityProcessChild::ActorDestroy, release any resources that you stored a reference to inRecvStartEmptyUtilService(). This will probably include a reference to theEmptyUtilChild. -
The specific sandboxing requirements can be implemented by tracking
SandboxingKind, and it starts within {searchfox}UtilityProcessSandboxing header <ipc/glue/UtilityProcessSandboxing.h> -
Try and make sure you at least add some
gtestcoverage of your new actor, for example like in {searchfox}existing gtest <ipc/glue/test/gtest/TestUtilityProcess.cpp> -
Also ensure actual sandbox testing within
SandboxTestto start your new process, {searchfox}security/sandbox/common/test/SandboxTest.cppSandboxTestingChildTeststo define the test {searchfox}security/sandbox/common/test/SandboxTestingChildTests.hSandboxTestingChildto run your test {searchfox}security/sandbox/common/test/SandboxTestingChild.cpp
-
Please also consider having a look at {ref}
Process Bookkeeping <process-bookkeeping>for anything you may want to ensure is supported by your new process, like e.g. profiler, crash reporting, etc.