Add-on SDK 1.4.3 Released

[dcm]

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-onThis 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:

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.

[Colin Keenan]

This bug will affect me, but I don't know how to upgrade the SDK version. I started with Add-on SDK 1.4.2, and that's what I'm still using. How do I upgrade to Add-on SDK 1.4.3 so that I can follow these instructions to make sure simple-storage data is not lost on future updates of the SDK.

[dcm]

 

Hi Colin,

 

I answered you on the blog too - but reposting here to make sure you see it! 

 

Its just a matter of grabbing the tarball or zipfile and either installing those files into your existing add-on sdk directory or using it from the default directory it installs into. We are looking into the possibility of using http://addons.mozilla.org to distribute the SDK so that upgrading will be easier and automatic – for now its just a matter of grabbing the new files.

Thanks!

Dave

[Colin Keenan]

Thanks for the quick reply.

[Colin Keenan]

I don't know if anyone is putting my add-on to serious use other than me, but it was easy to fix the add-on for myself. I already had the following line in my main.js: var ss = require("simple-storage");

Of course, updating to SDK 1..4.3 caused me to loose access to all previously stored data in ss.storage.

All I had to do to fix it was to add the following few lines immediately after the ss declaration:

var prefs = require("simple-prefs").prefs;
var recovery = require('./recovery');

if (!prefs.storageRecovered) { //this recovers data stored while using SDK 1.4.2 and is only run one time
   for (var key in recovery.storage) //recovery.storage contains data stored while using SDK 1.4.2
      ss.storage[key]=recovery.storage[key]; //in order for ss.storage to access it, the key needs to be the same
   prefs.storageRecovered = true;

}

My case was very simple because there can't possibly be any data from before the SDK 1.4.*, so I don't have to test for anything. It worked for me, and I'm sure I'm the heaviest user of my add-on (Rental Application).

Is there anything I should worry about in leaving this as is for my next xpi version for distribution?