Add-on SDK 1.4.3 Released

2

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:

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.

Getting In Touch

As always we’d love to hear from you about your experiences. And we are always available to help with issues you may encounter. You can contact us in a variety of ways:

post to our discussion group
chat with us on irc.mozilla.org #jetpack
report a bug
check out the source and contribute bug fixes, enhancements, or documentation

Categories: general

2 responses

  1. Colin Keenan

    I am affected, but I don’t know how to upgrade the SDK version. I started with and am still using Add-on SDK 1.4.2. How do I upgrade? You instructions for recovery are fine, but there’s no explanation as to how to actually do the upgrade, which is the first step.

    1. Dave Mason Author

      Hi Colin,

      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.