Lifecycle of offscreen documents

[Jackie Han]

References:

• Blog: https://developer.chrome.com/blog/Offscreen-Documents-in-Manifest-v3/
• API Doc: https://developer.chrome.com/docs/extensions/reference/offscreen/
• Design Doc: https://docs.google.com/document/d/1b-I-vXq2h7OFFmus78jZXIWcKilKJLKLeGplnY9wt7k/edit

1. Lifecycle

The design doc and blog say:

The page will have a lifetime mechanism similar to event pages in Manifest V2, in that it will be torn down when it stops performing actions.  Additionally, the user agent may place further restrictions on the lifetime specific to the purpose specified.

But I tried the offscreen api yesterday. In my test on Chrome 109 stable, the offscreen document has never been terminated (over 12 hours, it still exists). My code is 

await chrome.offscreen.createDocument({
  url: 'off_screen.html',
  reasons: ['DOM_SCRAPING'],
  justification: 'reason for needing the document',
});

in offscreen document, it only has a message listener

chrome.runtime.onMessage.addListener(...);

What is its life cycle? persistent until calling closeDocument() by developers? 

2. Single or multiple

The blog says:

For implementation ease, the first version of this API only supports a single page per-extension, per-profile at a time. In future versions, we may relax this to support multiple pages.

I wrote a response to how to detect if the offscreen doc exists when createDocument() in another thread. At present, createDocument() will throw an error if it already exists. When it supports multiple documents, it will not throw errors? 

Thus, 1) developers should not use "try catch" to create documents. 2) the signature of chrome.offscreen.hasDocument() method should accept a url as parameter and return an array of boolean.

3. Forward and backward compatibility

The blog says:

Additionally, as DOM functionality and APIs are added to the service worker, the list of reasons to create a document will be added to or reduced depending on the current state of the service worker, and reasons to use offscreen documents.

 

Offscreen Documents allow extensions that require DOM or window interaction access that cannot be achieved in service workers currently. It also provides a flexible approach, where new use cases can be added and future-solved use cases can be removed. 

What I understand is that if some feature is added to service worker in the future then the offscreen api might remove some "Reason". My question is how do developers write code that is both forward and backward compatible? Developers may die due to illness or accidents, so the code needs to be as forward compatible as possible.

Jackie Han

[hrg...@gmail.com]

For your code to be forward compatible, the underlying platform has to remain backwards compatible. But the Extensions Team had no problem in breaking compatibility with MV2 to such an extent that most extensions require a partial or complete re-engineering to make them work under MV3.

So, what the point in asking the Extensions Team to keep the platform stable?

It's like asking a drug lord to respect traffic laws.

[Jackie Han]

In this context, the blog says they will add functions in service worker and remove functions in offscreen api.

This leads to a transition period. At that time, some users use the new version of Chrome, some users use the old version of Chrome. Your code needs to be compatible with both versions. The blog doesn't say how to handle this case in details. So I ask this question to them.

So, what the point in asking the Extensions Team to keep the platform stable?

Nobody wants to go through such disruptive changes again, right? So I also have the meaning of reminding them of this point.

 

[Oliver Dunk]

Hi Jackie,

I'll try to answer each of your questions in turn...

What is its life cycle? persistent until calling closeDocument() by developers?

Great question, and apologies for not having this better documented. We're hoping to do that soon. There are currently two types of enforcement:

• When the AUDIO_PLAYBACK reason is used, the offscreen document will be closed if it is open for longer than 30 seconds without playing audio.
• For all other reasons, the lifetime is unbounded (the page can remain open forever).

This is mentioned (albeit briefly and with little detail) here: https://developer.chrome.com/docs/extensions/reference/offscreen/#reasons

Over time I expect we'll add more checks to ensure offscreen documents are closed when they are no longer being used. I understand that doing that on short notice could be a concern so I hope we can announce that ahead of time.

Thus, 1) developers should not use "try catch" to create documents. 2) the signature of chrome.offscreen.hasDocument() method should accept a url as parameter and return an array of boolean.

I'm not sure if the exact API for multiple documents is known yet. That said, I think option 3 (sending a message) from the thread you linked is probably the safest. I appreciate that it's a little bit of extra wiring but it does feel like the try/catch may be an issue in the future. At the moment hasDocument has been removed (it was only ever available while the API was experimental) because it doesn't make sense for multiple documents as you say - I'd personally like to see it back with a new signature but I don't know what the plans are there.

My question is how do developers write code that is both forward and backward compatible? Developers may die due to illness or accidents, so the code needs to be as forward compatible as possible.

I think this is unfortunately a case where developers will need to spend some time adopting new APIs as we make them available in service workers - there's no way with feature detection to write a single extension today that will definitely work as we change the supported reasons in the future. That said, everyone I've spoken to seems to agree that we'll need to give developers time to migrate as reasons are removed. So I expect by the time a reason is removed the alternative will have been around for a significant amount of time and long enough to allow developers to migrate.

I hope this all helps! Let me know if you have more questions.

