Pyr8 User's Manual

« The JavaScript APIs | The Filesystem API »

The Capability API

Pyr8 is an object-capability platform where JavaScript object references play the role of capabilities in most situations.

There are three kinds of object reference in the Pyr8 system.

  1. Authority-bearing objects. Properties of the global variable pyr8 are JavaScript objects holding references to C++ objects that define the behavior of system resources like the file system and the network; they are the only kind of references that can be passed between threads. The properties available on pyr8 are specified either by the command line or by the parent thread. A few authority-bearing objects support a natural notion of attenuation by providing substructures, but otherwise these capabilities can only be delegated; for example, one can provide a subdirectory as the root of the forked thread’s filesystem, but one cannot provide a read-only subdirectory. Authority-bearing objects have a long random id that can be sent over an open network to clients so that they can specify the object later.

  2. JavaScript delegates. When the stdlib has been loaded, these wrap the authority-bearing objects in an API that hides the unguessable ids behind unforgeable JavaScript object references. If pyr8 is running any untrusted code, these can be delegated to the code without the risk of the capabilities being leaked over a bit channel. The standard library understands how to unwrap delegates to send the underlying authority across an inter-thread channel and rewrap them on the other side.

  3. References to other JavaScript objects. These objects often attenuate or combine authorities at the cost of not being transferrable across thread boundaries. For example, given a string channel, one can construct a revocable, logging, read-only channel, but one cannot provide it to a forked thread directly.

The Capability Class

Entries in the captable object are instances of the Capability class. Instances of the Capability class are never directly used when the standard library has been loaded.

Methods

id(): string
Returns this capability's id.
ref(): object
Returns a JavaScript object backed by a C++ object.

The Captable object

The captable object holds all the system resources. To get a resource, a client must present a capability id.

Methods

cap(): Capability<Captable>
Returns a C++-backed capability object for this captable.
get(id: string): Capability<any> | undefined
Returns the capability with the given id or undefined.
id(): string
Convenience method. Returns cap().id().
newCapability(): Capability<any>
Returns a new empty capability object.
newCapabilityId(): string
Returns a random id.
newChannel(): Capability<StringChannel>
Returns a capability holding a new string channel.
newString(str: string): Capability<String>
Returns a capability holding the given string.

When the standard library has been loaded, the captable delegate object has only one method:

newChannel(): Channel
Returns a new Channel object.
« Previous Chapter Link Text | The Filesystem API »