1 files changed, 192 insertions, 0 deletions
diff --git a/toolkit/components/extensions/mozIExtensionAPIRequestHandling.idl b/toolkit/components/extensions/mozIExtensionAPIRequestHandling.idl
new file mode 100644
index 0000000000..0a2e3c7a5d
--- /dev/null
+++ b/toolkit/components/extensions/mozIExtensionAPIRequestHandling.idl
@@ -0,0 +1,192 @@
+/* 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 "nsISupports.idl"
+
+interface nsIPrincipal;
+
+[scriptable, builtinclass, uuid(e6862533-8844-4207-a6ab-04748a29d859)]
+interface mozIExtensionServiceWorkerInfo : nsISupports
+{
+  readonly attribute nsIPrincipal principal;
+  readonly attribute AString scriptURL;
+  readonly attribute AString clientInfoId;
+  readonly attribute unsigned long long descriptorId;
+};
+
+[scriptable, uuid(876d45db-5c1b-4c9b-9148-1c86b33d120b)]
+interface mozIExtensionListenerCallOptions : nsISupports
+{
+  cenum APIObjectType: 8 {
+    // Default: no api object is prepended to the event listener call arguments.
+    NONE,
+
+    // A runtime.Port instance is prepended to the event listener call arguments.
+    RUNTIME_PORT,
+  };
+
+  readonly attribute mozIExtensionListenerCallOptions_APIObjectType apiObjectType;
+
+  // An optional javascript object that should provide the attributes expected
+  // by related apiObjectType webidl dictionary type (e.g. ExtensionPortDescriptor
+  // if apiObjectType is RUNTIME_PORT).
+  readonly attribute jsval apiObjectDescriptor;
+
+  // An optional boolean to be set to true if the api object should be
+  // prepended to the rest of the call arguments (by default it is appended).
+  readonly attribute bool apiObjectPrepended;
+
+  cenum CallbackType: 8 {
+    // Default: no callback argument is passed to the call to the event listener.
+    CALLBACK_NONE,
+
+    // The event listener will be called with a function as the last call parameter
+    // that behaves like the runtime.onMessage's sendResponse parameter:
+    //
+    // - if the event listener already returned false, sendResponse calls are ignored
+    //   (if it has not been called already)
+    // - if the event listener already returned true, the first sendResponse call
+    //   resolves the promise returned by the mozIExtensionCallback method call
+    // - if the event listener already returned a Promise, sendResponse calls
+    //   are ignored
+    CALLBACK_SEND_RESPONSE,
+  };
+
+  attribute mozIExtensionListenerCallOptions_CallbackType callbackType;
+};
+
+[scriptable, builtinclass, uuid(e68e3c19-1b35-4112-8faa-5c5b84086a5b)]
+interface mozIExtensionEventListener : nsISupports
+{
+  [implicit_jscontext, can_run_script]
+  Promise callListener(
+    in Array<jsval> args,
+    [optional] in mozIExtensionListenerCallOptions listenerCallOptions);
+};
+
+[scriptable, builtinclass, uuid(0fee1c8f-e363-46a6-bd0c-d3c3338e2534)]
+interface mozIExtensionAPIRequest : nsISupports
+{
+  AUTF8String toString();
+
+  // Determine what the caller and receiver should expect, e.g. what should
+  // be provided to the API request handler and what to expect it to return.
+  cenum RequestType: 8 {
+    CALL_FUNCTION,
+    CALL_FUNCTION_NO_RETURN,
+    CALL_FUNCTION_ASYNC,
+    ADD_LISTENER,
+    REMOVE_LISTENER,
+    GET_PROPERTY,
+  };
+
+  // The type of the request.
+  readonly attribute AUTF8String requestType;
+
+  // WebExtension API namespace (e.g. tabs, runtime, webRequest, ...)
+  readonly attribute AUTF8String apiNamespace;
+  // method or event name
+  readonly attribute AUTF8String apiName;
+
+  // API object type (e.g. Port, Panel, ...) and its unique id, this
+  // properties are used by API requests originated by an API object
+  // instance (like a runtime Port returned by browser.runtime.connect).
+  readonly attribute AUTF8String apiObjectType;
+  readonly attribute AUTF8String apiObjectId;
+
+  // An array of API call arguments.
+  [implicit_jscontext] readonly attribute jsval args;
+
+  // A property to store on the request objects the arguments normalized
+  // based on the API jsonschema, so that they are being propagated along
+  // with the API request object.
+  // TODO: change this attribute to a readonly attribute if we moved
+  // the parameters validation and normalization to the C++ layer.
+  [implicit_jscontext] attribute jsval normalizedArgs;
+
+  // The caller SavedFrame (only set for calls originated off of the main thread
+  // from a service worker).
+  [implicit_jscontext] readonly attribute jsval callerSavedFrame;
+
+  // Set for requests coming from an extension service worker.
+  readonly attribute mozIExtensionServiceWorkerInfo serviceWorkerInfo;
+
+  // Set for `addListener`/`removeListener` API requests.
+  readonly attribute mozIExtensionEventListener eventListener;
+};
+
+[scriptable, uuid(59fd4097-d88e-40fd-8664-fedd8ab67ab6)]
+interface mozIExtensionAPIRequestResult : nsISupports
+{
+  cenum ResultType: 8 {
+    // The result is a value to be returned as a result for the API request.
+    // The value attribute can be set to:
+    // - a structured clonable result value (which may be the result of the
+    //   API call itself, or be used by the API method webidl implementation
+    //   to initialize a webidl object to return to the caller, e.g.
+    //   ExtensionPort returned by a call to browser.runtime.connect())
+    // - an error object (which also include internally converted to and from
+    //   ClonedErrorHolder to make it structured clonable).
+    // - a Promise (which can be resolved to a structured clonable value or
+    //   an error object).
+    RETURN_VALUE,
+
+    // The result is an error object that should be thrown as an extension error
+    // to the caller on the thread that originated the request.
+    EXTENSION_ERROR,
+  };
+
+  readonly attribute mozIExtensionAPIRequestResult_ResultType type;
+  readonly attribute jsval value;
+};
+
+[scriptable, uuid(0c61bd33-0557-43a2-9497-96c449f39e33)]
+interface mozIExtensionAPIRequestHandler : nsISupports
+{
+  /**
+   * Handle an API request originated from the WebExtensions webidl API
+   * bindings.
+   *
+   * @param extension An instance of the WebExtensionPolicy webidl interface.
+   * @param apiRequest An instance of the mozIExtensionAPIRequest xpcom interface.
+   *
+   * @return mozIExtensionAPIRequestResult
+   *         JS value returned by the API request handler, may contain a value
+   *         (the result of the API call or a WebIDL dictionary that is used to
+   *         initialize WebIDL-based API object, e.g. ExtensionPort) or
+   *         an Error to be throw on the thread that originated the request.
+   */
+  void handleAPIRequest(in nsISupports extension,
+                        in mozIExtensionAPIRequest apiRequest,
+                        [optional, retval] out mozIExtensionAPIRequestResult apiRequestResult);
+
+  /**
+   * A method called when an extension background service worker is initialized and
+   * ready to execute its main script.
+   *
+   * @param extension An instance of the WebExtensionPolicy webidl interface.
+   * @param serviceWorkerInfo
+   */
+  void initExtensionWorker(in nsISupports extension,
+                           in mozIExtensionServiceWorkerInfo serviceWorkerInfo);
+
+  /**
+   * A method called when an extension background service worker has loaded its
+   * main script.
+   *
+   * @param extension An instance of the WebExtensionPolicy webidl interface.
+   * @param serviceWorkerDescriptorId
+   */
+   void onExtensionWorkerLoaded(in nsISupports extension,
+                                in unsigned long long serviceWorkerDescriptorId);
+
+  /**
+   * A method called when an extension background service worker is destroyed.
+   *
+   * @param extension An instance of the WebExtensionPolicy webidl interface.
+   * @param serviceWorkerDescriptorId
+   */
+   void onExtensionWorkerDestroyed(in nsISupports extension,
+                                   in unsigned long long serviceWorkerDescriptorId);
+};