Bug 1751229 - Add Utility into Process Model doc r=nika

Differential Revision: https://phabricator.services.mozilla.com/D136578
This commit is contained in:
Alexandre Lissy 2022-01-25 23:47:13 +00:00
parent 7db4048bdb
commit bc59ee68ea
3 changed files with 36 additions and 1 deletions

View File

@ -3,7 +3,7 @@ Process Model
The complete set of recognized process types is defined in `GeckoProcessTypes <https://searchfox.org/mozilla-central/source/xpcom/geckoprocesstypes_generator/geckoprocesstypes/__init__.py>`_.
For more details on how process types are added and managed by IPC, see the process creation documentation. (FIXME: being added in `<https://phabricator.services.mozilla.com/D121871>`_)
For more details on how process types are added and managed by IPC, see the process creation documentation :ref:`Gecko Processes`.
Diagram
-------
@ -62,6 +62,7 @@ Diagram
<TR><TD BORDER="1">VR Process</TD></TR>
<TR><TD BORDER="1">Data Decoder (RDD) Process</TD></TR>
<TR><TD BORDER="1">Network (Socket) Process</TD></TR>
<TR><TD BORDER="1">Utility Process</TD></TR>
<TR><TD BORDER="1">Remote Sandbox Broker Process</TD></TR>
<TR><TD BORDER="1">Fork Server</TD></TR>
</TABLE>
@ -304,3 +305,12 @@ IPDLUnitTest
:primary protocol: varies
This test-only process type is intended for use when writing IPDL unit tests. However, it is currently broken, due to these tests having never been run in CI. The type may be removed or re-used when these unit tests are fixed.
Utility Process
---------------
:primary protocol: `PUtilityProcess <https://searchfox.org/mozilla-central/source/ipc/glue/PUtilityProcess.ipdl>`_
:metabug: `Bug 1722051 <https://bugzilla.mozilla.org/show_bug.cgi?id=1722051>`_
:sandboxed?: yes, customizable
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. Details can be found in :ref:`Utility Process`.

View File

@ -8,6 +8,7 @@ These pages contain the documentation for Gecko's architecture for platform proc
ipdl
processes
utility_process
For inter-process communication involving Javascript, see `JSActors`_. They are a very limited case, used for communication between elements in the DOM, which may exist in separate processes. They only involve the main process and content processes -- no other processes run Javascript.

View File

@ -0,0 +1,24 @@
Utility Process
===============
.. warning::
As of january 2022, this process is under heavy work, and many things can
evolve. Documentation might not always be as accurate as it should be.
Please reach to #ipc 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 <https://phabricator.services.mozilla.com/D126402>`_:
- Define a new IPC actor, e.g., ``PEmptyUtil`` that allows to get some string via ``GetSomeString()`` from the child to the parent
- In the ``PUtilityProcess`` definition, expose a new child-level method, e.g., ``StartEmptyUtilService(Endpoint<PEmptyUtilChild>)``
- Implement ``EmptyUtilChild`` and ``EmptyUtilParent`` classes both deriving from their ``PEmptyUtilXX``. If you want or need to run things from a different thread, you can have a look at ``UtilityProcessGenericActor``
- Make sure both are refcounted
- Expose your new service on ``UtilityProcessManager`` with a method performing the heavy lifting of starting your process, you can take inspiration from ``StartEmptyUtil()`` there.
- Handle reception of ``StartEmptyUtilService`` on the child side of ``UtilityProcess`` within ``RecvStartEmptyUtilService()``
- The specific sandboxing requirements can be implemented by tracking ``SandboxingKind``, and it starts within `UtilityProcessSandboxing header <https://searchfox.org/mozilla-central/source/ipc/glue/UtilityProcessSandboxing.h>`_
- Try and make sure you at least add some ``gtest`` coverage of your new actor, for example like in `existing gtest <https://searchfox.org/mozilla-central/source/ipc/glue/test/gtest/TestUtilityProcess.cpp>`_
- Also ensure actual sandbox testing within
+ ``SandboxTest`` to start your new process, `<https://searchfox.org/mozilla-central/source/security/sandbox/common/test/SandboxTest.cpp>`_
+ ``SandboxTestingChildTests`` to define the test `<https://searchfox.org/mozilla-central/source/security/sandbox/common/test/SandboxTestingChildTests.h>`_
+ ``SandboxTestingChild`` to run your test `<https://searchfox.org/mozilla-central/source/security/sandbox/common/test/SandboxTestingChild.cpp>`_