diff options
Diffstat (limited to '')
29 files changed, 4527 insertions, 0 deletions
diff --git a/devtools/shared/protocol.js b/devtools/shared/protocol.js new file mode 100644 index 0000000000..5ed63fbc23 --- /dev/null +++ b/devtools/shared/protocol.js @@ -0,0 +1,36 @@ +/* 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/. */ + +"use strict"; + +var { Actor } = require("resource://devtools/shared/protocol/Actor.js"); +var { Pool } = require("resource://devtools/shared/protocol/Pool.js"); +var { + types, + registerFront, + getFront, + createRootFront, +} = require("resource://devtools/shared/protocol/types.js"); +var { Front } = require("resource://devtools/shared/protocol/Front.js"); +var { + FrontClassWithSpec, +} = require("resource://devtools/shared/protocol/Front/FrontClassWithSpec.js"); +var { Arg, Option } = require("resource://devtools/shared/protocol/Request.js"); +const { RetVal } = require("resource://devtools/shared/protocol/Response.js"); +const { + generateActorSpec, +} = require("resource://devtools/shared/protocol/Actor/generateActorSpec.js"); + +exports.Front = Front; +exports.Pool = Pool; +exports.Actor = Actor; +exports.types = types; +exports.generateActorSpec = generateActorSpec; +exports.FrontClassWithSpec = FrontClassWithSpec; +exports.Arg = Arg; +exports.Option = Option; +exports.RetVal = RetVal; +exports.registerFront = registerFront; +exports.getFront = getFront; +exports.createRootFront = createRootFront; diff --git a/devtools/shared/protocol/Actor.js b/devtools/shared/protocol/Actor.js new file mode 100644 index 0000000000..ea37f6fea2 --- /dev/null +++ b/devtools/shared/protocol/Actor.js @@ -0,0 +1,260 @@ +/* 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/. */ + +"use strict"; + +var { Pool } = require("resource://devtools/shared/protocol/Pool.js"); + +/** + * Keep track of which actorSpecs have been created. If a replica of a spec + * is created, it can be caught, and specs which inherit from other specs will + * not overwrite eachother. + */ +var actorSpecs = new WeakMap(); + +exports.actorSpecs = actorSpecs; + +/** + * An actor in the actor tree. + * + * @param optional conn + * Either a DevToolsServerConnection or a DevToolsClient. Must have + * addActorPool, removeActorPool, and poolFor. + * conn can be null if the subclass provides a conn property. + * @constructor + */ + +class Actor extends Pool { + constructor(conn, spec) { + super(conn); + + this.typeName = spec.typeName; + + // Will contain the actor's ID + this.actorID = null; + + // Ensure computing requestTypes only one time per class + const proto = Object.getPrototypeOf(this); + if (!proto.requestTypes) { + proto.requestTypes = generateRequestTypes(spec); + } + + // Forward events to the connection. + if (spec.events) { + for (const [name, request] of spec.events.entries()) { + this.on(name, (...args) => { + this._sendEvent(name, request, ...args); + }); + } + } + } + + toString() { + return "[Actor " + this.typeName + "/" + this.actorID + "]"; + } + + _sendEvent(name, request, ...args) { + if (this.isDestroyed()) { + console.error( + `Tried to send a '${name}' event on an already destroyed actor` + + ` '${this.typeName}'` + ); + return; + } + let packet; + try { + packet = request.write(args, this); + } catch (ex) { + console.error("Error sending event: " + name); + throw ex; + } + packet.from = packet.from || this.actorID; + this.conn.send(packet); + + // This can really be a hot path, even computing the marker label can + // have some performance impact. + // Guard against missing `Services.profiler` because Services is mocked to + // an empty object in the worker loader. + if (Services.profiler?.IsActive()) { + ChromeUtils.addProfilerMarker( + "DevTools:RDP Actor", + null, + `${this.typeName}.${name}` + ); + } + } + + destroy() { + super.destroy(); + this.actorID = null; + this._isDestroyed = true; + } + + /** + * Override this method in subclasses to serialize the actor. + * @param [optional] string hint + * Optional string to customize the form. + * @returns A jsonable object. + */ + form(hint) { + return { actor: this.actorID }; + } + + writeError(error, typeName, method) { + console.error( + `Error while calling actor '${typeName}'s method '${method}'`, + error.message || error + ); + // Also log the error object as-is in order to log the server side stack + // nicely in the console, while the previous log will log the client side stack only. + if (error.stack) { + console.error(error); + } + + // Do not try to send the error if the actor is destroyed + // as the connection is probably also destroyed and may throw. + if (this.isDestroyed()) { + return; + } + + this.conn.send({ + from: this.actorID, + // error.error -> errors created using the throwError() helper + // error.name -> errors created using `new Error` or Components.exception + // typeof(error)=="string" -> a method thrown like this `throw "a string"` + error: + error.error || + error.name || + (typeof error == "string" ? error : "unknownError"), + message: error.message, + // error.fileName -> regular Error instances + // error.filename -> errors created using Components.exception + fileName: error.fileName || error.filename, + lineNumber: error.lineNumber, + columnNumber: error.columnNumber, + }); + } + + _queueResponse(create) { + const pending = this._pendingResponse || Promise.resolve(null); + const response = create(pending); + this._pendingResponse = response; + } + + /** + * Throw an error with the passed message and attach an `error` property to the Error + * object so it can be consumed by the writeError function. + * @param {String} error: A string (usually a single word serving as an id) that will + * be assign to error.error. + * @param {String} message: The string that will be passed to the Error constructor. + * @throws This always throw. + */ + throwError(error, message) { + const err = new Error(message); + err.error = error; + throw err; + } +} + +exports.Actor = Actor; + +/** + * Generate the "requestTypes" object used by DevToolsServerConnection to implement RDP. + * When a RDP packet is received for calling an actor method, this lookup for + * the method name in this object and call the function holded on this attribute. + * + * @params {Object} actorSpec + * The procotol-js actor specific coming from devtools/shared/specs/*.js files + * This describes the types for methods and events implemented by all actors. + * @return {Object} requestTypes + * An object where attributes are actor method names + * and values are function implementing these methods. + * These methods receive a RDP Packet (JSON-serializable object) and a DevToolsServerConnection. + * We expect them to return a promise that reserves with the response object + * to send back to the client (JSON-serializable object). + */ +var generateRequestTypes = function (actorSpec) { + // Generate request handlers for each method definition + const requestTypes = Object.create(null); + actorSpec.methods.forEach(spec => { + const handler = function (packet, conn) { + try { + const startTime = isWorker ? null : Cu.now(); + let args; + try { + args = spec.request.read(packet, this); + } catch (ex) { + console.error("Error reading request: " + packet.type); + throw ex; + } + + if (!this[spec.name]) { + throw new Error( + `Spec for '${actorSpec.typeName}' specifies a '${spec.name}'` + + ` method that isn't implemented by the actor` + ); + } + const ret = this[spec.name].apply(this, args); + + const sendReturn = retToSend => { + if (spec.oneway) { + // No need to send a response. + return; + } + if (this.isDestroyed()) { + console.error( + `Tried to send a '${spec.name}' method reply on an already destroyed actor` + + ` '${this.typeName}'` + ); + return; + } + + let response; + try { + response = spec.response.write(retToSend, this); + } catch (ex) { + console.error("Error writing response to: " + spec.name); + throw ex; + } + response.from = this.actorID; + // If spec.release has been specified, destroy the object. + if (spec.release) { + try { + this.destroy(); + } catch (e) { + this.writeError(e, actorSpec.typeName, spec.name); + return; + } + } + + conn.send(response); + + ChromeUtils.addProfilerMarker( + "DevTools:RDP Actor", + startTime, + `${actorSpec.typeName}:${spec.name}()` + ); + }; + + this._queueResponse(p => { + return p + .then(() => ret) + .then(sendReturn) + .catch(e => this.writeError(e, actorSpec.typeName, spec.name)); + }); + } catch (e) { + this._queueResponse(p => { + return p.then(() => + this.writeError(e, actorSpec.typeName, spec.name) + ); + }); + } + }; + + requestTypes[spec.request.type] = handler; + }); + + return requestTypes; +}; +exports.generateRequestTypes = generateRequestTypes; diff --git a/devtools/shared/protocol/Actor/generateActorSpec.js b/devtools/shared/protocol/Actor/generateActorSpec.js new file mode 100644 index 0000000000..9b3b166c8b --- /dev/null +++ b/devtools/shared/protocol/Actor/generateActorSpec.js @@ -0,0 +1,62 @@ +/* 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/. */ + +"use strict"; + +var { Request } = require("resource://devtools/shared/protocol/Request.js"); +const { Response } = require("resource://devtools/shared/protocol/Response.js"); +var { + types, + registeredTypes, +} = require("resource://devtools/shared/protocol/types.js"); + +/** + * Generates an actor specification from an actor description. + */ +var generateActorSpec = function (actorDesc) { + const actorSpec = { + typeName: actorDesc.typeName, + methods: [], + }; + + // Find additional method specifications + if (actorDesc.methods) { + for (const name in actorDesc.methods) { + const methodSpec = actorDesc.methods[name]; + const spec = {}; + + spec.name = methodSpec.name || name; + spec.request = new Request( + Object.assign({ type: spec.name }, methodSpec.request || undefined) + ); + spec.response = new Response(methodSpec.response || undefined); + spec.release = methodSpec.release; + spec.oneway = methodSpec.oneway; + + actorSpec.methods.push(spec); + } + } + + // Find event specifications + if (actorDesc.events) { + actorSpec.events = new Map(); + for (const name in actorDesc.events) { + const eventRequest = actorDesc.events[name]; + Object.freeze(eventRequest); + actorSpec.events.set( + name, + new Request(Object.assign({ type: name }, eventRequest)) + ); + } + } + + if (!registeredTypes.has(actorSpec.typeName)) { + types.addActorType(actorSpec.typeName); + } + registeredTypes.get(actorSpec.typeName).actorSpec = actorSpec; + + return actorSpec; +}; + +exports.generateActorSpec = generateActorSpec; diff --git a/devtools/shared/protocol/Actor/moz.build b/devtools/shared/protocol/Actor/moz.build new file mode 100644 index 0000000000..3e3c46d49b --- /dev/null +++ b/devtools/shared/protocol/Actor/moz.build @@ -0,0 +1,8 @@ +# vim: set filetype=python: +# 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/. + +DevToolsModules( + "generateActorSpec.js", +) diff --git a/devtools/shared/protocol/Front.js b/devtools/shared/protocol/Front.js new file mode 100644 index 0000000000..32aed37b35 --- /dev/null +++ b/devtools/shared/protocol/Front.js @@ -0,0 +1,411 @@ +/* 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/. */ + +"use strict"; + +var { settleAll } = require("resource://devtools/shared/DevToolsUtils.js"); +var EventEmitter = require("resource://devtools/shared/event-emitter.js"); + +var { Pool } = require("resource://devtools/shared/protocol/Pool.js"); +var { + getStack, + callFunctionWithAsyncStack, +} = require("resource://devtools/shared/platform/stack.js"); +const defer = require("resource://devtools/shared/defer.js"); + +/** + * Base class for client-side actor fronts. + * + * @param [DevToolsClient|null] conn + * The conn must either be DevToolsClient or null. Must have + * addActorPool, removeActorPool, and poolFor. + * conn can be null if the subclass provides a conn property. + * @param [Target|null] target + * If we are instantiating a target-scoped front, this is a reference to the front's + * Target instance, otherwise this is null. + * @param [Front|null] parentFront + * The parent front. This is only available if the Front being initialized is a child + * of a parent front. + * @constructor + */ +class Front extends Pool { + constructor(conn = null, targetFront = null, parentFront = null) { + super(conn); + if (!conn) { + throw new Error("Front without conn"); + } + this.actorID = null; + // The targetFront attribute represents the debuggable context. Only target-scoped + // fronts and their children fronts will have the targetFront attribute set. + this.targetFront = targetFront; + // The parentFront attribute points to its parent front. Only children of + // target-scoped fronts will have the parentFront attribute set. + this.parentFront = parentFront; + this._requests = []; + + // Front listener functions registered via `watchFronts` + this._frontCreationListeners = null; + this._frontDestructionListeners = null; + + // List of optional listener for each event, that is processed immediatly on packet + // receival, before emitting event via EventEmitter on the Front. + // These listeners are register via Front.before function. + // Map(Event Name[string] => Event Listener[function]) + this._beforeListeners = new Map(); + + // This flag allows to check if the `initialize` method has resolved. + // Used to avoid notifying about initialized fronts in `watchFronts`. + this._initializeResolved = false; + } + + /** + * Return the parent front. + */ + getParent() { + return this.parentFront && this.parentFront.actorID + ? this.parentFront + : null; + } + + destroy() { + // Prevent destroying twice if a `forwardCancelling` event has already been received + // and already called `baseFrontClassDestroy` + this.baseFrontClassDestroy(); + + // Keep `clearEvents` out of baseFrontClassDestroy as we still want TargetMixin to be + // able to emit `target-destroyed` after we called baseFrontClassDestroy from DevToolsClient.purgeRequests. + this.clearEvents(); + } + + // This method is also called from `DevToolsClient`, when a connector is destroyed + // and we should: + // - reject all pending request made to the remote process/target/thread. + // - avoid trying to do new request against this remote context. + // - unmanage this front, so that DevToolsClient.getFront no longer returns it. + // + // When a connector is destroyed a `forwardCancelling` RDP event is sent by the server. + // This is done in a distinct method from `destroy` in order to do all that immediately, + // even if `Front.destroy` is overloaded by an async method. + baseFrontClassDestroy() { + // Reject all outstanding requests, they won't make sense after + // the front is destroyed. + while (this._requests.length) { + const { deferred, to, type, stack } = this._requests.shift(); + // Note: many tests are ignoring `Connection closed` promise rejections, + // via PromiseTestUtils.allowMatchingRejectionsGlobally. + // Do not update the message without updating the tests. + const msg = + "Connection closed, pending request to " + + to + + ", type " + + type + + " failed" + + "\n\nRequest stack:\n" + + stack.formattedStack; + deferred.reject(new Error(msg)); + } + + if (this.actorID) { + super.destroy(); + this.actorID = null; + } + this._isDestroyed = true; + + this.targetFront = null; + this.parentFront = null; + this._frontCreationListeners = null; + this._frontDestructionListeners = null; + this._beforeListeners = null; + } + + async manage(front, form, ctx) { + if (!front.actorID) { + throw new Error( + "Can't manage front without an actor ID.\n" + + "Ensure server supports " + + front.typeName + + "." + ); + } + + if (front.parentFront && front.parentFront !== this) { + throw new Error( + `${this.actorID} (${this.typeName}) can't manage ${front.actorID} + (${front.typeName}) since it has a different parentFront ${ + front.parentFront + ? front.parentFront.actorID + "(" + front.parentFront.typeName + ")" + : "<no parentFront>" + }` + ); + } + + super.manage(front); + + if (typeof front.initialize == "function") { + await front.initialize(); + } + front._initializeResolved = true; + + // Ensure calling form() *before* notifying about this front being just created. + // We exprect the front to be fully initialized, especially via its form attributes. + // But do that *after* calling manage() so that the front is already registered + // in Pools and can be fetched by its ID, in case a child actor, created in form() + // tries to get a reference to its parent via the actor ID. + if (form) { + front.form(form, ctx); + } + + // Call listeners registered via `watchFronts` method + // (ignore if this front has been destroyed) + if (this._frontCreationListeners) { + this._frontCreationListeners.emit(front.typeName, front); + } + } + + async unmanage(front) { + super.unmanage(front); + + // Call listeners registered via `watchFronts` method + if (this._frontDestructionListeners) { + this._frontDestructionListeners.emit(front.typeName, front); + } + } + + /* + * Listen for the creation and/or destruction of fronts matching one of the provided types. + * + * @param {String} typeName + * Actor type to watch. + * @param {Function} onAvailable (optional) + * Callback fired when a front has been just created or was already available. + * The function is called with one arguments, the front. + * @param {Function} onDestroy (optional) + * Callback fired in case of front destruction. + * The function is called with the same argument than onAvailable. + */ + watchFronts(typeName, onAvailable, onDestroy) { + if (this.isDestroyed()) { + // The front was already destroyed, bail out. + console.error( + `Tried to call watchFronts for the '${typeName}' type on an ` + + `already destroyed front '${this.typeName}'.` + ); + return; + } + + if (onAvailable) { + // First fire the callback on fronts with the correct type and which have + // been initialized. If initialize() is still in progress, the front will + // be emitted via _frontCreationListeners shortly after. + for (const front of this.poolChildren()) { + if (front.typeName == typeName && front._initializeResolved) { + onAvailable(front); + } + } + + if (!this._frontCreationListeners) { + this._frontCreationListeners = new EventEmitter(); + } + // Then register the callback for fronts instantiated in the future + this._frontCreationListeners.on(typeName, onAvailable); + } + + if (onDestroy) { + if (!this._frontDestructionListeners) { + this._frontDestructionListeners = new EventEmitter(); + } + this._frontDestructionListeners.on(typeName, onDestroy); + } + } + + /** + * Stop listening for the creation and/or destruction of a given type of fronts. + * See `watchFronts()` for documentation of the arguments. + */ + unwatchFronts(typeName, onAvailable, onDestroy) { + if (this.isDestroyed()) { + // The front was already destroyed, bail out. + console.error( + `Tried to call unwatchFronts for the '${typeName}' type on an ` + + `already destroyed front '${this.typeName}'.` + ); + return; + } + + if (onAvailable && this._frontCreationListeners) { + this._frontCreationListeners.off(typeName, onAvailable); + } + if (onDestroy && this._frontDestructionListeners) { + this._frontDestructionListeners.off(typeName, onDestroy); + } + } + + /** + * Register an event listener that will be called immediately on packer receival. + * The given callback is going to be called before emitting the event via EventEmitter + * API on the Front. Event emitting will be delayed if the callback is async. + * Only one such listener can be registered per type of event. + * + * @param String type + * Event emitted by the actor to intercept. + * @param Function callback + * Function that will process the event. + */ + before(type, callback) { + if (this._beforeListeners.has(type)) { + throw new Error( + `Can't register multiple before listeners for "${type}".` + ); + } + this._beforeListeners.set(type, callback); + } + + toString() { + return "[Front for " + this.typeName + "/" + this.actorID + "]"; + } + + /** + * Update the actor from its representation. + * Subclasses should override this. + */ + form(form) {} + + /** + * Send a packet on the connection. + */ + send(packet) { + if (packet.to) { + this.conn._transport.send(packet); + } else { + packet.to = this.actorID; + // The connection might be closed during the promise resolution + if (this.conn && this.conn._transport) { + this.conn._transport.send(packet); + } + } + } + + /** + * Send a two-way request on the connection. + */ + request(packet) { + const deferred = defer(); + // Save packet basics for debugging + const { to, type } = packet; + this._requests.push({ + deferred, + to: to || this.actorID, + type, + stack: getStack(), + }); + this.send(packet); + return deferred.promise; + } + + /** + * Handler for incoming packets from the client's actor. + */ + onPacket(packet) { + if (this.isDestroyed()) { + // If the Front was already destroyed, all the requests have been purged + // and rejected with detailed error messages in baseFrontClassDestroy. + return; + } + + // Pick off event packets + const type = packet.type || undefined; + if (this._clientSpec.events && this._clientSpec.events.has(type)) { + const event = this._clientSpec.events.get(packet.type); + let args; + try { + args = event.request.read(packet, this); + } catch (ex) { + console.error("Error reading event: " + packet.type); + console.exception(ex); + throw ex; + } + // Check for "pre event" callback to be processed before emitting events on fronts + // Use event.name instead of packet.type to use specific event name instead of RDP + // packet's type. + const beforeEvent = this._beforeListeners.get(event.name); + if (beforeEvent) { + const result = beforeEvent.apply(this, args); + // Check to see if the beforeEvent returned a promise -- if so, + // wait for their resolution before emitting. Otherwise, emit synchronously. + if (result && typeof result.then == "function") { + result.then(() => { + super.emit(event.name, ...args); + ChromeUtils.addProfilerMarker( + "DevTools:RDP Front", + null, + `${this.typeName}.${event.name}` + ); + }); + return; + } + } + + super.emit(event.name, ...args); + ChromeUtils.addProfilerMarker( + "DevTools:RDP Front", + null, + `${this.typeName}.${event.name}` + ); + return; + } + + // Remaining packets must be responses. + if (this._requests.length === 0) { + const msg = + "Unexpected packet " + this.actorID + ", " + JSON.stringify(packet); + const err = Error(msg); + console.error(err); + throw err; + } + + const { deferred, stack } = this._requests.shift(); + callFunctionWithAsyncStack( + () => { + if (packet.error) { + let message; + if (packet.error && packet.message) { + message = + "Protocol error (" + packet.error + "): " + packet.message; + } else { + message = packet.error; + } + message += " from: " + this.actorID; + if (packet.fileName) { + const { fileName, columnNumber, lineNumber } = packet; + message += ` (${fileName}:${lineNumber}:${columnNumber})`; + } + const packetError = new Error(message); + deferred.reject(packetError); + } else { + deferred.resolve(packet); + } + }, + stack, + "DevTools RDP" + ); + } + + hasRequests() { + return !!this._requests.length; + } + + /** + * Wait for all current requests from this front to settle. This is especially useful + * for tests and other utility environments that may not have events or mechanisms to + * await the completion of requests without this utility. + * + * @return Promise + * Resolved when all requests have settled. + */ + waitForRequestsToSettle() { + return settleAll(this._requests.map(({ deferred }) => deferred.promise)); + } +} + +exports.Front = Front; diff --git a/devtools/shared/protocol/Front/FrontClassWithSpec.js b/devtools/shared/protocol/Front/FrontClassWithSpec.js new file mode 100644 index 0000000000..55091be3e4 --- /dev/null +++ b/devtools/shared/protocol/Front/FrontClassWithSpec.js @@ -0,0 +1,118 @@ +/* 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/. */ + +"use strict"; + +var { Front } = require("resource://devtools/shared/protocol/Front.js"); + +/** + * Generates request methods as described by the given actor specification on + * the given front prototype. Returns the front prototype. + */ +var generateRequestMethods = function (actorSpec, frontProto) { + if (frontProto._actorSpec) { + throw new Error("frontProto called twice on the same front prototype!"); + } + + frontProto.typeName = actorSpec.typeName; + + // Generate request methods. + const methods = actorSpec.methods; + methods.forEach(spec => { + const name = spec.name; + + frontProto[name] = function (...args) { + // If the front is destroyed, the request will not be able to complete. + if (this.isDestroyed()) { + throw new Error( + `Can not send request '${name}' because front '${this.typeName}' is already destroyed.` + ); + } + + const startTime = Cu.now(); + let packet; + try { + packet = spec.request.write(args, this); + } catch (ex) { + console.error("Error writing request: " + name); + throw ex; + } + if (spec.oneway) { + // Fire-and-forget oneway packets. + this.send(packet); + return undefined; + } + + return this.request(packet).then(response => { + let ret; + if (!this.conn) { + throw new Error("Missing conn on " + this); + } + if (this.isDestroyed()) { + throw new Error( + `Can not interpret '${name}' response because front '${this.typeName}' is already destroyed.` + ); + } + try { + ret = spec.response.read(response, this); + } catch (ex) { + console.error("Error reading response to: " + name + "\n" + ex); + throw ex; + } + ChromeUtils.addProfilerMarker( + "RDP Front", + startTime, + `${this.typeName}:${name}()` + ); + return ret; + }); + }; + + // Release methods should call the destroy function on return. + if (spec.release) { + const fn = frontProto[name]; + frontProto[name] = function (...args) { + return fn.apply(this, args).then(result => { + this.destroy(); + return result; + }); + }; + } + }); + + // Process event specifications + frontProto._clientSpec = {}; + + const actorEvents = actorSpec.events; + if (actorEvents) { + frontProto._clientSpec.events = new Map(); + + for (const [name, request] of actorEvents) { + frontProto._clientSpec.events.set(request.type, { + name, + request, + }); + } + } + + frontProto._actorSpec = actorSpec; + + return frontProto; +}; + +/** + * Create a front class for the given actor specification and front prototype. + * + * @param object actorSpec + * The actor specification you're creating a front for. + * @param object proto + * The object prototype. Must have a 'typeName' property, + * should have method definitions, can have event definitions. + */ +var FrontClassWithSpec = function (actorSpec) { + class OneFront extends Front {} + generateRequestMethods(actorSpec, OneFront.prototype); + return OneFront; +}; +exports.FrontClassWithSpec = FrontClassWithSpec; diff --git a/devtools/shared/protocol/Front/moz.build b/devtools/shared/protocol/Front/moz.build new file mode 100644 index 0000000000..75b36c5eab --- /dev/null +++ b/devtools/shared/protocol/Front/moz.build @@ -0,0 +1,8 @@ +# vim: set filetype=python: +# 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/. + +DevToolsModules( + "FrontClassWithSpec.js", +) diff --git a/devtools/shared/protocol/Pool.js b/devtools/shared/protocol/Pool.js new file mode 100644 index 0000000000..b5cb4c3eb1 --- /dev/null +++ b/devtools/shared/protocol/Pool.js @@ -0,0 +1,220 @@ +/* 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/. */ + +"use strict"; + +var EventEmitter = require("resource://devtools/shared/event-emitter.js"); + +/** + * Actor and Front implementations + */ + +/** + * A protocol object that can manage the lifetime of other protocol + * objects. Pools are used on both sides of the connection to help coordinate lifetimes. + * + * @param {DevToolsServerConnection|DevToolsClient} [conn] + * Either a DevToolsServerConnection or a DevToolsClient. Must have + * addActorPool, removeActorPool, and poolFor. + * conn can be null if the subclass provides a conn property. + * @param {String} [label] + * An optional label for the Pool. + * @constructor + */ +class Pool extends EventEmitter { + constructor(conn, label) { + super(); + + if (conn) { + this.conn = conn; + } + this.label = label; + + // Will be individually flipped to true by Actor/Front classes. + // Will also only be exposed via Actor/Front::isDestroyed(). + this._isDestroyed = false; + } + + __poolMap = null; + parentPool = null; + + /** + * Return the parent pool for this client. + */ + getParent() { + return this.parentPool; + } + + /** + * A pool is at the top of its pool hierarchy if it has: + * - no parent + * - or it is its own parent + */ + isTopPool() { + const parent = this.getParent(); + return !parent || parent === this; + } + + poolFor(actorID) { + return this.conn.poolFor(actorID); + } + + /** + * Override this if you want actors returned by this actor + * to belong to a different actor by default. + */ + marshallPool() { + return this; + } + + /** + * Pool is the base class for all actors, even leaf nodes. + * If the child map is actually referenced, go ahead and create + * the stuff needed by the pool. + */ + get _poolMap() { + if (this.__poolMap) { + return this.__poolMap; + } + this.__poolMap = new Map(); + this.conn.addActorPool(this); + return this.__poolMap; + } + + /** + * Add an actor as a child of this pool. + */ + manage(actor) { + if (!actor.actorID) { + actor.actorID = this.conn.allocID(actor.typeName); + } else { + // If the actor is already registered in a pool, remove it without destroying it. + // This happens for example when an addon is reloaded. To see this behavior, take a + // look at devtools/server/tests/xpcshell/test_addon_reload.js + + const parent = actor.getParent(); + if (parent && parent !== this) { + parent.unmanage(actor); + } + } + + this._poolMap.set(actor.actorID, actor); + actor.parentPool = this; + } + + unmanageChildren(FrontType) { + for (const front of this.poolChildren()) { + if (!FrontType || front instanceof FrontType) { + this.unmanage(front); + } + } + } + + /** + * Remove an actor as a child of this pool. + */ + unmanage(actor) { + if (this.__poolMap) { + this.__poolMap.delete(actor.actorID); + } + actor.parentPool = null; + } + + // true if the given actor ID exists in the pool. + has(actorID) { + return this.__poolMap && this._poolMap.has(actorID); + } + + /** + * Search for an actor in this pool, given an actorID + * @param {String} actorID + * @returns {Actor/null} Returns null if the actor wasn't found + */ + getActorByID(actorID) { + if (this.__poolMap) { + return this._poolMap.get(actorID); + } + return null; + } + + // Generator that yields each non-self child of the pool. + *poolChildren() { + if (!this.__poolMap) { + return; + } + for (const actor of this.__poolMap.values()) { + // Self-owned actors are ok, but don't need visiting twice. + if (actor === this) { + continue; + } + yield actor; + } + } + + isDestroyed() { + // Note: _isDestroyed is only flipped from Actor and Front subclasses for + // now, so this method should not be called on pure Pool instances. + // See Bug 1717811. + return this._isDestroyed; + } + + /** + * Pools can override this method in order to opt-out of a destroy sequence. + * + * For instance, Fronts are destroyed during the toolbox destroy. However when + * the toolbox is destroyed, the document holding the toolbox is also + * destroyed. So it should not be necessary to cleanup Fronts during toolbox + * destroy. + * + * For the time being, Fronts (or Pools in general) which want to opt-out of + * toolbox destroy can override this method and check the value of + * `this.conn.isToolboxDestroy`. + */ + skipDestroy() { + return false; + } + + /** + * Destroy this item, removing it from a parent if it has one, + * and destroying all children if necessary. + */ + destroy() { + const parent = this.getParent(); + if (parent) { + parent.unmanage(this); + } + if (!this.__poolMap) { + return; + } + // Immediately clear the poolmap so that we bail out early if the code is reentrant. + const poolMap = this.__poolMap; + this.__poolMap = null; + + for (const actor of poolMap.values()) { + // Self-owned actors are ok, but don't need destroying twice. + if (actor === this) { + continue; + } + + // Some pool-managed values don't extend Pool and won't have skipDestroy + // defined. For instance, the root actor and the lazy actors. + if (typeof actor.skipDestroy === "function" && actor.skipDestroy()) { + continue; + } + + const destroy = actor.destroy; + if (destroy) { + // Disconnect destroy while we're destroying in case of (misbehaving) + // circular ownership. + actor.destroy = null; + destroy.call(actor); + actor.destroy = destroy; + } + } + this.conn.removeActorPool(this); + this.conn = null; + } +} + +exports.Pool = Pool; diff --git a/devtools/shared/protocol/Request.js b/devtools/shared/protocol/Request.js new file mode 100644 index 0000000000..20befd938a --- /dev/null +++ b/devtools/shared/protocol/Request.js @@ -0,0 +1,169 @@ +/* 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/. */ + +"use strict"; + +const { extend } = require("resource://devtools/shared/extend.js"); +var { + findPlaceholders, + getPath, +} = require("resource://devtools/shared/protocol/utils.js"); +var { types } = require("resource://devtools/shared/protocol/types.js"); + +/** + * Manages a request template. + * + * @param object template + * The request template. + * @construcor + */ +var Request = function (template = {}) { + this.type = template.type; + this.template = template; + this.args = findPlaceholders(template, Arg); +}; + +Request.prototype = { + /** + * Write a request. + * + * @param array fnArgs + * The function arguments to place in the request. + * @param object ctx + * The object making the request. + * @returns a request packet. + */ + write(fnArgs, ctx) { + const ret = {}; + for (const key in this.template) { + const value = this.template[key]; + if (value instanceof Arg) { + ret[key] = value.write( + value.index in fnArgs ? fnArgs[value.index] : undefined, + ctx, + key + ); + } else if (key == "type") { + ret[key] = value; + } else { + throw new Error( + "Request can only an object with `Arg` or `Option` properties" + ); + } + } + return ret; + }, + + /** + * Read a request. + * + * @param object packet + * The request packet. + * @param object ctx + * The object making the request. + * @returns an arguments array + */ + read(packet, ctx) { + const fnArgs = []; + for (const templateArg of this.args) { + const arg = templateArg.placeholder; + const path = templateArg.path; + const name = path[path.length - 1]; + arg.read(getPath(packet, path), ctx, fnArgs, name); + } + return fnArgs; + }, +}; + +exports.Request = Request; + +/** + * Request/Response templates and generation + * + * Request packets are specified as json templates with + * Arg and Option placeholders where arguments should be + * placed. + * + * Reponse packets are also specified as json templates, + * with a RetVal placeholder where the return value should be + * placed. + */ + +/** + * Placeholder for simple arguments. + * + * @param number index + * The argument index to place at this position. + * @param type type + * The argument should be marshalled as this type. + * @constructor + */ +var Arg = function (index, type) { + this.index = index; + // Prevent force loading all Arg types by accessing it only when needed + loader.lazyGetter(this, "type", function () { + return types.getType(type); + }); +}; + +Arg.prototype = { + write(arg, ctx) { + return this.type.write(arg, ctx); + }, + + read(v, ctx, outArgs) { + outArgs[this.index] = this.type.read(v, ctx); + }, +}; + +// Outside of protocol.js, Arg is called as factory method, without the new keyword. +exports.Arg = function (index, type) { + return new Arg(index, type); +}; + +/** + * Placeholder for an options argument value that should be hoisted + * into the packet. + * + * If provided in a method specification: + * + * { optionArg: Option(1)} + * + * Then arguments[1].optionArg will be placed in the packet in this + * value's place. + * + * @param number index + * The argument index of the options value. + * @param type type + * The argument should be marshalled as this type. + * @constructor + */ +var Option = function (index, type) { + Arg.call(this, index, type); +}; + +Option.prototype = extend(Arg.prototype, { + write(arg, ctx, name) { + // Ignore if arg is undefined or null; allow other falsy values + if (arg == undefined || arg[name] == undefined) { + return undefined; + } + const v = arg[name]; + return this.type.write(v, ctx); + }, + read(v, ctx, outArgs, name) { + if (outArgs[this.index] === undefined) { + outArgs[this.index] = {}; + } + if (v === undefined) { + return; + } + outArgs[this.index][name] = this.type.read(v, ctx); + }, +}); + +// Outside of protocol.js, Option is called as factory method, without the new keyword. +exports.Option = function (index, type) { + return new Option(index, type); +}; diff --git a/devtools/shared/protocol/Response.js b/devtools/shared/protocol/Response.js new file mode 100644 index 0000000000..b456fe6149 --- /dev/null +++ b/devtools/shared/protocol/Response.js @@ -0,0 +1,119 @@ +/* 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/. */ + +"use strict"; + +var { + findPlaceholders, + getPath, +} = require("resource://devtools/shared/protocol/utils.js"); +var { types } = require("resource://devtools/shared/protocol/types.js"); + +/** + * Manages a response template. + * + * @param object template + * The response template. + * @construcor + */ +var Response = function (template = {}) { + this.template = template; + if (this.template instanceof RetVal && this.template.isArrayType()) { + throw Error("Arrays should be wrapped in objects"); + } + + const placeholders = findPlaceholders(template, RetVal); + if (placeholders.length > 1) { + throw Error("More than one RetVal specified in response"); + } + const placeholder = placeholders.shift(); + if (placeholder) { + this.retVal = placeholder.placeholder; + this.path = placeholder.path; + } +}; + +Response.prototype = { + /** + * Write a response for the given return value. + * + * @param val ret + * The return value. + * @param object ctx + * The object writing the response. + */ + write(ret, ctx) { + // Consider that `template` is either directly a `RetVal`, + // or a dictionary with may be one `RetVal`. + if (this.template instanceof RetVal) { + return this.template.write(ret, ctx); + } + const result = {}; + for (const key in this.template) { + const value = this.template[key]; + if (value instanceof RetVal) { + result[key] = value.write(ret, ctx); + } else { + throw new Error( + "Response can only be a `RetVal` instance or an object " + + "with one property being a `RetVal` instance." + ); + } + } + return result; + }, + + /** + * Read a return value from the given response. + * + * @param object packet + * The response packet. + * @param object ctx + * The object reading the response. + */ + read(packet, ctx) { + if (!this.retVal) { + return undefined; + } + const v = getPath(packet, this.path); + return this.retVal.read(v, ctx); + }, +}; + +exports.Response = Response; + +/** + * Placeholder for return values in a response template. + * + * @param type type + * The return value should be marshalled as this type. + */ +var RetVal = function (type) { + this._type = type; + // Prevent force loading all RetVal types by accessing it only when needed + loader.lazyGetter(this, "type", function () { + return types.getType(type); + }); +}; + +RetVal.prototype = { + write(v, ctx) { + return this.type.write(v, ctx); + }, + + read(v, ctx) { + return this.type.read(v, ctx); + }, + + isArrayType() { + // `_type` should always be a string, but a few incorrect RetVal calls + // pass `0`. See Bug 1677703. + return typeof this._type === "string" && this._type.startsWith("array:"); + }, +}; + +// Outside of protocol.js, RetVal is called as factory method, without the new keyword. +exports.RetVal = function (type) { + return new RetVal(type); +}; diff --git a/devtools/shared/protocol/lazy-pool.js b/devtools/shared/protocol/lazy-pool.js new file mode 100644 index 0000000000..0829fef1e0 --- /dev/null +++ b/devtools/shared/protocol/lazy-pool.js @@ -0,0 +1,224 @@ +/* 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/. */ + +"use strict"; + +const { extend } = require("devtools/shared/extend"); +const { Pool } = require("devtools/shared/protocol"); + +/** + * A Special Pool for RootActor and WindowGlobalTargetActor, which allows lazy loaded + * actors to be added to the pool. + * + * Like the Pool, this is a protocol object that can manage the lifetime of other protocol + * objects. Pools are used on both sides of the connection to help coordinate lifetimes. + * + * @param conn + * Is a DevToolsServerConnection. Must have + * addActorPool, removeActorPool, and poolFor. + * @constructor + */ +function LazyPool(conn) { + this.conn = conn; +} + +LazyPool.prototype = extend(Pool.prototype, { + // The actor for a given actor id stored in this pool + getActorByID(actorID) { + if (this.__poolMap) { + const entry = this._poolMap.get(actorID); + if (entry instanceof LazyActor) { + return entry.createActor(); + } + return entry; + } + return null; + }, +}); + +exports.LazyPool = LazyPool; + +/** + * Populate |parent._extraActors| as specified by |registeredActors|, reusing whatever + * actors are already there. Add all actors in the final extra actors table to + * |pool|. _extraActors is treated as a cache for lazy actors + * + * The target actor uses this to instantiate actors that other + * parts of the browser have specified with ActorRegistry.addTargetScopedActor + * + * @param factories + * An object whose own property names are the names of properties to add to + * some reply packet (say, a target actor grip or the "listTabs" response + * form), and whose own property values are actor constructor functions, as + * documented for addTargetScopedActor + * + * @param parent + * The parent TargetActor with which the new actors + * will be associated. It should support whatever API the |factories| + * constructor functions might be interested in, as it is passed to them. + * For the sake of CommonCreateExtraActors itself, it should have at least + * the following properties: + * + * - _extraActors + * An object whose own property names are factory table (and packet) + * property names, and whose values are no-argument actor constructors, + * of the sort that one can add to a Pool. + * + * - conn + * The DevToolsServerConnection in which the new actors will participate. + * + * - actorID + * The actor's name, for use as the new actors' parentID. + * @param pool + * An object which implements the protocol.js Pool interface, and has the + * following properties + * + * - manage + * a function which adds a given actor to an actor pool + */ +function createExtraActors(registeredActors, pool, parent) { + // Walk over global actors added by extensions. + const nameMap = {}; + for (const name in registeredActors) { + let actor = parent._extraActors[name]; + if (!actor) { + // Register another factory, but this time specific to this connection. + // It creates a fake actor that looks like an regular actor in the pool, + // but without actually instantiating the actor. + // It will only be instantiated on the first request made to the actor. + actor = new LazyActor(registeredActors[name], parent, pool); + parent._extraActors[name] = actor; + } + + // If the actor already exists in the pool, it may have been instantiated, + // so make sure not to overwrite it by a non-instantiated version. + if (!pool.has(actor.actorID)) { + pool.manage(actor); + } + nameMap[name] = actor.actorID; + } + return nameMap; +} + +exports.createExtraActors = createExtraActors; + +/** + * Creates an "actor-like" object which responds in the same way as an ordinary actor + * but has fewer capabilities (ie, does not manage lifetimes or have it's own pool). + * + * + * @param factories + * An object whose own property names are the names of properties to add to + * some reply packet (say, a target actor grip or the "listTabs" response + * form), and whose own property values are actor constructor functions, as + * documented for addTargetScopedActor + * + * @param parent + * The parent TargetActor with which the new actors + * will be associated. It should support whatever API the |factories| + * constructor functions might be interested in, as it is passed to them. + * For the sake of CommonCreateExtraActors itself, it should have at least + * the following properties: + * + * - _extraActors + * An object whose own property names are factory table (and packet) + * property names, and whose values are no-argument actor constructors, + * of the sort that one can add to a Pool. + * + * - conn + * The DevToolsServerConnection in which the new actors will participate. + * + * - actorID + * The actor's name, for use as the new actors' parentID. + * @param pool + * An object which implements the protocol.js Pool interface, and has the + * following properties + * + * - manage + * a function which adds a given actor to an actor pool + */ + +function LazyActor(factory, parent, pool) { + this._options = factory.options; + this._parentActor = parent; + this._name = factory.name; + this._pool = pool; + + // needed for taking a place in a pool + this.typeName = factory.name; +} + +LazyActor.prototype = { + loadModule(id) { + const options = this._options; + try { + return require(id); + // Fetch the actor constructor + } catch (e) { + throw new Error( + `Unable to load actor module '${options.id}'\n${e.message}\n${e.stack}\n` + ); + } + }, + + getConstructor() { + const options = this._options; + if (options.constructorFun) { + // Actor definition registered by testing helpers + return options.constructorFun; + } + // Lazy actor definition, where options contains all the information + // required to load the actor lazily. + // Exposes `name` attribute in order to allow removeXXXActor to match + // the actor by its actor constructor name. + this.name = options.constructorName; + const module = this.loadModule(options.id); + const constructor = module[options.constructorName]; + if (!constructor) { + throw new Error( + `Unable to find actor constructor named '${this.name}'. (Is it exported?)` + ); + } + return constructor; + }, + + /** + * Return the parent pool for this lazy actor. + */ + getParent() { + return this.conn && this.conn.poolFor(this.actorID); + }, + + /** + * This will only happen if the actor is destroyed before it is created + * We do not want to use the Pool destruction method, because this actor + * has no pool. However, it might have a parent that should unmange this + * actor + */ + destroy() { + const parent = this.getParent(); + if (parent) { + parent.unmanage(this); + } + }, + + createActor() { + // Fetch the actor constructor + const Constructor = this.getConstructor(); + // Instantiate a new actor instance + const conn = this._parentActor.conn; + // this should be taken care of once all actors are moved to protocol.js + const instance = new Constructor(conn, this._parentActor); + instance.conn = conn; + + // We want the newly-constructed actor to completely replace the factory + // actor. Reusing the existing actor ID will make sure Pool.manage + // replaces the old actor with the new actor. + instance.actorID = this.actorID; + + this._pool.manage(instance); + + return instance; + }, +}; diff --git a/devtools/shared/protocol/moz.build b/devtools/shared/protocol/moz.build new file mode 100644 index 0000000000..87bf999c25 --- /dev/null +++ b/devtools/shared/protocol/moz.build @@ -0,0 +1,22 @@ +# vim: set filetype=python: +# 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/. + +DIRS += [ + "Actor", + "Front", +] + +DevToolsModules( + "Actor.js", + "Front.js", + "lazy-pool.js", + "Pool.js", + "Request.js", + "Response.js", + "types.js", + "utils.js", +) + +XPCSHELL_TESTS_MANIFESTS += ["tests/xpcshell/xpcshell.ini"] diff --git a/devtools/shared/protocol/tests/xpcshell/.eslintrc.js b/devtools/shared/protocol/tests/xpcshell/.eslintrc.js new file mode 100644 index 0000000000..8611c174f5 --- /dev/null +++ b/devtools/shared/protocol/tests/xpcshell/.eslintrc.js @@ -0,0 +1,6 @@ +"use strict"; + +module.exports = { + // Extend from the common devtools xpcshell eslintrc config. + extends: "../../../../.eslintrc.xpcshell.js", +}; diff --git a/devtools/shared/protocol/tests/xpcshell/head.js b/devtools/shared/protocol/tests/xpcshell/head.js new file mode 100644 index 0000000000..dd055ddb42 --- /dev/null +++ b/devtools/shared/protocol/tests/xpcshell/head.js @@ -0,0 +1,99 @@ +/* Any copyright is dedicated to the Public Domain. + http://creativecommons.org/publicdomain/zero/1.0/ */ + +"use strict"; + +const { require } = ChromeUtils.importESModule( + "resource://devtools/shared/loader/Loader.sys.mjs" +); +const { + DevToolsServer, +} = require("resource://devtools/server/devtools-server.js"); +const { + DevToolsClient, +} = require("resource://devtools/client/devtools-client.js"); + +function dumpn(msg) { + dump("DBG-TEST: " + msg + "\n"); +} + +function connectPipeTracing() { + return new TracingTransport(DevToolsServer.connectPipe()); +} + +/** + * Mock the `Transport` class in order to intercept all the packet + * getting in and out and then being able to assert them and dump them. + */ +function TracingTransport(childTransport) { + this.hooks = null; + this.child = childTransport; + this.child.hooks = this; + + this.expectations = []; + this.packets = []; + this.checkIndex = 0; +} + +TracingTransport.prototype = { + // Remove actor names + normalize(packet) { + return JSON.parse( + JSON.stringify(packet, (key, value) => { + if (key === "to" || key === "from" || key === "actor") { + return "<actorid>"; + } + return value; + }) + ); + }, + send(packet) { + this.packets.push({ + type: "sent", + packet: this.normalize(packet), + }); + return this.child.send(packet); + }, + close() { + return this.child.close(); + }, + ready() { + return this.child.ready(); + }, + onPacket(packet) { + this.packets.push({ + type: "received", + packet: this.normalize(packet), + }); + this.hooks.onPacket(packet); + }, + onTransportClosed() { + if (this.hooks.onTransportClosed) { + this.hooks.onTransportClosed(); + } + }, + + expectSend(expected) { + const packet = this.packets[this.checkIndex++]; + Assert.equal(packet.type, "sent"); + deepEqual(packet.packet, this.normalize(expected)); + }, + + expectReceive(expected) { + const packet = this.packets[this.checkIndex++]; + Assert.equal(packet.type, "received"); + deepEqual(packet.packet, this.normalize(expected)); + }, + + // Write your tests, call dumpLog at the end, inspect the output, + // then sprinkle the calls through the right places in your test. + dumpLog() { + for (const entry of this.packets) { + if (entry.type === "sent") { + dumpn("trace.expectSend(" + entry.packet + ");"); + } else { + dumpn("trace.expectReceive(" + entry.packet + ");"); + } + } + }, +}; diff --git a/devtools/shared/protocol/tests/xpcshell/test_protocol_abort.js b/devtools/shared/protocol/tests/xpcshell/test_protocol_abort.js new file mode 100644 index 0000000000..ce237e1c00 --- /dev/null +++ b/devtools/shared/protocol/tests/xpcshell/test_protocol_abort.js @@ -0,0 +1,79 @@ +/* Any copyright is dedicated to the Public Domain. + http://creativecommons.org/publicdomain/zero/1.0/ */ + +"use strict"; + +/** + * Outstanding requests should be rejected when the connection aborts + * unexpectedly. + */ + +var protocol = require("resource://devtools/shared/protocol.js"); +var { RetVal } = protocol; + +const rootSpec = protocol.generateActorSpec({ + typeName: "root", + + methods: { + simpleReturn: { + response: { value: RetVal() }, + }, + }, +}); + +class RootActor extends protocol.Actor { + constructor(conn) { + super(conn, rootSpec); + + // Root actor owns itself. + this.manage(this); + this.actorID = "root"; + this.sequence = 0; + } + + sayHello() { + return { + from: "root", + applicationType: "xpcshell-tests", + traits: [], + }; + } + + simpleReturn() { + return this.sequence++; + } +} + +class RootFront extends protocol.FrontClassWithSpec(rootSpec) { + constructor(client) { + super(client); + this.actorID = "root"; + // Root owns itself. + this.manage(this); + } +} +protocol.registerFront(RootFront); + +add_task(async function () { + DevToolsServer.createRootActor = conn => new RootActor(conn); + DevToolsServer.init(); + + const trace = connectPipeTracing(); + const client = new DevToolsClient(trace); + await client.connect(); + + const rootFront = client.mainRoot; + + const onSimpleReturn = rootFront.simpleReturn(); + trace.close(); + + try { + await onSimpleReturn; + ok(false, "Connection was aborted, request shouldn't resolve"); + } catch (e) { + const error = e.toString(); + ok(true, "Connection was aborted, request rejected correctly"); + ok(error.includes("Request stack:"), "Error includes request stack"); + ok(error.includes("test_protocol_abort.js"), "Stack includes this test"); + } +}); diff --git a/devtools/shared/protocol/tests/xpcshell/test_protocol_async.js b/devtools/shared/protocol/tests/xpcshell/test_protocol_async.js new file mode 100644 index 0000000000..dd7196710b --- /dev/null +++ b/devtools/shared/protocol/tests/xpcshell/test_protocol_async.js @@ -0,0 +1,192 @@ +/* Any copyright is dedicated to the Public Domain. + http://creativecommons.org/publicdomain/zero/1.0/ */ + +"use strict"; + +/** + * Make sure we get replies in the same order that we sent their + * requests even when earlier requests take several event ticks to + * complete. + */ + +const { waitForTick } = require("resource://devtools/shared/DevToolsUtils.js"); +const protocol = require("resource://devtools/shared/protocol.js"); +const { Arg, RetVal } = protocol; + +const rootSpec = protocol.generateActorSpec({ + typeName: "root", + + methods: { + simpleReturn: { + response: { value: RetVal() }, + }, + promiseReturn: { + request: { toWait: Arg(0, "number") }, + response: { value: RetVal("number") }, + }, + simpleThrow: { + response: { value: RetVal("number") }, + }, + promiseThrow: { + request: { toWait: Arg(0, "number") }, + response: { value: RetVal("number") }, + }, + }, +}); + +class RootActor extends protocol.Actor { + constructor(conn) { + super(conn, rootSpec); + + // Root actor owns itself. + this.manage(this); + this.actorID = "root"; + this.sequence = 0; + } + + sayHello() { + return { + from: "root", + applicationType: "xpcshell-tests", + traits: [], + }; + } + + simpleReturn() { + return this.sequence++; + } + + // Guarantee that this resolves after simpleReturn returns. + async promiseReturn(toWait) { + const sequence = this.sequence++; + + // Wait until the number of requests specified by toWait have + // happened, to test queuing. + while (this.sequence - sequence < toWait) { + await waitForTick(); + } + + return sequence; + } + + simpleThrow() { + throw new Error(this.sequence++); + } + + // Guarantee that this resolves after simpleReturn returns. + promiseThrow(toWait) { + return this.promiseReturn(toWait).then(Promise.reject); + } +} + +class RootFront extends protocol.FrontClassWithSpec(rootSpec) { + constructor(client) { + super(client); + this.actorID = "root"; + // Root owns itself. + this.manage(this); + } +} +protocol.registerFront(RootFront); + +add_task(async function () { + DevToolsServer.createRootActor = conn => new RootActor(conn); + DevToolsServer.init(); + + const trace = connectPipeTracing(); + const client = new DevToolsClient(trace); + await client.connect(); + + const rootFront = client.mainRoot; + + const calls = []; + let sequence = 0; + + // Execute a call that won't finish processing until 2 + // more calls have happened + calls.push( + rootFront.promiseReturn(2).then(ret => { + // Check right return order + Assert.equal(sequence, 0); + // Check request handling order + Assert.equal(ret, sequence++); + }) + ); + + // Put a few requests into the backlog + + calls.push( + rootFront.simpleReturn().then(ret => { + // Check right return order + Assert.equal(sequence, 1); + // Check request handling order + Assert.equal(ret, sequence++); + }) + ); + + calls.push( + rootFront.simpleReturn().then(ret => { + // Check right return order + Assert.equal(sequence, 2); + // Check request handling order + Assert.equal(ret, sequence++); + }) + ); + + calls.push( + rootFront.simpleThrow().then( + () => { + Assert.ok(false, "simpleThrow shouldn't succeed!"); + }, + error => { + // Check right return order + Assert.equal(sequence++, 3); + } + ) + ); + + calls.push( + rootFront.promiseThrow(2).then( + () => { + Assert.ok(false, "promiseThrow shouldn't succeed!"); + }, + error => { + // Check right return order + Assert.equal(sequence++, 4); + Assert.ok(true, "simple throw should throw"); + } + ) + ); + + calls.push( + rootFront.simpleReturn().then(ret => { + // Check right return order + Assert.equal(sequence, 5); + // Check request handling order + Assert.equal(ret, sequence++); + }) + ); + + // Break up the backlog with a long request that waits + // for another simpleReturn before completing + calls.push( + rootFront.promiseReturn(1).then(ret => { + // Check right return order + Assert.equal(sequence, 6); + // Check request handling order + Assert.equal(ret, sequence++); + }) + ); + + calls.push( + rootFront.simpleReturn().then(ret => { + // Check right return order + Assert.equal(sequence, 7); + // Check request handling order + Assert.equal(ret, sequence++); + }) + ); + + await Promise.all(calls); + await client.close(); +}); diff --git a/devtools/shared/protocol/tests/xpcshell/test_protocol_children.js b/devtools/shared/protocol/tests/xpcshell/test_protocol_children.js new file mode 100644 index 0000000000..728e58c6b9 --- /dev/null +++ b/devtools/shared/protocol/tests/xpcshell/test_protocol_children.js @@ -0,0 +1,700 @@ +/* Any copyright is dedicated to the Public Domain. + http://creativecommons.org/publicdomain/zero/1.0/ */ +/* eslint-disable max-nested-callbacks */ + +"use strict"; + +/** + * Test simple requests using the protocol helpers. + */ +const protocol = require("resource://devtools/shared/protocol.js"); +const { types, Arg, RetVal } = protocol; + +// Predeclaring the actor type so that it can be used in the +// implementation of the child actor. +types.addActorType("childActor"); +types.addActorType("otherChildActor"); +types.addPolymorphicType("polytype", ["childActor", "otherChildActor"]); + +const childSpec = protocol.generateActorSpec({ + typeName: "childActor", + + events: { + event1: { + a: Arg(0), + b: Arg(1), + c: Arg(2), + }, + event2: { + a: Arg(0), + b: Arg(1), + c: Arg(2), + }, + "named-event": { + type: "namedEvent", + a: Arg(0), + b: Arg(1), + c: Arg(2), + }, + "object-event": { + type: "objectEvent", + detail: Arg(0, "childActor#actorid"), + }, + "array-object-event": { + type: "arrayObjectEvent", + detail: Arg(0, "array:childActor#actorid"), + }, + }, + + methods: { + echo: { + request: { str: Arg(0) }, + response: { str: RetVal("string") }, + }, + getDetail1: { + response: { + child: RetVal("childActor#actorid"), + }, + }, + getDetail2: { + response: { + child: RetVal("childActor#actorid"), + }, + }, + getIDDetail: { + response: { + idDetail: RetVal("childActor#actorid"), + }, + }, + getIntArray: { + request: { inputArray: Arg(0, "array:number") }, + response: { + intArray: RetVal("array:number"), + }, + }, + getSibling: { + request: { id: Arg(0) }, + response: { sibling: RetVal("childActor") }, + }, + emitEvents: { + response: { value: RetVal("string") }, + }, + release: { + release: true, + }, + }, +}); + +class ChildActor extends protocol.Actor { + constructor(conn, id) { + super(conn, childSpec); + this.childID = id; + } + + // Actors returned by this actor should be owned by the root actor. + marshallPool() { + return this.getParent(); + } + + toString() { + return "[ChildActor " + this.childID + "]"; + } + + destroy() { + super.destroy(); + this.destroyed = true; + } + + form() { + return { + actor: this.actorID, + childID: this.childID, + }; + } + + echo(str) { + return str; + } + + getDetail1() { + return this; + } + + getDetail2() { + return this; + } + + getIDDetail() { + return this; + } + + getIntArray(inputArray) { + // Test that protocol.js converts an iterator to an array. + const f = function* () { + for (const i of inputArray) { + yield 2 * i; + } + }; + return f(); + } + + getSibling(id) { + return this.getParent().getChild(id); + } + + emitEvents() { + this.emit("event1", 1, 2, 3); + this.emit("event2", 4, 5, 6); + this.emit("named-event", 1, 2, 3); + this.emit("object-event", this); + this.emit("array-object-event", [this]); + return "correct response"; + } + + release() {} +} + +class ChildFront extends protocol.FrontClassWithSpec(childSpec) { + constructor(client, targetFront, parentFront) { + super(client, targetFront, parentFront); + this._parentFront = parentFront; + + this.before("event1", this.onEvent1.bind(this)); + this.before("event2", this.onEvent2a.bind(this)); + this.on("event2", this.onEvent2b.bind(this)); + } + + destroy() { + this.destroyed = true; + // Call parent's destroy, which may be re-entrant and recall this function + this._parentFront.destroy(); + super.destroy(); + } + + marshallPool() { + return this.getParent(); + } + + toString() { + return "[child front " + this.childID + "]"; + } + + form(form) { + this.childID = form.childID; + } + + onEvent1(a, b, c) { + this.event1arg3 = c; + } + + onEvent2a(a, b, c) { + return Promise.resolve().then(() => { + this.event2arg3 = c; + }); + } + + onEvent2b(a, b, c) { + this.event2arg2 = b; + } +} +protocol.registerFront(ChildFront); + +const otherChildSpec = protocol.generateActorSpec({ + typeName: "otherChildActor", + methods: { + getOtherChild: { + request: {}, + response: { sibling: RetVal("otherChildActor") }, + }, + }, + events: {}, +}); + +class OtherChildActor extends protocol.Actor { + constructor(conn) { + super(conn, otherChildSpec); + } + + getOtherChild() { + return new OtherChildActor(this.conn); + } +} + +class OtherChildFront extends protocol.FrontClassWithSpec(otherChildSpec) {} +protocol.registerFront(OtherChildFront); + +types.addDictType("manyChildrenDict", { + child5: "childActor", + more: "array:childActor", +}); + +const rootSpec = protocol.generateActorSpec({ + typeName: "root", + + methods: { + getChild: { + request: { str: Arg(0) }, + response: { actor: RetVal("childActor") }, + }, + getOtherChild: { + request: {}, + response: { sibling: RetVal("otherChildActor") }, + }, + getChildren: { + request: { ids: Arg(0, "array:string") }, + response: { children: RetVal("array:childActor") }, + }, + getChildren2: { + request: { ids: Arg(0, "array:childActor") }, + response: { children: RetVal("array:childActor") }, + }, + getManyChildren: { + response: RetVal("manyChildrenDict"), + }, + getPolymorphism: { + request: { id: Arg(0, "number") }, + response: { child: RetVal("polytype") }, + }, + requestPolymorphism: { + request: { + id: Arg(0, "number"), + actor: Arg(1, "polytype"), + }, + response: { child: RetVal("polytype") }, + }, + }, +}); + +let rootActor = null; +class RootActor extends protocol.Actor { + constructor(conn) { + super(conn, rootSpec); + + rootActor = this; + this.actorID = "root"; + this._children = {}; + } + + toString() { + return "[root actor]"; + } + + sayHello() { + return { + from: "root", + applicationType: "xpcshell-tests", + traits: [], + }; + } + + getChild(id) { + if (id in this._children) { + return this._children[id]; + } + const child = new ChildActor(this.conn, id); + this._children[id] = child; + return child; + } + + // Other child actor won't all be own by the root actor + // and can have their own children + getOtherChild() { + return new OtherChildActor(this.conn); + } + + getChildren(ids) { + return ids.map(id => this.getChild(id)); + } + + getChildren2(ids) { + const f = function* () { + for (const c of ids) { + yield c; + } + }; + return f(); + } + + getManyChildren() { + return { + // note that this isn't in the specialization array. + foo: "bar", + child5: this.getChild("child5"), + more: [this.getChild("child6"), this.getChild("child7")], + }; + } + + getPolymorphism(id) { + if (id == 0) { + return new ChildActor(this.conn, id); + } else if (id == 1) { + return new OtherChildActor(this.conn); + } + throw new Error("Unexpected id"); + } + + requestPolymorphism(id, actor) { + if (id == 0 && actor instanceof ChildActor) { + return actor; + } else if (id == 1 && actor instanceof OtherChildActor) { + return actor; + } + throw new Error("Unexpected id or actor"); + } +} + +class RootFront extends protocol.FrontClassWithSpec(rootSpec) { + constructor(client, targetFront, parentFront) { + super(client, targetFront, parentFront); + this.actorID = "root"; + // Root actor owns itself. + this.manage(this); + } + + toString() { + return "[root front]"; + } +} + +let rootFront, childFront; +function expectRootChildren(size) { + Assert.equal(rootActor._poolMap.size, size); + Assert.equal(rootFront._poolMap.size, size + 1); + if (childFront) { + Assert.equal(childFront._poolMap.size, 0); + } +} +protocol.registerFront(RootFront); + +function childrenOfType(pool, type) { + const children = [...rootFront.poolChildren()]; + return children.filter(child => child instanceof type); +} + +add_task(async function () { + DevToolsServer.createRootActor = conn => { + return new RootActor(conn); + }; + DevToolsServer.init(); + + const trace = connectPipeTracing(); + const client = new DevToolsClient(trace); + const [applicationType] = await client.connect(); + trace.expectReceive({ + from: "<actorid>", + applicationType: "xpcshell-tests", + traits: [], + }); + Assert.equal(applicationType, "xpcshell-tests"); + + rootFront = client.mainRoot; + + await testSimpleChildren(trace); + await testDetail(trace); + await testSibling(trace); + await testEvents(trace); + await testManyChildren(trace); + await testGenerator(trace); + await testPolymorphism(trace); + await testUnmanageChildren(trace); + // Execute that assertion very last as it destroy the root front and actor + await testDestroy(trace); + + await client.close(); +}); + +async function testSimpleChildren(trace) { + childFront = await rootFront.getChild("child1"); + trace.expectSend({ type: "getChild", str: "child1", to: "<actorid>" }); + trace.expectReceive({ actor: "<actorid>", from: "<actorid>" }); + + Assert.ok(childFront instanceof ChildFront); + Assert.equal(childFront.childID, "child1"); + expectRootChildren(1); + + // Request the child again, make sure the same is returned. + let ret = await rootFront.getChild("child1"); + trace.expectSend({ type: "getChild", str: "child1", to: "<actorid>" }); + trace.expectReceive({ actor: "<actorid>", from: "<actorid>" }); + + expectRootChildren(1); + Assert.ok(ret === childFront); + + ret = await childFront.echo("hello"); + trace.expectSend({ type: "echo", str: "hello", to: "<actorid>" }); + trace.expectReceive({ str: "hello", from: "<actorid>" }); + + Assert.equal(ret, "hello"); +} + +async function testDetail(trace) { + let ret = await childFront.getDetail1(); + trace.expectSend({ type: "getDetail1", to: "<actorid>" }); + trace.expectReceive({ child: childFront.actorID, from: "<actorid>" }); + Assert.ok(ret === childFront); + + ret = await childFront.getDetail2(); + trace.expectSend({ type: "getDetail2", to: "<actorid>" }); + trace.expectReceive({ child: childFront.actorID, from: "<actorid>" }); + Assert.ok(ret === childFront); + + ret = await childFront.getIDDetail(); + trace.expectSend({ type: "getIDDetail", to: "<actorid>" }); + trace.expectReceive({ + idDetail: childFront.actorID, + from: "<actorid>", + }); + Assert.ok(ret === childFront); +} + +async function testSibling(trace) { + await childFront.getSibling("siblingID"); + trace.expectSend({ + type: "getSibling", + id: "siblingID", + to: "<actorid>", + }); + trace.expectReceive({ + sibling: { actor: "<actorid>", childID: "siblingID" }, + from: "<actorid>", + }); + + expectRootChildren(2); +} + +async function testEvents(trace) { + const ret = await rootFront.getChildren(["child1", "child2"]); + trace.expectSend({ + type: "getChildren", + ids: ["child1", "child2"], + to: "<actorid>", + }); + trace.expectReceive({ + children: [ + { actor: "<actorid>", childID: "child1" }, + { actor: "<actorid>", childID: "child2" }, + ], + from: "<actorid>", + }); + + expectRootChildren(3); + Assert.ok(ret[0] === childFront); + Assert.ok(ret[1] !== childFront); + Assert.ok(ret[1] instanceof ChildFront); + + // On both children, listen to events. We're only + // going to trigger events on the first child, so an event + // triggered on the second should cause immediate failures. + + const set = new Set([ + "event1", + "event2", + "named-event", + "object-event", + "array-object-event", + ]); + + childFront.on("event1", (a, b, c) => { + Assert.equal(a, 1); + Assert.equal(b, 2); + Assert.equal(c, 3); + // Verify that the pre-event handler was called. + Assert.equal(childFront.event1arg3, 3); + set.delete("event1"); + }); + childFront.on("event2", (a, b, c) => { + Assert.equal(a, 4); + Assert.equal(b, 5); + Assert.equal(c, 6); + // Verify that the async pre-event handler was called, + // setting the property before this handler was called. + Assert.equal(childFront.event2arg3, 6); + // And check that the sync preEvent with the same name is also + // executed + Assert.equal(childFront.event2arg2, 5); + set.delete("event2"); + }); + childFront.on("named-event", (a, b, c) => { + Assert.equal(a, 1); + Assert.equal(b, 2); + Assert.equal(c, 3); + set.delete("named-event"); + }); + childFront.on("object-event", obj => { + Assert.ok(obj === childFront); + set.delete("object-event"); + }); + childFront.on("array-object-event", array => { + Assert.ok(array[0] === childFront); + set.delete("array-object-event"); + }); + + const fail = function () { + do_throw("Unexpected event"); + }; + ret[1].on("event1", fail); + ret[1].on("event2", fail); + ret[1].on("named-event", fail); + ret[1].on("object-event", fail); + ret[1].on("array-object-event", fail); + + await childFront.emitEvents(); + trace.expectSend({ type: "emitEvents", to: "<actorid>" }); + trace.expectReceive({ + type: "event1", + a: 1, + b: 2, + c: 3, + from: "<actorid>", + }); + trace.expectReceive({ + type: "event2", + a: 4, + b: 5, + c: 6, + from: "<actorid>", + }); + trace.expectReceive({ + type: "namedEvent", + a: 1, + b: 2, + c: 3, + from: "<actorid>", + }); + trace.expectReceive({ + type: "objectEvent", + detail: childFront.actorID, + from: "<actorid>", + }); + trace.expectReceive({ + type: "arrayObjectEvent", + detail: [childFront.actorID], + from: "<actorid>", + }); + trace.expectReceive({ value: "correct response", from: "<actorid>" }); + + Assert.equal(set.size, 0); +} + +async function testManyChildren(trace) { + const ret = await rootFront.getManyChildren(); + trace.expectSend({ type: "getManyChildren", to: "<actorid>" }); + trace.expectReceive({ + foo: "bar", + child5: { actor: "<actorid>", childID: "child5" }, + more: [ + { actor: "<actorid>", childID: "child6" }, + { actor: "<actorid>", childID: "child7" }, + ], + from: "<actorid>", + }); + + // Check all the crazy stuff we did in getManyChildren + Assert.equal(ret.foo, "bar"); + Assert.equal(ret.child5.childID, "child5"); + Assert.equal(ret.more[0].childID, "child6"); + Assert.equal(ret.more[1].childID, "child7"); +} + +async function testGenerator(trace) { + // Test accepting a generator. + const f = function* () { + for (const i of [1, 2, 3, 4, 5]) { + yield i; + } + }; + let ret = await childFront.getIntArray(f()); + Assert.equal(ret.length, 5); + const expected = [2, 4, 6, 8, 10]; + for (let i = 0; i < 5; ++i) { + Assert.equal(ret[i], expected[i]); + } + + const ids = await rootFront.getChildren(["child1", "child2"]); + const f2 = function* () { + for (const id of ids) { + yield id; + } + }; + ret = await rootFront.getChildren2(f2()); + Assert.equal(ret.length, 2); + Assert.ok(ret[0] === childFront); + Assert.ok(ret[1] !== childFront); + Assert.ok(ret[1] instanceof ChildFront); +} + +async function testPolymorphism(trace) { + // Check polymorphic types returned by an actor + const firstChild = await rootFront.getPolymorphism(0); + Assert.ok(firstChild instanceof ChildFront); + + // Check polymorphic types passed to a front + const sameFirstChild = await rootFront.requestPolymorphism(0, firstChild); + Assert.ok(sameFirstChild instanceof ChildFront); + Assert.equal(sameFirstChild, firstChild); + + // Same with the second possible type + const secondChild = await rootFront.getPolymorphism(1); + Assert.ok(secondChild instanceof OtherChildFront); + + const sameSecondChild = await rootFront.requestPolymorphism(1, secondChild); + Assert.ok(sameSecondChild instanceof OtherChildFront); + Assert.equal(sameSecondChild, secondChild); + + // Check that any other type is rejected + Assert.throws(() => { + rootFront.requestPolymorphism(0, null); + }, /Was expecting one of these actors 'childActor,otherChildActor' but instead got an empty value/); + Assert.throws(() => { + rootFront.requestPolymorphism(0, 42); + }, /Was expecting one of these actors 'childActor,otherChildActor' but instead got value: '42'/); + Assert.throws(() => { + rootFront.requestPolymorphism(0, rootFront); + }, /Was expecting one of these actors 'childActor,otherChildActor' but instead got an actor of type: 'root'/); +} + +async function testUnmanageChildren(trace) { + // There is already one front of type OtherChildFront + Assert.equal(childrenOfType(rootFront, OtherChildFront).length, 1); + + // Create another front of type OtherChildFront + const front = await rootFront.getPolymorphism(1); + Assert.ok(front instanceof OtherChildFront); + Assert.equal(childrenOfType(rootFront, OtherChildFront).length, 2); + + // Remove all fronts of type OtherChildFront + rootFront.unmanageChildren(OtherChildFront); + Assert.ok( + !front.isDestroyed(), + "Unmanaged front is not considered as destroyed" + ); + Assert.equal(childrenOfType(rootFront, OtherChildFront).length, 0); +} + +async function testDestroy(trace) { + const front = await rootFront.getOtherChild(); + const otherChildFront = await front.getOtherChild(); + Assert.equal( + otherChildFront.getParent(), + front, + "the child is a children of first front" + ); + + front.destroy(); + Assert.ok(front.isDestroyed(), "sibling is correctly reported as destroyed"); + Assert.ok(!front.getParent(), "sibling has no more parent declared"); + Assert.ok(otherChildFront.isDestroyed(), "the child is also destroyed"); + Assert.ok( + !otherChildFront.getParent(), + "the child also has no more parent declared" + ); + Assert.ok( + !otherChildFront.parentPool, + "the child also has its parentPool attribute nullified" + ); + + // Verify that re-entrant Front.destroy doesn't throw, nor loop + // Execute that very last as it will destroy the root actor and front + const sibling = await childFront.getSibling("siblingID"); + sibling.destroy(); +} diff --git a/devtools/shared/protocol/tests/xpcshell/test_protocol_index.js b/devtools/shared/protocol/tests/xpcshell/test_protocol_index.js new file mode 100644 index 0000000000..ef566d6b97 --- /dev/null +++ b/devtools/shared/protocol/tests/xpcshell/test_protocol_index.js @@ -0,0 +1,52 @@ +/* Any copyright is dedicated to the Public Domain. + http://creativecommons.org/publicdomain/zero/1.0/ */ + +"use strict"; +const { lazyLoadFront } = require("resource://devtools/shared/specs/index.js"); +const Types = + require("resource://devtools/shared/specs/index.js").__TypesForTests; +const { getType } = require("resource://devtools/shared/protocol.js").types; + +function run_test() { + test_index_is_alphabetically_sorted(); + test_specs(); + test_fronts(); +} + +// Check alphabetic order of specs defined in devtools/shared/specs/index.js, +// in order to ease its maintenance and readability. +function test_index_is_alphabetically_sorted() { + let lastSpec = ""; + for (const type of Types) { + const spec = type.spec; + if (lastSpec && spec < lastSpec) { + ok(false, `Spec definition for "${spec}" should be before "${lastSpec}"`); + } + lastSpec = spec; + } + ok(true, "Specs index is alphabetically sorted"); +} + +function test_specs() { + for (const type of Types) { + for (const typeName of type.types) { + ok(!!getType(typeName), `${typeName} spec is defined`); + } + } + ok(true, "Specs are all accessible"); +} + +function test_fronts() { + for (const item of Types) { + if (!item.front) { + continue; + } + for (const typeName of item.types) { + lazyLoadFront(typeName); + const type = getType(typeName); + ok(!!type, `Front for ${typeName} has a spec`); + ok(type.frontClass, `${typeName} has a front correctly defined`); + } + } + ok(true, "Front are all accessible"); +} diff --git a/devtools/shared/protocol/tests/xpcshell/test_protocol_invalid_response.js b/devtools/shared/protocol/tests/xpcshell/test_protocol_invalid_response.js new file mode 100644 index 0000000000..6b530f0a61 --- /dev/null +++ b/devtools/shared/protocol/tests/xpcshell/test_protocol_invalid_response.js @@ -0,0 +1,52 @@ +/* Any copyright is dedicated to the Public Domain. + http://creativecommons.org/publicdomain/zero/1.0/ */ + +"use strict"; + +const protocol = require("resource://devtools/shared/protocol.js"); +const { RetVal } = protocol; + +// Test invalid response specs throw when generating the Actor specification. + +// Test top level array response +add_task(async function () { + Assert.throws(() => { + protocol.generateActorSpec({ + typeName: "invalidArrayResponse", + methods: { + invalidMethod: { + response: RetVal("array:string"), + }, + }, + }); + }, /Arrays should be wrapped in objects/); + + protocol.generateActorSpec({ + typeName: "validArrayResponse", + methods: { + validMethod: { + response: { + someArray: RetVal("array:string"), + }, + }, + }, + }); + ok(true, "Arrays wrapped in object are valid response packets"); +}); + +// Test response with several placeholders +add_task(async function () { + Assert.throws(() => { + protocol.generateActorSpec({ + typeName: "tooManyPlaceholdersResponse", + methods: { + invalidMethod: { + response: { + prop1: RetVal("json"), + prop2: RetVal("json"), + }, + }, + }, + }); + }, /More than one RetVal specified in response/); +}); diff --git a/devtools/shared/protocol/tests/xpcshell/test_protocol_lifecycle.js b/devtools/shared/protocol/tests/xpcshell/test_protocol_lifecycle.js new file mode 100644 index 0000000000..bd887ba88a --- /dev/null +++ b/devtools/shared/protocol/tests/xpcshell/test_protocol_lifecycle.js @@ -0,0 +1,27 @@ +/* Any copyright is dedicated to the Public Domain. + http://creativecommons.org/publicdomain/zero/1.0/ */ + +"use strict"; + +const { Actor } = require("resource://devtools/shared/protocol/Actor.js"); +const { Front } = require("resource://devtools/shared/protocol/Front.js"); + +add_task(async function () { + // Front constructor expect to be provided a client object + const client = {}; + const front = new Front(client); + ok( + !front.isDestroyed(), + "Blank front with no actor ID is not considered as destroyed" + ); + front.destroy(); + ok(front.isDestroyed(), "Front is destroyed"); + + const actor = new Actor(null, { typeName: "actor", methods: [] }); + ok( + !actor.isDestroyed(), + "Blank actor with no actor ID is not considered as destroyed" + ); + actor.destroy(); + ok(actor.isDestroyed(), "Actor is destroyed"); +}); diff --git a/devtools/shared/protocol/tests/xpcshell/test_protocol_longstring.js b/devtools/shared/protocol/tests/xpcshell/test_protocol_longstring.js new file mode 100644 index 0000000000..cda1708520 --- /dev/null +++ b/devtools/shared/protocol/tests/xpcshell/test_protocol_longstring.js @@ -0,0 +1,310 @@ +/* Any copyright is dedicated to the Public Domain. + http://creativecommons.org/publicdomain/zero/1.0/ */ +/* eslint-disable max-nested-callbacks */ + +"use strict"; + +/** + * Test simple requests using the protocol helpers. + */ +var protocol = require("resource://devtools/shared/protocol.js"); +var { RetVal, Arg } = protocol; +var EventEmitter = require("resource://devtools/shared/event-emitter.js"); +var { + LongStringActor, +} = require("resource://devtools/server/actors/string.js"); + +// The test implicitly relies on this. +require("resource://devtools/client/fronts/string.js"); + +DevToolsServer.LONG_STRING_LENGTH = + DevToolsServer.LONG_STRING_INITIAL_LENGTH = + DevToolsServer.LONG_STRING_READ_LENGTH = + 5; + +var SHORT_STR = "abc"; +var LONG_STR = "abcdefghijklmnop"; + +var rootActor = null; + +const rootSpec = protocol.generateActorSpec({ + typeName: "root", + + events: { + "string-event": { + str: Arg(0, "longstring"), + }, + }, + + methods: { + shortString: { + response: { value: RetVal("longstring") }, + }, + longString: { + response: { value: RetVal("longstring") }, + }, + emitShortString: { + oneway: true, + }, + emitLongString: { + oneway: true, + }, + }, +}); + +class RootActor extends protocol.Actor { + constructor(conn) { + super(conn, rootSpec); + + rootActor = this; + // Root actor owns itself. + this.manage(this); + this.actorID = "root"; + } + + sayHello() { + return { + from: "root", + applicationType: "xpcshell-tests", + traits: [], + }; + } + + shortString() { + return new LongStringActor(this.conn, SHORT_STR); + } + + longString() { + return new LongStringActor(this.conn, LONG_STR); + } + + emitShortString() { + EventEmitter.emit( + this, + "string-event", + new LongStringActor(this.conn, SHORT_STR) + ); + } + + emitLongString() { + EventEmitter.emit( + this, + "string-event", + new LongStringActor(this.conn, LONG_STR) + ); + } +} + +class RootFront extends protocol.FrontClassWithSpec(rootSpec) { + constructor(client) { + super(client); + this.actorID = "root"; + + // Root owns itself. + this.manage(this); + } +} +protocol.registerFront(RootFront); + +function run_test() { + DevToolsServer.createRootActor = conn => { + return new RootActor(conn); + }; + + DevToolsServer.init(); + + const trace = connectPipeTracing(); + const client = new DevToolsClient(trace); + let rootFront; + + let strfront = null; + + const expectRootChildren = function (size) { + Assert.equal(rootActor.__poolMap.size, size + 1); + Assert.equal(rootFront.__poolMap.size, size + 1); + }; + + client.connect().then(([applicationType, traits]) => { + rootFront = client.mainRoot; + + // Root actor has no children yet. + expectRootChildren(0); + + trace.expectReceive({ + from: "<actorid>", + applicationType: "xpcshell-tests", + traits: [], + }); + Assert.equal(applicationType, "xpcshell-tests"); + rootFront + .shortString() + .then(ret => { + trace.expectSend({ type: "shortString", to: "<actorid>" }); + trace.expectReceive({ value: "abc", from: "<actorid>" }); + + // Should only own the one reference (itself) at this point. + expectRootChildren(0); + strfront = ret; + }) + .then(() => { + return strfront.string(); + }) + .then(ret => { + Assert.equal(ret, SHORT_STR); + }) + .then(() => { + return rootFront.longString(); + }) + .then(ret => { + trace.expectSend({ type: "longString", to: "<actorid>" }); + trace.expectReceive({ + value: { + type: "longString", + actor: "<actorid>", + length: 16, + initial: "abcde", + }, + from: "<actorid>", + }); + + strfront = ret; + // Should own a reference to itself and an extra string now. + expectRootChildren(1); + }) + .then(() => { + return strfront.string(); + }) + .then(ret => { + trace.expectSend({ + type: "substring", + start: 5, + end: 10, + to: "<actorid>", + }); + trace.expectReceive({ substring: "fghij", from: "<actorid>" }); + trace.expectSend({ + type: "substring", + start: 10, + end: 15, + to: "<actorid>", + }); + trace.expectReceive({ substring: "klmno", from: "<actorid>" }); + trace.expectSend({ + type: "substring", + start: 15, + end: 20, + to: "<actorid>", + }); + trace.expectReceive({ substring: "p", from: "<actorid>" }); + + Assert.equal(ret, LONG_STR); + }) + .then(() => { + return strfront.release(); + }) + .then(() => { + trace.expectSend({ type: "release", to: "<actorid>" }); + trace.expectReceive({ from: "<actorid>" }); + + // That reference should be removed now. + expectRootChildren(0); + }) + .then(() => { + return new Promise(resolve => { + rootFront.once("string-event", str => { + trace.expectSend({ type: "emitShortString", to: "<actorid>" }); + trace.expectReceive({ + type: "string-event", + str: "abc", + from: "<actorid>", + }); + + Assert.ok(!!str); + strfront = str; + // Shouldn't generate any new references + expectRootChildren(0); + // will generate no packets. + strfront.string().then(value => { + resolve(value); + }); + }); + rootFront.emitShortString(); + }); + }) + .then(value => { + Assert.equal(value, SHORT_STR); + }) + .then(() => { + // Will generate no packets + return strfront.release(); + }) + .then(() => { + return new Promise(resolve => { + rootFront.once("string-event", str => { + trace.expectSend({ type: "emitLongString", to: "<actorid>" }); + trace.expectReceive({ + type: "string-event", + str: { + type: "longString", + actor: "<actorid>", + length: 16, + initial: "abcde", + }, + from: "<actorid>", + }); + + Assert.ok(!!str); + // Should generate one new reference + expectRootChildren(1); + strfront = str; + strfront.string().then(value => { + trace.expectSend({ + type: "substring", + start: 5, + end: 10, + to: "<actorid>", + }); + trace.expectReceive({ substring: "fghij", from: "<actorid>" }); + trace.expectSend({ + type: "substring", + start: 10, + end: 15, + to: "<actorid>", + }); + trace.expectReceive({ substring: "klmno", from: "<actorid>" }); + trace.expectSend({ + type: "substring", + start: 15, + end: 20, + to: "<actorid>", + }); + trace.expectReceive({ substring: "p", from: "<actorid>" }); + + resolve(value); + }); + }); + rootFront.emitLongString(); + }); + }) + .then(value => { + Assert.equal(value, LONG_STR); + }) + .then(() => { + return strfront.release(); + }) + .then(() => { + trace.expectSend({ type: "release", to: "<actorid>" }); + trace.expectReceive({ from: "<actorid>" }); + expectRootChildren(0); + }) + .then(() => { + client.close().then(() => { + do_test_finished(); + }); + }) + .catch(err => { + do_report_unexpected_exception(err, "Failure executing test"); + }); + }); + do_test_pending(); +} diff --git a/devtools/shared/protocol/tests/xpcshell/test_protocol_simple.js b/devtools/shared/protocol/tests/xpcshell/test_protocol_simple.js new file mode 100644 index 0000000000..523d147f6c --- /dev/null +++ b/devtools/shared/protocol/tests/xpcshell/test_protocol_simple.js @@ -0,0 +1,316 @@ +/* Any copyright is dedicated to the Public Domain. + http://creativecommons.org/publicdomain/zero/1.0/ */ + +"use strict"; + +/** + * Test simple requests using the protocol helpers. + */ + +var protocol = require("resource://devtools/shared/protocol.js"); +var { Arg, Option, RetVal } = protocol; +var EventEmitter = require("resource://devtools/shared/event-emitter.js"); + +const rootSpec = protocol.generateActorSpec({ + typeName: "root", + + events: { + oneway: { a: Arg(0) }, + falsyOptions: { + zero: Option(0), + farce: Option(0), + }, + }, + + methods: { + simpleReturn: { + response: { value: RetVal() }, + }, + promiseReturn: { + response: { value: RetVal("number") }, + }, + simpleArgs: { + request: { + firstArg: Arg(0), + secondArg: Arg(1), + }, + response: RetVal(), + }, + optionArgs: { + request: { + option1: Option(0), + option2: Option(0), + }, + response: RetVal(), + }, + optionalArgs: { + request: { + a: Arg(0), + b: Arg(1, "nullable:number"), + }, + response: { + value: RetVal("number"), + }, + }, + arrayArgs: { + request: { + a: Arg(0, "array:number"), + }, + response: { + arrayReturn: RetVal("array:number"), + }, + }, + nestedArrayArgs: { + request: { a: Arg(0, "array:array:number") }, + response: { value: RetVal("array:array:number") }, + }, + renamedEcho: { + request: { + type: "echo", + a: Arg(0), + }, + response: { + value: RetVal("string"), + }, + }, + testOneWay: { + request: { a: Arg(0) }, + oneway: true, + }, + emitFalsyOptions: { + oneway: true, + }, + }, +}); + +class RootActor extends protocol.Actor { + constructor(conn) { + super(conn, rootSpec); + + // Root actor owns itself. + this.manage(this); + this.actorID = "root"; + } + + sayHello() { + return { + from: "root", + applicationType: "xpcshell-tests", + traits: [], + }; + } + + simpleReturn() { + return 1; + } + + promiseReturn() { + return Promise.resolve(1); + } + + simpleArgs(a, b) { + return { firstResponse: a + 1, secondResponse: b + 1 }; + } + + optionArgs(options) { + return { option1: options.option1, option2: options.option2 }; + } + + optionalArgs(a, b = 200) { + return b; + } + + arrayArgs(a) { + return a; + } + + nestedArrayArgs(a) { + return a; + } + + /** + * Test that the 'type' part of the request packet works + * correctly when the type isn't the same as the method name + */ + renamedEcho(a) { + if (this.conn.currentPacket.type != "echo") { + return "goodbye"; + } + return a; + } + + testOneWay(a) { + // Emit to show that we got this message, because there won't be a response. + EventEmitter.emit(this, "oneway", a); + } + + emitFalsyOptions() { + EventEmitter.emit(this, "falsyOptions", { zero: 0, farce: false }); + } +} + +class RootFront extends protocol.FrontClassWithSpec(rootSpec) { + constructor(client) { + super(client); + this.actorID = "root"; + // Root owns itself. + this.manage(this); + } +} +protocol.registerFront(RootFront); + +add_task(async function () { + DevToolsServer.createRootActor = conn => { + return new RootActor(conn); + }; + DevToolsServer.init(); + + protocol.types.getType("array:array:array:number"); + protocol.types.getType("array:array:array:number"); + + Assert.throws( + () => protocol.types.getType("unknown"), + /Unknown type:/, + "Should throw for unknown type" + ); + Assert.throws( + () => protocol.types.getType("array:unknown"), + /Unknown type:/, + "Should throw for unknown type" + ); + Assert.throws( + () => protocol.types.getType("unknown:number"), + /Unknown collection type:/, + "Should throw for unknown collection type" + ); + const trace = connectPipeTracing(); + const client = new DevToolsClient(trace); + + const [applicationType] = await client.connect(); + trace.expectReceive({ + from: "<actorid>", + applicationType: "xpcshell-tests", + traits: [], + }); + Assert.equal(applicationType, "xpcshell-tests"); + + const rootFront = client.mainRoot; + + let ret = await rootFront.simpleReturn(); + trace.expectSend({ type: "simpleReturn", to: "<actorid>" }); + trace.expectReceive({ value: 1, from: "<actorid>" }); + Assert.equal(ret, 1); + + ret = await rootFront.promiseReturn(); + trace.expectSend({ type: "promiseReturn", to: "<actorid>" }); + trace.expectReceive({ value: 1, from: "<actorid>" }); + Assert.equal(ret, 1); + + Assert.throws( + () => rootFront.simpleArgs(5), + /undefined passed where a value is required/, + "Should throw if simpleArgs is missing an argument." + ); + + ret = await rootFront.simpleArgs(5, 10); + trace.expectSend({ + type: "simpleArgs", + firstArg: 5, + secondArg: 10, + to: "<actorid>", + }); + trace.expectReceive({ + firstResponse: 6, + secondResponse: 11, + from: "<actorid>", + }); + Assert.equal(ret.firstResponse, 6); + Assert.equal(ret.secondResponse, 11); + + ret = await rootFront.optionArgs({ + option1: 5, + option2: 10, + }); + trace.expectSend({ + type: "optionArgs", + option1: 5, + option2: 10, + to: "<actorid>", + }); + trace.expectReceive({ option1: 5, option2: 10, from: "<actorid>" }); + Assert.equal(ret.option1, 5); + Assert.equal(ret.option2, 10); + + ret = await rootFront.optionArgs({}); + trace.expectSend({ type: "optionArgs", to: "<actorid>" }); + trace.expectReceive({ from: "<actorid>" }); + Assert.ok(typeof ret.option1 === "undefined"); + Assert.ok(typeof ret.option2 === "undefined"); + + // Explicitly call an optional argument... + ret = await rootFront.optionalArgs(5, 10); + trace.expectSend({ + type: "optionalArgs", + a: 5, + b: 10, + to: "<actorid>", + }); + trace.expectReceive({ value: 10, from: "<actorid>" }); + Assert.equal(ret, 10); + + // Now don't pass the optional argument, expect the default. + ret = await rootFront.optionalArgs(5); + trace.expectSend({ type: "optionalArgs", a: 5, to: "<actorid>" }); + trace.expectReceive({ value: 200, from: "<actorid>" }); + Assert.equal(ret, 200); + + ret = await rootFront.arrayArgs([0, 1, 2, 3, 4, 5]); + trace.expectSend({ + type: "arrayArgs", + a: [0, 1, 2, 3, 4, 5], + to: "<actorid>", + }); + trace.expectReceive({ + arrayReturn: [0, 1, 2, 3, 4, 5], + from: "<actorid>", + }); + Assert.equal(ret[0], 0); + Assert.equal(ret[5], 5); + + ret = await rootFront.arrayArgs([[5]]); + trace.expectSend({ type: "arrayArgs", a: [[5]], to: "<actorid>" }); + trace.expectReceive({ arrayReturn: [[5]], from: "<actorid>" }); + Assert.equal(ret[0][0], 5); + + const str = await rootFront.renamedEcho("hello"); + trace.expectSend({ type: "echo", a: "hello", to: "<actorid>" }); + trace.expectReceive({ value: "hello", from: "<actorid>" }); + Assert.equal(str, "hello"); + + const onOneWay = rootFront.once("oneway"); + Assert.ok(typeof rootFront.testOneWay("hello") === "undefined"); + const response = await onOneWay; + trace.expectSend({ type: "testOneWay", a: "hello", to: "<actorid>" }); + trace.expectReceive({ + type: "oneway", + a: "hello", + from: "<actorid>", + }); + Assert.equal(response, "hello"); + + const onFalsyOptions = rootFront.once("falsyOptions"); + rootFront.emitFalsyOptions(); + const res = await onFalsyOptions; + trace.expectSend({ type: "emitFalsyOptions", to: "<actorid>" }); + trace.expectReceive({ + type: "falsyOptions", + farce: false, + zero: 0, + from: "<actorid>", + }); + + Assert.ok(res.zero === 0); + Assert.ok(res.farce === false); + + await client.close(); +}); diff --git a/devtools/shared/protocol/tests/xpcshell/test_protocol_stack.js b/devtools/shared/protocol/tests/xpcshell/test_protocol_stack.js new file mode 100644 index 0000000000..faf8402ea6 --- /dev/null +++ b/devtools/shared/protocol/tests/xpcshell/test_protocol_stack.js @@ -0,0 +1,98 @@ +/* Any copyright is dedicated to the Public Domain. + http://creativecommons.org/publicdomain/zero/1.0/ */ + +"use strict"; + +/** + * Client request stacks should span the entire process from before making the + * request to handling the reply from the server. The server frames are not + * included, nor can they be in most cases, since the server can be a remote + * device. + */ + +var protocol = require("resource://devtools/shared/protocol.js"); +var { RetVal } = protocol; + +const rootSpec = protocol.generateActorSpec({ + typeName: "root", + + methods: { + simpleReturn: { + response: { value: RetVal() }, + }, + }, +}); + +class RootActor extends protocol.Actor { + constructor(conn) { + super(conn, rootSpec); + + // Root actor owns itself. + this.manage(this); + this.actorID = "root"; + this.sequence = 0; + } + + sayHello() { + return { + from: "root", + applicationType: "xpcshell-tests", + traits: [], + }; + } + + simpleReturn() { + return this.sequence++; + } +} + +class RootFront extends protocol.FrontClassWithSpec(rootSpec) { + constructor(client) { + super(client); + this.actorID = "root"; + // Root owns itself. + this.manage(this); + } +} +protocol.registerFront(RootFront); + +function run_test() { + DevToolsServer.createRootActor = conn => new RootActor(conn); + DevToolsServer.init(); + + const trace = connectPipeTracing(); + const client = new DevToolsClient(trace); + let rootFront; + + client.connect().then(function onConnect() { + rootFront = client.mainRoot; + + rootFront + .simpleReturn() + .then( + () => { + let stack = Components.stack; + while (stack) { + info(stack.name); + if (stack.name.includes("onConnect")) { + // Reached back to outer function before request + ok(true, "Complete stack"); + return; + } + stack = stack.asyncCaller || stack.caller; + } + ok(false, "Incomplete stack"); + }, + () => { + ok(false, "Request failed unexpectedly"); + } + ) + .then(() => { + client.close().then(() => { + do_test_finished(); + }); + }); + }); + + do_test_pending(); +} diff --git a/devtools/shared/protocol/tests/xpcshell/test_protocol_types.js b/devtools/shared/protocol/tests/xpcshell/test_protocol_types.js new file mode 100644 index 0000000000..4a62c5e073 --- /dev/null +++ b/devtools/shared/protocol/tests/xpcshell/test_protocol_types.js @@ -0,0 +1,65 @@ +"use strict"; + +const { types } = require("resource://devtools/shared/protocol.js"); + +function run_test() { + types.addActorType("myActor1"); + types.addActorType("myActor2"); + types.addActorType("myActor3"); + + types.addPolymorphicType("ptype1", ["myActor1", "myActor2"]); + const ptype1 = types.getType("ptype1"); + Assert.equal(ptype1.name, "ptype1"); + Assert.equal(ptype1.category, "polymorphic"); + + types.addPolymorphicType("ptype2", ["myActor1", "myActor2", "myActor3"]); + const ptype2 = types.getType("ptype2"); + Assert.equal(ptype2.name, "ptype2"); + Assert.equal(ptype2.category, "polymorphic"); + + // Polymorphic types only accept actor types + try { + types.addPolymorphicType("ptype", ["myActor1", "myActor4"]); + Assert.ok(false, "getType should fail"); + } catch (ex) { + Assert.equal(ex.toString(), "Error: Unknown type: myActor4"); + } + try { + types.addPolymorphicType("ptype", ["myActor1", "string"]); + Assert.ok(false, "getType should fail"); + } catch (ex) { + Assert.equal( + ex.toString(), + "Error: In polymorphic type 'myActor1,string', the type 'string' isn't an actor" + ); + } + try { + types.addPolymorphicType("ptype", ["myActor1", "boolean"]); + Assert.ok(false, "getType should fail"); + } catch (ex) { + Assert.equal( + ex.toString(), + "Error: In polymorphic type 'myActor1,boolean', the type 'boolean' isn't an actor" + ); + } + + // Polymorphic types are not compatible with array or nullables + try { + types.addPolymorphicType("ptype", ["array:myActor1", "myActor2"]); + Assert.ok(false, "addType should fail"); + } catch (ex) { + Assert.equal( + ex.toString(), + "Error: In polymorphic type 'array:myActor1,myActor2', the type 'array:myActor1' isn't an actor" + ); + } + try { + types.addPolymorphicType("ptype", ["nullable:myActor1", "myActor2"]); + Assert.ok(false, "addType should fail"); + } catch (ex) { + Assert.equal( + ex.toString(), + "Error: In polymorphic type 'nullable:myActor1,myActor2', the type 'nullable:myActor1' isn't an actor" + ); + } +} diff --git a/devtools/shared/protocol/tests/xpcshell/test_protocol_unregister.js b/devtools/shared/protocol/tests/xpcshell/test_protocol_unregister.js new file mode 100644 index 0000000000..060a1743b1 --- /dev/null +++ b/devtools/shared/protocol/tests/xpcshell/test_protocol_unregister.js @@ -0,0 +1,41 @@ +"use strict"; + +const { types } = require("resource://devtools/shared/protocol.js"); + +function run_test() { + types.addType("test", { + read: v => "successful read: " + v, + write: v => "successful write: " + v, + }); + + // Verify the type registered correctly. + + const type = types.getType("test"); + const arrayType = types.getType("array:test"); + Assert.equal(type.read("foo"), "successful read: foo"); + Assert.equal(arrayType.read(["foo"])[0], "successful read: foo"); + + types.removeType("test"); + + Assert.equal(type.name, "DEFUNCT:test"); + try { + types.getType("test"); + Assert.ok(false, "getType should fail"); + } catch (ex) { + Assert.equal(ex.toString(), "Error: Unknown type: test"); + } + + try { + type.read("foo"); + Assert.ok(false, "type.read should have thrown an exception."); + } catch (ex) { + Assert.equal(ex.toString(), "Error: Using defunct type: test"); + } + + try { + arrayType.read(["foo"]); + Assert.ok(false, "array:test.read should have thrown an exception."); + } catch (ex) { + Assert.equal(ex.toString(), "Error: Using defunct type: test"); + } +} diff --git a/devtools/shared/protocol/tests/xpcshell/test_protocol_watchFronts.js b/devtools/shared/protocol/tests/xpcshell/test_protocol_watchFronts.js new file mode 100644 index 0000000000..16f98f176b --- /dev/null +++ b/devtools/shared/protocol/tests/xpcshell/test_protocol_watchFronts.js @@ -0,0 +1,183 @@ +/* Any copyright is dedicated to the Public Domain. + http://creativecommons.org/publicdomain/zero/1.0/ */ + +"use strict"; + +/** + * Test Front.watchFronts method. + */ + +const protocol = require("resource://devtools/shared/protocol.js"); +const { RetVal } = protocol; + +const childSpec = protocol.generateActorSpec({ + typeName: "childActor", + + methods: { + release: { + release: true, + }, + }, +}); + +class ChildActor extends protocol.Actor { + constructor(conn, id) { + super(conn, childSpec); + this.childID = id; + } + + release() {} + + form() { + return { + actor: this.actorID, + childID: this.childID, + foo: "bar", + }; + } +} + +const rootSpec = protocol.generateActorSpec({ + typeName: "root", + + methods: { + createChild: { + request: {}, + response: { actor: RetVal("childActor") }, + }, + }, +}); + +class RootActor extends protocol.Actor { + constructor(conn) { + super(conn, rootSpec); + + this.actorID = "root"; + + // Root actor owns itself. + this.manage(this); + + this.sequence = 0; + } + + sayHello() { + return { + from: "root", + applicationType: "xpcshell-tests", + traits: [], + }; + } + + createChild() { + return new ChildActor(this.conn, this.sequence++); + } +} + +class ChildFront extends protocol.FrontClassWithSpec(childSpec) { + form(form) { + this.childID = form.childID; + this.foo = form.foo; + } +} +protocol.registerFront(ChildFront); + +class RootFront extends protocol.FrontClassWithSpec(rootSpec) { + constructor(client) { + super(client); + this.actorID = "root"; + // Root owns itself. + this.manage(this); + } +} +protocol.registerFront(RootFront); + +add_task(async function run_test() { + DevToolsServer.createRootActor = conn => new RootActor(conn); + DevToolsServer.init(); + + const trace = connectPipeTracing(); + const client = new DevToolsClient(trace); + await client.connect(); + + const rootFront = client.mainRoot; + + const fronts = []; + const listener = front => { + equal( + front.foo, + "bar", + "Front's form is set before watchFronts listeners are called" + ); + fronts.push(front); + }; + rootFront.watchFronts("childActor", listener); + + const firstChild = await rootFront.createChild(); + ok( + firstChild instanceof ChildFront, + "createChild returns a ChildFront instance" + ); + equal(firstChild.childID, 0, "First child has ID=0"); + + equal( + fronts.length, + 1, + "watchFronts fires the callback, even if the front is created in the future" + ); + equal( + fronts[0], + firstChild, + "watchFronts fires the callback with the right front instance" + ); + + const watchFrontsAfter = await new Promise(resolve => { + rootFront.watchFronts("childActor", resolve); + }); + equal( + watchFrontsAfter, + firstChild, + "watchFronts fires the callback, even if the front is already created, " + + " with the same front instance" + ); + + equal( + fronts.length, + 1, + "There is still only one front reported from the first listener" + ); + + const secondChild = await rootFront.createChild(); + + equal( + fronts.length, + 2, + "After a second call to createChild, two fronts are reported" + ); + equal(fronts[1], secondChild, "And the new front is the right instance"); + + // Test unregistering a front listener + rootFront.unwatchFronts("childActor", listener); + + const thirdChild = await rootFront.createChild(); + equal( + fronts.length, + 2, + "After calling unwatchFronts, the listener is no longer called" + ); + + // Test front destruction + const destroyed = []; + rootFront.watchFronts("childActor", null, front => { + destroyed.push(front); + }); + await thirdChild.release(); + equal( + destroyed.length, + 1, + "After the destruction of the front, one destruction is reported" + ); + equal(destroyed[0], thirdChild, "And the destroyed front is the right one"); + + trace.close(); + await client.close(); +}); diff --git a/devtools/shared/protocol/tests/xpcshell/xpcshell.ini b/devtools/shared/protocol/tests/xpcshell/xpcshell.ini new file mode 100644 index 0000000000..9af8c5de49 --- /dev/null +++ b/devtools/shared/protocol/tests/xpcshell/xpcshell.ini @@ -0,0 +1,19 @@ +[DEFAULT] +tags = devtools +head = head.js +firefox-appdir = browser +skip-if = toolkit == 'android' +support-files = + +[test_protocol_abort.js] +[test_protocol_async.js] +[test_protocol_children.js] +[test_protocol_index.js] +[test_protocol_invalid_response.js] +[test_protocol_lifecycle.js] +[test_protocol_longstring.js] +[test_protocol_simple.js] +[test_protocol_stack.js] +[test_protocol_types.js] +[test_protocol_unregister.js] +[test_protocol_watchFronts.js] diff --git a/devtools/shared/protocol/types.js b/devtools/shared/protocol/types.js new file mode 100644 index 0000000000..41764fbd79 --- /dev/null +++ b/devtools/shared/protocol/types.js @@ -0,0 +1,587 @@ +/* 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/. */ + +"use strict"; + +var { Actor } = require("resource://devtools/shared/protocol/Actor.js"); +var { + lazyLoadSpec, + lazyLoadFront, +} = require("resource://devtools/shared/specs/index.js"); + +/** + * Types: named marshallers/demarshallers. + * + * Types provide a 'write' function that takes a js representation and + * returns a protocol representation, and a "read" function that + * takes a protocol representation and returns a js representation. + * + * The read and write methods are also passed a context object that + * represent the actor or front requesting the translation. + * + * Types are referred to with a typestring. Basic types are + * registered by name using addType, and more complex types can + * be generated by adding detail to the type name. + */ + +var types = Object.create(null); +exports.types = types; + +var registeredTypes = (types.registeredTypes = new Map()); + +exports.registeredTypes = registeredTypes; + +/** + * Return the type object associated with a given typestring. + * If passed a type object, it will be returned unchanged. + * + * Types can be registered with addType, or can be created on + * the fly with typestrings. Examples: + * + * boolean + * threadActor + * threadActor#detail + * array:threadActor + * array:array:threadActor#detail + * + * @param [typestring|type] type + * Either a typestring naming a type or a type object. + * + * @returns a type object. + */ +types.getType = function (type) { + if (!type) { + return types.Primitive; + } + + if (typeof type !== "string") { + return type; + } + + // If already registered, we're done here. + let reg = registeredTypes.get(type); + if (reg) { + return reg; + } + + // Try to lazy load the spec, if not already loaded. + if (lazyLoadSpec(type)) { + // If a spec module was lazy loaded, it will synchronously call + // generateActorSpec, and set the type in `registeredTypes`. + reg = registeredTypes.get(type); + if (reg) { + return reg; + } + } + + // New type, see if it's a collection type: + const sep = type.indexOf(":"); + if (sep >= 0) { + const collection = type.substring(0, sep); + const subtype = types.getType(type.substring(sep + 1)); + + if (collection === "array") { + return types.addArrayType(subtype); + } else if (collection === "nullable") { + return types.addNullableType(subtype); + } + + throw Error("Unknown collection type: " + collection); + } + + // Not a collection, might be actor detail + const pieces = type.split("#", 2); + if (pieces.length > 1) { + if (pieces[1] != "actorid") { + throw new Error( + "Unsupported detail, only support 'actorid', got: " + pieces[1] + ); + } + return types.addActorDetail(type, pieces[0], pieces[1]); + } + + throw Error("Unknown type: " + type); +}; + +/** + * Don't allow undefined when writing primitive types to packets. If + * you want to allow undefined, use a nullable type. + */ +function identityWrite(v) { + if (v === undefined) { + throw Error("undefined passed where a value is required"); + } + // This has to handle iterator->array conversion because arrays of + // primitive types pass through here. + if (v && typeof v.next === "function") { + return [...v]; + } + return v; +} + +/** + * Add a type to the type system. + * + * When registering a type, you can provide `read` and `write` methods. + * + * The `read` method will be passed a JS object value from the JSON + * packet and must return a native representation. The `write` method will + * be passed a native representation and should provide a JSONable value. + * + * These methods will both be passed a context. The context is the object + * performing or servicing the request - on the server side it will be + * an Actor, on the client side it will be a Front. + * + * @param typestring name + * Name to register + * @param object typeObject + * An object whose properties will be stored in the type, including + * the `read` and `write` methods. + * @param object options + * Can specify `thawed` to prevent the type from being frozen. + * + * @returns a type object that can be used in protocol definitions. + */ +types.addType = function (name, typeObject = {}, options = {}) { + if (registeredTypes.has(name)) { + throw Error("Type '" + name + "' already exists."); + } + + const type = Object.assign( + { + toString() { + return "[protocol type:" + name + "]"; + }, + name, + primitive: !(typeObject.read || typeObject.write), + read: identityWrite, + write: identityWrite, + }, + typeObject + ); + + registeredTypes.set(name, type); + + return type; +}; + +/** + * Remove a type previously registered with the system. + * Primarily useful for types registered by addons. + */ +types.removeType = function (name) { + // This type may still be referenced by other types, make sure + // those references don't work. + const type = registeredTypes.get(name); + + type.name = "DEFUNCT:" + name; + type.category = "defunct"; + type.primitive = false; + type.read = type.write = function () { + throw new Error("Using defunct type: " + name); + }; + + registeredTypes.delete(name); +}; + +/** + * Add an array type to the type system. + * + * getType() will call this function if provided an "array:<type>" + * typestring. + * + * @param type subtype + * The subtype to be held by the array. + */ +types.addArrayType = function (subtype) { + subtype = types.getType(subtype); + + const name = "array:" + subtype.name; + + // Arrays of primitive types are primitive types themselves. + if (subtype.primitive) { + return types.addType(name); + } + return types.addType(name, { + category: "array", + read: (v, ctx) => { + if (v && typeof v.next === "function") { + v = [...v]; + } + return v.map(i => subtype.read(i, ctx)); + }, + write: (v, ctx) => { + if (v && typeof v.next === "function") { + v = [...v]; + } + return v.map(i => subtype.write(i, ctx)); + }, + }); +}; + +/** + * Add a dict type to the type system. This allows you to serialize + * a JS object that contains non-primitive subtypes. + * + * Properties of the value that aren't included in the specializations + * will be serialized as primitive values. + * + * @param object specializations + * A dict of property names => type + */ +types.addDictType = function (name, specializations) { + const specTypes = {}; + for (const prop in specializations) { + try { + specTypes[prop] = types.getType(specializations[prop]); + } catch (e) { + // Types may not be defined yet. Sometimes, we define the type *after* using it, but + // also, we have cyclic definitions on types. So lazily load them when they are not + // immediately available. + loader.lazyGetter(specTypes, prop, () => { + return types.getType(specializations[prop]); + }); + } + } + return types.addType(name, { + category: "dict", + specializations, + read: (v, ctx) => { + const ret = {}; + for (const prop in v) { + if (prop in specTypes) { + ret[prop] = specTypes[prop].read(v[prop], ctx); + } else { + ret[prop] = v[prop]; + } + } + return ret; + }, + + write: (v, ctx) => { + const ret = {}; + for (const prop in v) { + if (prop in specTypes) { + ret[prop] = specTypes[prop].write(v[prop], ctx); + } else { + ret[prop] = v[prop]; + } + } + return ret; + }, + }); +}; + +/** + * Register an actor type with the type system. + * + * Types are marshalled differently when communicating server->client + * than they are when communicating client->server. The server needs + * to provide useful information to the client, so uses the actor's + * `form` method to get a json representation of the actor. When + * making a request from the client we only need the actor ID string. + * + * This function can be called before the associated actor has been + * constructed, but the read and write methods won't work until + * the associated addActorImpl or addActorFront methods have been + * called during actor/front construction. + * + * @param string name + * The typestring to register. + */ +types.addActorType = function (name) { + // We call addActorType from: + // FrontClassWithSpec when registering front synchronously, + // generateActorSpec when defining specs, + // specs modules to register actor type early to use them in other types + if (registeredTypes.has(name)) { + return registeredTypes.get(name); + } + const type = types.addType(name, { + _actor: true, + category: "actor", + read: (v, ctx, detail) => { + // If we're reading a request on the server side, just + // find the actor registered with this actorID. + if (ctx instanceof Actor) { + return ctx.conn.getActor(v); + } + + // Reading a response on the client side, check for an + // existing front on the connection, and create the front + // if it isn't found. + const actorID = typeof v === "string" ? v : v.actor; + // `ctx.conn` is a DevToolsClient + let front = ctx.conn.getFrontByID(actorID); + + // When the type `${name}#actorid` is used, `v` is a string refering to the + // actor ID. We cannot read form information in this case and the actorID was + // already set when creating the front, so no need to do anything. + let form = null; + if (detail != "actorid") { + form = identityWrite(v); + } + + if (!front) { + // If front isn't instantiated yet, create one. + // Try lazy loading front if not already loaded. + // The front module will synchronously call `FrontClassWithSpec` and + // augment `type` with the `frontClass` attribute. + if (!type.frontClass) { + lazyLoadFront(name); + } + + const parentFront = ctx.marshallPool(); + const targetFront = parentFront.isTargetFront + ? parentFront + : parentFront.targetFront; + + // Use intermediate Class variable to please eslint requiring + // a capital letter for all constructors. + const Class = type.frontClass; + front = new Class(ctx.conn, targetFront, parentFront); + front.actorID = actorID; + + parentFront.manage(front, form, ctx); + } else if (form) { + front.form(form, ctx); + } + + return front; + }, + write: (v, ctx, detail) => { + // If returning a response from the server side, make sure + // the actor is added to a parent object and return its form. + if (v instanceof Actor) { + if (v.isDestroyed()) { + throw new Error( + `Attempted to write a response containing a destroyed actor` + ); + } + if (!v.actorID) { + ctx.marshallPool().manage(v); + } + if (detail == "actorid") { + return v.actorID; + } + return identityWrite(v.form(detail)); + } + + // Writing a request from the client side, just send the actor id. + return v.actorID; + }, + }); + return type; +}; + +types.addPolymorphicType = function (name, subtypes) { + // Assert that all subtypes are actors, as the marshalling implementation depends on that. + for (const subTypeName of subtypes) { + const subtype = types.getType(subTypeName); + if (subtype.category != "actor") { + throw new Error( + `In polymorphic type '${subtypes.join( + "," + )}', the type '${subTypeName}' isn't an actor` + ); + } + } + + return types.addType(name, { + category: "polymorphic", + read: (value, ctx) => { + // `value` is either a string which is an Actor ID or a form object + // where `actor` is an actor ID + const actorID = typeof value === "string" ? value : value.actor; + if (!actorID) { + throw new Error( + `Was expecting one of these actors '${subtypes}' but instead got value: '${value}'` + ); + } + + // Extract the typeName out of the actor ID, which should be composed like this + // ${DevToolsServerConnectionPrefix}.${typeName}${Number} + const typeName = actorID.match(/\.([a-zA-Z]+)\d+$/)[1]; + if (!subtypes.includes(typeName)) { + throw new Error( + `Was expecting one of these actors '${subtypes}' but instead got an actor of type: '${typeName}'` + ); + } + + const subtype = types.getType(typeName); + return subtype.read(value, ctx); + }, + write: (value, ctx) => { + if (!value) { + throw new Error( + `Was expecting one of these actors '${subtypes}' but instead got an empty value.` + ); + } + // value is either an `Actor` or a `Front` and both classes exposes a `typeName` + const typeName = value.typeName; + if (!typeName) { + throw new Error( + `Was expecting one of these actors '${subtypes}' but instead got value: '${value}'. Did you pass a form instead of an Actor?` + ); + } + + if (!subtypes.includes(typeName)) { + throw new Error( + `Was expecting one of these actors '${subtypes}' but instead got an actor of type: '${typeName}'` + ); + } + + const subtype = types.getType(typeName); + return subtype.write(value, ctx); + }, + }); +}; +types.addNullableType = function (subtype) { + subtype = types.getType(subtype); + return types.addType("nullable:" + subtype.name, { + category: "nullable", + read: (value, ctx) => { + if (value == null) { + return value; + } + return subtype.read(value, ctx); + }, + write: (value, ctx) => { + if (value == null) { + return value; + } + return subtype.write(value, ctx); + }, + }); +}; + +/** + * Register an actor detail type. This is just like an actor type, but + * will pass a detail hint to the actor's form method during serialization/ + * deserialization. + * + * This is called by getType() when passed an 'actorType#detail' string. + * + * @param string name + * The typestring to register this type as. + * @param type actorType + * The actor type you'll be detailing. + * @param string detail + * The detail to pass. + */ +types.addActorDetail = function (name, actorType, detail) { + actorType = types.getType(actorType); + if (!actorType._actor) { + throw Error( + `Details only apply to actor types, tried to add detail '${detail}' ` + + `to ${actorType.name}` + ); + } + return types.addType(name, { + _actor: true, + category: "detail", + read: (v, ctx) => actorType.read(v, ctx, detail), + write: (v, ctx) => actorType.write(v, ctx, detail), + }); +}; + +// Add a few named primitive types. +types.Primitive = types.addType("primitive"); +types.String = types.addType("string"); +types.Number = types.addType("number"); +types.Boolean = types.addType("boolean"); +types.JSON = types.addType("json"); + +exports.registerFront = function (cls) { + const { typeName } = cls.prototype; + if (!registeredTypes.has(typeName)) { + types.addActorType(typeName); + } + registeredTypes.get(typeName).frontClass = cls; +}; + +/** + * Instantiate a front of the given type. + * + * @param DevToolsClient client + * The DevToolsClient instance to use. + * @param string typeName + * The type name of the front to instantiate. This is defined in its specifiation. + * @returns Front + * The created front. + */ +function createFront(client, typeName, target = null) { + const type = types.getType(typeName); + if (!type) { + throw new Error(`No spec for front type '${typeName}'.`); + } else if (!type.frontClass) { + lazyLoadFront(typeName); + } + + // Use intermediate Class variable to please eslint requiring + // a capital letter for all constructors. + const Class = type.frontClass; + return new Class(client, target, target); +} + +/** + * Instantiate a global (preference, device) or target-scoped (webconsole, inspector) + * front of the given type by picking its actor ID out of either the target or root + * front's form. + * + * @param DevToolsClient client + * The DevToolsClient instance to use. + * @param string typeName + * The type name of the front to instantiate. This is defined in its specifiation. + * @param json form + * If we want to instantiate a global actor's front, this is the root front's form, + * otherwise we are instantiating a target-scoped front from the target front's form. + * @param [Target|null] target + * If we are instantiating a target-scoped front, this is a reference to the front's + * Target instance, otherwise this is null. + */ +async function getFront(client, typeName, form, target = null) { + const front = createFront(client, typeName, target); + const { formAttributeName } = front; + if (!formAttributeName) { + throw new Error(`Can't find the form attribute name for ${typeName}`); + } + // Retrieve the actor ID from root or target actor's form + front.actorID = form[formAttributeName]; + if (!front.actorID) { + throw new Error( + `Can't find the actor ID for ${typeName} from root or target` + + ` actor's form.` + ); + } + + if (!target) { + await front.manage(front); + } else { + await target.manage(front); + } + + return front; +} +exports.getFront = getFront; + +/** + * Create a RootFront. + * + * @param DevToolsClient client + * The DevToolsClient instance to use. + * @param Object packet + * @returns RootFront + */ +function createRootFront(client, packet) { + const rootFront = createFront(client, "root"); + rootFront.form(packet); + + // Root Front is a special case, managing itself as it doesn't have any parent. + // It will register itself to DevToolsClient as a Pool via Front._poolMap. + rootFront.manage(rootFront); + + return rootFront; +} +exports.createRootFront = createRootFront; diff --git a/devtools/shared/protocol/utils.js b/devtools/shared/protocol/utils.js new file mode 100644 index 0000000000..3433c2f446 --- /dev/null +++ b/devtools/shared/protocol/utils.js @@ -0,0 +1,44 @@ +/* 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/. */ + +"use strict"; + +/** + * Find Placeholders in the template and save them along with their + * paths. + */ +function findPlaceholders(template, constructor, path = [], placeholders = []) { + if (!template || typeof template != "object") { + return placeholders; + } + + if (template instanceof constructor) { + placeholders.push({ placeholder: template, path: [...path] }); + return placeholders; + } + + for (const name in template) { + path.push(name); + findPlaceholders(template[name], constructor, path, placeholders); + path.pop(); + } + + return placeholders; +} + +exports.findPlaceholders = findPlaceholders; + +/** + * Get the value at a given path, or undefined if not found. + */ +function getPath(obj, path) { + for (const name of path) { + if (!(name in obj)) { + return undefined; + } + obj = obj[name]; + } + return obj; +} +exports.getPath = getPath; |