etcher/lib/child-writer/README.md

Etcher Child Writer

This module is in charge of dealing with the gory details of elevating and managing the child writer process. As a word of warning, it contains tons of workarounds and "hacks" to deal with platform differences, packaging, and inter-process communication. This empowers us to write this small guide to explain how it works in a more high level manner, hoping to make it easier to grok for contributors.

The problem

Elevating a forked process is an easy task. Thanks to the widely available NPM modules to display nice GUI prompt dialogs, elevation is just a matter of executing the process with one of those modules instead of with child_process directly.

The main problems we faced are:

• The modules that implement elevation provide "execution" support, but don't allow us to fork/spawn the process and consume its stdout and stderr in a stream fashion. This also means that we can't use the nice process.send IPC communication channel directly that child_process.fork gives us to send messages back to the parent.

• Since we can't assume anything from the environment Etcher is running on, we must make use of the same application entry point to execute both the GUI and the CLI code, which starts to get messy once we throw asar packaging into the mix.

• Each elevation mechanism has its quirks, mainly on GNU/Linux. Making sure that the forked process was elevated correctly and could work without issues required various workarounds targeting pkexec or kdesudo.

How it works

The Etcher binary runs in CLI or GUI mode depending on an environment variable called ELECTRON_RUN_AS_NODE. When this variable is set, it instructs Electron to run as a normal NodeJS process (without Chromium, etc), but still keep any patches applied by Electron, like asar support.

When the Etcher GUI is ran, and the user presses the "Flash!" button, the GUI creates an IPC server, and forks a process called the "writer proxy", passing it all the required information to perform the flashing, such as the image path, the device path, the current settings, etc.

The writer proxy then checks if its currently elevated, and if not, prompts the user for elevation and re-spawns itself.

Once the writer proxy has enough permissions to directly access devices, it spawns the Etcher CLI passing the --robot option along with all the information gathered before. The --robot option basically tells the Etcher CLI to output state information in a way that can be very easily parsed by the parent process.

The output of the Etcher CLI is then sent to the IPC server that was opened by the GUI, which nicely displays them in the progress bar the user sees.

Summary

There are lots of details we're omitting for the sake of clarity. Feel free to dive in inside the child writer code, which is heavily commented to explain the reasons behind each decision or workaround.

Don't hesitate in getting in touch if you have any suggestion, or just want to know more!