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