diff options
Diffstat (limited to 'dom/interfaces/base/nsIServiceWorkerManager.idl')
| -rw-r--r-- | dom/interfaces/base/nsIServiceWorkerManager.idl | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/dom/interfaces/base/nsIServiceWorkerManager.idl b/dom/interfaces/base/nsIServiceWorkerManager.idl new file mode 100644 index 0000000000..d89da1ac9c --- /dev/null +++ b/dom/interfaces/base/nsIServiceWorkerManager.idl @@ -0,0 +1,308 @@ +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#include "domstubs.idl" +#include "nsIRequest.idl" + +interface mozIDOMWindow; +interface nsPIDOMWindowInner; +interface mozIDOMWindowProxy; +interface nsIArray; +interface nsIInterceptedChannel; +interface nsIPrincipal; +interface nsIRunnable; +interface nsIURI; +%{C++ +namespace mozilla { +namespace dom { +class ClientInfo; +class ServiceWorkerDescriptor; +} // namespace dom +} // namespace mozilla +%} + +[ref] native const_ClientInfoRef(const mozilla::dom::ClientInfo); +[ref] native const_ServiceWorkerDescriptorRef(const mozilla::dom::ServiceWorkerDescriptor); + +[scriptable, uuid(52ee2c9d-ee87-4caf-9588-23ae77ff8798)] +interface nsIServiceWorkerUnregisterCallback : nsISupports +{ + // aState is true if the unregistration succeded. + // It's false if this ServiceWorkerRegistration doesn't exist. + void unregisterSucceeded(in bool aState); + void unregisterFailed(); +}; + +interface nsIWorkerDebugger; + +[scriptable, builtinclass, uuid(76e357ed-208d-4e4c-9165-1c4059707879)] +interface nsIServiceWorkerInfo : nsISupports +{ + // State values below should match the ServiceWorkerState enumeration. + const unsigned short STATE_PARSED = 0; + const unsigned short STATE_INSTALLING = 1; + const unsigned short STATE_INSTALLED = 2; + const unsigned short STATE_ACTIVATING = 3; + const unsigned short STATE_ACTIVATED = 4; + const unsigned short STATE_REDUNDANT = 5; + const unsigned short STATE_UNKNOWN = 6; + + readonly attribute AString id; + + readonly attribute AString scriptSpec; + readonly attribute AString cacheName; + + readonly attribute unsigned short state; + + readonly attribute nsIWorkerDebugger debugger; + + // Return whether the ServiceWorker has a "fetch" event listener. Throws if + // this is unknown because the worker's main script hasn't finished executing + // (when exposed as evaluatingWorker). + readonly attribute bool handlesFetchEvents; + + readonly attribute PRTime installedTime; + readonly attribute PRTime activatedTime; + readonly attribute PRTime redundantTime; + + // Total number of navigation faults experienced by this ServiceWorker since + // it was loaded from disk at startup or was installed. + readonly attribute unsigned long navigationFaultCount; + + // Testing mechanism to induce synthetic failure of fetch events. If set to + // something other than NS_OK, all fetch events dispatched will be propagated + // to the content process, but when it comes time to dispatch the fetch event, + // the cancellation control flow path will be triggered. + attribute nsresult testingInjectCancellation; + + void attachDebugger(); + + void detachDebugger(); +}; + +[scriptable, uuid(87e63548-d440-4b8a-b158-65ad1de0211E)] +interface nsIServiceWorkerRegistrationInfoListener : nsISupports +{ + void onChange(); +}; + +[scriptable, builtinclass, uuid(ddbc1fd4-2f2e-4fca-a395-6e010bbedfe3)] +interface nsIServiceWorkerRegistrationInfo : nsISupports +{ + // State values below should match the ServiceWorkerUpdateViaCache enumeration. + const unsigned short UPDATE_VIA_CACHE_IMPORTS = 0; + const unsigned short UPDATE_VIA_CACHE_ALL = 1; + const unsigned short UPDATE_VIA_CACHE_NONE = 2; + + readonly attribute nsIPrincipal principal; + readonly attribute boolean unregistered; + + readonly attribute AString scope; + readonly attribute AString scriptSpec; + readonly attribute unsigned short updateViaCache; + + readonly attribute PRTime lastUpdateTime; + + readonly attribute nsIServiceWorkerInfo evaluatingWorker; + readonly attribute nsIServiceWorkerInfo installingWorker; + readonly attribute nsIServiceWorkerInfo waitingWorker; + readonly attribute nsIServiceWorkerInfo activeWorker; + + // Exposes the number of times we have ever checked the usage of this origin + // for the purposes of mitigating ServiceWorker navigation faults that we + // suspect to be due to quota limit problems. This should start out 0 and + // max out at 1 for the time being. + // + // Note that the underlying value is tracked on our per-Principal data, but + // we don't currently expose that data directly via XPCOM so we're exposing + // this here as the next best thing and because most non-test consumers would + // work in terms of the registration anyways. + // + // This will return -1 if there is no longer any per-origin data because the + // last registration for the origin (principal) has been unregistered. + // (Retaining a reference to this interface does not impact anything the + // underlying scope-to-registration map that is implemented per spec.) + readonly attribute long quotaUsageCheckCount; + + // Allows to get the related nsIServiceWorkerInfo for a given + // nsIWorkerDebugger. Over time we shouldn't need this anymore, + // and instead always control then nsIWorkerDebugger from + // nsIServiceWorkerInfo and not the other way around. Returns + // null if the service worker is no longer registered. + nsIServiceWorkerInfo getWorkerByID(in unsigned long long aID); + + void addListener(in nsIServiceWorkerRegistrationInfoListener listener); + + void removeListener(in nsIServiceWorkerRegistrationInfoListener listener); + + // Terminate all the service worker relate to this registration. + // This is used by the WebExtensions framework to shutdown the extension's + // background service workers as part of shutdown, which happens when: + // - the extension has been disabled. + // - the extension is shutting down to be updated. + // - the extension is shutting down as part of the uninstall flow. + // + // All the service workers instances related to this registration are expected + // to be terminate immediately. + // + // TODO - Bug 1638099: This method should also allow the WebExtension framework + // to mark the registration as disabled (e.g. through an additional parameter), + // to avoid it to be started again until the WebExtensions framework does explicitly + // mark it back to enabled. + void forceShutdown(); +}; + +[scriptable, uuid(9e523e7c-ad6f-4df0-8077-c74aebbc679d)] +interface nsIServiceWorkerManagerListener : nsISupports +{ + void onRegister(in nsIServiceWorkerRegistrationInfo aInfo); + + void onUnregister(in nsIServiceWorkerRegistrationInfo aInfo); + + /** + * Called by ServiceWorker bypass mitigations when checking whether an + * origin's quota usage is sufficiently full that we need to clear the origin + * (and possibly group's) data as part of our mitigation. + * This notification is provided primarily for testing code that needs to wait + * for this check to happen but has no other mechanism for knowing it's + * completed. Probably not relevant to devtools. + */ + void onQuotaUsageCheckFinish(in nsIServiceWorkerRegistrationInfo aInfo); +}; + +[scriptable, builtinclass, uuid(7404c8e8-4d47-4449-8ed1-47d1261d4e33)] +interface nsIServiceWorkerManager : nsISupports +{ + /** + * A testing helper that is meant to only be used in xpcshell-test to test behaviors + * that would need a browser restart to re-initialize the ServiceWorkerManager from + * the service worker registration dumped on disk (the one listed in the serviceworker.txt + * file part of the Firefox profile directory). + * + * NOTE: this test helper does + * - fail if "dom.serviceWorkers.testing.enabled" is not set to true + * - fail if there are controlled clients (the test case is responsible of making sure that + * there is none when this method is being called) + * - shutdown and clear all service worker registrations (but without removing them from + * the registration stored in serviceworker.txt) + * - force reload the registration data stored in serviceworker.txt (but the test case using + * this helper is responsible to be sure that the registrations have been already written + * on disk) + */ + void reloadRegistrationsForTest(); + + /** + * A testing helper that registers a service worker for testing purpose (e.g. used to test + * a remote worker that has to spawn a new process to be launched). + * This method can only be used when "dom.serviceWorkers.testing.enabled" is true and + * it doesn't support all the registration options (e.g. updateViaCache is set automatically + * to "imports"). + */ + [implicit_jscontext] + Promise registerForTest(in nsIPrincipal aPrincipal, + in AString aScope, + in AString aScriptURL); + + /** + * Register an extension background service worker for a given + * extension principal and return a promise that resolves to the + * nsIServiceWorkerRegistrationInfo (or rejects if there was one + * already registered). + */ + [implicit_jscontext] + Promise registerForAddonPrincipal(in nsIPrincipal aPrincipal); + + /** + * Get an extension background service worker registration for a + * given extension principal, return an nsIServiceWorkerRegistrationInfo + * if one exists (or null if no registration has been found). + */ + void getRegistrationForAddonPrincipal(in nsIPrincipal aPrincipal, + [optional, retval] out nsIServiceWorkerRegistrationInfo regInfo); + + /** + * Wake up the extension background service worker given its extension base url, + * for an API event identified by the namespace and event name strings. + * + * Returns a Promise which is resolved to true if a listener has been subscribed + * during the synchronous worker script execution for the expected WebExtensions + * API event. + * + * NOTE: ExtensionBrowser and ExtensionEventManager interfaces are keeping track + * of these listeners. These are WebExtensions API event listeners and they do not + * involve any functional events at all. + */ + [implicit_jscontext] + Promise wakeForExtensionAPIEvent(in AString aExtensionBaseURL, + in AString aAPINamespace, + in AString aAPIEventName); + + /** + * Unregister an existing ServiceWorker registration for `aScope`. + * It keeps aCallback alive until the operation is concluded. + */ + void unregister(in nsIPrincipal aPrincipal, + in nsIServiceWorkerUnregisterCallback aCallback, + in AString aScope); + + nsIServiceWorkerRegistrationInfo getRegistrationByPrincipal(in nsIPrincipal aPrincipal, + in AString aScope); + + [notxpcom, nostdcall] bool StartControlling(in const_ClientInfoRef aClientInfo, + in const_ServiceWorkerDescriptorRef aServiceWorker); + + // Testing + AString getScopeForUrl(in nsIPrincipal aPrincipal, in AString aPath); + + // It returns an array of nsIServiceWorkerRegistrationInfos. + nsIArray getAllRegistrations(); + + // For clear-origin-attributes-data + void removeRegistrationsByOriginAttributes(in AString aOriginAttributes); + + // It calls unregister() in each child process. The callback is used to + // inform when unregister() is completed on the current process. + void propagateUnregister(in nsIPrincipal aPrincipal, + in nsIServiceWorkerUnregisterCallback aCallback, + in AString aScope); + + void sendNotificationClickEvent(in ACString aOriginSuffix, + in ACString scope, + in AString aID, + in AString aTitle, + in AString aDir, + in AString aLang, + in AString aBody, + in AString aTag, + in AString aIcon, + in AString aData, + in AString aBehavior); + + void sendNotificationCloseEvent(in ACString aOriginSuffix, + in ACString scope, + in AString aID, + in AString aTitle, + in AString aDir, + in AString aLang, + in AString aBody, + in AString aTag, + in AString aIcon, + in AString aData, + in AString aBehavior); + + [optional_argc] void sendPushEvent(in ACString aOriginAttributes, + in ACString aScope, + [optional] in Array<uint8_t> aDataBytes); + void sendPushSubscriptionChangeEvent(in ACString aOriginAttributes, + in ACString scope); + + void addListener(in nsIServiceWorkerManagerListener aListener); + + void removeListener(in nsIServiceWorkerManagerListener aListener); +}; + +%{ C++ +#define SERVICEWORKERMANAGER_CONTRACTID "@mozilla.org/serviceworkers/manager;1" +%} |