Closed Bug 1891478 Opened 2 years ago Closed 4 months ago

Implement documentId in extension APIs

Categories

(WebExtensions :: General, enhancement, P3)

Product:
WebExtensions
Component:
General
Type:
enhancement

Tracking

(firefox153 fixed)

Status:
RESOLVED FIXED
Milestone:
153 Branch
Tracking Flags:
Tracking Status
firefox153 --- fixed

People

(Reporter: robwu, Assigned: robwu)

References

(Blocks 2 open bugs)

Details

(Keywords: dev-doc-complete, Whiteboard: [wecg][addons-jira])

Attachments

(7 external files)

The extension API currently has tabId + frameId to identify specific frames. Several APIs (e.g. scripting.executeScript) support a way to run code in that specific frame. The issue with the current API is that the document may have navigated between notifying the extension and the call to scripting.executeScript. We therefore need a way for extensions to target specific documents, independent of the frame.

Chrome introduced the documentId concept to identify specific document instances, coupled with the documentLifeCycle and frameType properties. This was announced at https://developer.chrome.com/blog/extension-instantnav/

Note: in the WECG there are several requests/proposals/enhancements that rely on documentId as a primitive: https://github.com/w3c/webextensions/issues?q=is%3Aissue+documentId

Blocks: 1891480
See Also: → 1930776

There is still no official "spec" for documentId, but we discussed runtime.getDocumentId (to complement runtime.getFrameId) at https://github.com/w3c/webextensions/issues/800.

See Also: → https://github.com/w3c/webextensions/issues/800

New WECG ticket filed about standardizing documentId: https://github.com/w3c/webextensions/issues/890

I left a comment describing all APIs that currently support documentId in Chrome, at https://github.com/w3c/webextensions/issues/890#issuecomment-3446258636

See Also: → https://github.com/w3c/webextensions/issues/890
Assignee: nobody → rob
Depends on: 2037284
Depends on: 1750196

I'd consider tabs.query to be out of scope for this bug. The PR proposal is still open and there are no implementations in Safari and Chrome. Moreover I question the utility in its design when there is no tabs.Tab.documentId counterpart. I expressed these thoughts here: https://github.com/w3c/webextensions/issues/553#issuecomment-4416596765

Depends on: 2040339
See Also: → 2036556

Introduces ExtensionDocumentId.sys.mjs as the module responsible for
mapping innerWindowId to documentId UUIDs. This module will be used by
any extension API needing a documentId, starting with
runtime.getDocumentId in this patch.

Attachment #9593364 - Attachment description: Bug 1891478 - Add documentId to scripting API → Bug 1891478 - Add documentId to scripting and userScripts API
See Also: → 2047009

Given the many APIs touched here, here is a full list of what is (and in some cases not implemented).
Where parentDocumentId is mentioned, it is only set if a parent document exists, otherwise the field is omitted.
I also includes references to relevant WECG issues / proposals for future reference.

  • runtime namespace:
  • scripting namespace:
    • scripting.executeScript, scripting.insertCSS and scripting.removeCSS now support target.documentId (InjectionTarget.documentId)
    • scripting.executeScript - includes documentId in all results (InjectionResult type)
  • userScripts namespaces:
  • tabs namespace:
    • tabs.connect - options.documentId supported
    • tabs.sendMessage - options.documentId supported
    • (tabs.executeScript, insertCSS and removeCSS did NOT get documentId support - use scripting API instead)
  • webNavigation namespace:
    • webNavigation.getAllFrames() - documentId and parentDocumentId includes in returned objects
    • webNavigation.getFrame() - details.documentId option introduced, details.frameId is now optional. Returned object includes documentId option.
    • webNavigation.onBeforeNavigate - parentDocumentId only (no documentId because the target document does not exist yet)
    • webNavigation.onCommitted - documentId and parentDocumentId
    • webNavigation.onDOMContentLoaded - documentId and parentDocumentId
    • webNavigation.onCompleted - documentId and parentDocumentId
    • webNavigation.onErrorOccurred - documentId and parentDocumentId
    • webNavigation.onCreatedNavigationTarget - (no changes, target document does not exist; there was already an sourceFrameId so an equivalent could have been sourceDocumentId, but Chrome does not have this either, so I did not bother adding it)
    • webNavigation.onReferenceFragmentUpdated - documentId,parentDocumentId
    • webNavigation.onTabReplaced - (no changes, does not relate to documents, we never fire it either)
    • webNavigation.onHistoryStateUpdated - documentId and parentDocumentId
  • webRequest namespace:
    • all webRequest events receive documentId and parentDocumentId when applicable. Document navigations do not have documentId set since their target document is unknown.
  • proxy namespace:
    • proxy.onRequest event receives documentId and parentDocumentId when applicable.

I considered the following but did not proceed with their implementation. They are not implemented by any other browser either:

EDIT: runtime.sendMesage and runtime.connect were erroneously listed as accepting documentId; that is not the case, but there is an open proposal for the option at https://github.com/w3c/webextensions/issues/294

Keywords: dev-doc-needed
See Also: → 2047351

Documentation updates in:

Flags: needinfo?(rob)
Keywords: dev-doc-needed → dev-doc-complete
Flags: needinfo?(rob)
Regressions: 2050882
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Creator:
Created:
Updated:
Size: