The Tor Browser / file revision

 /* 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;

 }