SparkleProject/Sparkle
1
0
Fork 0
mirror of https://github.com/sparkle-project/Sparkle.git synced 2025-11-01 15:34:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updating installation docs into sections rather than bulleted points

Browse Source 
Also make some other changes with choice of wording
This commit is contained in:
Zorg
2016-07-04 19:51:40 -04:00
parent b4f7a28aa3
commit 63febfd9cd
1 changed files with 18 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Documentation/Installation.md
+18 -11
View File
@@ -9,13 +9,17 @@
## After downloading the update:
1. SUCoreBasedUpdateDriver invokes SUInstallerDriver's extraction method. It starts up a local port for listening to IPC, and launches the Autoupdate installer tool (which is ran from a user caches directory). This launch is done can be spawned via a task (where the privileges would inherit the updater process), or launched via LaunchServices from a non-sandboxed XPC service (which would be necessary for sandboxing). In either case, the arguments that are passed to Autoupdate are the host bundle identifier and a boolean if the privileges were inherited (i.e, task spawned directly). The host bundle identifier is necessary for IPC so that we can listen and connect to the same mach service name (which partially uses the bundle identifier).
### Launching Autoupdate
SUCoreBasedUpdateDriver invokes SUInstallerDriver's extraction method. It starts up a local port for listening to IPC, and launches the Autoupdate installer tool (which is ran from a user caches directory). This launch is done can be spawned via a task (where the privileges would inherit the updater process), or launched via LaunchServices from a non-sandboxed XPC service (which would be necessary for sandboxing). In either case, the arguments that are passed to Autoupdate are the host bundle identifier and a boolean if the privileges were inherited (i.e, task spawned directly). The host bundle identifier is necessary for IPC so that we can listen and connect to the same mach service name (which partially uses the bundle identifier).
2. After Autoupdate (installer) launches, it creates a local listening port for IPC as well as a remote port back to the updater process. The Autoupdate installer then sends a message `SURequestInstallationParameters` back to the updater. The updater receives the message and sends installation data back to the installer through `SUInstallationData`. This data includes the bundle application path to relaunch, DSA signature from the appcast item, decryption password for dmg if available, path to GUI updater tool for showing progress, the path to the downloaded directory and name of the downloaded item.
### Requested Installation Data
After Autoupdate (installer) launches, it creates a local listening port for IPC as well as a remote port back to the updater process. The Autoupdate installer then sends a message `SURequestInstallationParameters` back to the updater. The updater receives the message and sends installation data back to the installer through `SUInstallationData`. This data includes the bundle application path to relaunch, DSA signature from the appcast item, decryption password for dmg if available, path to GUI updater tool for showing progress, the path to the downloaded directory and name of the downloaded item.
3. Once the installer receives the installation data, it starts extracting the update. It may send several `SUExtractedArchiveWithProgress` messages indicating the unarchival progress back to the updater. On failure, the installer will send `SUArchiveExtractionFailed`. In the updater, if the update is a delta update, then the delta update is downloaded and we go back to step #1, except this time the local port for listening isn't started again, nor is the installer launched again (because it's already running), but the installation data is sent again and the extraction begins again. If the update is not a delta update on the other hand, then the updater aborts causing the installer to abort as well.
### Update Extraction
Once the installer receives the installation data, it starts extracting the update. It may send several `SUExtractedArchiveWithProgress` messages indicating the unarchival progress back to the updater. On failure, the installer will send `SUArchiveExtractionFailed`. In the updater, if the update is a delta update, then the delta update is downloaded and we go back to step #1, except this time the local port for listening isn't started again, nor is the installer launched again (because it's already running), but the installation data is sent again and the extraction begins again. If the update is not a delta update on the other hand, then the updater aborts causing the installer to abort as well.
4. If the unarchiving succeeds, a `SUValidationStarted` message is sent back to the updater, and the installer begins validating the update. If validation fails, the installer aborts, causing the updater to abort the update as well. Otherwise, the installer sends a message `SUInstallationStartedStage1` to the updater and begins the installation. The installer figures out what kind of installer to use (regular, guided pkg, nonguided pkg) and performs the first stage of installation:
### Starting Installation
If the unarchiving succeeds, a `SUValidationStarted` message is sent back to the updater, and the installer begins validating the update. If validation fails, the installer aborts, causing the updater to abort the update as well. Otherwise, the installer sends a message `SUInstallationStartedStage1` to the updater and begins the installation. The installer figures out what kind of installer to use (regular, guided pkg, nonguided pkg) and performs the first stage of installation:
* Regular application installer 1st stage: Makes sure this update is not a downgrade.
* Guided Package installer 1st stage: Does nothing.
@@ -27,7 +31,8 @@ Otherwise a `SUInstallationFinishedStage1` message is sent back to the updater a
The installer then listens and waits for the target application to relaunch terminates. If it is already terminated, then it resumes to stage 2 and 3 of the installation immediately assuming that it does not have permission to show UI interaction to the user. Thus if the installer does not have sufficient privileges to update the application already, the install will fail. If the target is already terminated, the installer will also assume that the target should not be relaunched after installation.
5. On the other hand, if the target applicaton to relaunch is still alive.. Well the updater receives `SUInstallationFinishedStage1` message in either case. The updater sends a message `SUSentUpdateAppcastItemData` with the appcast data in case the updater may request for it later (due to resumability, discussed later). It also reads if the target has already been terminated (implying that the installer will continue installing the update immediately), and if the installation will be done silently.
### Installation Waiting Period
On the other hand, if the target applicaton to relaunch is still alive.. Well the updater receives `SUInstallationFinishedStage1` message in either case. The updater sends a message `SUSentUpdateAppcastItemData` with the appcast data in case the updater may request for it later (due to resumability, discussed later). It also reads if the target has already been terminated (implying that the installer will continue installing the update immediately), and if the installation will be done silently.
For UI based update drivers, the updater tells the user driver to show that the application is ready to be relaunched - the user can continue to install & relaunch the app. The user driver is only alerted however if the installation isn't happening immediately (that is, if the target application to relaunch is still alive). The user driver can decide whether to a) install b) install & relaunch or c) delay installation. If installation is delayed, it can be resumed later, or if the target application terminates, the installer will try to continue installation if it has sufficient privileges to without user interaction.
@@ -37,9 +42,10 @@ Otherwise if the updater delegate doesn't handle immediate installation for auto
If an update driver is resumed (which cannot happen if the target applicaton is already terminated by the way), then the updater first asks the installer for the appcast item data that the installer received before through synchronous `SUReceiveUpdateAppcastItemData` message. The updater can use this for showing release notes, etc. Note the updater and target application don't have to live in the same process, and the updater could choose to terminate and resume later as a new process - so having the installer keep the appcast item data is necessary.
After the resumed update driver then allows the user driver to decide whether to a) install the update now, b) install & relaunch the update, or to c) delay the update installation and abort the update driver. Note we are now back to the same options discussed earlier.
Afterwards the resumed update driver then allows the user driver to decide whether to a) install the update now, b) install & relaunch the update, or to c) delay the update installation and abort the update driver. Note we are now back to the same options discussed earlier.
6. If the user driver decides to install the update, it sends a `SUResumeInstallationToStage2` message to the installer and supplies whether the update should be relaunched, and whether user interface can be displayed. The user driver always specifies that the user interface can be displayed; it's only in the case earlier for when the updater's delegate handles immediate installation where UI cannot be displayed.
### Continue to Installation
If the user driver decides to install the update, it sends a `SUResumeInstallationToStage2` message to the installer and supplies whether the update should be relaunched, and whether user interface can be displayed. The user driver always specifies that the user interface can be displayed; it's only in the case earlier for when the updater's delegate handles immediate installation where UI cannot be displayed.
The installer receives `SUResumeInstallationToStage2` and reads whether it should relaunch the target application and whether it can show UI (thus be allowed to show user interaction). The installer then resumes to stage 2 of the installation if it has not been performed already (that is if the target app already terminated). Note if the installer doesn't receive this message before the target application terminates, then the installer will not relaunch or show UI and resume stage 2 & 3 by itself. Also note that showing UI impacts whether or not the installer can request for authorization.
@@ -47,19 +53,20 @@ During this stage, if the installer is allowed to show UI and it is not inheriti
If the 2nd stage succeeds, the installer sends a `SUInstallationFinishedStage2` message back to the updater, including if the target application has already terminated at this time, and if the user explicitly cancelled the authorization request.
7. The updater receives a `SUInstallationFinishedStage2` message, and reads whether the user explicitly cancelled the update and if the target application had already been terminated. If the user cancelled the update, the updater simply aborts. Otherwise if the target application has not already terminated, the updater requests the user driver to terminate the application.
The updater receives a `SUInstallationFinishedStage2` message, and reads whether the user explicitly cancelled the update and if the target application had already been terminated. If the user cancelled the update, the updater simply aborts. Otherwise if the target application has not already terminated, the updater requests the user driver to terminate the application.
8. When the target application is terminated, the installer starts stage 3 of the installation. (It is significant to note that a long duration can go by between the 2nd and 3rd stages of installation, so the 2nd stage can't for example place files in temporary directories). If the GUI progress tool is available and the installer is allowed to show UI and the installer's connection to the updater is disconnected and the installer doesn't show progress (a nonguided pkg installer shows progress), then after a short delay, the progress tool is launched via LaunchServices showing a dock icon and indefinite progress window. Under most circumstances, the installation will finish faster than the progress tool will have the chance to show progress. Potentially large updates with many scattered files and updates over a network may be slow enough to trigger this progress tool. Note that if the connection to the updater is still connected, then it is the updater's job to show progress instead - which can happen when the updater and the target application don't live in the same process (eg: sparkle-cli).
### Finishing the Installation
When the target application is terminated, the installer starts stage 3 of the installation. (It is significant to note that a long duration can go by between the 2nd and 3rd stages of installation, so the 2nd stage can't for example place files in temporary directories). If the GUI progress tool is available and the installer is allowed to show UI and the installer's connection to the updater is disconnected and the installer doesn't show progress (only a nonguided pkg installer shows progress), then after a short delay, the progress tool is launched via LaunchServices showing a dock icon and indefinite progress window. Under most circumstances, the installation will finish faster than the progress tool will have the chance to show progress. Potentially large updates with many scattered files and updates over a network may be slow enough to trigger this progress tool. Note that if the connection to the updater is still connected, then it is the updater's job to show progress instead - which can happen when the updater and the target application don't live in the same process (eg: sparkle-cli).
The third stage does the final installation for updating and replacing the new updated bundle.
If the third stage fails, then the installer aborts, causing the updater driver to abort if it's still running. The target application is not ever relaunched on failure.
Otherwise the progress tool is explicitly terminated if it's running (note it will also terminate when the installer terminates due to IPC connection being lost). If the connection to the updater is still alive, a `SUInstallationFinishedStage3` message is sent back to the updater and the updater driver silently aborts the update. The installer then relaunches the new application if the installer was requested to relaunch it, and then does cleanup work (eg, moving old app to trash), and lastly the installer exits.
Otherwise if the third stage succeeds the progress tool is explicitly terminated if it's running (note it will also terminate when the installer terminates due to IPC connection being lost). If the connection to the updater is still alive, a `SUInstallationFinishedStage3` message is sent back to the updater and the updater driver silently aborts the update. The installer then relaunches the new application if the installer was requested to relaunch it, and then does cleanup work (eg, moving old app to trash), and lastly the installer exits.
## Notes:
* Performing an update if the application is already terminated will not request for user authorization, so sufficient privileges are needed beforehand in this case. The common case involves the updater living inside the application so this is not typically a worry.
* We use an auxiliary application for the installer rather than going through a launchd launch agent or daemon service still. Some components in the installer rely on AppKit such as seeing if an application process terminated or launching the update progress tool via LaunchServices (these could perhaps still be daemon safe though..). Changing to a launchd service would mean authorization would have to be requested *before* launching the Autoupdate installer in the first place (if needed), thus before extraction if we want to do this securely. Currently, the automatic update driver can start up the installer for extraction silently even with insufficient privileges. The launchd job may also have to be installed at some proper location first outside the app bundle first, but I'm unsure of the details. And the job may also have to be removed first. Securely blessing the job (via code signing) would be the most secure way to do this but also the most inconvenient, which for us is not worth it.
* We use an auxiliary application for the installer rather than going through a launchd launch agent or daemon service still. Some components in the installer rely on AppKit such as seeing if an application process terminated or launching the update progress tool via LaunchServices (these actions could perhaps still be daemon safe though..). Changing to a launchd service would mean authorization would have to be requested *before* launching the Autoupdate installer in the first place (if needed), thus before extraction if we want to do this securely. Currently, the automatic update driver can start up the installer for extraction silently even with insufficient privileges. The launchd job may also have to be installed at some proper location first outside the app bundle first, but I'm unsure of the details. And the job may also have to be removed first. Securely blessing the job (via code signing) would be the most secure way to do this but also the most inconvenient, which for us is not worth it.
* We use LaunchServices as an escape-hatch for launching processes that inherit from the current user session. For example, in a sandboxed environment to get around the fact that authorization API functions don't work from XPC services (even when not sandboxed), we launch the installer tool via LaunchServices. We also can launch the progress GUI tool from the installer even if the installer is inheriting from the updater which may be running as root because we do it through LaunchServices. In this case, the progress tool will not be ran as root.
* We use IPC in such a way that the installer process does not trust the updater process, which is why the installer does extraction, validation, and installation -- all in a single process. The only hole left in our model is the installer shelling out to authorization, which maybe some day can be replaced by launchd.