ipc/docs/utility_process.rst

   1 Utility Process
   2 ===============
   3
   4 .. warning::
   5   As of january 2022, this process is under heavy work, and many things can
   6   evolve. Documentation might not always be as accurate as it should be.
   7   Please reach to #ipc if you intent to add a new utility.
   8
   9 The utility process is used to provide a simple way to implement IPC actor with
  10 some more specific sandboxing properties, in case where you don't need or want
  11 to deal with the extra complexity of adding a whole new process type but you
  12 just want to apply different sandboxing policies.
  13 To implement such an actor, you will have to follow a few steps like for
  14 implementing the trivial example visible in `EmptyUtil
  15 <https://phabricator.services.mozilla.com/D126402>`_:
  16
  17   - Define a new IPC actor, e.g., ``PEmptyUtil`` that allows to get some string
  18     via ``GetSomeString()`` from the child to the parent
  19
  20   - In the ``PUtilityProcess`` definition, expose a new child-level method,
  21     e.g., ``StartEmptyUtilService(Endpoint<PEmptyUtilChild>)``
  22
  23   - Implement ``EmptyUtilChild`` and ``EmptyUtilParent`` classes both deriving
  24     from their ``PEmptyUtilXX``. If you want or need to run things from a
  25     different thread, you can have a look at ``UtilityProcessGenericActor``
  26
  27   - Make sure both are refcounted
  28
  29   - Expose your new service on ``UtilityProcessManager`` with a method
  30     performing the heavy lifting of starting your process, you can take
  31     inspiration from ``StartEmptyUtil()`` in the sample.
  32
  33   - Ideally, this starting method should rely on `StartUtility() <https://searchfox.org/mozilla-central/rev/fb511723f821ceabeea23b123f1c50c9e93bde9d/ipc/glue/UtilityProcessManager.cpp#210-258,266>`_
  34
  35   - To use ``StartUtility()`` mentioned above, please ensure that you provide
  36     a ``nsresult BindToUtilityProcess(RefPtr<UtilityProcessParent>
  37     aUtilityParent)``. Usually, it should be in charge of creating a set of
  38     endpoints and performing ``Bind()`` to setup the IPC. You can see some example for `Utility AudioDecoder <https://searchfox.org/mozilla-central/rev/4b3039b48c3cb67774270ebcc2a7d8624d888092/ipc/glue/UtilityAudioDecoderChild.h#31-51>`_
  39
  40   - For proper user-facing exposition in ``about:processes`` you will have to also provide an actor
  41     name via a method ``UtilityActorName GetActorName() { return UtilityActorName::EmptyUtil; }``
  42
  43     + Add member within `enum WebIDLUtilityActorName in <https://searchfox.org/mozilla-central/rev/fb511723f821ceabeea23b123f1c50c9e93bde9d/dom/chrome-webidl/ChromeUtils.webidl#686-689>`_
  44
  45   - Handle reception of ``StartEmptyUtilService`` on the child side of
  46     ``UtilityProcess`` within ``RecvStartEmptyUtilService()``
  47
  48   - In ``UtilityProcessChild::ActorDestroy``, release any resources that
  49     you stored a reference to in ``RecvStartEmptyUtilService()``.  This
  50     will probably include a reference to the ``EmptyUtilChild``.
  51
  52   - The specific sandboxing requirements can be implemented by tracking
  53     ``SandboxingKind``, and it starts within `UtilityProcessSandboxing header
  54     <https://searchfox.org/mozilla-central/source/ipc/glue/UtilityProcessSandboxing.h>`_
  55
  56   - Try and make sure you at least add some ``gtest`` coverage of your new
  57     actor, for example like in `existing gtest
  58     <https://searchfox.org/mozilla-central/source/ipc/glue/test/gtest/TestUtilityProcess.cpp>`_
  59
  60   - Also ensure actual sandbox testing within
  61
  62     + ``SandboxTest`` to start your new process,
  63       `<https://searchfox.org/mozilla-central/source/security/sandbox/common/test/SandboxTest.cpp>`_
  64
  65     + ``SandboxTestingChildTests`` to define the test
  66       `<https://searchfox.org/mozilla-central/source/security/sandbox/common/test/SandboxTestingChildTests.h>`_
  67
  68     + ``SandboxTestingChild`` to run your test
  69       `<https://searchfox.org/mozilla-central/source/security/sandbox/common/test/SandboxTestingChild.cpp>`_