Extension Manager:API Rewrite

Overview

The current extension manager API is focussed on managing XPI style add-ons and is currently very limited forcing the UI and other callers to rely on direct access to the RDF datastore to glean required information about add-ons.

The main goals of this rewrite are:

• Support a wider range of add-on types managed through the same API
• Allow application/extension developers to be able to easily query the state of installed items
• Make it easier for applications to replace the add-ons UI with their own implementation by making all necessary information available through the defined API
• Remove direct access to the datastore

High Level View

The new API is accessed through a global AddonManager object that is included in a JavaScript module. There will also be a limited amount of access provided through an XPCOM component but this is intended for the XRE to use during startup. The API makes no assumptions about what types of add-ons do and how they are used, it does make some basic assumptions about the information available about them and the install process.

Users of the API can register to receive events about all add-ons. The API also gives access to two main types of objects:

Addon

The Addon object represents an add-on that is installed on the local system. This is a loose term since it also includes add-ons that have been downloaded and will be installed when the application is restarted. It is likely that the API will hand out multiple instances of Addon for the same underlying add-on since the alternative right now would involve caching each Addon for the lifetime of the application. The only way around this would be to add some form of weak reference support to JS. There are a set of properties that will be available for all types of add-ons and then each type of add-on may have additional properties. The same goes for operations that can be performed on the add-on.

Certain add-ons may have restrictions over what operations can be performed. These restrictions could be just down to the nature of the add-on (themes cannot be disabled normally) or down to system policies (user's may not have access to uninstall some add-ons f.e.). Each Addon has a permissions property that indicates what operations can currently be performed.

Some types of add-ons may require restarts for certain operations. XPI style extensions for example require restarts for almost all operations. The API exposes the operations that are pending in the pendingOperations property. It is also possible that this property may be used to indicate operations that have been deferred for any reason, maybe timing issues, maybe a dependency is pending install. Pending operations can make it hard to tell what state an actual add-on is in. To help solve this the isActive property indicates whether the add-on is currently active. This is separate to and may be different to the various userDisabled, isCompatible and other properties that indicate whether an add-on can be active or not.

It is currently undecided whether Addon objects are truly live views or not. There are a few options with pros and cons

Totally live

Here the Addon object's properties are always guaranteed to be up to date. There are really only two ways to do this, either a property access ends up as a database query or we cache every Addon object retrieved through the API and make sure that is up to date. The former is a problem since we want to avoid synchronous database queries and making all property accesses asynch would be wrong. The latter is a potential memory concern perhaps mitigated if we could get some weak reference support into JS.

Single instance live

Here if you perform an operation on an instance of Addon then that instance will have its properties updated. Any other cached instances of Addon that are representing the same add-on would not get updated though. This is potentially confusing for obvious reasons, but maybe not terrible. A general rule of recommending people not keep instances cached anywhere would seem to solve it.

Never live

Here the Addon's properties are fixed at time of retrieval and never update. It is perhaps less confusing that the previous option but ultimately less useful too I think.

AddonInstall

The AddonInstall object represents an add-on that is not yet installed. Again this is a loose definition, technically an AddonInstall object exists for add-ons that have just been installed. Essentially this object begins representing an add-on that can be installed (and may come from an update check to an existing add-on, a request to install a new add-on or a search for new add-ons). It tracks the high level progress of any necessary downloads and installation of the add-on.

The AddonInstall goes through a set of states:

Available

Represents an add-on that is known to be available for install. Depending on where the AddonInstall came from there may be very little information about the add-on available.

Downloading

This state tracks add-on downloads and as such it may not be necessary for add-ons installed from local files for example.

Downloaded

At this point all the main parts of the add-on's files are somewhere on the local computer to be installed. Almost all information about the add-on should be available at this point through an Addon object.

Installing

Here the add-on is being installed by its provider. This may cover file extraction etc.

Checking

In some cases the install may be delayed to allow further work such as compatibility checking.

Installed

Here the add-on has been installed and its Addon object will appear in AddonManager.getAddons. The add-on itself however may not be active until after an application restart.

These states are modelled on the current states XPI add-ons go through. Are they right?

In some ways it may make more sense for the checking phase to come between downloading and downloaded. This way when in the downloaded state we will know everything necessary to say whether installing is possible.

Should we automatically jump to states?

If we have an AddonInstall for a local file should we jump straight to Downlaoded? Perhaps not if we move checking to earlier as suggested above.

If we start an add-on download should it jump straight to installing as soon as downloading is complete and installation is known to be possible or should that be controlled through the API? In the latter case should we allow installation through the API even if the add-on is incompatible or has some other fault? I think it might be a good option in the API even if not exposed through the UI normally. It allows for better customisation on an application level or by extensions.

Add-on Providers

Underneath the manager (and essentially invisible through the API) are a set of add-on providers. Each one manages a specific type of add-on, for example there can be a provider for XPI style add-ons (perhaps multiple providers for each type of XPI add-on but that's unlikely), a provider for plugins, a provider for lightweight themes, etc. There will probably be a hardcoded set of providers for the application and then some means for add-ons to register their own providers. It is up to the providers to maintain their lists of installed add-ons, perform installation and uninstallation and send appropriate notifications out to registered listeners.

The new APIs represent add-ons in a number of states but these can broadly be split into two types, Local add-ons and Available add-ons. The API objects representing these add-ons are considered live views of the add-on. As operations are performed (disabling, downloading etc.) the properties of the object will update to reflect the new state. The objects represent add-on instances however. If I have an object representing the installed add-on "foo", then the user uninstalls and then reinstalls "foo" then the object still represents the old uninstalled instance of "foo". It is undefined whether retrieving the same add-on from the API twice will give two references to the same object or two separate objects that have the same properties.