Labs/Jetpack/Binary Components

nsJetpack

nsJetpack is a binary component used to provide services to Jetpack that aren't otherwise available to scripted chrome code in the Mozilla platform.

Accessing the Component

Because the goal of nsJetpack is to provide functionality to scripted code, and because much of its functionality is concerned with providing access to SpiderMonkey internals, the XPCOM interface for the component is rather trivial. To obtain the component, simply do:

 var nsJetpack = Cc["@labs.mozilla.com/jetpackdi;1"]
                 .createInstance(Ci.nsIJetpack).get();

This will give you the nsJetpack native JavaScript object, which provides access to all the component's functionality.

Flexible Membrane Functionality

nsJetpack contains functionality that exposes many SpiderMonkey C API calls to JavaScript, allowing chrome code to create custom membranes (aka wrappers) that allow trusted and untrusted code to interoperate.

Aside from security, however, this functionality can also be used to implement APIs that can't normally be implemented using the JavaScript language, such as the window.localStorage interface in HTML5.

The source code for this functionality is in wrapper.cpp.

Security Concerns

Note that the Flexible Membrane functionality is intended primarily for prototyping purposes; its use is discouraged for production code for two reasons:

1. The membrane methods have a tendency to get called very frequently, and as a result, implementing them in JavaScript is likely to not be efficient.
2. JavaScript is an inherently dynamic language, and it's very hard to predict what all the possible outcomes of JavaScript code for a membrane might be—especially when the membrane's script is in the same JSRuntime as the code it's trying to protect. Because of this, it's hard to code review a Flexible Membrane for security vulnerabilities.

Because of these concerns, it's advised that any flexible membranes be re-written in C++ before being reviewed for security and placed in production code. Before being re-written, however, a test suite should be created for the membrane to ensure that its new implementation has the same characteristics as the original.

Functions

nsJetpack.wrap(wrappee, membrane)

This function wraps wrappee with membrane (meaning that membrane mediates all access to and from wrappee). The wrapped object is returned.

nsJetpack.unwrap(wrappedObject)

Removes the membrane from wrappedObject and returns the wrappee. If wrappedObject wasn't ever wrapped by nsJetpack.wrap(), this function returns null.

nsJetpack.getWrapper(wrappedObject)

Returns the membrane for the given wrappedObject. If wrappedObject wasn't ever wrapped by nsJetpack.wrap(), this function returns null.

Membrane Objects

A membrane object is a user-defined JavaScript object with any of the following optional methods defined:

membrane.call(wrappee, membrane, thisObj, args)

This is essentially a JavaScript version of JSClass.call; alternatively, it could be described as the analog of Python's __call__ magic method. thisObj is the object that the callee's this variable should be set to, and args is the array of arguments to be passed to the callee. This method should return whatever the return value of the callee is, or raise an exception.

membrane.construct(wrappee, membrane, thisObj, args)

This is essentially a JavaScript version of JSClass.construct. It's just like membrane.call(), only it's called when the call is preceded by the new operator.

membrane.convert(wrappee, membrane, type)

This is essentially a JavaScript version of JSClass.convert, and is called when SpiderMonkey needs to coerce wrappee to a different type. type is a string identifying the name of the desired type to coerce to, and can be anything ordinarily returned by JavaScript's typeof operator. The default implementation of this is to call wrappee.valueOf().

NOTE: Be very careful about implementing this function, as it can easily cause infinite recursion.

membrane.resolve(wrappee, membrane, name)

This is essentially a JavaScript version of JSClass.resolve. It's called when the property identified by name doesn't exist on wrappee. The membrane should either define name on wrappee and return wrappee, or—if name doesn't exist—it should return undefined.

membrane.enumerate(wrappee, membrane)

This is essentially a JavaScript version of JSClass.enumerate. It should return an iterator that iterates through all the property names in wrappee.

membrane.getProperty(wrappee, membrane, name, defaultValue)

This is essentially a JavaScript version of JSClass.getProperty; alternatively, it could be described as the analog of Python's __getattr__ magic method. name is the name of the property being accessed, and defaultValue is the value that JavaScript would ordinarily return. This function should return the value of the property, which may be defaultValue or something different. Alternatively, the method may also throw an exception.

membrane.setProperty(wrappee, membrane, name, defaultValue)

This is essentially a JavaScript version of JSClass.setProperty; alternatively, it could be described as the analog of Python's __setattr__ magic method. name is the name of the property being accessed, and defaultValue is the value that JavaScript would ordinarily set the value of the property to. This function should return the value to set the property to, which may be defaultValue or something different. Alternatively, the method may also throw an exception.

membrane.addProperty(wrappee, membrane, name, defaultValue)

This is essentially a JavaScript version of JSClass.addProperty, and is called immediately after a new property has been added to wrappee. name is the name of the property being accessed, and defaultValue is the value that JavaScript would ordinarily set the initial value of the property to. This function should return the initial value to set the property to, which may be defaultValue or something different. Alternatively, the method may also throw an exception.

membrane.delProperty(wrappee, membrane, name)

This is essentially a JavaScript version of JSClass.delProperty; alternatively, it could be described as the analog of Python's __delattr__ magic method. name is the name of the property being deleted. This function should return true if the property can be deleted, and false if not.

Memory Profiling

nsJetpack contains functionality allowing chrome code to examine the JavaScript heap. The semantics of this are described at a high level in Atul's blog post entitled Fun with SpiderMonkey.

The source code for this functionality is in memory_profiler.cpp.

nsJetpack.profileMemory(code, filename, lineNumber, namedObjects)

TODO: Document this function.

Miscellaneous Functions

The source code for this functionality is in tcb.cpp.

nsJetpack.functionInfo(func)

TODO: Document this function.

nsJetpack.seal(object)

TODO: Document this function.