962705 - Write an e10s migration guide for add-on authors

Status: RESOLVED FIXED

(Developer Documentation Graveyard :: Add-ons, defect)

Description

[Will Bamberg [:wbamberg]]

We need some documentation on MDN to help add-on developers update their add-ons so they work with e10s. It should cover:

* what do you need to do?
  * nothing
  * update using CPOWs
  * update using the message manager
* details of how to migrate code to use CPOWs and their limitations
* details of how to migrate code to use the message manager
* how to test your add-on under e10s

* example add-ons
  * trivial examples
  * real-world (but simple) examples

Comment 1

[Will Bamberg [:wbamberg]]

Etherpad with links and chat about this work: https://etherpad.mozilla.org/e10s-addon-docs

Comment 2

[Jorge Villalobos [:jorgev] (he/him)]

I have a plan of blogging about this in the future, and I already have one in mind about the Message Manager. However, I'm currently focused on Australis compatibility, so it might be a while before I publish anything.

Comment 3

[Will Bamberg [:wbamberg]]

Here's v1 of a guide: https://developer.mozilla.org/en-US/Add-ons/Working_with_multiprocess_Firefox

Comment 4

[Dave Garrett]

(In reply to Will Bamberg [:wbamberg] from comment #3)
> Here's v1 of a guide:
> https://developer.mozilla.org/en-US/Add-ons/Working_with_multiprocess_Firefox

The first diagram and associated text implies that you use async messages for chrome->content and sync messages for content->chrome. This is quite bad to imply without further information given. Asyncronous messages should be used whenever possible and are valid for all content<->chrome whilst sync is restricted to content->chrome. Async should be generally recommended in both directions. Additionally, it should note that if you wish to return a value from any message listener(s) then you have to use sync which can return an array of responses (also note that it is always an array, even if one item is returned; this bit is poorly documented elsewhere).

I'm considering generalizing the sandbox in content script code I wrote to do custom JavaScript actions in Flagfox under e10s (which function as small user scripts) and donating it to MDC as a code example. It took a bit to write, but it's quite small and easy to read so it could be helpful to others.

Comment 5

[Dave Garrett]

Noting bug 1051238 somewhere on the page would also be a good idea.

Comment 6

[Will Bamberg [:wbamberg]]

(In reply to Dave Garrett from comment #4)
> (In reply to Will Bamberg [:wbamberg] from comment #3)
> > Here's v1 of a guide:
> > https://developer.mozilla.org/en-US/Add-ons/Working_with_multiprocess_Firefox
> 
> The first diagram and associated text implies that you use async messages
> for chrome->content and sync messages for content->chrome. This is quite bad
> to imply without further information given. Asyncronous messages should be
> used whenever possible and are valid for all content<->chrome whilst sync is
> restricted to content->chrome. Async should be generally recommended in both
> directions.

Thanks for this, I've updated the diagram and associated text.

> Additionally, it should note that if you wish to return a value
> from any message listener(s) then you have to use sync which can return an
> array of responses (also note that it is always an array, even if one item
> is returned; this bit is poorly documented elsewhere).

I don't want this overview section to go into details of the message manager API: I'd prefer to point to https://developer.mozilla.org/en-US/docs/The_message_manager for the details.

(In reply to Dave Garrett from comment #5)
> Noting bug 1051238 somewhere on the page would also be a good idea.

I've added a "Known bugs" section.

Comment 7

[Dave Garrett]

(In reply to Will Bamberg [:wbamberg] from comment #6)
> Thanks for this, I've updated the diagram and associated text.

Much better now. Thanks.

> I don't want this overview section to go into details of the message manager
> API: I'd prefer to point to
> https://developer.mozilla.org/en-US/docs/The_message_manager for the details.

OK. If I do end up writing something up I'll stick it up on the blog. If it looks useful, we could stick it on its own MDN code example page and link to in instead.

I didn't write up a big long thing like I did with restartless conversion because Flagfox actually managed to work under e10s just fine with CPOWs save for custom JS actions. (current version does without most CPOWs now, though)

On that note, you're probably going to want a section on CPOWs in there.

Comment 8

[Will Bamberg [:wbamberg]]

(In reply to Dave Garrett from comment #7)
> (In reply to Will Bamberg [:wbamberg] from comment #6)
> > Thanks for this, I've updated the diagram and associated text.
> 
> Much better now. Thanks.
> 
> > I don't want this overview section to go into details of the message manager
> > API: I'd prefer to point to
> > https://developer.mozilla.org/en-US/docs/The_message_manager for the details.
> 
> OK. If I do end up writing something up I'll stick it up on the blog. If it
> looks useful, we could stick it on its own MDN code example page and link to
> in instead.

I'd (obviously) be really happy to incorporate anything you write up on this, sample code or tutorials or both.

Comment 9

[Dave Garrett]

From current draft:
> We'll register a chrome:// URL for the frame script:
> // chrome.manifest
> content    modify-all-pages    chrome/content/    contentaccessible=yes

Why the "contentaccessible=yes"? That flag is generally considered harmful, and I don't see it being needed at all here. The content script needs access to the content webpage, which it always gets, but the page has no need to access the content script(s) via its own script(s). I don't think this provides access to the running script global, but rather just the ability to load up that chrome:// URI (plaintext JS), which I thought was a disabled or removed feature for chrome:// (can't find bug, atm; might be misremembering) This flag also produces privacy leaks as it allows sites to easily fingerprint/profile users via stuff exposed to the web via addons. (e.g. at some point in the past, Adblock Plus could be detected by websites via "contentaccessible=yes" by default mounts it used) The resource:// protocol still does this, but chrome:// has had it off by default for a long time. At minimum, I don't think this is a topic for a starter example, though I'm curious as to if there's a specific instance where this could actually be useful.

Comment 10

[Will Bamberg [:wbamberg]]

(In reply to Dave Garrett from comment #9)
> From current draft:
> > We'll register a chrome:// URL for the frame script:
> > // chrome.manifest
> > content    modify-all-pages    chrome/content/    contentaccessible=yes
> 
> Why the "contentaccessible=yes"? That flag is generally considered harmful,
> and I don't see it being needed at all here.

No, I don't know any reason why that should be included, and the example seems to work fine without it, so I've removed it from the article and the example code.

Comment 11

[Chris Peterson [:cpeterson]]

Move old M2's low-priority bugs to M6 milestone.

Comment 12

[Jeferson Hultmann]

Hi, I have some questions that I would like to see added to the migration guide:

* It's not clear how to unload/remove a frame script. It seems it will remain running even after my extension is disabled or uninstalled.

* Is "document-element-inserted" notification still valid? I believe not. What should I do?

* What about nsILoadContext.associatedWindow?

Comment 13

[Dave Garrett]

(In reply to Jeferson Hultmann from comment #12)
> * It's not clear how to unload/remove a frame script. It seems it will
> remain running even after my extension is disabled or uninstalled.

The running context goes away when the window it's running in is closed, as far as I know. Unregister the message listeners for it when you're done with it. The script itself, however, is very much brokenly implemented and will stay around forever. See bug 1051238.

Comment 14

[Chris Peterson [:cpeterson]]

(In reply to Jeferson Hultmann from comment #12)
> Hi, I have some questions that I would like to see added to the migration
> guide:

Jeferson, if you have more questions, please drop by the #e10s IRC channel on irc.mozilla.org. The e10s developers hang out there and can answer your questions.

Comment 15

[Bill McCloskey [inactive unless it's an emergency] (:billm)]

Hi Will, we're planning to go to Aurora in the next release. Is there any more work you wanted to do for our documentation?

Comment 16

[Will Bamberg [:wbamberg]]

Bill, 2 things:
* there are some clarifications that I wanted to add from bug 1122083
* bug 1140193

Apart from that I don't know of anything. Do you?

Comment 17

[:Gijs (he/him)]

IMO this would ideally also cover:

- the recent additions from bug 1133594
- reviewing https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox/The_message_manager , fixing it where it's inaccurate, and/or clarifying it where it's unclear. In particular, from that document, it's hard to get from "I want to send a message to the parent/child" to "which message manager do I need for that and how do I get one".

Comment 18

[Bill McCloskey [inactive unless it's an emergency] (:billm)]

Will has rewritten a lot of this stuff to cover process scripts and other things. I'm going to close this. Thanks Will!