Add documentation for persistent startup listeners in webextensions.

[chrisdavidmills]

I'm going to try and get this down well enough to be understood. aswan can clarify anywhere necessary.

For some functionality provided by extensions, it is important to receive events as early as possible on startup of Firefox. To avoid performance issues during startup, extensions start later in the cycle. To handle some functionality, the webextension system in firefox has a notion of "persistent listeners". These are essentially cached listeners that firefox handles until the extension can be loaded.

Examples of extensions that need early startup support include ad blockers and proxy extensions.

If you want a listener to work on startup, it must be a persistent listener.

Not all event APIs support persistent listeners, but webRequest blocking listeners and proxy.onRequest can be persisted as well as others.

For a listener to become persistent, it must be added during evaluation/initial execution of the background script. If it happens later (asynchronously or otherwise) then it is not persisted. The extension must remain enabled.

During startup, persisted listeners are handled by the webextension system, not by the extension. If an event is received, it is held until the extensions background script is loaded. For proxy and webRequest listeners, this results in the request being suspended until the event can be handled. If the listener is added again, during evaluation/initial execution, then the event is passed to the extension at that time. If the listener is not added again, you will see the error (which I responded about in bug 1501159 comment 27).

Possible caveat:

A lot of stuff happens on startup, some stuff could potentially happen before persistent listeners are activated by the webextension code.

[Grossdm]

I'm curious - is this issue is getting any attention?

Thanks

[ghostwords]

@mixedpuppy Does it matter if the listener is removed at some point later? EFForg/privacybadger#2438 (comment)