Issue with Chrome Offscreen Document Context in Service Worker

298 views
Skip to first unread message

fei liu

unread,
Jun 3, 2024, 5:27:44 AM6/3/24
to Chromium Extensions

Hello,

I'm currently working on a Chrome extension where I need to process multiple HTML contents using an offscreen document in the service worker. The aim is to ensure that each HTML content is parsed and processed correctly. However, I am encountering an issue where the chrome.runtime.getContexts method returns an empty array, even though the offscreen document appears to be created and functioning properly.

Here is the code I am using:

```

// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

const OFFSCREEN_DOCUMENT_PATH = '/offscreen.html';

let creating; // A global promise to avoid concurrency issues

async function setupOffscreenDocument(path) {
const offscreenUrl = chrome.runtime.getURL(path);
const existingContexts = await chrome.runtime.getContexts({
contextTypes: ['OFFSCREEN_DOCUMENT'],
documentUrls: [offscreenUrl]
});
console.log("existingContexts", existingContexts);
if (existingContexts.length > 0) {
console.log('Offscreen document already exists.');
return;
}

if (creating) {
await creating;
} else {
console.log("creating offscreen document");
creating = chrome.offscreen.createDocument({
url: path,
reasons: [chrome.offscreen.Reason.DOM_PARSER],
justification: 'Parse DOM'
});
await creating;
creating = null;
let contexts = await chrome.runtime.getContexts({
contextTypes: ['OFFSCREEN_DOCUMENT'],
documentUrls: [offscreenUrl]
});
console.log("contexts after create:", contexts);
}
}

chrome.action.onClicked.addListener(async () => {
await setupOffscreenDocument(OFFSCREEN_DOCUMENT_PATH);

// Array of HTML contents
const htmlContents = [
'<html><head></head><body><h1>Hello World 1</h1></body></html>',
// '<html><head></head><body><h1>Hello World 2</h1></body></html>',
// '<html><head></head><body><h1>Hello World 3</h1></body></html>',
// '<html><head></head><body><h1>Hello World 4</h1></body></html>',
// '<html><head></head><body><h1>Hello World 5</h1></body></html>'
];

// Send each HTML content to offscreen document
const processingPromises = [];
for (const htmlContent of htmlContents) {
processingPromises.push(sendMessageToOffscreenDocument('add-exclamationmarks-to-headings', htmlContent)
.then(() => console.log("parsed htmlcontent:", htmlContent))
.catch(error => console.error('Failed to process HTML content:', error)));
}
console.log('All HTML contents processed.');
Promise.all(processingPromises).then(result => {
console.log(result);
}).catch(error => console.log(`Error in promises ${error}`));

await closeOffscreenDocument();
});

async function sendMessageToOffscreenDocument(type, data) {
const messageId = generateUUID();
return new Promise((resolve, reject) => {
const messageHandler = (message, sender, sendResponse) => {
if (message.type === 'add-exclamationmarks-result' && message.id === messageId) {
chrome.runtime.onMessage.removeListener(messageHandler);
resolve(message.result);
}
};

chrome.runtime.onMessage.addListener(messageHandler);

chrome.runtime.sendMessage({
type,
target: 'offscreen',
data,
id: messageId
});
console.log("sended message to offscreen: ",type, data, messageId)
});
}

chrome.runtime.onMessage.addListener(handleMessages);

async function handleMessages(message) {
if (message.target !== 'background') {
return;
}

switch (message.type) {
case 'add-exclamationmarks-result':
handleAddExclamationMarkResult(message.data);
break;
default:
console.warn(`Unexpected message type received: '${message.type}'.`);
}
}

async function handleAddExclamationMarkResult(dom) {
console.log('Received dom', dom);
}

async function closeOffscreenDocument() {
if (!(await hasOffscreenDocument())) {
console.log("no offscreen document to close ")
return;
}
console.log("closing offscreen document")
await chrome.offscreen.closeDocument();
console.log("closed offscreen document");
}

async function hasOffscreenDocument() {
console.log("checking offscreen document")
if ('getContexts' in chrome.runtime) {
const contexts = await chrome.runtime.getContexts({
contextTypes: ['OFFSCREEN_DOCUMENT'],
documentUrls: [OFFSCREEN_DOCUMENT_PATH]
});
console.log("contexts", contexts)
return Boolean(contexts.length);
} else {
const matchedClients = await clients.matchAll();
console.log("matchedClients", matchedClients)
return matchedClients.some(client => client.url.includes(chrome.runtime.id));
}
}

function generateUUID() {
return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
const r = (Math.random() * 16) | 0;
const v = c === 'x' ? r : (r & 0x3) | 0x8;
return v.toString(16);
});
}



the offscreen code:

// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Registering this listener when the script is first executed ensures that the
// offscreen document will be able to receive messages when the promise returned
// by `offscreen.createDocument()` resolves.
chrome.runtime.onMessage.addListener(handleMessages);

// This function performs basic filtering and error checking on messages before
// dispatching the message to a more specific message handler.
async function handleMessages(message) {
// Return early if this message isn't meant for the offscreen document.
if (message.target !== 'offscreen') {
return false;
}
console.log("received message in offscreen:",message)
// Dispatch the message to an appropriate handler.
switch (message.type) {
case 'add-exclamationmarks-to-headings':
addExclamationMarksToHeadings(message.data);
break;
default:
console.warn(`Unexpected message type received: '${message.type}'.`);
return false;
}
}

function addExclamationMarksToHeadings(htmlString) {
const parser = new DOMParser();
const document = parser.parseFromString(htmlString, 'text/html');
document
.querySelectorAll('h1')
.forEach((heading) => (heading.textContent = heading.textContent + '!!!'));
sendToBackground(
'add-exclamationmarks-result',
document.documentElement.outerHTML
);
}

function sendToBackground(type, data) {
chrome.runtime.sendMessage({
type,
target: 'background',
data
});
console.log("sended message to background: ",type, data)
}


the output is like this:

WX20240602-090057@2x.png


Issues:

  1. When checking for existing contexts with chrome.runtime.getContexts, the contexts array is empty, even though the offscreen document has been created and is functioning.
  2. The offscreen document is able to process the messages and send back results correctly, but the service worker logs indicate that it can't find the offscreen document context when trying to close it.

Questions:

  1. Why is chrome.runtime.getContexts returning an empty array even though the offscreen document exists?
  2. Is there a more reliable way to check for the existence of the offscreen document?
  3. How can I ensure that the offscreen document is properly closed after processing all HTML contents?



woxxom

unread,
Jun 3, 2024, 5:37:17 AM6/3/24
to Chromium Extensions, fei liu
Google's sample is unnecessarily overcomplicated and demonstrates an anti-pattern of using a separate listener for messages where the proper solution is to use sendResponse, on top of that getContexts seems to be bugged in Chrome itself.

Everything can simplified without any loss of functionality. You can also send all strings in one message, the size limit is 64MB.

// background.js

chrome.action.onClicked.addListener(async () => {
  await chrome.offscreen.createDocument({
    url: '/offscreen.html',
    reasons: ['DOM_PARSER'],
    justification: 'MV3 requirement',
  }).catch(e => {
    if (e.message !== 'Only a single offscreen document may be created.') throw e;
  });
  const res = await chrome.runtime.sendMessage({
    type: 'add-exclamationmarks-to-headings',
    data: [

      '<html><head></head><body><h1>Hello World 1</h1></body></html>',
      '<html><head></head><body><h1>Hello World 2</h1></body></html>',
    ],
  });
  console.log(res);
  await chrome.offscreen.closeDocument();
});

// offscreen.js

chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.type === 'add-exclamationmarks-to-headings') {
    sendResponse(addExclamationMarksToHeadings(msg.data));
  }
});

function addExclamationMarksToHeadings(htmls) {

  const parser = new DOMParser();
  return htmls.map(html => {
    const doc = parser.parseFromString(html, 'text/html');
    for (const el of doc.querySelectorAll('h1')) el.append('!!!');
    return doc.documentElement.outerHTML;
  });
}

Note that `chrome` messaging in Chrome is limited to 64MB and JSON types (string, number, boolean, null, and arrays/objects consisting of the listed types). To send data types like Blob or typed arrays or overcome the 64MB limit you can use `navigator.serviceWorker` messaging, example: https://stackoverflow.com/a/77427098

Jackie Han

unread,
Jun 3, 2024, 9:23:29 AM6/3/24
to fei liu, Chromium Extensions
Your code has a bug in the hasOffscreenDocument() function.

// hasOffscreenDocument
  if ('getContexts' in chrome.runtime) {
    const contexts = await chrome.runtime.getContexts({
      contextTypes: ['OFFSCREEN_DOCUMENT'],
      documentUrls: [OFFSCREEN_DOCUMENT_PATH]
    });
  }

Here you pass OFFSCREEN_DOCUMENT_PATH  ('/offscreen.html') to documentUrls, it should be [chrome.runtime.getURL(OFFSCREEN_DOCUMENT_PATH)]; 
So hasOffscreenDocument returns an empty array. 

I suggest you just remove documentUrls in runtime.getContexts(). i.e. 

const contexts = await chrome.runtime.getContexts({
   contextTypes: ['OFFSCREEN_DOCUMENT']
});


--
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/8868ea51-edf4-4753-a455-4fb025818928n%40chromium.org.

woxxom

unread,
Jun 3, 2024, 9:31:50 AM6/3/24
to Chromium Extensions, Jackie Han, Chromium Extensions, fei liu
This is a bug in the API design/implementation because any context in an extension can only have its own origin, so getContexts() must process paths like '/offscreen.html' the same way it's done in chrome.tabs.create/update and other API.

Jackie Han

unread,
Jun 3, 2024, 9:45:26 AM6/3/24
to fei liu, Chromium Extensions
I know you copied the official document code. That code ( documentUrls: [OFFSCREEN_DOCUMENT_PATH]) is seriously misleading.

I just read the getContext() proposal. It says:
Document-related properties (documentId, documentUrl, documentOrigin) refer to the document associated with this context. For extension documents (such as tabs, popups, and offscreen documents), these will point to the extension (e.g., chrome-extension://<id>/popup.html). If/when we add support for content scripts, this will be the document the script is injected within. For service workers (which have no document), these are undefined.

In order to support content scripts in the future, they designed to use absolute URLs.


woxxom

unread,
Jun 3, 2024, 9:47:49 AM6/3/24
to Chromium Extensions, Jackie Han, Chromium Extensions, fei liu
Okay, that part makes sense, but chrome.tabs.create/update still recognize relative/absolute paths like those belonging to the extension, so lack of such processing makes the platform API fragmented. Either all methods should reject relative paths or getContexts should support them.

woxxom

unread,
Jun 3, 2024, 10:01:25 AM6/3/24
to Chromium Extensions, woxxom, Jackie Han, Chromium Extensions, fei liu
Furthermore, getContexts has a problem with documentOrigin and documentUrl, because they're not listed for the background script context, but the service worker actually does have a URL as can be seen by checking `location` in its context. I guess these properties should be deprecated in favor of `url` and `origin` that are present for the SW context as well.

woxxom

unread,
Jun 3, 2024, 10:57:00 AM6/3/24
to Chromium Extensions, woxxom, Jackie Han, Chromium Extensions, fei liu
The proposal says documentUrl is chosen because it "allows for potential future expansion where other URLs (such as script URLs) may exist" but it's unclear how that's better than having a unified url both for document or service worker url.

woxxom

unread,
Jun 3, 2024, 12:29:45 PM6/3/24
to Chromium Extensions, woxxom, Jackie Han, Chromium Extensions, fei liu
I think I see now. The plan was to add scriptUrl to match individual content scripts. Theoretically useful.
Reply all
Reply to author
Forward
0 new messages