*Rocketeers!*
We have identified a serious bug in the 1.4.* releases, and have made a
hotfix release of the Add-on SDK. The hotfix release is version 1.4.3.
*If you are potentially affected by the bug, then you will need to take
action to recover from it.*
This note explains:
- how to work out whether you are potentially affected
- what the impact is
- how to recover from the bug
- what went wrong
Are You Affected?
You are potentially affected by this bug if you meet *ALL THREE OF* the
following conditions:
1. *Your add-on uses any of the following SDK modules: simple-storage,
passwords, simple-prefs*. Using *passwords* is only a problem if you’re
using it to store passwords specific to your add-on, rather than just web
site passwords).
2. *You did not explicitly specify an ID for your add-on*This means: you
didn’t edit your “package.json” file to set your add-on’s ID, so the first
time you ran `cfx`, it generated an ID for you in “package.json”.If you’re
not sure about this, open your add-on’s “package.json” file and examine its
“id” entry. If it does not contain “@”, and is not in the form:
“{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx}”, then it is an auto-generated ID
and you meet this condition. For example:
"id": "jid1-MKxcan0H26wiRw"
3. *You have ever built and distributed your add-on using the 1.4, 1.4.1
or 1.4.2 releases of the SDK *This means either:
- you initially built your add-on with 1.4, 1.4.1 or 1.4.2
- you initially built your add-on using 1.3 or an earlier release,
but rebuilt it using 1.4, 1.4.1, or 1.4.2.
What’s the Impact?
The impact of this is:
1. suppose your add-on was originally built and distributed using a version
of the SDK earlier than 1.4. People use it, and store data with it, using
the simple-storage or passwords modules. Then you rebuild using SDK
1.4/1.4.1/1.4.2. Now, any data which users had previously stored in
simple-storage, and any add-on-specific passwords stored using passwords,
will seem to have disappeared. You must upgrade to 1.4.3 to recover this
data.
2. suppose your add-on is built using SDK 1.4/1.4.1/1.4.2. People use it,
and store data with it, using *simple-storage*, *simple-prefs*, or *
passwords*. Then you upgrade to version 1.4.3. Now, this data will
apparently disappear. You must take steps to recover this data.
How To Recover
First, upgrade your add-on to use 1.4.3. After this, data entered using
releases of the SDK before 1.4 will reappear.
Next, you’ll have to recover any data that users entered using the
1.4/1.4.1/1.4.2 versions.
To help with this we’ve written a module called “recovery.js”. This module
won’t ship with the SDK itself, though.
- If you’re using the Add-on SDK, download “recovery.js” from https://gist.github.com/1733262
and save it in your add-on’s “lib” directory.
- If you’re using the Add-on Builder, move your mouse over “Libraries”
in the left-hand sidebar until a plus sign appears next to it, then click
the plus sign. Then in the dialog type “recovery” and select “recovery by
gozala” to add it to your project:
[image: screenshot of adding recovery library]
You need to import the recovery module in the normal way:
var recovery = require('recovery');
The recovery module contains any data that was written using *simple-storage
*, *simple-prefs*, and *passwords* while your add-on was built with the
1.4, 1.4.1, or 1.4.2 releases of the SDK. The data is stored as three
properties, one for each module:
- recovery.storage
- recovery.prefs
- recovery.passwords
You’ll need to merge these properties with the data stored in *
simple-storage*, *simple-prefs*, and *passwords* in whichever way makes
sense for your add-on.
The files at https://gist.github.com/1733262 include some examples of
performing this merge using the recovery module.
What Went Wrong
SDK-based add-ons have an ID, which is used for, among other things,
figuring out which stored data belongs to this add-on. The ID is stored in
the add-on’s “package.json” file. If you do not specify an ID for your
add-on by editing “package.json” directly, then the SDK generates one for
you automatically.
This auto-generated ID in “package.json” looks something like
“jid1-y1AFbAhD9jXVcg”. The SDK takes this value and appends “@jetpack” to
it, and uses the result as an ID. So if you call:
console.log(require("self").id);
…you’ll see something like:
info: jid1-y1AFbAhD9jXVcg@jetpack
This value is then used as a key for data stored using *simple-storage*, *
simple-prefs*, and certain data in *passwords* (specifically, passwords
that are associated with your add-on rather than a web site).
In 1.4 we broke the code that appends “@jetpack” to the ID. This means that
a 1.4/1.4.1/1.4.2 add-on will look for data using just
“jid1-y1AFbAhD9jXVcg”, and won’t find any data that was entered using an
add-on built against an earlier version of the SDK.
In 1.4.3 we are reverting that change: so a 1.4.3 add-on will look for data
using “jid1 y1AFbAhD9jXVcg@jetpack”. This means that a 1.4.3-based add-on
it will find data which was entered using an add-on built using pre-1.4
release of the SDK. However, a 1.4.3 based add-on *will not* find data
entered using an add-on built against 1.4/1.4.1/1.4.2. That’s why you have
to recover that data explicitly.
We considered making the 1.4.3 release perform automatic recovery, looking
for data stored under “my-jid”, and if it finds any, automatically updating
the version stored under “my-jid@jetpack”. But the structure of stored data
is very specific to an add-on, and we decided that there was a significant
risk that automatic update would break some add-ons, so it’s safer if each
add-in implements its own recovery.
