Proposal: filter by documentId in tabs.query()

[bershanskiy]

Background

tabs.query() is not currently aware of tabs being navigated and moved around, so there is very little information to refer to the same document. Luckily, most use cases require querying info about the active tab, which happens to be the default behavior for this API. Unfortunately, some use cases require querying info about non-active tabs. Currently, the best way to match a document belonging to an inactive tab is to refer to its coincidental mutable non-unique attributes like its location (window id and an index on tab strip), its URL or title, which are problematic from privacy perspective.

Problem

tabs.query() and other APIs under tabs are async and inherently racy. For example, the background may get a message from content script, call tabs.query() to get more information about the sender and receive a response containing information about a different document (because the tab may navigate between the message being sent and the tabs.query() being called).

Proposal

Extend tabs.query(queryInfo: QueryInfo, callback)argument QueryInfo (Chrome docs, MDN) to take optional documentId argument.

If developer specifies documentId, browser returns only the tab which currently hosts the corresponding document. If the provided documentId has invalid format, then an error is returned. If provided documentId is semantically valid, but browser is not aware of a document with this id, then nothing is matched so an empty array is returned (since this may be an id from an older browser session, tab open on a different device and synced via storage.sync or something like this). If the provided documentId corresponds to a sub-frame or a top-level frame currently sitting in BFCache, then nothing is returned to match existing behavior.

Relevant links

• Chromium bug: https://issues.chromium.org/issues/326749718
• Chromium CL: https://chromium-review.googlesource.com/c/chromium/src/+/5318738
• Proposal: Include documentId in Tab object #496
• Proposal: documentId in tabs.query() filter #586

[carlosjeurissen]

I'm curious about this (the subframe behavior). It seems like being able to query which tab holds a document could be useful, independent of if it's a main frame or subframe (e.g., for querying which tab holds a particular frame that the extension may have injected into via a scripting API).
Originally posted by @rdcronin in #586 (comment)

In general does it really make sense to have this functionality under tabs.query()? If we disconnect this from tabs.query, and instead extend runtime.getContexts() to support any document existing in the browser. You can imagine running:

browser.runtime.getContexts({
  documentIds: [documentId],
});

If only top level contexts should be returned, you would run:

browser.runtime.getContexts({
  documentIds: [documentId],
  frameIds: [0],
});

To check if a specific tabId/frameId still has the same document:

const context = await browser.runtime.getContexts({
  documentIds: [documentId],
  frameIds: [0],
  tabIds: [135135],
});
const documentLostInTime = !context[0];

You will end up with an API covering much more use cases. If the returned context object does not have all the required properties, it can be given to tabs.get(tabId).

@bershanskiy would that cover the race conditions you are talking about? Nontheless extending getContexts() with other non-extension contexts would be very valuable.

As a sidenote, passing documentId in tabs.query in some browsers may be ignored without warnings/errors. So when introducing this filter it would be very valuable to address #769 (comment) as well.