diff --git a/dom/docs/ipc/process_model.rst b/dom/docs/ipc/process_model.rst index 9b066dce4ba9..d94b85a10d6c 100644 --- a/dom/docs/ipc/process_model.rst +++ b/dom/docs/ipc/process_model.rst @@ -3,7 +3,7 @@ Process Model The complete set of recognized process types is defined in `GeckoProcessTypes `_. -For more details on how process types are added and managed by IPC, see the process creation documentation. (FIXME: being added in ``_) +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 VR Process Data Decoder (RDD) Process Network (Socket) Process + Utility Process Remote Sandbox Broker Process Fork Server @@ -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 `_ +:metabug: `Bug 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`. diff --git a/ipc/docs/index.rst b/ipc/docs/index.rst index 8b8d870a968b..3678f4b2fc6a 100644 --- a/ipc/docs/index.rst +++ b/ipc/docs/index.rst @@ -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. diff --git a/ipc/docs/utility_process.rst b/ipc/docs/utility_process.rst new file mode 100644 index 000000000000..d83a62db3a21 --- /dev/null +++ b/ipc/docs/utility_process.rst @@ -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 `_: + + - 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)`` + - 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 `_ + - Try and make sure you at least add some ``gtest`` coverage of your new actor, for example like in `existing gtest `_ + - Also ensure actual sandbox testing within + + + ``SandboxTest`` to start your new process, ``_ + + ``SandboxTestingChildTests`` to define the test ``_ + + ``SandboxTestingChild`` to run your test ``_