Squirrel

Squirrel is an OS X framework focused on making application updates as safe
and transparent as updates to a website.

Instead of publishing a feed of versions from which your app must select,
Squirrel updates to the version your server tells it to. This allows you to
intelligently update your clients based on the request you give to Squirrel.
The server can remotely drive behaviors like rolling back or phased rollouts.

Your request can include authentication details, custom headers or a request
body so that your server has the context it needs in order to supply the most
suitable update.

The update JSON Squirrel requests should be dynamically generated based on
criteria in the request, and whether an update is required. Squirrel relies
on server side support for determining whether an update is required, see
Server Support.

Squirrel's installer is also designed to be fault tolerant, and ensure that any
updates installed are valid.

Adopting Squirrel

1. Install xctool with brew install xctool
2. Add the Squirrel repository as a git submodule
3. Run script/bootstrap from within the submodule
4. Add references to Squirrel.xcodeproj and its dependencies to
   your project
5. Add Squirrel.framework as a target dependency
6. Link Squirrel.framework and add it to a Copy Files build phase which copies
   it into your Frameworks directory
7. Ensure your application includes the dependencies. Squirrel
   does not embed them itself.

If you’re developing Squirrel on its own, then use Squirrel.xcworkspace.

Dependencies

Squirrel depends on ReactiveCocoa
and Mantle.

If your application is already using ReactiveCocoa, ensure it is using the same
version as Squirrel.

Otherwise, add a target dependency and Copy Files build phase entry for the
ReactiveCocoa.framework target included in Squirrel's repository, in
Carthage/Checkouts/ReactiveCocoa.

Similarly, ensure your application includes Mantle, or copies in the Squirrel
version.

Finally, ensure your application's Runpath Search Paths (LD_RUNPATH_SEARCH_PATHS)
includes the directory that Squirrel.framework, ReactiveCocoa.framework
and Mantle.framework are copied into.

Configuration

Once Squirrel is added to your project, you need to configure and start it.

#import <Squirrel/Squirrel.h>

- (void)applicationDidFinishLaunching:(NSNotification *)notification {
	NSURLComponents *components = [[NSURLComponents alloc] init];

	components.scheme = @"https";
	components.host = @"mycompany.com";
	components.path = @"/myapp/latest";

	NSString *bundleVersion = NSBundle.mainBundle.sqrl_bundleVersion;
	components.query = [[NSString stringWithFormat:@"version=%@", bundleVersion] stringByAddingPercentEncodingWithAllowedCharacters:NSCharacterSet.URLQueryAllowedCharacterSet]

	self.updater = [[SQRLUpdater alloc] initWithUpdateRequest:[NSURLRequest requestWithURL:components.URL]];

	// Check for updates every 4 hours.
	[self.updater startAutomaticChecksWithInterval:60 * 60 * 4];
}

Squirrel will periodically request and automatically download any updates. When
your application terminates, any downloaded update will be automatically
installed.

Update Requests

Squirrel is indifferent to the request the client application provides for
update checking. Accept: application/json is added to the request headers
because Squirrel is responsible for parsing the response.

For the requirements imposed on the responses and the body format of an update
response see Server Support.

Your update request must at least include a version identifier so that the
server can determine whether an update for this specific version is required. It
may also include other identifying criteria such as operating system version or
username, to allow the server to deliver as fine grained an update as you
would like.

How you include the version identifier or other criteria is specific to the
server that you are requesting updates from. A common approach is to use query
parameters, Configuration shows an example of this.

Update Available Notifications

To know when an update is ready to be installed, you can subscribe to the
updates signal on SQRLUpdater:

[self.updater.updates subscribeNext:^(SQRLDownloadedUpdate *downloadedUpdate) {
    NSLog(@"An update is ready to install: %@", downloadedUpdate);
}];

Installing Updates

While downloaded updates are automatically installed when your application
terminates, if don't want to wait you can manually terminate the app to begin
the installation process immediately.

Once an update available notification has
been received, you may want to present an interface informing the user about
the update and offering the ability to install and relaunch.

To explicitly install a downloaded update and automatically relaunch afterward,
subscribe to the relaunchToInstallUpdate signal on SQRLUpdater:

[[self.updater relaunchToInstallUpdate] subscribeError:^(NSError *error) {
    NSLog(@"Error preparing update: %@", error);
}];

Server Support

Your server should determine whether an update is required based on the
Update Request your client issues.

If an update is required your server should respond with a status code of
200 OK and include the
update JSON in the body. Squirrel will download and
install this update, even if the version of the update is the same as the
currently running version. To save redundantly downloading the same version
multiple times your server must not inform the client to update.

If no update is required your server must respond with a status code of
204 No Content. Squirrel
will check for an update again at the interval you specify.

Update Server JSON Format

When an update is available, Squirrel expects the following schema in response
to the update request provided:

{
	"url": "https://mycompany.example.com/myapp/releases/myrelease",
	"name": "My Release Name",
	"notes": "Theses are some release notes innit",
	"pub_date": "2013-09-18T12:29:53+01:00"
}

The only required key is "url", the others are optional.

Squirrel will request "url" with Accept: application/zip and only supports
installing ZIP updates. If future update formats are supported their MIME type
will be added to the Accept header so that your server can return the
appropriate format.

"pub_date" if present must be formatted according to ISO 8601.

Update File JSON Format

The alternate update technique uses a plain JSON file meaning you can store your
update metadata on S3 or another static file store. The format of this file is
detailed below:

{
	"currentRelease": "1.2.3",
	"releases": [
		{
			"version": "1.2.1",
			"updateTo": {
				"version": "1.2.1",
				"pub_date": "2013-09-18T12:29:53+01:00",
				"notes": "Theses are some release notes innit",
				"name": "1.2.1",
				"url": "https://mycompany.example.com/myapp/releases/myrelease"
			}
		},
		{
			"version": "1.2.3",
			"updateTo": {
				"version": "1.2.3",
				"pub_date": "2014-09-18T12:29:53+01:00",
				"notes": "Theses are some more release notes innit",
				"name": "1.2.3",
				"url": "https://mycompany.example.com/myapp/releases/myrelease3"
			}
		}
	]
}

User Interface

Squirrel does not provide any GUI components for presenting updates. If you want
to indicate updates to the user, make sure to listen for downloaded
updates.