@stryke/capnp
Version:
A package to assist in running the Cap'n Proto compiler and creating Cap'n Proto serialization protocol schemas.
1,322 lines (1,321 loc) • 108 kB
JavaScript
Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
const require_src = require('./src-B6FhDNiV.cjs');
//#region schemas/rpc.ts
const _capnpFileId = BigInt("0xb312981b2552a250");
const Message_Which = {
/**
* The sender previously received this message from the peer but didn't understand it or doesn't
* yet implement the functionality that was requested. So, the sender is echoing the message
* back. In some cases, the receiver may be able to recover from this by pretending the sender
* had taken some appropriate "null" action.
*
* For example, say `resolve` is received by a level 0 implementation (because a previous call
* or return happened to contain a promise). The level 0 implementation will echo it back as
* `unimplemented`. The original sender can then simply release the cap to which the promise
* had resolved, thus avoiding a leak.
*
* For any message type that introduces a question, if the message comes back unimplemented,
* the original sender may simply treat it as if the question failed with an exception.
*
* In cases where there is no sensible way to react to an `unimplemented` message (without
* resource leaks or other serious problems), the connection may need to be aborted. This is
* a gray area; different implementations may take different approaches.
*
*/
UNIMPLEMENTED: 0,
/**
* Sent when a connection is being aborted due to an unrecoverable error. This could be e.g.
* because the sender received an invalid or nonsensical message or because the sender had an
* internal error. The sender will shut down the outgoing half of the connection after `abort`
* and will completely close the connection shortly thereafter (it's up to the sender how much
* of a time buffer they want to offer for the client to receive the `abort` before the
* connection is reset).
*
*/
ABORT: 1,
/**
* Request the peer's bootstrap interface.
*
*/
BOOTSTRAP: 8,
/**
* Begin a method call.
*
*/
CALL: 2,
/**
* Complete a method call.
*
*/
RETURN: 3,
/**
* Release a returned answer / cancel a call.
*
*/
FINISH: 4,
/**
* Resolve a previously-sent promise.
*
*/
RESOLVE: 5,
/**
* Release a capability so that the remote object can be deallocated.
*
*/
RELEASE: 6,
/**
* Lift an embargo used to enforce E-order over promise resolution.
*
*/
DISEMBARGO: 13,
/**
* Obsolete request to save a capability, resulting in a SturdyRef. This has been replaced
* by the `Persistent` interface defined in `persistent.capnp`. This operation was never
* implemented.
*
*/
OBSOLETE_SAVE: 7,
/**
* Obsolete way to delete a SturdyRef. This operation was never implemented.
*
*/
OBSOLETE_DELETE: 9,
/**
* Provide a capability to a third party.
*
*/
PROVIDE: 10,
/**
* Accept a capability provided by a third party.
*
*/
ACCEPT: 11,
/**
* Directly connect to the common root of two or more proxied caps.
*
*/
JOIN: 12
};
/**
* An RPC connection is a bi-directional stream of Messages.
*
*/
var Message = class Message extends require_src.Struct {
static UNIMPLEMENTED = Message_Which.UNIMPLEMENTED;
static ABORT = Message_Which.ABORT;
static BOOTSTRAP = Message_Which.BOOTSTRAP;
static CALL = Message_Which.CALL;
static RETURN = Message_Which.RETURN;
static FINISH = Message_Which.FINISH;
static RESOLVE = Message_Which.RESOLVE;
static RELEASE = Message_Which.RELEASE;
static DISEMBARGO = Message_Which.DISEMBARGO;
static OBSOLETE_SAVE = Message_Which.OBSOLETE_SAVE;
static OBSOLETE_DELETE = Message_Which.OBSOLETE_DELETE;
static PROVIDE = Message_Which.PROVIDE;
static ACCEPT = Message_Which.ACCEPT;
static JOIN = Message_Which.JOIN;
static _capnp = {
displayName: "Message",
id: "91b79f1f808db032",
size: new require_src.ObjectSize(8, 1)
};
_adoptUnimplemented(value) {
require_src.utils.setUint16(0, 0, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownUnimplemented() {
return require_src.utils.disown(this.unimplemented);
}
/**
* The sender previously received this message from the peer but didn't understand it or doesn't
* yet implement the functionality that was requested. So, the sender is echoing the message
* back. In some cases, the receiver may be able to recover from this by pretending the sender
* had taken some appropriate "null" action.
*
* For example, say `resolve` is received by a level 0 implementation (because a previous call
* or return happened to contain a promise). The level 0 implementation will echo it back as
* `unimplemented`. The original sender can then simply release the cap to which the promise
* had resolved, thus avoiding a leak.
*
* For any message type that introduces a question, if the message comes back unimplemented,
* the original sender may simply treat it as if the question failed with an exception.
*
* In cases where there is no sensible way to react to an `unimplemented` message (without
* resource leaks or other serious problems), the connection may need to be aborted. This is
* a gray area; different implementations may take different approaches.
*
*/
get unimplemented() {
require_src.utils.testWhich("unimplemented", require_src.utils.getUint16(0, this), 0, this);
return require_src.utils.getStruct(0, Message, this);
}
_hasUnimplemented() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
_initUnimplemented() {
require_src.utils.setUint16(0, 0, this);
return require_src.utils.initStructAt(0, Message, this);
}
get _isUnimplemented() {
return require_src.utils.getUint16(0, this) === 0;
}
set unimplemented(value) {
require_src.utils.setUint16(0, 0, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
_adoptAbort(value) {
require_src.utils.setUint16(0, 1, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownAbort() {
return require_src.utils.disown(this.abort);
}
/**
* Sent when a connection is being aborted due to an unrecoverable error. This could be e.g.
* because the sender received an invalid or nonsensical message or because the sender had an
* internal error. The sender will shut down the outgoing half of the connection after `abort`
* and will completely close the connection shortly thereafter (it's up to the sender how much
* of a time buffer they want to offer for the client to receive the `abort` before the
* connection is reset).
*
*/
get abort() {
require_src.utils.testWhich("abort", require_src.utils.getUint16(0, this), 1, this);
return require_src.utils.getStruct(0, Exception, this);
}
_hasAbort() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
_initAbort() {
require_src.utils.setUint16(0, 1, this);
return require_src.utils.initStructAt(0, Exception, this);
}
get _isAbort() {
return require_src.utils.getUint16(0, this) === 1;
}
set abort(value) {
require_src.utils.setUint16(0, 1, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
_adoptBootstrap(value) {
require_src.utils.setUint16(0, 8, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownBootstrap() {
return require_src.utils.disown(this.bootstrap);
}
/**
* Request the peer's bootstrap interface.
*
*/
get bootstrap() {
require_src.utils.testWhich("bootstrap", require_src.utils.getUint16(0, this), 8, this);
return require_src.utils.getStruct(0, Bootstrap, this);
}
_hasBootstrap() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
_initBootstrap() {
require_src.utils.setUint16(0, 8, this);
return require_src.utils.initStructAt(0, Bootstrap, this);
}
get _isBootstrap() {
return require_src.utils.getUint16(0, this) === 8;
}
set bootstrap(value) {
require_src.utils.setUint16(0, 8, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
_adoptCall(value) {
require_src.utils.setUint16(0, 2, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownCall() {
return require_src.utils.disown(this.call);
}
/**
* Begin a method call.
*
*/
get call() {
require_src.utils.testWhich("call", require_src.utils.getUint16(0, this), 2, this);
return require_src.utils.getStruct(0, Call, this);
}
_hasCall() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
_initCall() {
require_src.utils.setUint16(0, 2, this);
return require_src.utils.initStructAt(0, Call, this);
}
get _isCall() {
return require_src.utils.getUint16(0, this) === 2;
}
set call(value) {
require_src.utils.setUint16(0, 2, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
_adoptReturn(value) {
require_src.utils.setUint16(0, 3, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownReturn() {
return require_src.utils.disown(this.return);
}
/**
* Complete a method call.
*
*/
get return() {
require_src.utils.testWhich("return", require_src.utils.getUint16(0, this), 3, this);
return require_src.utils.getStruct(0, Return, this);
}
_hasReturn() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
_initReturn() {
require_src.utils.setUint16(0, 3, this);
return require_src.utils.initStructAt(0, Return, this);
}
get _isReturn() {
return require_src.utils.getUint16(0, this) === 3;
}
set return(value) {
require_src.utils.setUint16(0, 3, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
_adoptFinish(value) {
require_src.utils.setUint16(0, 4, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownFinish() {
return require_src.utils.disown(this.finish);
}
/**
* Release a returned answer / cancel a call.
*
*/
get finish() {
require_src.utils.testWhich("finish", require_src.utils.getUint16(0, this), 4, this);
return require_src.utils.getStruct(0, Finish, this);
}
_hasFinish() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
_initFinish() {
require_src.utils.setUint16(0, 4, this);
return require_src.utils.initStructAt(0, Finish, this);
}
get _isFinish() {
return require_src.utils.getUint16(0, this) === 4;
}
set finish(value) {
require_src.utils.setUint16(0, 4, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
_adoptResolve(value) {
require_src.utils.setUint16(0, 5, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownResolve() {
return require_src.utils.disown(this.resolve);
}
/**
* Resolve a previously-sent promise.
*
*/
get resolve() {
require_src.utils.testWhich("resolve", require_src.utils.getUint16(0, this), 5, this);
return require_src.utils.getStruct(0, Resolve, this);
}
_hasResolve() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
_initResolve() {
require_src.utils.setUint16(0, 5, this);
return require_src.utils.initStructAt(0, Resolve, this);
}
get _isResolve() {
return require_src.utils.getUint16(0, this) === 5;
}
set resolve(value) {
require_src.utils.setUint16(0, 5, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
_adoptRelease(value) {
require_src.utils.setUint16(0, 6, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownRelease() {
return require_src.utils.disown(this.release);
}
/**
* Release a capability so that the remote object can be deallocated.
*
*/
get release() {
require_src.utils.testWhich("release", require_src.utils.getUint16(0, this), 6, this);
return require_src.utils.getStruct(0, Release, this);
}
_hasRelease() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
_initRelease() {
require_src.utils.setUint16(0, 6, this);
return require_src.utils.initStructAt(0, Release, this);
}
get _isRelease() {
return require_src.utils.getUint16(0, this) === 6;
}
set release(value) {
require_src.utils.setUint16(0, 6, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
_adoptDisembargo(value) {
require_src.utils.setUint16(0, 13, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownDisembargo() {
return require_src.utils.disown(this.disembargo);
}
/**
* Lift an embargo used to enforce E-order over promise resolution.
*
*/
get disembargo() {
require_src.utils.testWhich("disembargo", require_src.utils.getUint16(0, this), 13, this);
return require_src.utils.getStruct(0, Disembargo, this);
}
_hasDisembargo() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
_initDisembargo() {
require_src.utils.setUint16(0, 13, this);
return require_src.utils.initStructAt(0, Disembargo, this);
}
get _isDisembargo() {
return require_src.utils.getUint16(0, this) === 13;
}
set disembargo(value) {
require_src.utils.setUint16(0, 13, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
_adoptObsoleteSave(value) {
require_src.utils.setUint16(0, 7, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownObsoleteSave() {
return require_src.utils.disown(this.obsoleteSave);
}
/**
* Obsolete request to save a capability, resulting in a SturdyRef. This has been replaced
* by the `Persistent` interface defined in `persistent.capnp`. This operation was never
* implemented.
*
*/
get obsoleteSave() {
require_src.utils.testWhich("obsoleteSave", require_src.utils.getUint16(0, this), 7, this);
return require_src.utils.getPointer(0, this);
}
_hasObsoleteSave() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
get _isObsoleteSave() {
return require_src.utils.getUint16(0, this) === 7;
}
set obsoleteSave(value) {
require_src.utils.setUint16(0, 7, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
_adoptObsoleteDelete(value) {
require_src.utils.setUint16(0, 9, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownObsoleteDelete() {
return require_src.utils.disown(this.obsoleteDelete);
}
/**
* Obsolete way to delete a SturdyRef. This operation was never implemented.
*
*/
get obsoleteDelete() {
require_src.utils.testWhich("obsoleteDelete", require_src.utils.getUint16(0, this), 9, this);
return require_src.utils.getPointer(0, this);
}
_hasObsoleteDelete() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
get _isObsoleteDelete() {
return require_src.utils.getUint16(0, this) === 9;
}
set obsoleteDelete(value) {
require_src.utils.setUint16(0, 9, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
_adoptProvide(value) {
require_src.utils.setUint16(0, 10, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownProvide() {
return require_src.utils.disown(this.provide);
}
/**
* Provide a capability to a third party.
*
*/
get provide() {
require_src.utils.testWhich("provide", require_src.utils.getUint16(0, this), 10, this);
return require_src.utils.getStruct(0, Provide, this);
}
_hasProvide() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
_initProvide() {
require_src.utils.setUint16(0, 10, this);
return require_src.utils.initStructAt(0, Provide, this);
}
get _isProvide() {
return require_src.utils.getUint16(0, this) === 10;
}
set provide(value) {
require_src.utils.setUint16(0, 10, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
_adoptAccept(value) {
require_src.utils.setUint16(0, 11, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownAccept() {
return require_src.utils.disown(this.accept);
}
/**
* Accept a capability provided by a third party.
*
*/
get accept() {
require_src.utils.testWhich("accept", require_src.utils.getUint16(0, this), 11, this);
return require_src.utils.getStruct(0, Accept, this);
}
_hasAccept() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
_initAccept() {
require_src.utils.setUint16(0, 11, this);
return require_src.utils.initStructAt(0, Accept, this);
}
get _isAccept() {
return require_src.utils.getUint16(0, this) === 11;
}
set accept(value) {
require_src.utils.setUint16(0, 11, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
_adoptJoin(value) {
require_src.utils.setUint16(0, 12, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownJoin() {
return require_src.utils.disown(this.join);
}
/**
* Directly connect to the common root of two or more proxied caps.
*
*/
get join() {
require_src.utils.testWhich("join", require_src.utils.getUint16(0, this), 12, this);
return require_src.utils.getStruct(0, Join, this);
}
_hasJoin() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
_initJoin() {
require_src.utils.setUint16(0, 12, this);
return require_src.utils.initStructAt(0, Join, this);
}
get _isJoin() {
return require_src.utils.getUint16(0, this) === 12;
}
set join(value) {
require_src.utils.setUint16(0, 12, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
toString() {
return "Message_" + super.toString();
}
which() {
return require_src.utils.getUint16(0, this);
}
};
/**
* **(level 0)**
*
* Get the "bootstrap" interface exported by the remote vat.
*
* For level 0, 1, and 2 implementations, the "bootstrap" interface is simply the main interface
* exported by a vat. If the vat acts as a server fielding connections from clients, then the
* bootstrap interface defines the basic functionality available to a client when it connects.
* The exact interface definition obviously depends on the application.
*
* We call this a "bootstrap" because in an ideal Cap'n Proto world, bootstrap interfaces would
* never be used. In such a world, any time you connect to a new vat, you do so because you
* received an introduction from some other vat (see `ThirdPartyCapId`). Thus, the first message
* you send is `Accept`, and further communications derive from there. `Bootstrap` is not used.
*
* In such an ideal world, DNS itself would support Cap'n Proto -- performing a DNS lookup would
* actually return a new Cap'n Proto capability, thus introducing you to the target system via
* level 3 RPC. Applications would receive the capability to talk to DNS in the first place as
* an initial endowment or part of a Powerbox interaction. Therefore, an app can form arbitrary
* connections without ever using `Bootstrap`.
*
* Of course, in the real world, DNS is not Cap'n-Proto-based, and we don't want Cap'n Proto to
* require a whole new internet infrastructure to be useful. Therefore, we offer bootstrap
* interfaces as a way to get up and running without a level 3 introduction. Thus, bootstrap
* interfaces are used to "bootstrap" from other, non-Cap'n-Proto-based means of service discovery,
* such as legacy DNS.
*
* Note that a vat need not provide a bootstrap interface, and in fact many vats (especially those
* acting as clients) do not. In this case, the vat should either reply to `Bootstrap` with a
* `Return` indicating an exception, or should return a dummy capability with no methods.
*
*/
var Bootstrap = class extends require_src.Struct {
static _capnp = {
displayName: "Bootstrap",
id: "e94ccf8031176ec4",
size: new require_src.ObjectSize(8, 1)
};
/**
* A new question ID identifying this request, which will eventually receive a Return message
* containing the restored capability.
*
*/
get questionId() {
return require_src.utils.getUint32(0, this);
}
set questionId(value) {
require_src.utils.setUint32(0, value, this);
}
_adoptDeprecatedObjectId(value) {
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownDeprecatedObjectId() {
return require_src.utils.disown(this.deprecatedObjectId);
}
/**
* ** DEPRECATED **
*
* A Vat may export multiple bootstrap interfaces. In this case, `deprecatedObjectId` specifies
* which one to return. If this pointer is null, then the default bootstrap interface is returned.
*
* As of version 0.5, use of this field is deprecated. If a service wants to export multiple
* bootstrap interfaces, it should instead define a single bootstrap interface that has methods
* that return each of the other interfaces.
*
* **History**
*
* In the first version of Cap'n Proto RPC (0.4.x) the `Bootstrap` message was called `Restore`.
* At the time, it was thought that this would eventually serve as the way to restore SturdyRefs
* (level 2). Meanwhile, an application could offer its "main" interface on a well-known
* (non-secret) SturdyRef.
*
* Since level 2 RPC was not implemented at the time, the `Restore` message was in practice only
* used to obtain the main interface. Since most applications had only one main interface that
* they wanted to restore, they tended to designate this with a null `objectId`.
*
* Unfortunately, the earliest version of the EZ RPC interfaces set a precedent of exporting
* multiple main interfaces by allowing them to be exported under string names. In this case,
* `objectId` was a Text value specifying the name.
*
* All of this proved problematic for several reasons:
*
* - The arrangement assumed that a client wishing to restore a SturdyRef would know exactly what
* machine to connect to and would be able to immediately restore a SturdyRef on connection.
* However, in practice, the ability to restore SturdyRefs is itself a capability that may
* require going through an authentication process to obtain. Thus, it makes more sense to
* define a "restorer service" as a full Cap'n Proto interface. If this restorer interface is
* offered as the vat's bootstrap interface, then this is equivalent to the old arrangement.
*
* - Overloading "Restore" for the purpose of obtaining well-known capabilities encouraged the
* practice of exporting singleton services with string names. If singleton services are desired,
* it is better to have one main interface that has methods that can be used to obtain each
* service, in order to get all the usual benefits of schemas and type checking.
*
* - Overloading "Restore" also had a security problem: Often, "main" or "well-known"
* capabilities exported by a vat are in fact not public: they are intended to be accessed only
* by clients who are capable of forming a connection to the vat. This can lead to trouble if
* the client itself has other clients and wishes to forward some `Restore` requests from those
* external clients -- it has to be very careful not to allow through `Restore` requests
* addressing the default capability.
*
* For example, consider the case of a sandboxed Sandstorm application and its supervisor. The
* application exports a default capability to its supervisor that provides access to
* functionality that only the supervisor is supposed to access. Meanwhile, though, applications
* may publish other capabilities that may be persistent, in which case the application needs
* to field `Restore` requests that could come from anywhere. These requests of course have to
* pass through the supervisor, as all communications with the outside world must. But, the
* supervisor has to be careful not to honor an external request addressing the application's
* default capability, since this capability is privileged. Unfortunately, the default
* capability cannot be given an unguessable name, because then the supervisor itself would not
* be able to address it!
*
* As of Cap'n Proto 0.5, `Restore` has been renamed to `Bootstrap` and is no longer planned for
* use in restoring SturdyRefs.
*
* Note that 0.4 also defined a message type called `Delete` that, like `Restore`, addressed a
* SturdyRef, but indicated that the client would not restore the ref again in the future. This
* operation was never implemented, so it was removed entirely. If a "delete" operation is desired,
* it should exist as a method on the same interface that handles restoring SturdyRefs. However,
* the utility of such an operation is questionable. You wouldn't be able to rely on it for
* garbage collection since a client could always disappear permanently without remembering to
* delete all its SturdyRefs, thus leaving them dangling forever. Therefore, it is advisable to
* design systems such that SturdyRefs never represent "owned" pointers.
*
* For example, say a SturdyRef points to an image file hosted on some server. That image file
* should also live inside a collection (a gallery, perhaps) hosted on the same server, owned by
* a user who can delete the image at any time. If the user deletes the image, the SturdyRef
* stops working. On the other hand, if the SturdyRef is discarded, this has no effect on the
* existence of the image in its collection.
*
*/
get deprecatedObjectId() {
return require_src.utils.getPointer(0, this);
}
_hasDeprecatedObjectId() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
set deprecatedObjectId(value) {
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
toString() {
return "Bootstrap_" + super.toString();
}
};
const Call_SendResultsTo_Which = {
/**
* Send the return message back to the caller (the usual).
*
*/
CALLER: 0,
/**
* **(level 1)**
*
* Don't actually return the results to the sender. Instead, hold on to them and await
* instructions from the sender regarding what to do with them. In particular, the sender
* may subsequently send a `Return` for some other call (which the receiver had previously made
* to the sender) with `takeFromOtherQuestion` set. The results from this call are then used
* as the results of the other call.
*
* When `yourself` is used, the receiver must still send a `Return` for the call, but sets the
* field `resultsSentElsewhere` in that `Return` rather than including the results.
*
* This feature can be used to implement tail calls in which a call from Vat A to Vat B ends up
* returning the result of a call from Vat B back to Vat A.
*
* In particular, the most common use case for this feature is when Vat A makes a call to a
* promise in Vat B, and then that promise ends up resolving to a capability back in Vat A.
* Vat B must forward all the queued calls on that promise back to Vat A, but can set `yourself`
* in the calls so that the results need not pass back through Vat B.
*
* For example:
* - Alice, in Vat A, calls foo() on Bob in Vat B.
* - Alice makes a pipelined call bar() on the promise returned by foo().
* - Later on, Bob resolves the promise from foo() to point at Carol, who lives in Vat A (next
* to Alice).
* - Vat B dutifully forwards the bar() call to Carol. Let us call this forwarded call bar'().
* Notice that bar() and bar'() are travelling in opposite directions on the same network
* link.
* - The `Call` for bar'() has `sendResultsTo` set to `yourself`.
* - Vat B sends a `Return` for bar() with `takeFromOtherQuestion` set in place of the results,
* with the value set to the question ID of bar'(). Vat B does not wait for bar'() to return,
* as doing so would introduce unnecessary round trip latency.
* - Vat A receives bar'() and delivers it to Carol.
* - When bar'() returns, Vat A sends a `Return` for bar'() to Vat B, with `resultsSentElsewhere`
* set in place of results.
* - Vat A sends a `Finish` for the bar() call to Vat B.
* - Vat B receives the `Finish` for bar() and sends a `Finish` for bar'().
*
*/
YOURSELF: 1,
/**
* **(level 3)**
*
* The call's result should be returned to a different vat. The receiver (the callee) expects
* to receive an `Accept` message from the indicated vat, and should return the call's result
* to it, rather than to the sender of the `Call`.
*
* This operates much like `yourself`, above, except that Carol is in a separate Vat C. `Call`
* messages are sent from Vat A -> Vat B and Vat B -> Vat C. A `Return` message is sent from
* Vat B -> Vat A that contains `acceptFromThirdParty` in place of results. When Vat A sends
* an `Accept` to Vat C, it receives back a `Return` containing the call's actual result. Vat C
* also sends a `Return` to Vat B with `resultsSentElsewhere`.
*
*/
THIRD_PARTY: 2
};
/**
* Where should the return message be sent?
*
*/
var Call_SendResultsTo = class extends require_src.Struct {
static CALLER = Call_SendResultsTo_Which.CALLER;
static YOURSELF = Call_SendResultsTo_Which.YOURSELF;
static THIRD_PARTY = Call_SendResultsTo_Which.THIRD_PARTY;
static _capnp = {
displayName: "sendResultsTo",
id: "dae8b0f61aab5f99",
size: new require_src.ObjectSize(24, 3)
};
get _isCaller() {
return require_src.utils.getUint16(6, this) === 0;
}
set caller(_) {
require_src.utils.setUint16(6, 0, this);
}
get _isYourself() {
return require_src.utils.getUint16(6, this) === 1;
}
set yourself(_) {
require_src.utils.setUint16(6, 1, this);
}
_adoptThirdParty(value) {
require_src.utils.setUint16(6, 2, this);
require_src.utils.adopt(value, require_src.utils.getPointer(2, this));
}
_disownThirdParty() {
return require_src.utils.disown(this.thirdParty);
}
/**
* **(level 3)**
*
* The call's result should be returned to a different vat. The receiver (the callee) expects
* to receive an `Accept` message from the indicated vat, and should return the call's result
* to it, rather than to the sender of the `Call`.
*
* This operates much like `yourself`, above, except that Carol is in a separate Vat C. `Call`
* messages are sent from Vat A -> Vat B and Vat B -> Vat C. A `Return` message is sent from
* Vat B -> Vat A that contains `acceptFromThirdParty` in place of results. When Vat A sends
* an `Accept` to Vat C, it receives back a `Return` containing the call's actual result. Vat C
* also sends a `Return` to Vat B with `resultsSentElsewhere`.
*
*/
get thirdParty() {
require_src.utils.testWhich("thirdParty", require_src.utils.getUint16(6, this), 2, this);
return require_src.utils.getPointer(2, this);
}
_hasThirdParty() {
return !require_src.utils.isNull(require_src.utils.getPointer(2, this));
}
get _isThirdParty() {
return require_src.utils.getUint16(6, this) === 2;
}
set thirdParty(value) {
require_src.utils.setUint16(6, 2, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(2, this));
}
toString() {
return "Call_SendResultsTo_" + super.toString();
}
which() {
return require_src.utils.getUint16(6, this);
}
};
/**
* **(level 0)**
*
* Message type initiating a method call on a capability.
*
*/
var Call = class Call extends require_src.Struct {
static _capnp = {
displayName: "Call",
id: "836a53ce789d4cd4",
size: new require_src.ObjectSize(24, 3),
defaultAllowThirdPartyTailCall: require_src.getBitMask(false, 0),
defaultNoPromisePipelining: require_src.getBitMask(false, 1),
defaultOnlyPromisePipeline: require_src.getBitMask(false, 2)
};
/**
* A number, chosen by the caller, that identifies this call in future messages. This number
* must be different from all other calls originating from the same end of the connection (but
* may overlap with question IDs originating from the opposite end). A fine strategy is to use
* sequential question IDs, but the recipient should not assume this.
*
* A question ID can be reused once both:
* - A matching Return has been received from the callee.
* - A matching Finish has been sent from the caller.
*
*/
get questionId() {
return require_src.utils.getUint32(0, this);
}
set questionId(value) {
require_src.utils.setUint32(0, value, this);
}
_adoptTarget(value) {
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownTarget() {
return require_src.utils.disown(this.target);
}
/**
* The object that should receive this call.
*
*/
get target() {
return require_src.utils.getStruct(0, MessageTarget, this);
}
_hasTarget() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
_initTarget() {
return require_src.utils.initStructAt(0, MessageTarget, this);
}
set target(value) {
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
/**
* The type ID of the interface being called. Each capability may implement multiple interfaces.
*
*/
get interfaceId() {
return require_src.utils.getUint64(8, this);
}
set interfaceId(value) {
require_src.utils.setUint64(8, value, this);
}
/**
* The ordinal number of the method to call within the requested interface.
*
*/
get methodId() {
return require_src.utils.getUint16(4, this);
}
set methodId(value) {
require_src.utils.setUint16(4, value, this);
}
/**
* Indicates whether or not the receiver is allowed to send a `Return` containing
* `acceptFromThirdParty`. Level 3 implementations should set this true. Otherwise, the callee
* will have to proxy the return in the case of a tail call to a third-party vat.
*
*/
get allowThirdPartyTailCall() {
return require_src.utils.getBit(128, this, Call._capnp.defaultAllowThirdPartyTailCall);
}
set allowThirdPartyTailCall(value) {
require_src.utils.setBit(128, value, this, Call._capnp.defaultAllowThirdPartyTailCall);
}
/**
* If true, the sender promises that it won't make any promise-pipelined calls on the results of
* this call. If it breaks this promise, the receiver may throw an arbitrary error from such
* calls.
*
* The receiver may use this as an optimization, by skipping the bookkeeping needed for pipelining
* when no pipelined calls are expected. The sender typically sets this to false when the method's
* schema does not specify any return capabilities.
*
*/
get noPromisePipelining() {
return require_src.utils.getBit(129, this, Call._capnp.defaultNoPromisePipelining);
}
set noPromisePipelining(value) {
require_src.utils.setBit(129, value, this, Call._capnp.defaultNoPromisePipelining);
}
/**
* If true, the sender only plans to use this call to make pipelined calls. The receiver need not
* send a `Return` message (but is still allowed to do so).
*
* Since the sender does not know whether a `Return` will be sent, it must release all state
* related to the call when it sends `Finish`. However, in the case that the callee does not
* recognize this hint and chooses to send a `Return`, then technically the caller is not allowed
* to reuse the question ID until it receives said `Return`. This creates a conundrum: How does
* the caller decide when it's OK to reuse the ID? To sidestep the problem, the C++ implementation
* uses high-numbered IDs (with the high-order bit set) for such calls, and cycles through the
* IDs in order. If all 2^31 IDs in this space are used without ever seeing a `Return`, then the
* implementation assumes that the other end is in fact honoring the hint, and the ID counter is
* allowed to loop around. If a `Return` is ever seen when `onlyPromisePipeline` was set, then
* the implementation stops using this hint.
*
*/
get onlyPromisePipeline() {
return require_src.utils.getBit(130, this, Call._capnp.defaultOnlyPromisePipeline);
}
set onlyPromisePipeline(value) {
require_src.utils.setBit(130, value, this, Call._capnp.defaultOnlyPromisePipeline);
}
_adoptParams(value) {
require_src.utils.adopt(value, require_src.utils.getPointer(1, this));
}
_disownParams() {
return require_src.utils.disown(this.params);
}
/**
* The call parameters. `params.content` is a struct whose fields correspond to the parameters of
* the method.
*
*/
get params() {
return require_src.utils.getStruct(1, Payload, this);
}
_hasParams() {
return !require_src.utils.isNull(require_src.utils.getPointer(1, this));
}
_initParams() {
return require_src.utils.initStructAt(1, Payload, this);
}
set params(value) {
require_src.utils.copyFrom(value, require_src.utils.getPointer(1, this));
}
/**
* Where should the return message be sent?
*
*/
get sendResultsTo() {
return require_src.utils.getAs(Call_SendResultsTo, this);
}
_initSendResultsTo() {
return require_src.utils.getAs(Call_SendResultsTo, this);
}
toString() {
return "Call_" + super.toString();
}
};
const Return_Which = {
/**
* Equal to the QuestionId of the corresponding `Call` message.
*
*/
RESULTS: 0,
/**
* If true, all capabilities that were in the params should be considered released. The sender
* must not send separate `Release` messages for them. Level 0 implementations in particular
* should always set this true. This defaults true because if level 0 implementations forget to
* set it they'll never notice (just silently leak caps), but if level >=1 implementations forget
* to set it to false they'll quickly get errors.
*
* The receiver should act as if the sender had sent a release message with count=1 for each
* CapDescriptor in the original Call message.
*
*/
EXCEPTION: 1,
/**
* The result.
*
* For regular method calls, `results.content` points to the result struct.
*
* For a `Return` in response to an `Accept` or `Bootstrap`, `results` contains a single
* capability (rather than a struct), and `results.content` is just a capability pointer with
* index 0. A `Finish` is still required in this case.
*
*/
CANCELED: 2,
/**
* Indicates that the call failed and explains why.
*
*/
RESULTS_SENT_ELSEWHERE: 3,
/**
* Indicates that the call was canceled due to the caller sending a Finish message
* before the call had completed.
*
*/
TAKE_FROM_OTHER_QUESTION: 4,
/**
* This is set when returning from a `Call` that had `sendResultsTo` set to something other
* than `caller`.
*
* It doesn't matter too much when this is sent, as the receiver doesn't need to do anything
* with it, but the C++ implementation appears to wait for the call to finish before sending
* this.
*
*/
ACCEPT_FROM_THIRD_PARTY: 5
};
/**
* **(level 0)**
*
* Message type sent from callee to caller indicating that the call has completed.
*
*/
var Return = class Return extends require_src.Struct {
static RESULTS = Return_Which.RESULTS;
static EXCEPTION = Return_Which.EXCEPTION;
static CANCELED = Return_Which.CANCELED;
static RESULTS_SENT_ELSEWHERE = Return_Which.RESULTS_SENT_ELSEWHERE;
static TAKE_FROM_OTHER_QUESTION = Return_Which.TAKE_FROM_OTHER_QUESTION;
static ACCEPT_FROM_THIRD_PARTY = Return_Which.ACCEPT_FROM_THIRD_PARTY;
static _capnp = {
displayName: "Return",
id: "9e19b28d3db3573a",
size: new require_src.ObjectSize(16, 1),
defaultReleaseParamCaps: require_src.getBitMask(true, 0),
defaultNoFinishNeeded: require_src.getBitMask(false, 1)
};
/**
* Equal to the QuestionId of the corresponding `Call` message.
*
*/
get answerId() {
return require_src.utils.getUint32(0, this);
}
set answerId(value) {
require_src.utils.setUint32(0, value, this);
}
/**
* If true, all capabilities that were in the params should be considered released. The sender
* must not send separate `Release` messages for them. Level 0 implementations in particular
* should always set this true. This defaults true because if level 0 implementations forget to
* set it they'll never notice (just silently leak caps), but if level >=1 implementations forget
* to set it to false they'll quickly get errors.
*
* The receiver should act as if the sender had sent a release message with count=1 for each
* CapDescriptor in the original Call message.
*
*/
get releaseParamCaps() {
return require_src.utils.getBit(32, this, Return._capnp.defaultReleaseParamCaps);
}
set releaseParamCaps(value) {
require_src.utils.setBit(32, value, this, Return._capnp.defaultReleaseParamCaps);
}
/**
* If true, the sender does not need the receiver to send a `Finish` message; its answer table
* entry has already been cleaned up. This implies that the results do not contain any
* capabilities, since the `Finish` message would normally release those capabilities from
* promise pipelining responsibility. The caller may still send a `Finish` message if it wants,
* which will be silently ignored by the callee.
*
*/
get noFinishNeeded() {
return require_src.utils.getBit(33, this, Return._capnp.defaultNoFinishNeeded);
}
set noFinishNeeded(value) {
require_src.utils.setBit(33, value, this, Return._capnp.defaultNoFinishNeeded);
}
_adoptResults(value) {
require_src.utils.setUint16(6, 0, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownResults() {
return require_src.utils.disown(this.results);
}
/**
* The result.
*
* For regular method calls, `results.content` points to the result struct.
*
* For a `Return` in response to an `Accept` or `Bootstrap`, `results` contains a single
* capability (rather than a struct), and `results.content` is just a capability pointer with
* index 0. A `Finish` is still required in this case.
*
*/
get results() {
require_src.utils.testWhich("results", require_src.utils.getUint16(6, this), 0, this);
return require_src.utils.getStruct(0, Payload, this);
}
_hasResults() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
_initResults() {
require_src.utils.setUint16(6, 0, this);
return require_src.utils.initStructAt(0, Payload, this);
}
get _isResults() {
return require_src.utils.getUint16(6, this) === 0;
}
set results(value) {
require_src.utils.setUint16(6, 0, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
_adoptException(value) {
require_src.utils.setUint16(6, 1, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownException() {
return require_src.utils.disown(this.exception);
}
/**
* Indicates that the call failed and explains why.
*
*/
get exception() {
require_src.utils.testWhich("exception", require_src.utils.getUint16(6, this), 1, this);
return require_src.utils.getStruct(0, Exception, this);
}
_hasException() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
_initException() {
require_src.utils.setUint16(6, 1, this);
return require_src.utils.initStructAt(0, Exception, this);
}
get _isException() {
return require_src.utils.getUint16(6, this) === 1;
}
set exception(value) {
require_src.utils.setUint16(6, 1, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
get _isCanceled() {
return require_src.utils.getUint16(6, this) === 2;
}
set canceled(_) {
require_src.utils.setUint16(6, 2, this);
}
get _isResultsSentElsewhere() {
return require_src.utils.getUint16(6, this) === 3;
}
set resultsSentElsewhere(_) {
require_src.utils.setUint16(6, 3, this);
}
/**
* The sender has also sent (before this message) a `Call` with the given question ID and with
* `sendResultsTo.yourself` set, and the results of that other call should be used as the
* results here. `takeFromOtherQuestion` can only used once per question.
*
*/
get takeFromOtherQuestion() {
require_src.utils.testWhich("takeFromOtherQuestion", require_src.utils.getUint16(6, this), 4, this);
return require_src.utils.getUint32(8, this);
}
get _isTakeFromOtherQuestion() {
return require_src.utils.getUint16(6, this) === 4;
}
set takeFromOtherQuestion(value) {
require_src.utils.setUint16(6, 4, this);
require_src.utils.setUint32(8, value, this);
}
_adoptAcceptFromThirdParty(value) {
require_src.utils.setUint16(6, 5, this);
require_src.utils.adopt(value, require_src.utils.getPointer(0, this));
}
_disownAcceptFromThirdParty() {
return require_src.utils.disown(this.acceptFromThirdParty);
}
/**
* **(level 3)**
*
* The caller should contact a third-party vat to pick up the results. An `Accept` message
* sent to the vat will return the result. This pairs with `Call.sendResultsTo.thirdParty`.
* It should only be used if the corresponding `Call` had `allowThirdPartyTailCall` set.
*
*/
get acceptFromThirdParty() {
require_src.utils.testWhich("acceptFromThirdParty", require_src.utils.getUint16(6, this), 5, this);
return require_src.utils.getPointer(0, this);
}
_hasAcceptFromThirdParty() {
return !require_src.utils.isNull(require_src.utils.getPointer(0, this));
}
get _isAcceptFromThirdParty() {
return require_src.utils.getUint16(6, this) === 5;
}
set acceptFromThirdParty(value) {
require_src.utils.setUint16(6, 5, this);
require_src.utils.copyFrom(value, require_src.utils.getPointer(0, this));
}
toString() {
return "Return_" + super.toString();
}
which() {
return require_src.utils.getUint16(6, this);
}
};
/**
* **(level 0)**
*
* Message type sent from the caller to the callee to indicate:
* 1) The questionId will no longer be used in any messages sent by the callee (no further
* pipelined requests).
* 2) If the call has not returned yet, the caller no longer cares about the result. If nothing
* else cares about the result either (e.g. there are no other outstanding calls pipelined on
* the result of this one) then the callee may wish to immediately cancel the operation and
* send back a Return message with "canceled" set. However, implementations are not required
* to support premature cancellation -- instead, the implementation may wait until the call
* actually completes and send a normal `Return` message.
*
* TODO(someday): Should we separate (1) and implicitly releasing result capabilities? It would be
* possible and useful to notify the server that it doesn't need to keep around the response to
* service pipeline requests even though the caller still wants to receive it / hasn't yet
* finished processing it. It could also be useful to notify the server that it need not marshal
* the results because the caller doesn't want them anyway, even if the caller is still sending
* pipelined calls, although this seems less useful (just saving some bytes on the wire).
*
*/
var Finish = class Finish extends require_src.Struct {
static _capnp = {
displayName: "Finish",
id: "d37d2eb2c2f80e63",
size: new require_src.ObjectSize(8, 0),
defaultReleaseResultCaps: require_src.getBitMask(true, 0),
defaultRequireEarlyCancellationWorkaround: require_src.getBitMask(true, 1)
};
/**
* ID of the call whose result is to be released.
*
*/
get questionId() {
return require_src.utils.getUint32(0, this);
}
set questionId(value) {
require_src.utils.setUint32(0, value, this);
}
/**
* If true, all capabilities that were in the results should be considered released. The sender
* must not send separate `Release` messages for them. Level 0 implementations in particular
* should always set this true. This defaults true because if level 0 implementations forget to
* set it they'll never notice (just silently leak caps), but if level >=1 implementations forget
* set it false they'll quickly get errors.
*
*/
get releaseResultCaps() {
return require_src.utils.getBit(32, this, Finish._capnp.defaultReleaseResultCaps);
}
set releaseResultCaps(value) {
require_src.utils.setBit(32, value, this, Finish._capnp.defaultReleaseResultCaps);
}
/**
* If true, if the RPC system receives this Finish message before the original call has even been
* delivered, it should defer cancellation util after delivery. In particular, this gives the
* destination object a chance to opt out of cancellation, e.g. as controlled by the
* `allowCancellation` annotation defined in `c++.capnp`.
*
* This is a work-around. Versions 1.0 and up of Cap'n Proto always set this to false. However,
* older versions of Cap'n Proto unintentionally exhibited this errant behavior by default, and
* as a result programs built with older versions could be inadvertently relying on their peers
* to implement the behavior. The purpose of this flag is to let newer versions know when the
* peer is an older version, so that it can attempt to work around the issue.
*
* See also comments in handleFinish() in rpc.c++ for more details.
*
*/
get requireEarlyCancellationWorkaround() {
return require_src.utils.getBit(33, this, Finish._capnp.defaultRequireEarlyCancellationWorkaround);
}
set requireEarlyCancellationWorkaround(value) {
require_src.utils.setBit(33, value, this, Finish._capnp.defaultRequireEarlyCancellationWorkaround);
}
toString() {
return "Finish_" + super.toString();
}
};
const Resolve_Which = {
/**
* The ID of the promise to be resolved.
*
* Unlike all other instances of `ExportId` sent from the exporter, the `Resolve` message does
* _not_ increase the reference count of `promiseId`. In fact, it is expected that the receiver
* will release the export soon after receiving `Resolve`, and the sender will not send this
* `ExportId` again until it has been released and recycled.
*
* When an export ID sent over the wire (e.g. in a `CapDescriptor`) is indicated to be a promise,
* this indicates that the sender will follow up at some point with a `Resolve` message. If the
* same `promiseId` is sent again before `Resolve`, still only one `Resolve` is sent. If the
* same ID is sent again later _after_ a `Resolve`, it can only be because the export's
* reference count hit zero in the meantime and the ID was re-assigned to a new export, therefore
* this later promise does _not_ correspond to the earlier `Resolve`.
*
* If a promise ID's reference count reaches zero before a `Resolve` is sent, the `Resolve`
* message may or may not still be sent (the `Resolve` may have already been in-flight when
* `