Sfink/Contexts and Compartments

See also http://www.christianwimmer.at/Publications/Wagner11a/Wagner11a.pdf

This is my attempt to make sense of a couple of fundamental SpiderMonkey data structures, compartments and contexts. I am far from an expert, but mrbkap (who *is* the expert) has read through this and pointed out only one glaring mistake, since fixed. So it should be more or less correct now.

Contexts are Control, Compartments are Data

JSContexts are control, JSCompartments are data.

A JSContext (from here on, just context) represents the execution of JS code. A context contains a JS stack and is associated with a runtime. A thread may use multiple contexts, but a given context will only execute on a single thread at a time.

A JSCompartment (compartment) is a memory space that objects and other garbage-collected things (GCthings) are stored within.

A context is associated with a single compartment at all times (not necessarily always the same one, but only ever one at a time). The context is often said to be "running inside" that compartment. Any object created with that context will be physically stored within the context's current compartment. Just about any GCthing read or touched by that context should also be within that same compartment.

To access data in another compartment, a context must first "enter" that other compartment. This is termed a "cross-compartment call" -- remember, contexts are control, so changing a context's compartment is only meaningful if you're going to run code. The context will enter another compartment, do some stuff, then return, at which time it'll exit back to the original compartment. (The APIs allow you to change to a different compartment and never change back, but that's almost certainly a bug and will quickly trigger an assertion in a debug build the first time you touch an object in a compartment that differs from your context's compartment.)

When a context is not running code -- as in, its JS stack is empty and it is not in a request -- then it isn't really associated with any compartment at all. In the future, starting a request and entering an initial compartment will become the same action. Also, a context is only ever running on one thread at a time. Update: or perhaps we'll eliminate contexts altogether and just map from a thread to the relevant data.

In implementation terms, a context has a field (cx->compartment) that gives the current compartment. Contexts also maintain a default scope object (cx->globalObject) that is required to always be within the same compartment, and a "pending exception" object which, if set, will also be in the same compartment. Any object created using a context will be created inside the context's current compartment, and the object's scope chain will be initialized to a scope object within that same compartment. (That scope object might be cx->globalObject, but really that's just the ultimate fallback. Usually the scope object will be found via the stack instead.)

To make a cross-compartment call, cx->compartment is updated to the new compartment. The scope object must also be updated, and for that reason you must pass in a target object in the destination compartment. The scope object will be set to the target object's global object. If an exception is pending, it will be set to a wrapper (really, a proxy) inside the new compartment. The wrapper mediates access to the original exception object that lives in the origin compartment.

The security privileges of executing code are determined by the current stack -- eg, if your chrome code in a chrome compartment calls a content script in a content compartment, that script will execute with content privileges until it returns, then will revert to chrome privileges.

When debugging, it is helpful to know that a compartment is associated with a "JSPrincipals" object that represents the "security information" for the contents of that compartment. This is used to decide who can access what, and is mostly opaque to the JS engine. But for Gecko, it'll typically contain a human-understandable URL, which makes it much easier to figure out what's going on:

 (gdb) p obj
 $1 = (JSObject *) 0x7fffbeef
 (gdb) p obj->compartment()
 $2 = (JSCompartment *) 0xbf5450
 (gdb) p obj->compartment()->principals()
 $3 = (JSPrincipals *) 0xc29860
 (gdb) p obj->compartment()->principals->codebase
 $4 = 0x7fffd120 "[System Principal]"
   ...or perhaps...
 $4 = 0x7fffd120 "http://angryhippos.com/accounts/"

Anything within a single compartment can freely and directly access anything else in that same compartment. No locking or wrappers are necessary (or possible). The overall model is thus a partitioning of all (garbage collectible) data into separate compartments, with controlled access from one compartment to another but lockless, direct access between objects within a compartment. Cross-compartment access is handled via "wrappers", the topic of the next section.

Wrappers

GCthings may be wrapped in cross-compartment wrappers for a number of reasons. When a context is transitioning from one compartment to another (ie, it's making a cross-compartment call), its scope object and pending exception (if any) are changed to wrappers pointing back to the objects in the old compartment. But any object can be wrapped in a cross-compartment wrapper if needed. You can clone an object from another compartment, and all of its properties will be wrappers pointing at the "real" properties in the origin compartment.

Cross-compartment wrappers do not compose. When you wrap an object, any existing wrappers will be ripped off first. (Slight oversimplification; there is one exception.) In fact, the type of wrapper used for an object is uniquely determined by the source and destination compartments.

The precise terminology is a little confusing. A cross-compartment wrapper is a JSObject whose class is one of the proxy classes. When you access such an object, it fetches its proxy handler (a subclass of JSProxyHandler) out of a slot to decide how to handle that access. Confusingly, in the code a JSCrossCompartmentWrapper is the subclass of JSProxyHandler that manages cross-compartment access, but usually when we refer to a "cross-compartment wrapper", we're really talking about the JSObject. (The JSObject of type js::SomethingProxyClass that has a private JSSLOT_PROXY_HANDLER field containing a JSProxyHandler subclass that knows how to mediate access to the proxied object stored in JSSLOT_PROXY_PRIVATE. Phew.)

A proxy handler mediates access to the proxied objects based on a set of rules embodied by some subclass of JSProxyHandler. A proxy handler might allow all accesses through, conceal certain properties, or check on each access whether the source compartment is allowed to see a particular property. Examples of proxy handler classes are the things listed on https://developer.mozilla.org/en/XPConnect_wrappers : cross-origin wrappers (XOWs), chrome object wrappers (COWs), etc.

Also, the same wrapper will always be used for a given object. This is necessary for equality testing between independently generated wrappings of the same object, and useful for performance and memory usage as well. Internally, every compartment has a wrapperCache that is keyed off of wrapped objects' identity. You could think of the flavor of wrapper (i.e., the type of proxy handler) being determined by the tuple <destination compartment, source compartment, object>, but the object is stored within the source compartment so those last two are redundant.

From the JS engine's point of view, there are a bunch of objects, every object lives in a different compartment, and whenever you call something or point to something in another compartment, the engine will interpose a cross-compartment wrapper for you. It's up to the embedding -- the user of the JS engine -- to decide how to divide up data into different compartments, and what behavior is triggered when you cross between compartments. You could have a "home" compartment and a "bigger" compartment, and the cross-compartment wrapper could convert any string to Pig Latin when it is retrieved from "bigger" by "home". More practically, you could conceal certain properties from view when accessing them from an "unprivileged" compartment (whatever that might mean in your embedding), or you could do locking or queuing when accessing one compartment from another compartment in a different thread. Or add a remoting layer.

XPConnect (Gecko's current SpiderMonkey embedding code) uses cross-compartment wrappers to implement security policies and access rules. The 'Introduction' section at https://developer.mozilla.org/en/XPConnect_security_membranes gives a very good description of what XPConnect is using the wrappers for. Gecko uses one compartment for chrome, and one compartment for each content domain. The wrapper is chosen based on whether the two compartments are the same origin, or whether one is privileged to see anything or a subset of the information in the other, etc. See js/src/xpconnect/wrappers/WrapperFactory.cpp for the gruesome details.