The Tor Browser: comparison toolkit/devtools/server/protocol.js

comparison: toolkit/devtools/server/protocol.js

toolkit/devtools/server/protocol.js

branch: TOR_BUG_3246
changeset 7: 129ffea94266

equal deleted inserted replaced

--1:000000000000
+:8e3f7fbf6260
+/* 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";
+let {Cu} = require("chrome");
+let Services = require("Services");
+let promise = require("devtools/toolkit/deprecated-sync-thenables");
+let {Class} = require("sdk/core/heritage");
+let {EventTarget} = require("sdk/event/target");
+let events = require("sdk/event/core");
+let object = require("sdk/util/object");
+// Waiting for promise.done() to be added, see bug 851321
+function promiseDone(err) {
+console.error(err);
+return promise.reject(err);
+}
+/**
+* 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.
+*/
+let types = Object.create(null);
+exports.types = types;
+let registeredTypes = new Map();
+let registeredLifetimes = new Map();
+/**
+* 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;
+// New type, see if it's a collection/lifetime type:
+let sep = type.indexOf(":");
+if (sep >= 0) {
+let collection = type.substring(0, sep);
+let subtype = types.getType(type.substring(sep + 1));
+if (collection === "array") {
+return types.addArrayType(subtype);
+} else if (collection === "nullable") {
+return types.addNullableType(subtype);
+}
+if (registeredLifetimes.has(collection)) {
+return types.addLifetimeType(collection, subtype);
+}
+throw Error("Unknown collection type: " + collection);
+}
+// Not a collection, might be actor detail
+let pieces = type.split("#", 2);
+if (pieces.length > 1) {
+return types.addActorDetail(type, pieces[0], pieces[1]);
+}
+// Might be a lazily-loaded type
+if (type === "longstring") {
+require("devtools/server/actors/string");
+return registeredTypes.get("longstring");
+}
+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");
+}
+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.");
+}
+let type = object.merge({
+name: name,
+primitive: !(typeObject.read || typeObject.write),
+read: identityWrite,
+write: identityWrite
+}, typeObject);
+registeredTypes.set(name, type);
+if (!options.thawed) {
+Object.freeze(type);
+}
+return type;
+};
+/**
+* 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);
+let 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) => [subtype.read(i, ctx) for (i of v)],
+write: (v, ctx) => [subtype.write(i, ctx) for (i of v)]
+});
+};
+/**
+* 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) {
+return types.addType(name, {
+category: "dict",
+specializations: specializations,
+read: (v, ctx) => {
+let ret = {};
+for (let prop in v) {
+if (prop in specializations) {
+ret[prop] = types.getType(specializations[prop]).read(v[prop], ctx);
+} else {
+ret[prop] = v[prop];
+}
+}
+return ret;
+},
+write: (v, ctx) => {
+let ret = {};
+for (let prop in v) {
+if (prop in specializations) {
+ret[prop] = types.getType(specializations[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) {
+let 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.
+let actorID = typeof(v) === "string" ? v : v.actor;
+let front = ctx.conn.getActor(actorID);
+if (front) {
+front.form(v, detail, ctx);
+} else {
+front = new type.frontClass(ctx.conn, v, detail, ctx)
+front.actorID = actorID;
+ctx.marshallPool().manage(front);
+}
+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.actorID) {
+ctx.marshallPool().manage(v);
+}
+return v.form(detail);
+}
+// Writing a request from the client side, just send the actor id.
+return v.actorID;
+},
+}, {
+// We usually freeze types, but actor types are updated when clients are
+// created, so don't freeze yet.
+thawed: true
+});
+return type;
+}
+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 + "\n");
+}
+return types.addType(name, {
+_actor: true,
+category: "detail",
+read: (v, ctx) => actorType.read(v, ctx, detail),
+write: (v, ctx) => actorType.write(v, ctx, detail)
+});
+}
+/**
+* Register an actor lifetime.  This lets the type system find a parent
+* actor that differs from the actor fulfilling the request.
+*
+* @param string name
+*    The lifetime name to use in typestrings.
+* @param string prop
+*    The property of the actor that holds the parent that should be used.
+*/
+types.addLifetime = function(name, prop) {
+if (registeredLifetimes.has(name)) {
+throw Error("Lifetime '" + name + "' already registered.");
+}
+registeredLifetimes.set(name, prop);
+}
+/**
+* Register a lifetime type.  This creates an actor type tied to the given
+* lifetime.
+*
+* This is called by getType() when passed a '<lifetimeType>:<actorType>'
+* typestring.
+*
+* @param string lifetime
+*    A lifetime string previously regisered with addLifetime()
+* @param type subtype
+*    An actor type
+*/
+types.addLifetimeType = function(lifetime, subtype) {
+subtype = types.getType(subtype);
+if (!subtype._actor) {
+throw Error("Lifetimes only apply to actor types, tried to apply lifetime '" + lifetime + "'' to " + subtype.name);
+}
+let prop = registeredLifetimes.get(lifetime);
+return types.addType(lifetime + ":" + subtype.name, {
+category: "lifetime",
+read: (value, ctx) => subtype.read(value, ctx[prop]),
+write: (value, ctx) => subtype.write(value, ctx[prop])
+})
+}
+// 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");
+/**
+* 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
+*/
+let Arg = Class({
+initialize: function(index, type) {
+this.index = index;
+this.type = types.getType(type);
+},
+write: function(arg, ctx) {
+return this.type.write(arg, ctx);
+},
+read: function(v, ctx, outArgs) {
+outArgs[this.index] = this.type.read(v, ctx);
+},
+describe: function() {
+return {
+_arg: this.index,
+type: this.type.name,
+}
+}
+});
+exports.Arg = Arg;
+/**
+* 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
+*/
+let Option = Class({
+extends: Arg,
+initialize: function(index, type) {
+Arg.prototype.initialize.call(this, index, type)
+},
+write: function(arg, ctx, name) {
+if (!arg) {
+return undefined;
+}
+let v = arg[name] || undefined;
+if (v === undefined) {
+return undefined;
+}
+return this.type.write(v, ctx);
+},
+read: function(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);
+},
+describe: function() {
+return {
+_option: this.index,
+type: this.type.name,
+}
+}
+});
+exports.Option = Option;
+/**
+* Placeholder for return values in a response template.
+*
+* @param type type
+*    The return value should be marshalled as this type.
+*/
+let RetVal = Class({
+initialize: function(type) {
+this.type = types.getType(type);
+},
+write: function(v, ctx) {
+return this.type.write(v, ctx);
+},
+read: function(v, ctx) {
+return this.type.read(v, ctx);
+},
+describe: function() {
+return {
+_retval: this.type.name
+}
+}
+});
+exports.RetVal = RetVal;
+/* Template handling functions */
+/**
+* Get the value at a given path, or undefined if not found.
+*/
+function getPath(obj, path) {
+for (let name of path) {
+if (!(name in obj)) {
+return undefined;
+}
+obj = obj[name];
+}
+return obj;
+}
+/**
+* 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: [p for (p of path)] });
+return placeholders;
+}
+for (let name in template) {
+path.push(name);
+findPlaceholders(template[name], constructor, path, placeholders);
+path.pop();
+}
+return placeholders;
+}
+function describeTemplate(template) {
+return JSON.parse(JSON.stringify(template, (key, value) => {
+if (value.describe) {
+return value.describe();
+}
+return value;
+}));
+}
+/**
+* Manages a request template.
+*
+* @param object template
+*    The request template.
+* @construcor
+*/
+let Request = Class({
+initialize: function(template={}) {
+this.type = template.type;
+this.template = template;
+this.args = findPlaceholders(template, Arg);
+},
+/**
+* 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: function(fnArgs, ctx) {
+let str = JSON.stringify(this.template, (key, value) => {
+if (value instanceof Arg) {
+return value.write(fnArgs[value.index], ctx, key);
+}
+return value;
+});
+return JSON.parse(str);
+},
+/**
+* Read a request.
+*
+* @param object packet
+*    The request packet.
+* @param object ctx
+*    The object making the request.
+* @returns an arguments array
+*/
+read: function(packet, ctx) {
+let fnArgs = [];
+for (let templateArg of this.args) {
+let arg = templateArg.placeholder;
+let path = templateArg.path;
+let name = path[path.length - 1];
+arg.read(getPath(packet, path), ctx, fnArgs, name);
+}
+return fnArgs;
+},
+describe: function() { return describeTemplate(this.template); }
+});
+/**
+* Manages a response template.
+*
+* @param object template
+*    The response template.
+* @construcor
+*/
+let Response = Class({
+initialize: function(template={}) {
+this.template = template;
+let placeholders = findPlaceholders(template, RetVal);
+if (placeholders.length > 1) {
+throw Error("More than one RetVal specified in response");
+}
+let placeholder = placeholders.shift();
+if (placeholder) {
+this.retVal = placeholder.placeholder;
+this.path = placeholder.path;
+}
+},
+/**
+* Write a response for the given return value.
+*
+* @param val ret
+*    The return value.
+* @param object ctx
+*    The object writing the response.
+*/
+write: function(ret, ctx) {
+return JSON.parse(JSON.stringify(this.template, function(key, value) {
+if (value instanceof RetVal) {
+return value.write(ret, ctx);
+}
+return value;
+}));
+},
+/**
+* Read a return value from the given response.
+*
+* @param object packet
+*    The response packet.
+* @param object ctx
+*    The object reading the response.
+*/
+read: function(packet, ctx) {
+if (!this.retVal) {
+return undefined;
+}
+let v = getPath(packet, this.path);
+return this.retVal.read(v, ctx);
+},
+describe: function() { return describeTemplate(this.template); }
+});
+/**
+* Actor and Front implementations
+*/
+/**
+* A protocol object that can manage the lifetime of other protocol
+* objects.
+*/
+let Pool = Class({
+extends: EventTarget,
+/**
+* Pools are used on both sides of the connection to help coordinate
+* lifetimes.
+*
+* @param optional conn
+*   Either a DebuggerServerConnection or a DebuggerClient.  Must have
+*   addActorPool, removeActorPool, and poolFor.
+*   conn can be null if the subclass provides a conn property.
+* @constructor
+*/
+initialize: function(conn) {
+if (conn) {
+this.conn = conn;
+}
+},
+/**
+* Return the parent pool for this client.
+*/
+parent: function() { return this.conn.poolFor(this.actorID) },
+/**
+* Override this if you want actors returned by this actor
+* to belong to a different actor by default.
+*/
+marshallPool: function() { 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.
+*/
+__poolMap: null,
+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: function(actor) {
+if (!actor.actorID) {
+actor.actorID = this.conn.allocID(actor.actorPrefix || actor.typeName);
+}
+this._poolMap.set(actor.actorID, actor);
+return actor;
+},
+/**
+* Remove an actor as a child of this pool.
+*/
+unmanage: function(actor) {
+this.__poolMap.delete(actor.actorID);
+},
+// true if the given actor ID exists in the pool.
+has: function(actorID) this.__poolMap && this._poolMap.has(actorID),
+// The actor for a given actor id stored in this pool
+actor: function(actorID) this.__poolMap ? this._poolMap.get(actorID) : null,
+// Same as actor, should update debugger connection to use 'actor'
+// and then remove this.
+get: function(actorID) this.__poolMap ? this._poolMap.get(actorID) : null,
+// True if this pool has no children.
+isEmpty: function() !this.__poolMap || this._poolMap.size == 0,
+/**
+* Destroy this item, removing it from a parent if it has one,
+* and destroying all children if necessary.
+*/
+destroy: function() {
+let parent = this.parent();
+if (parent) {
+parent.unmanage(this);
+}
+if (!this.__poolMap) {
+return;
+}
+for (let actor of this.__poolMap.values()) {
+// Self-owned actors are ok, but don't need destroying twice.
+if (actor === this) {
+continue;
+}
+let 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, true);
+this.__poolMap.clear();
+this.__poolMap = null;
+},
+/**
+* For getting along with the debugger server pools, should be removable
+* eventually.
+*/
+cleanup: function() {
+this.destroy();
+}
+});
+exports.Pool = Pool;
+/**
+* An actor in the actor tree.
+*/
+let Actor = Class({
+extends: Pool,
+// Will contain the actor's ID
+actorID: null,
+/**
+* Initialize an actor.
+*
+* @param optional conn
+*   Either a DebuggerServerConnection or a DebuggerClient.  Must have
+*   addActorPool, removeActorPool, and poolFor.
+*   conn can be null if the subclass provides a conn property.
+* @constructor
+*/
+initialize: function(conn) {
+Pool.prototype.initialize.call(this, conn);
+// Forward events to the connection.
+if (this._actorSpec && this._actorSpec.events) {
+for (let key of this._actorSpec.events.keys()) {
+let name = key;
+let sendEvent = this._sendEvent.bind(this, name)
+this.on(name, (...args) => {
+sendEvent.apply(null, args);
+});
+}
+}
+},
+_sendEvent: function(name, ...args) {
+if (!this._actorSpec.events.has(name)) {
+// It's ok to emit events that don't go over the wire.
+return;
+}
+let request = this._actorSpec.events.get(name);
+let packet = request.write(args, this);
+packet.from = packet.from || this.actorID;
+this.conn.send(packet);
+},
+destroy: function() {
+Pool.prototype.destroy.call(this);
+this.actorID = null;
+},
+/**
+* Override this method in subclasses to serialize the actor.
+* @param [optional] string hint
+*   Optional string to customize the form.
+* @returns A jsonable object.
+*/
+form: function(hint) {
+return { actor: this.actorID }
+},
+writeError: function(err) {
+console.error(err);
+if (err.stack) {
+dump(err.stack);
+}
+this.conn.send({
+from: this.actorID,
+error: "unknownError",
+message: err.toString()
+});
+},
+_queueResponse: function(create) {
+let pending = this._pendingResponse || promise.resolve(null);
+let response = create(pending);
+this._pendingResponse = response;
+}
+});
+exports.Actor = Actor;
+/**
+* Tags a prtotype method as an actor method implementation.
+*
+* @param function fn
+*    The implementation function, will be returned.
+* @param spec
+*    The method specification, with the following (optional) properties:
+*      request (object): a request template.
+*      response (object): a response template.
+*      oneway (bool): 'true' if no response should be sent.
+*      telemetry (string): Telemetry probe ID for measuring completion time.
+*/
+exports.method = function(fn, spec={}) {
+fn._methodSpec = Object.freeze(spec);
+if (spec.request) Object.freeze(spec.request);
+if (spec.response) Object.freeze(spec.response);
+return fn;
+}
+/**
+* Process an actor definition from its prototype and generate
+* request handlers.
+*/
+let actorProto = function(actorProto) {
+if (actorProto._actorSpec) {
+throw new Error("actorProto called twice on the same actor prototype!");
+}
+let protoSpec = {
+methods: [],
+};
+// Find method specifications attached to prototype properties.
+for (let name of Object.getOwnPropertyNames(actorProto)) {
+let desc = Object.getOwnPropertyDescriptor(actorProto, name);
+if (!desc.value) {
+continue;
+}
+if (desc.value._methodSpec) {
+let frozenSpec = desc.value._methodSpec;
+let spec = {};
+spec.name = frozenSpec.name || name;
+spec.request = Request(object.merge({type: spec.name}, frozenSpec.request || undefined));
+spec.response = Response(frozenSpec.response || undefined);
+spec.telemetry = frozenSpec.telemetry;
+spec.release = frozenSpec.release;
+spec.oneway = frozenSpec.oneway;
+protoSpec.methods.push(spec);
+}
+}
+// Find event specifications
+if (actorProto.events) {
+protoSpec.events = new Map();
+for (let name in actorProto.events) {
+let eventRequest = actorProto.events[name];
+Object.freeze(eventRequest);
+protoSpec.events.set(name, Request(object.merge({type: name}, eventRequest)));
+}
+}
+// Generate request handlers for each method definition
+actorProto.requestTypes = Object.create(null);
+protoSpec.methods.forEach(spec => {
+let handler = function(packet, conn) {
+try {
+let args = spec.request.read(packet, this);
+let ret = this[spec.name].apply(this, args);
+if (spec.oneway) {
+// No need to send a response.
+return;
+}
+let sendReturn = (ret) => {
+let response = spec.response.write(ret, this);
+response.from = this.actorID;
+// If spec.release has been specified, destroy the object.
+if (spec.release) {
+try {
+this.destroy();
+} catch(e) {
+this.writeError(e);
+return;
+}
+}
+conn.send(response);
+};
+this._queueResponse(p => {
+return p
+.then(() => ret)
+.then(sendReturn)
+.then(null, this.writeError.bind(this));
+})
+} catch(e) {
+this._queueResponse(p => {
+return p.then(() => this.writeError(e));
+});
+}
+};
+actorProto.requestTypes[spec.request.type] = handler;
+});
+actorProto._actorSpec = protoSpec;
+return actorProto;
+}
+/**
+* Create an actor class for the given actor prototype.
+*
+* @param object proto
+*    The object prototype.  Must have a 'typeName' property,
+*    should have method definitions, can have event definitions.
+*/
+exports.ActorClass = function(proto) {
+if (!proto.typeName) {
+throw Error("Actor prototype must have a typeName member.");
+}
+proto.extends = Actor;
+if (!registeredTypes.has(proto.typeName)) {
+types.addActorType(proto.typeName);
+}
+let cls = Class(actorProto(proto));
+registeredTypes.get(proto.typeName).actorSpec = proto._actorSpec;
+return cls;
+};
+/**
+* Base class for client-side actor fronts.
+*/
+let Front = Class({
+extends: Pool,
+actorID: null,
+/**
+* The base class for client-side actor fronts.
+*
+* @param optional conn
+*   Either a DebuggerServerConnection or a DebuggerClient.  Must have
+*   addActorPool, removeActorPool, and poolFor.
+*   conn can be null if the subclass provides a conn property.
+* @param optional form
+*   The json form provided by the server.
+* @constructor
+*/
+initialize: function(conn=null, form=null, detail=null, context=null) {
+Pool.prototype.initialize.call(this, conn);
+this._requests = [];
+if (form) {
+this.actorID = form.actor;
+this.form(form, detail, context);
+}
+},
+destroy: function() {
+// Reject all outstanding requests, they won't make sense after
+// the front is destroyed.
+while (this._requests && this._requests.length > 0) {
+let deferred = this._requests.shift();
+deferred.reject(new Error("Connection closed"));
+}
+Pool.prototype.destroy.call(this);
+this.actorID = null;
+},
+/**
+* @returns a promise that will resolve to the actorID this front
+* represents.
+*/
+actor: function() { return promise.resolve(this.actorID) },
+toString: function() { return "[Front for " + this.typeName + "/" + this.actorID + "]" },
+/**
+* Update the actor from its representation.
+* Subclasses should override this.
+*/
+form: function(form) {},
+/**
+* Send a packet on the connection.
+*/
+send: function(packet) {
+if (packet.to) {
+this.conn._transport.send(packet);
+} else {
+this.actor().then(actorID => {
+packet.to = actorID;
+this.conn._transport.send(packet);
+});
+}
+},
+/**
+* Send a two-way request on the connection.
+*/
+request: function(packet) {
+let deferred = promise.defer();
+this._requests.push(deferred);
+this.send(packet);
+return deferred.promise;
+},
+/**
+* Handler for incoming packets from the client's actor.
+*/
+onPacket: function(packet) {
+// Pick off event packets
+if (this._clientSpec.events && this._clientSpec.events.has(packet.type)) {
+let event = this._clientSpec.events.get(packet.type);
+let args = event.request.read(packet, this);
+if (event.pre) {
+event.pre.forEach((pre) => pre.apply(this, args));
+}
+events.emit.apply(null, [this, event.name].concat(args));
+return;
+}
+// Remaining packets must be responses.
+if (this._requests.length === 0) {
+let msg = "Unexpected packet " + this.actorID + ", " + JSON.stringify(packet);
+let err = Error(msg);
+console.error(err);
+throw err;
+}
+let deferred = this._requests.shift();
+if (packet.error) {
+deferred.reject(packet.error);
+} else {
+deferred.resolve(packet);
+}
+}
+});
+exports.Front = Front;
+/**
+* A method tagged with preEvent will be called after recieving a packet
+* for that event, and before the front emits the event.
+*/
+exports.preEvent = function(eventName, fn) {
+fn._preEvent = eventName;
+return fn;
+}
+/**
+* Mark a method as a custom front implementation, replacing the generated
+* front method.
+*
+* @param function fn
+*    The front implementation, will be returned.
+* @param object options
+*    Options object:
+*      impl (string): If provided, the generated front method will be
+*        stored as this property on the prototype.
+*/
+exports.custom = function(fn, options={}) {
+fn._customFront = options;
+return fn;
+}
+function prototypeOf(obj) {
+return typeof(obj) === "function" ? obj.prototype : obj;
+}
+/**
+* Process a front definition from its prototype and generate
+* request methods.
+*/
+let frontProto = function(proto) {
+let actorType = prototypeOf(proto.actorType);
+if (proto._actorSpec) {
+throw new Error("frontProto called twice on the same front prototype!");
+}
+proto._actorSpec = actorType._actorSpec;
+proto.typeName = actorType.typeName;
+// Generate request methods.
+let methods = proto._actorSpec.methods;
+methods.forEach(spec => {
+let name = spec.name;
+// If there's already a property by this name in the front, it must
+// be a custom front method.
+if (name in proto) {
+let custom = proto[spec.name]._customFront;
+if (custom === undefined) {
+throw Error("Existing method for " + spec.name + " not marked customFront while processing " + actorType.typeName + ".");
+}
+// If the user doesn't need the impl don't generate it.
+if (!custom.impl) {
+return;
+}
+name = custom.impl;
+}
+proto[name] = function(...args) {
+let histogram, startTime;
+if (spec.telemetry) {
+if (spec.oneway) {
+// That just doesn't make sense.
+throw Error("Telemetry specified for a oneway request");
+}
+let transportType = this.conn.localTransport
+? "LOCAL_"
+: "REMOTE_";
+let histogramId = "DEVTOOLS_DEBUGGER_RDP_"
++ transportType + spec.telemetry + "_MS";
+try {
+histogram = Services.telemetry.getHistogramById(histogramId);
+startTime = new Date();
+} catch(ex) {
+// XXX: Is this expected in xpcshell tests?
+console.error(ex);
+spec.telemetry = false;
+}
+}
+let packet = spec.request.write(args, this);
+if (spec.oneway) {
+// Fire-and-forget oneway packets.
+this.send(packet);
+return undefined;
+}
+return this.request(packet).then(response => {
+let ret = spec.response.read(response, this);
+if (histogram) {
+histogram.add(+new Date - startTime);
+}
+return ret;
+}).then(null, promiseDone);
+}
+// Release methods should call the destroy function on return.
+if (spec.release) {
+let fn = proto[name];
+proto[name] = function(...args) {
+return fn.apply(this, args).then(result => {
+this.destroy();
+return result;
+})
+}
+}
+});
+// Process event specifications
+proto._clientSpec = {};
+let events = proto._actorSpec.events;
+if (events) {
+// This actor has events, scan the prototype for preEvent handlers...
+let preHandlers = new Map();
+for (let name of Object.getOwnPropertyNames(proto)) {
+let desc = Object.getOwnPropertyDescriptor(proto, name);
+if (!desc.value) {
+continue;
+}
+if (desc.value._preEvent) {
+let preEvent = desc.value._preEvent;
+if (!events.has(preEvent)) {
+throw Error("preEvent for event that doesn't exist: " + preEvent);
+}
+let handlers = preHandlers.get(preEvent);
+if (!handlers) {
+handlers = [];
+preHandlers.set(preEvent, handlers);
+}
+handlers.push(desc.value);
+}
+}
+proto._clientSpec.events = new Map();
+for (let [name, request] of events) {
+proto._clientSpec.events.set(request.type, {
+name: name,
+request: request,
+pre: preHandlers.get(name)
+});
+}
+}
+return proto;
+}
+/**
+* Create a front class for the given actor class, with the given prototype.
+*
+* @param ActorClass actorType
+*    The actor class 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.
+*/
+exports.FrontClass = function(actorType, proto) {
+proto.actorType = actorType;
+proto.extends = Front;
+let cls = Class(frontProto(proto));
+registeredTypes.get(cls.prototype.typeName).frontClass = cls;
+return cls;
+}
+exports.dumpActorSpec = function(type) {
+let actorSpec = type.actorSpec;
+let ret = {
+category: "actor",
+typeName: type.name,
+methods: [],
+events: {}
+};
+for (let method of actorSpec.methods) {
+ret.methods.push({
+name: method.name,
+release: method.release || undefined,
+oneway: method.oneway || undefined,
+request: method.request.describe(),
+response: method.response.describe()
+});
+}
+if (actorSpec.events) {
+for (let [name, request] of actorSpec.events) {
+ret.events[name] = request.describe();
+}
+}
+JSON.stringify(ret);
+return ret;
+}
+exports.dumpProtocolSpec = function() {
+let ret = {
+types: {},
+};
+for (let [name, type] of registeredTypes) {
+// Force lazy instantiation if needed.
+type = types.getType(name);
+if (type.category === "dict") {
+ret.types[name] = {
+category: "dict",
+typeName: name,
+specializations: type.specializations
+}
+} else if (type.category === "actor") {
+ret.types[name] = exports.dumpActorSpec(type);
+}
+}
+return ret;
+}