Oliver Dunk | DevRel, Chrome Extensions | https://developer.chrome.com/ | London, GB

--
You received this message because you are subscribed to the Google Groups "Chromium Extensions" group.
To unsubscribe from this group and stop receiving emails from it, send an email to chromium-extens...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/chromium-extensions/CAAgdh1KuiW%2B2a%3DmowVNSqSLgAY3AHT_ndZitTiL6VcKTGp4i7Q%40mail.gmail.com.

[Jackie Han]

Thank you Oliver for your reply.

 

For all other reasons, the lifetime is unbounded (the page can remain open forever).

This is great, and I like to control its lifecycle manually, especially for functions that require a persistent (or long time) background page in MV2. But you said the browser might limit it in the future, which made me hesitant.

I think option 3 (sending a message) from the thread you linked is probably the safest. 

hasDocument has been removed ……

This way(sending a message) is too cumbersome and inefficient. Maybe extension.getContexts() can resolve it. Or a well designed hasDocument() could be more easier.

Since the API is very new, I don't think it is very mature, such as the lifecycle; how to ensure it is created in practice; single or multiple offscreen documents; I commented before. Right now, I'm thinking about how to use it, but I don't really use it, and I think other developers do the same. At this time, its design should be improved as soon as possible. If there are some API changes in the short term, I can accept it. After that, it should have a steady behavior expectation for developers.

[Jackie Han]

Also, if the browser supports multiple offscreen documents, the signature of `chrome.offscreen.closeDocument()` will be changed too. Developers need to specify which document to be closed.

[Robbi]

> Developers may die due to illness or accidents, so the code needs to be as forward compatible as possible.

I don't know the customs and the traditions of every part of the world, but Italians people (especially men) usually tend to grab and hold their private parts to propitiate good luck when they hear (or read) these kind of sentence.

However, we can think of bringing children into the world to whom we will bequeath our much cosseted codes :-)

[Jackie Han]

Robbi, 

A bit off topic, let me give you a real example about forward compatibility. I have a Battery Status extension. It uses Battery Status API to work. When I first started developing this extension, I knew that Chrome wanted to remove this API (other browsers already removed it). So I use feature detection to this API, if it is not available (in the future), I will show an error information on the extension UI. So when that day comes (but I don't know when), I don't need to update this extension.

[Oliver Dunk]

While the lifetime restrictions may change they are there to counter abuse, rather than break valid use cases. I think if you're doing something in the spirit of the reason you're specifying then you should feel comfortable that it's unlikely a restriction would be added in the future that would impact you.

I definitely agree that extension.getContexts could help with a lot of the discussion here.

That's a fair callout with closeDocument - I'm not sure what the thinking is there but I'll bring it up.

What you've done with the battery API seems like a pretty good approach :)

Oliver Dunk | DevRel, Chrome Extensions | https://developer.chrome.com/ | London, GB

[Robbi]

mine just wanted to be a joke to play down your (unfortunate?) sentence.
Do you really think that in 100 years when we are gone your (and mine) extensions will matter to anyone and do you think they will still work at that time?

[Oliver Dunk]

Robbi, I think it's probably best to leave the conversation here.

Feel free to jump in if you have thoughts on offscreen documents but I definitely want to stay on topic.

Oliver Dunk | DevRel, Chrome Extensions | https://developer.chrome.com/ | London, GB

[Robbi]

I completely agree.
However, we must find the time to have a laugh 'cause everyday we run the risk of waking up under a cypress :-)

[wOxxOm]

> if you're doing something in the spirit of the reason you're specifying then you should feel comfortable that it's unlikely a restriction would be added in the future that would impact you.

This is what we all (arguably) thought when we just started to get acquainted with the wonderful world of browser extensions in Chrome. Then came ManifestV3... and made a super unreasonable breaking change - the background script must be a service worker, the most hostile and the least suitable environment for an extension, the change that affected most extensions, many of them negatively e.g. the SW registration bug is still not fixed. We don't see notable improvements in performance or security, but we see costly workaround like the SW + chrome.offscreen combo that consumes twice as more CPU/memory resources than an event page for years to come while the SW-compatible replacements are implemented, which is often blocked by the lack of interest from the Web platform.

So the takeaway is don't be comfortable, don't be complacent. Voice your concerns. Find the relevant bug reports on https://crbug.com, star them, make sure it covers your use case, otherwise describe it in a comment or submit a new report if the issue wasn't already reported.

[Oliver Dunk]

Absolutely wOxxOm, I hope it was clear from my previous messages that we're open to feedback.

The important point I wanted to share is please do build things on top of offscreen documents. While some of the specifics may change, they are a direct response to feedback around certain use cases service workers caused problems for and given they are now in the stable channel developers should feel able to use them.

On Manifest V3 - I don't think there's too much to add here, but as I'm sure you know some of the concerns around breaking changes are exactly why we have the known issues list (https://developer.chrome.com/docs/extensions/mv3/known-issues/) and are revisiting the timeline.

Oliver Dunk | DevRel, Chrome Extensions | https://developer.chrome.com/ | London, GB