import { Struct, ObjectSize, Orphan, Pointer, ListCtor, List } from 'capnp-es'; declare const _capnpFileId: bigint; declare 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. * */ readonly 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). * */ readonly ABORT: 1; /** * Request the peer's bootstrap interface. * */ readonly BOOTSTRAP: 8; /** * Begin a method call. * */ readonly CALL: 2; /** * Complete a method call. * */ readonly RETURN: 3; /** * Release a returned answer / cancel a call. * */ readonly FINISH: 4; /** * Resolve a previously-sent promise. * */ readonly RESOLVE: 5; /** * Release a capability so that the remote object can be deallocated. * */ readonly RELEASE: 6; /** * Lift an embargo used to enforce E-order over promise resolution. * */ readonly 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. * */ readonly OBSOLETE_SAVE: 7; /** * Obsolete way to delete a SturdyRef. This operation was never implemented. * */ readonly OBSOLETE_DELETE: 9; /** * Provide a capability to a third party. * */ readonly PROVIDE: 10; /** * Accept a capability provided by a third party. * */ readonly ACCEPT: 11; /** * Directly connect to the common root of two or more proxied caps. * */ readonly JOIN: 12; }; type Message_Which = (typeof Message_Which)[keyof typeof Message_Which]; /** * An RPC connection is a bi-directional stream of Messages. * */ declare class Message extends Struct { static readonly UNIMPLEMENTED: 0; static readonly ABORT: 1; static readonly BOOTSTRAP: 8; static readonly CALL: 2; static readonly RETURN: 3; static readonly FINISH: 4; static readonly RESOLVE: 5; static readonly RELEASE: 6; static readonly DISEMBARGO: 13; static readonly OBSOLETE_SAVE: 7; static readonly OBSOLETE_DELETE: 9; static readonly PROVIDE: 10; static readonly ACCEPT: 11; static readonly JOIN: 12; static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; _adoptUnimplemented(value: Orphan): void; _disownUnimplemented(): Orphan; /** * 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(): Message; _hasUnimplemented(): boolean; _initUnimplemented(): Message; get _isUnimplemented(): boolean; set unimplemented(value: Message); _adoptAbort(value: Orphan): void; _disownAbort(): Orphan; /** * 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(): Exception; _hasAbort(): boolean; _initAbort(): Exception; get _isAbort(): boolean; set abort(value: Exception); _adoptBootstrap(value: Orphan): void; _disownBootstrap(): Orphan; /** * Request the peer's bootstrap interface. * */ get bootstrap(): Bootstrap; _hasBootstrap(): boolean; _initBootstrap(): Bootstrap; get _isBootstrap(): boolean; set bootstrap(value: Bootstrap); _adoptCall(value: Orphan): void; _disownCall(): Orphan; /** * Begin a method call. * */ get call(): Call; _hasCall(): boolean; _initCall(): Call; get _isCall(): boolean; set call(value: Call); _adoptReturn(value: Orphan): void; _disownReturn(): Orphan; /** * Complete a method call. * */ get return(): Return; _hasReturn(): boolean; _initReturn(): Return; get _isReturn(): boolean; set return(value: Return); _adoptFinish(value: Orphan): void; _disownFinish(): Orphan; /** * Release a returned answer / cancel a call. * */ get finish(): Finish; _hasFinish(): boolean; _initFinish(): Finish; get _isFinish(): boolean; set finish(value: Finish); _adoptResolve(value: Orphan): void; _disownResolve(): Orphan; /** * Resolve a previously-sent promise. * */ get resolve(): Resolve; _hasResolve(): boolean; _initResolve(): Resolve; get _isResolve(): boolean; set resolve(value: Resolve); _adoptRelease(value: Orphan): void; _disownRelease(): Orphan; /** * Release a capability so that the remote object can be deallocated. * */ get release(): Release; _hasRelease(): boolean; _initRelease(): Release; get _isRelease(): boolean; set release(value: Release); _adoptDisembargo(value: Orphan): void; _disownDisembargo(): Orphan; /** * Lift an embargo used to enforce E-order over promise resolution. * */ get disembargo(): Disembargo; _hasDisembargo(): boolean; _initDisembargo(): Disembargo; get _isDisembargo(): boolean; set disembargo(value: Disembargo); _adoptObsoleteSave(value: Orphan): void; _disownObsoleteSave(): Orphan; /** * 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(): Pointer; _hasObsoleteSave(): boolean; get _isObsoleteSave(): boolean; set obsoleteSave(value: Pointer); _adoptObsoleteDelete(value: Orphan): void; _disownObsoleteDelete(): Orphan; /** * Obsolete way to delete a SturdyRef. This operation was never implemented. * */ get obsoleteDelete(): Pointer; _hasObsoleteDelete(): boolean; get _isObsoleteDelete(): boolean; set obsoleteDelete(value: Pointer); _adoptProvide(value: Orphan): void; _disownProvide(): Orphan; /** * Provide a capability to a third party. * */ get provide(): Provide; _hasProvide(): boolean; _initProvide(): Provide; get _isProvide(): boolean; set provide(value: Provide); _adoptAccept(value: Orphan): void; _disownAccept(): Orphan; /** * Accept a capability provided by a third party. * */ get accept(): Accept; _hasAccept(): boolean; _initAccept(): Accept; get _isAccept(): boolean; set accept(value: Accept); _adoptJoin(value: Orphan): void; _disownJoin(): Orphan; /** * Directly connect to the common root of two or more proxied caps. * */ get join(): Join; _hasJoin(): boolean; _initJoin(): Join; get _isJoin(): boolean; set join(value: Join); toString(): string; which(): Message_Which; } /** * **(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. * */ declare class Bootstrap extends Struct { static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; /** * A new question ID identifying this request, which will eventually receive a Return message * containing the restored capability. * */ get questionId(): number; set questionId(value: number); _adoptDeprecatedObjectId(value: Orphan): void; _disownDeprecatedObjectId(): Orphan; /** * ** 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(): Pointer; _hasDeprecatedObjectId(): boolean; set deprecatedObjectId(value: Pointer); toString(): string; } declare const Call_SendResultsTo_Which: { /** * Send the return message back to the caller (the usual). * */ readonly 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'(). * */ readonly 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`. * */ readonly THIRD_PARTY: 2; }; type Call_SendResultsTo_Which = (typeof Call_SendResultsTo_Which)[keyof typeof Call_SendResultsTo_Which]; /** * Where should the return message be sent? * */ declare class Call_SendResultsTo extends Struct { static readonly CALLER: 0; static readonly YOURSELF: 1; static readonly THIRD_PARTY: 2; static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; get _isCaller(): boolean; set caller(_: true); get _isYourself(): boolean; set yourself(_: true); _adoptThirdParty(value: Orphan): void; _disownThirdParty(): Orphan; /** * **(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(): Pointer; _hasThirdParty(): boolean; get _isThirdParty(): boolean; set thirdParty(value: Pointer); toString(): string; which(): Call_SendResultsTo_Which; } /** * **(level 0)** * * Message type initiating a method call on a capability. * */ declare class Call extends Struct { static readonly _capnp: { displayName: string; id: string; size: ObjectSize; defaultAllowThirdPartyTailCall: DataView; defaultNoPromisePipelining: DataView; defaultOnlyPromisePipeline: DataView; }; /** * 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(): number; set questionId(value: number); _adoptTarget(value: Orphan): void; _disownTarget(): Orphan; /** * The object that should receive this call. * */ get target(): MessageTarget; _hasTarget(): boolean; _initTarget(): MessageTarget; set target(value: MessageTarget); /** * The type ID of the interface being called. Each capability may implement multiple interfaces. * */ get interfaceId(): bigint; set interfaceId(value: bigint); /** * The ordinal number of the method to call within the requested interface. * */ get methodId(): number; set methodId(value: number); /** * 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(): boolean; set allowThirdPartyTailCall(value: boolean); /** * 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(): boolean; set noPromisePipelining(value: boolean); /** * 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(): boolean; set onlyPromisePipeline(value: boolean); _adoptParams(value: Orphan): void; _disownParams(): Orphan; /** * The call parameters. `params.content` is a struct whose fields correspond to the parameters of * the method. * */ get params(): Payload; _hasParams(): boolean; _initParams(): Payload; set params(value: Payload); /** * Where should the return message be sent? * */ get sendResultsTo(): Call_SendResultsTo; _initSendResultsTo(): Call_SendResultsTo; toString(): string; } declare const Return_Which: { /** * Equal to the QuestionId of the corresponding `Call` message. * */ readonly 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. * */ readonly 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. * */ readonly CANCELED: 2; /** * Indicates that the call failed and explains why. * */ readonly RESULTS_SENT_ELSEWHERE: 3; /** * Indicates that the call was canceled due to the caller sending a Finish message * before the call had completed. * */ readonly 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. * */ readonly ACCEPT_FROM_THIRD_PARTY: 5; }; type Return_Which = (typeof Return_Which)[keyof typeof Return_Which]; /** * **(level 0)** * * Message type sent from callee to caller indicating that the call has completed. * */ declare class Return extends Struct { static readonly RESULTS: 0; static readonly EXCEPTION: 1; static readonly CANCELED: 2; static readonly RESULTS_SENT_ELSEWHERE: 3; static readonly TAKE_FROM_OTHER_QUESTION: 4; static readonly ACCEPT_FROM_THIRD_PARTY: 5; static readonly _capnp: { displayName: string; id: string; size: ObjectSize; defaultReleaseParamCaps: DataView; defaultNoFinishNeeded: DataView; }; /** * Equal to the QuestionId of the corresponding `Call` message. * */ get answerId(): number; set answerId(value: number); /** * 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(): boolean; set releaseParamCaps(value: boolean); /** * 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(): boolean; set noFinishNeeded(value: boolean); _adoptResults(value: Orphan): void; _disownResults(): Orphan; /** * 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(): Payload; _hasResults(): boolean; _initResults(): Payload; get _isResults(): boolean; set results(value: Payload); _adoptException(value: Orphan): void; _disownException(): Orphan; /** * Indicates that the call failed and explains why. * */ get exception(): Exception; _hasException(): boolean; _initException(): Exception; get _isException(): boolean; set exception(value: Exception); get _isCanceled(): boolean; set canceled(_: true); get _isResultsSentElsewhere(): boolean; set resultsSentElsewhere(_: true); /** * 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(): number; get _isTakeFromOtherQuestion(): boolean; set takeFromOtherQuestion(value: number); _adoptAcceptFromThirdParty(value: Orphan): void; _disownAcceptFromThirdParty(): Orphan; /** * **(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(): Pointer; _hasAcceptFromThirdParty(): boolean; get _isAcceptFromThirdParty(): boolean; set acceptFromThirdParty(value: Pointer); toString(): string; which(): Return_Which; } /** * **(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). * */ declare class Finish extends Struct { static readonly _capnp: { displayName: string; id: string; size: ObjectSize; defaultReleaseResultCaps: DataView; defaultRequireEarlyCancellationWorkaround: DataView; }; /** * ID of the call whose result is to be released. * */ get questionId(): number; set questionId(value: number); /** * 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(): boolean; set releaseResultCaps(value: boolean); /** * 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(): boolean; set requireEarlyCancellationWorkaround(value: boolean); toString(): string; } declare 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 * `Release` was sent, but if the `Release` is received before `Resolve` then there is no longer * any reason to send a `Resolve`). Thus a `Resolve` may be received for a promise of which * the receiver has no knowledge, because it already released it earlier. In this case, the * receiver should simply release the capability to which the promise resolved. * */ readonly CAP: 0; /** * The object to which the promise resolved. * * The sender promises that from this point forth, until `promiseId` is released, it shall * simply forward all messages to the capability designated by `cap`. This is true even if * `cap` itself happens to designate another promise, and that other promise later resolves -- * messages sent to `promiseId` shall still go to that other promise, not to its resolution. * This is important in the case that the receiver of the `Resolve` ends up sending a * `Disembargo` message towards `promiseId` in order to control message ordering -- that * `Disembargo` really needs to reflect back to exactly the object designated by `cap` even * if that object is itself a promise. * */ readonly EXCEPTION: 1; }; type Resolve_Which = (typeof Resolve_Which)[keyof typeof Resolve_Which]; /** * **(level 1)** * * Message type sent to indicate that a previously-sent promise has now been resolved to some other * object (possibly another promise) -- or broken, or canceled. * * Keep in mind that it's possible for a `Resolve` to be sent to a level 0 implementation that * doesn't implement it. For example, a method call or return might contain a capability in the * payload. Normally this is fine even if the receiver is level 0, because they will implicitly * release all such capabilities on return / finish. But if the cap happens to be a promise, then * a follow-up `Resolve` may be sent regardless of this release. The level 0 receiver will reply * with an `unimplemented` message, and the sender (of the `Resolve`) can respond to this as if the * receiver had immediately released any capability to which the promise resolved. * * When implementing promise resolution, it's important to understand how embargos work and the * tricky case of the Tribble 4-way race condition. See the comments for the Disembargo message, * below. * */ declare class Resolve extends Struct { static readonly CAP: 0; static readonly EXCEPTION: 1; static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; /** * 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 * `Release` was sent, but if the `Release` is received before `Resolve` then there is no longer * any reason to send a `Resolve`). Thus a `Resolve` may be received for a promise of which * the receiver has no knowledge, because it already released it earlier. In this case, the * receiver should simply release the capability to which the promise resolved. * */ get promiseId(): number; set promiseId(value: number); _adoptCap(value: Orphan): void; _disownCap(): Orphan; /** * The object to which the promise resolved. * * The sender promises that from this point forth, until `promiseId` is released, it shall * simply forward all messages to the capability designated by `cap`. This is true even if * `cap` itself happens to designate another promise, and that other promise later resolves -- * messages sent to `promiseId` shall still go to that other promise, not to its resolution. * This is important in the case that the receiver of the `Resolve` ends up sending a * `Disembargo` message towards `promiseId` in order to control message ordering -- that * `Disembargo` really needs to reflect back to exactly the object designated by `cap` even * if that object is itself a promise. * */ get cap(): CapDescriptor; _hasCap(): boolean; _initCap(): CapDescriptor; get _isCap(): boolean; set cap(value: CapDescriptor); _adoptException(value: Orphan): void; _disownException(): Orphan; /** * Indicates that the promise was broken. * */ get exception(): Exception; _hasException(): boolean; _initException(): Exception; get _isException(): boolean; set exception(value: Exception); toString(): string; which(): Resolve_Which; } /** * **(level 1)** * * Message type sent to indicate that the sender is done with the given capability and the receiver * can free resources allocated to it. * */ declare class Release extends Struct { static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; /** * What to release. * */ get id(): number; set id(value: number); /** * The amount by which to decrement the reference count. The export is only actually released * when the reference count reaches zero. * */ get referenceCount(): number; set referenceCount(value: number); toString(): string; } declare const Disembargo_Context_Which: { /** * The sender is requesting a disembargo on a promise that is known to resolve back to a * capability hosted by the sender. As soon as the receiver has echoed back all pipelined calls * on this promise, it will deliver the Disembargo back to the sender with `receiverLoopback` * set to the same value as `senderLoopback`. This value is chosen by the sender, and since * it is also consumed be the sender, the sender can use whatever strategy it wants to make sure * the value is unambiguous. * * The receiver must verify that the target capability actually resolves back to the sender's * vat. Otherwise, the sender has committed a protocol error and should be disconnected. * */ readonly SENDER_LOOPBACK: 0; /** * The receiver previously sent a `senderLoopback` Disembargo towards a promise resolving to * this capability, and that Disembargo is now being echoed back. * */ readonly RECEIVER_LOOPBACK: 1; /** * **(level 3)** * * The sender is requesting a disembargo on a promise that is known to resolve to a third-party * capability that the sender is currently in the process of accepting (using `Accept`). * The receiver of this `Disembargo` has an outstanding `Provide` on said capability. The * receiver should now send a `Disembargo` with `provide` set to the question ID of that * `Provide` message. * * See `Accept.embargo` for an example. * */ readonly ACCEPT: 2; /** * **(level 3)** * * The sender is requesting a disembargo on a capability currently being provided to a third * party. The question ID identifies the `Provide` message previously sent by the sender to * this capability. On receipt, the receiver (the capability host) shall release the embargo * on the `Accept` message that it has received from the third party. See `Accept.embargo` for * an example. * */ readonly PROVIDE: 3; }; type Disembargo_Context_Which = (typeof Disembargo_Context_Which)[keyof typeof Disembargo_Context_Which]; declare class Disembargo_Context extends Struct { static readonly SENDER_LOOPBACK: 0; static readonly RECEIVER_LOOPBACK: 1; static readonly ACCEPT: 2; static readonly PROVIDE: 3; static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; /** * The sender is requesting a disembargo on a promise that is known to resolve back to a * capability hosted by the sender. As soon as the receiver has echoed back all pipelined calls * on this promise, it will deliver the Disembargo back to the sender with `receiverLoopback` * set to the same value as `senderLoopback`. This value is chosen by the sender, and since * it is also consumed be the sender, the sender can use whatever strategy it wants to make sure * the value is unambiguous. * * The receiver must verify that the target capability actually resolves back to the sender's * vat. Otherwise, the sender has committed a protocol error and should be disconnected. * */ get senderLoopback(): number; get _isSenderLoopback(): boolean; set senderLoopback(value: number); /** * The receiver previously sent a `senderLoopback` Disembargo towards a promise resolving to * this capability, and that Disembargo is now being echoed back. * */ get receiverLoopback(): number; get _isReceiverLoopback(): boolean; set receiverLoopback(value: number); get _isAccept(): boolean; set accept(_: true); /** * **(level 3)** * * The sender is requesting a disembargo on a capability currently being provided to a third * party. The question ID identifies the `Provide` message previously sent by the sender to * this capability. On receipt, the receiver (the capability host) shall release the embargo * on the `Accept` message that it has received from the third party. See `Accept.embargo` for * an example. * */ get provide(): number; get _isProvide(): boolean; set provide(value: number); toString(): string; which(): Disembargo_Context_Which; } /** * **(level 1)** * * Message sent to indicate that an embargo on a recently-resolved promise may now be lifted. * * Embargos are used to enforce E-order in the presence of promise resolution. That is, if an * application makes two calls foo() and bar() on the same capability reference, in that order, * the calls should be delivered in the order in which they were made. But if foo() is called * on a promise, and that promise happens to resolve before bar() is called, then the two calls * may travel different paths over the network, and thus could arrive in the wrong order. In * this case, the call to `bar()` must be embargoed, and a `Disembargo` message must be sent along * the same path as `foo()` to ensure that the `Disembargo` arrives after `foo()`. Once the * `Disembargo` arrives, `bar()` can then be delivered. * * There are two particular cases where embargos are important. Consider object Alice, in Vat A, * who holds a promise P, pointing towards Vat B, that eventually resolves to Carol. The two * cases are: * - Carol lives in Vat A, i.e. next to Alice. In this case, Vat A needs to send a `Disembargo` * message that echos through Vat B and back, to ensure that all pipelined calls on the promise * have been delivered. * - Carol lives in a different Vat C. When the promise resolves, a three-party handoff occurs * (see `Provide` and `Accept`, which constitute level 3 of the protocol). In this case, we * piggyback on the state that has already been set up to handle the handoff: the `Accept` * message (from Vat A to Vat C) is embargoed, as are all pipelined messages sent to it, while * a `Disembargo` message is sent from Vat A through Vat B to Vat C. See `Accept.embargo` for * an example. * * Note that in the case where Carol actually lives in Vat B (i.e., the same vat that the promise * already pointed at), no embargo is needed, because the pipelined calls are delivered over the * same path as the later direct calls. * * Keep in mind that promise resolution happens both in the form of Resolve messages as well as * Return messages (which resolve PromisedAnswers). Embargos apply in both cases. * * An alternative strategy for enforcing E-order over promise resolution could be for Vat A to * implement the embargo internally. When Vat A is notified of promise resolution, it could * send a dummy no-op call to promise P and wait for it to complete. Until that call completes, * all calls to the capability are queued locally. This strategy works, but is pessimistic: * in the three-party case, it requires an A -> B -> C -> B -> A round trip before calls can start * being delivered directly to from Vat A to Vat C. The `Disembargo` message allows latency to be * reduced. (In the two-party loopback case, the `Disembargo` message is just a more explicit way * of accomplishing the same thing as a no-op call, but isn't any faster.) * * *The Tribble 4-way Race Condition* * * Any implementation of promise resolution and embargos must be aware of what we call the * "Tribble 4-way race condition", after Dean Tribble, who explained the problem in a lively * Friam meeting. * * Embargos are designed to work in the case where a two-hop path is being shortened to one hop. * But sometimes there are more hops. Imagine that Alice has a reference to a remote promise P1 * that eventually resolves to _another_ remote promise P2 (in a third vat), which _at the same * time_ happens to resolve to Bob (in a fourth vat). In this case, we're shortening from a 3-hop * path (with four parties) to a 1-hop path (Alice -> Bob). * * Extending the embargo/disembargo protocol to be able to shorted multiple hops at once seems * difficult. Instead, we make a rule that prevents this case from coming up: * * One a promise P has been resolved to a remote object reference R, then all further messages * received addressed to P will be forwarded strictly to R. Even if it turns out later that R is * itself a promise, and has resolved to some other object Q, messages sent to P will still be * forwarded to R, not directly to Q (R will of course further forward the messages to Q). * * This rule does not cause a significant performance burden because once P has resolved to R, it * is expected that people sending messages to P will shortly start sending them to R instead and * drop P. P is at end-of-life anyway, so it doesn't matter if it ignores chances to further * optimize its path. * * Note well: the Tribble 4-way race condition does not require each vat to be *distinct*; as long * as each resolution crosses a network boundary the race can occur -- so this concerns even level * 1 implementations, not just level 3 implementations. * */ declare class Disembargo extends Struct { static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; _adoptTarget(value: Orphan): void; _disownTarget(): Orphan; /** * What is to be disembargoed. * */ get target(): MessageTarget; _hasTarget(): boolean; _initTarget(): MessageTarget; set target(value: MessageTarget); get context(): Disembargo_Context; _initContext(): Disembargo_Context; toString(): string; } /** * **(level 3)** * * Message type sent to indicate that the sender wishes to make a particular capability implemented * by the receiver available to a third party for direct access (without the need for the third * party to proxy through the sender). * * (In CapTP, `Provide` and `Accept` are methods of the global `NonceLocator` object exported by * every vat. In Cap'n Proto, we bake this into the core protocol.) * */ declare class Provide extends Struct { static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; /** * Question ID to be held open until the recipient has received the capability. A result will be * returned once the third party has successfully received the capability. The sender must at some * point send a `Finish` message as with any other call, and that message can be used to cancel the * whole operation. * */ get questionId(): number; set questionId(value: number); _adoptTarget(value: Orphan): void; _disownTarget(): Orphan; /** * What is to be provided to the third party. * */ get target(): MessageTarget; _hasTarget(): boolean; _initTarget(): MessageTarget; set target(value: MessageTarget); _adoptRecipient(value: Orphan): void; _disownRecipient(): Orphan; /** * Identity of the third party that is expected to pick up the capability. * */ get recipient(): Pointer; _hasRecipient(): boolean; set recipient(value: Pointer); toString(): string; } /** * **(level 3)** * * Message type sent to pick up a capability hosted by the receiving vat and provided by a third * party. The third party previously designated the capability using `Provide`. * * This message is also used to pick up a redirected return -- see `Return.acceptFromThirdParty`. * */ declare class Accept extends Struct { static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; /** * A new question ID identifying this accept message, which will eventually receive a Return * message containing the provided capability (or the call result in the case of a redirected * return). * */ get questionId(): number; set questionId(value: number); _adoptProvision(value: Orphan): void; _disownProvision(): Orphan; /** * Identifies the provided object to be picked up. * */ get provision(): Pointer; _hasProvision(): boolean; set provision(value: Pointer); /** * If true, this accept shall be temporarily embargoed. The resulting `Return` will not be sent, * and any pipelined calls will not be delivered, until the embargo is released. The receiver * (the capability host) will expect the provider (the vat that sent the `Provide` message) to * eventually send a `Disembargo` message with the field `context.provide` set to the question ID * of the original `Provide` message. At that point, the embargo is released and the queued * messages are delivered. * * For example: * - Alice, in Vat A, holds a promise P, which currently points toward Vat B. * - Alice calls foo() on P. The `Call` message is sent to Vat B. * - The promise P in Vat B ends up resolving to Carol, in Vat C. * - Vat B sends a `Provide` message to Vat C, identifying Vat A as the recipient. * - Vat B sends a `Resolve` message to Vat A, indicating that the promise has resolved to a * `ThirdPartyCapId` identifying Carol in Vat C. * - Vat A sends an `Accept` message to Vat C to pick up the capability. Since Vat A knows that * it has an outstanding call to the promise, it sets `embargo` to `true` in the `Accept` * message. * - Vat A sends a `Disembargo` message to Vat B on promise P, with `context.accept` set. * - Alice makes a call bar() to promise P, which is now pointing towards Vat C. Alice doesn't * know anything about the mechanics of promise resolution happening under the hood, but she * expects that bar() will be delivered after foo() because that is the order in which she * initiated the calls. * - Vat A sends the bar() call to Vat C, as a pipelined call on the result of the `Accept` (which * hasn't returned yet, due to the embargo). Since calls to the newly-accepted capability * are embargoed, Vat C does not deliver the call yet. * - At some point, Vat B forwards the foo() call from the beginning of this example on to Vat C. * - Vat B forwards the `Disembargo` from Vat A on to vat C. It sets `context.provide` to the * question ID of the `Provide` message it had sent previously. * - Vat C receives foo() before `Disembargo`, thus allowing it to correctly deliver foo() * before delivering bar(). * - Vat C receives `Disembargo` from Vat B. It can now send a `Return` for the `Accept` from * Vat A, as well as deliver bar(). * */ get embargo(): boolean; set embargo(value: boolean); toString(): string; } /** * **(level 4)** * * Message type sent to implement E.join(), which, given a number of capabilities that are * expected to be equivalent, finds the underlying object upon which they all agree and forms a * direct connection to it, skipping any proxies that may have been constructed by other vats * while transmitting the capability. See: * http://erights.org/elib/equality/index.html * * Note that this should only serve to bypass fully-transparent proxies -- proxies that were * created merely for convenience, without any intention of hiding the underlying object. * * For example, say Bob holds two capabilities hosted by Alice and Carol, but he expects that both * are simply proxies for a capability hosted elsewhere. He then issues a join request, which * operates as follows: * - Bob issues Join requests on both Alice and Carol. Each request contains a different piece * of the JoinKey. * - Alice is proxying a capability hosted by Dana, so forwards the request to Dana's cap. * - Dana receives the first request and sees that the JoinKeyPart is one of two. She notes that * she doesn't have the other part yet, so she records the request and responds with a * JoinResult. * - Alice relays the JoinAnswer back to Bob. * - Carol is also proxying a capability from Dana, and so forwards her Join request to Dana as * well. * - Dana receives Carol's request and notes that she now has both parts of a JoinKey. She * combines them in order to form information needed to form a secure connection to Bob. She * also responds with another JoinResult. * - Bob receives the responses from Alice and Carol. He uses the returned JoinResults to * determine how to connect to Dana and attempts to form the connection. Since Bob and Dana now * agree on a secret key that neither Alice nor Carol ever saw, this connection can be made * securely even if Alice or Carol is conspiring against the other. (If Alice and Carol are * conspiring _together_, they can obviously reproduce the key, but this doesn't matter because * the whole point of the join is to verify that Alice and Carol agree on what capability they * are proxying.) * * If the two capabilities aren't actually proxies of the same object, then the join requests * will come back with conflicting `hostId`s and the join will fail before attempting to form any * connection. * */ declare class Join extends Struct { static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; /** * Question ID used to respond to this Join. (Note that this ID only identifies one part of the * request for one hop; each part has a different ID and relayed copies of the request have * (probably) different IDs still.) * * The receiver will reply with a `Return` whose `results` is a JoinResult. This `JoinResult` * is relayed from the joined object's host, possibly with transformation applied as needed * by the network. * * Like any return, the result must be released using a `Finish`. However, this release * should not occur until the joiner has either successfully connected to the joined object. * Vats relaying a `Join` message similarly must not release the result they receive until the * return they relayed back towards the joiner has itself been released. This allows the * joined object's host to detect when the Join operation is canceled before completing -- if * it receives a `Finish` for one of the join results before the joiner successfully * connects. It can then free any resources it had allocated as part of the join. * */ get questionId(): number; set questionId(value: number); _adoptTarget(value: Orphan): void; _disownTarget(): Orphan; /** * The capability to join. * */ get target(): MessageTarget; _hasTarget(): boolean; _initTarget(): MessageTarget; set target(value: MessageTarget); _adoptKeyPart(value: Orphan): void; _disownKeyPart(): Orphan; /** * A part of the join key. These combine to form the complete join key, which is used to establish * a direct connection. * */ get keyPart(): Pointer; _hasKeyPart(): boolean; set keyPart(value: Pointer); toString(): string; } declare const MessageTarget_Which: { /** * This message is to a capability or promise previously imported by the caller (exported by * the receiver). * */ readonly IMPORTED_CAP: 0; /** * This message is to a capability that is expected to be returned by another call that has not * yet been completed. * * At level 0, this is supported only for addressing the result of a previous `Bootstrap`, so * that initial startup doesn't require a round trip. * */ readonly PROMISED_ANSWER: 1; }; type MessageTarget_Which = (typeof MessageTarget_Which)[keyof typeof MessageTarget_Which]; /** * The target of a `Call` or other messages that target a capability. * */ declare class MessageTarget extends Struct { static readonly IMPORTED_CAP: 0; static readonly PROMISED_ANSWER: 1; static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; /** * This message is to a capability or promise previously imported by the caller (exported by * the receiver). * */ get importedCap(): number; get _isImportedCap(): boolean; set importedCap(value: number); _adoptPromisedAnswer(value: Orphan): void; _disownPromisedAnswer(): Orphan; /** * This message is to a capability that is expected to be returned by another call that has not * yet been completed. * * At level 0, this is supported only for addressing the result of a previous `Bootstrap`, so * that initial startup doesn't require a round trip. * */ get promisedAnswer(): PromisedAnswer; _hasPromisedAnswer(): boolean; _initPromisedAnswer(): PromisedAnswer; get _isPromisedAnswer(): boolean; set promisedAnswer(value: PromisedAnswer); toString(): string; which(): MessageTarget_Which; } /** * Represents some data structure that might contain capabilities. * */ declare class Payload extends Struct { static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; static _CapTable: ListCtor; _adoptContent(value: Orphan): void; _disownContent(): Orphan; /** * Some Cap'n Proto data structure. Capability pointers embedded in this structure index into * `capTable`. * */ get content(): Pointer; _hasContent(): boolean; set content(value: Pointer); _adoptCapTable(value: Orphan>): void; _disownCapTable(): Orphan>; /** * Descriptors corresponding to the cap pointers in `content`. * */ get capTable(): List; _hasCapTable(): boolean; _initCapTable(length: number): List; set capTable(value: List); toString(): string; } declare const CapDescriptor_Which: { /** * There is no capability here. This `CapDescriptor` should not appear in the payload content. * A `none` CapDescriptor can be generated when an application inserts a capability into a * message and then later changes its mind and removes it -- rewriting all of the other * capability pointers may be hard, so instead a tombstone is left, similar to the way a removed * struct or list instance is zeroed out of the message but the space is not reclaimed. * Hopefully this is unusual. * */ readonly NONE: 0; /** * The ID of a capability in the sender's export table (receiver's import table). It may be a * newly allocated table entry, or an existing entry (increments the reference count). * */ readonly SENDER_HOSTED: 1; /** * A promise that the sender will resolve later. The sender will send exactly one Resolve * message at a future point in time to replace this promise. Note that even if the same * `senderPromise` is received multiple times, only one `Resolve` is sent to cover all of * them. If `senderPromise` is released before the `Resolve` is sent, the sender (of this * `CapDescriptor`) may choose not to send the `Resolve` at all. * */ readonly SENDER_PROMISE: 2; /** * A capability (or promise) previously exported by the receiver (imported by the sender). * */ readonly RECEIVER_HOSTED: 3; /** * A capability expected to be returned in the results of a currently-outstanding call posed * by the sender. * */ readonly RECEIVER_ANSWER: 4; /** * **(level 3)** * * A capability that lives in neither the sender's nor the receiver's vat. The sender needs * to form a direct connection to a third party to pick up the capability. * * Level 1 and 2 implementations that receive a `thirdPartyHosted` may simply send calls to its * `vine` instead. * */ readonly THIRD_PARTY_HOSTED: 5; }; type CapDescriptor_Which = (typeof CapDescriptor_Which)[keyof typeof CapDescriptor_Which]; /** * **(level 1)** * * When an application-defined type contains an interface pointer, that pointer contains an index * into the message's capability table -- i.e. the `capTable` part of the `Payload`. Each * capability in the table is represented as a `CapDescriptor`. The runtime API should not reveal * the CapDescriptor directly to the application, but should instead wrap it in some kind of * callable object with methods corresponding to the interface that the capability implements. * * Keep in mind that `ExportIds` in a `CapDescriptor` are subject to reference counting. See the * description of `ExportId`. * * Note that it is currently not possible to include a broken capability in the CapDescriptor * table. Instead, create a new export (`senderPromise`) for each broken capability and then * immediately follow the payload-bearing Call or Return message with one Resolve message for each * broken capability, resolving it to an exception. * */ declare class CapDescriptor extends Struct { static readonly NONE: 0; static readonly SENDER_HOSTED: 1; static readonly SENDER_PROMISE: 2; static readonly RECEIVER_HOSTED: 3; static readonly RECEIVER_ANSWER: 4; static readonly THIRD_PARTY_HOSTED: 5; static readonly _capnp: { displayName: string; id: string; size: ObjectSize; defaultAttachedFd: DataView; }; get _isNone(): boolean; set none(_: true); /** * The ID of a capability in the sender's export table (receiver's import table). It may be a * newly allocated table entry, or an existing entry (increments the reference count). * */ get senderHosted(): number; get _isSenderHosted(): boolean; set senderHosted(value: number); /** * A promise that the sender will resolve later. The sender will send exactly one Resolve * message at a future point in time to replace this promise. Note that even if the same * `senderPromise` is received multiple times, only one `Resolve` is sent to cover all of * them. If `senderPromise` is released before the `Resolve` is sent, the sender (of this * `CapDescriptor`) may choose not to send the `Resolve` at all. * */ get senderPromise(): number; get _isSenderPromise(): boolean; set senderPromise(value: number); /** * A capability (or promise) previously exported by the receiver (imported by the sender). * */ get receiverHosted(): number; get _isReceiverHosted(): boolean; set receiverHosted(value: number); _adoptReceiverAnswer(value: Orphan): void; _disownReceiverAnswer(): Orphan; /** * A capability expected to be returned in the results of a currently-outstanding call posed * by the sender. * */ get receiverAnswer(): PromisedAnswer; _hasReceiverAnswer(): boolean; _initReceiverAnswer(): PromisedAnswer; get _isReceiverAnswer(): boolean; set receiverAnswer(value: PromisedAnswer); _adoptThirdPartyHosted(value: Orphan): void; _disownThirdPartyHosted(): Orphan; /** * **(level 3)** * * A capability that lives in neither the sender's nor the receiver's vat. The sender needs * to form a direct connection to a third party to pick up the capability. * * Level 1 and 2 implementations that receive a `thirdPartyHosted` may simply send calls to its * `vine` instead. * */ get thirdPartyHosted(): ThirdPartyCapDescriptor; _hasThirdPartyHosted(): boolean; _initThirdPartyHosted(): ThirdPartyCapDescriptor; get _isThirdPartyHosted(): boolean; set thirdPartyHosted(value: ThirdPartyCapDescriptor); /** * If the RPC message in which this CapDescriptor was delivered also had file descriptors * attached, and `fd` is a valid index into the list of attached file descriptors, then * that file descriptor should be attached to this capability. If `attachedFd` is out-of-bounds * for said list, then no FD is attached. * * For example, if the RPC message arrived over a Unix socket, then file descriptors may be * attached by sending an SCM_RIGHTS ancillary message attached to the data bytes making up the * raw message. Receivers who wish to opt into FD passing should arrange to receive SCM_RIGHTS * whenever receiving an RPC message. Senders who wish to send FDs need not verify whether the * receiver knows how to receive them, because the operating system will automatically discard * ancillary messages like SCM_RIGHTS if the receiver doesn't ask to receive them, including * automatically closing any FDs. * * It is up to the application protocol to define what capabilities are expected to have file * descriptors attached, and what those FDs mean. But, for example, an application could use this * to open a file on disk and then transmit the open file descriptor to a sandboxed process that * does not otherwise have permission to access the filesystem directly. This is usually an * optimization: the sending process could instead provide an RPC interface supporting all the * operations needed (such as reading and writing a file), but by passing the file descriptor * directly, the recipient can often perform operations much more efficiently. Application * designers are encouraged to provide such RPC interfaces and automatically fall back to them * when FD passing is not available, so that the application can still work when the parties are * remote over a network. * * An attached FD is most often associated with a `senderHosted` descriptor. It could also make * sense in the case of `thirdPartyHosted`: in this case, the sender is forwarding the FD that * they received from the third party, so that the receiver can start using it without first * interacting with the third party. This is an optional optimization -- the middleman may choose * not to forward capabilities, in which case the receiver will need to complete the handshake * with the third party directly before receiving the FD. If an implementation receives a second * attached FD after having already received one previously (e.g. both in a `thirdPartyHosted` * CapDescriptor and then later again when receiving the final capability directly from the * third party), the implementation should discard the later FD and stick with the original. At * present, there is no known reason why other capability types (e.g. `receiverHosted`) would want * to carry an attached FD, but we reserve the right to define a meaning for this in the future. * * Each file descriptor attached to the message must be used in no more than one CapDescriptor, * so that the receiver does not need to use dup() or refcounting to handle the possibility of * multiple capabilities using the same descriptor. If multiple CapDescriptors do point to the * same FD index, then the receiver can arbitrarily choose which capability ends up having the * FD attached. * * To mitigate DoS attacks, RPC implementations should limit the number of FDs they are willing to * receive in a single message to a small value. If a message happens to contain more than that, * the list is truncated. Moreover, in some cases, FD passing needs to be blocked entirely for * security or implementation reasons, in which case the list may be truncated to zero. Hence, * `attachedFd` might point past the end of the list, which the implementation should treat as if * no FD was attached at all. * * The type of this field was chosen to be UInt8 because Linux supports sending only a maximum * of 253 file descriptors in an SCM_RIGHTS message anyway, and CapDescriptor had two bytes of * padding left -- so after adding this, there is still one byte for a future feature. * Conveniently, this also means we're able to use 0xff as the default value, which will always * be out-of-range (of course, the implementation should explicitly enforce that 255 descriptors * cannot be sent at once, rather than relying on Linux to do so). * */ get attachedFd(): number; set attachedFd(value: number); toString(): string; which(): CapDescriptor_Which; } declare const PromisedAnswer_Op_Which: { /** * Does nothing. This member is mostly defined so that we can make `Op` a union even * though (as of this writing) only one real operation is defined. * */ readonly NOOP: 0; /** * Get a pointer field within a struct. The number is an index into the pointer section, NOT * a field ordinal, so that the receiver does not need to understand the schema. * */ readonly GET_POINTER_FIELD: 1; }; type PromisedAnswer_Op_Which = (typeof PromisedAnswer_Op_Which)[keyof typeof PromisedAnswer_Op_Which]; declare class PromisedAnswer_Op extends Struct { static readonly NOOP: 0; static readonly GET_POINTER_FIELD: 1; static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; get _isNoop(): boolean; set noop(_: true); /** * Get a pointer field within a struct. The number is an index into the pointer section, NOT * a field ordinal, so that the receiver does not need to understand the schema. * */ get getPointerField(): number; get _isGetPointerField(): boolean; set getPointerField(value: number); toString(): string; which(): PromisedAnswer_Op_Which; } /** * **(mostly level 1)** * * Specifies how to derive a promise from an unanswered question, by specifying the path of fields * to follow from the root of the eventual result struct to get to the desired capability. Used * to address method calls to a not-yet-returned capability or to pass such a capability as an * input to some other method call. * * Level 0 implementations must support `PromisedAnswer` only for the case where the answer is * to a `Bootstrap` message. In this case, `path` is always empty since `Bootstrap` always returns * a raw capability. * */ declare class PromisedAnswer extends Struct { static readonly Op: typeof PromisedAnswer_Op; static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; static _Transform: ListCtor; /** * ID of the question (in the sender's question table / receiver's answer table) whose answer is * expected to contain the capability. * */ get questionId(): number; set questionId(value: number); _adoptTransform(value: Orphan>): void; _disownTransform(): Orphan>; /** * Operations / transformations to apply to the result in order to get the capability actually * being addressed. E.g. if the result is a struct and you want to call a method on a capability * pointed to by a field of the struct, you need a `getPointerField` op. * */ get transform(): List; _hasTransform(): boolean; _initTransform(length: number): List; set transform(value: List); toString(): string; } /** * **(level 3)** * * Identifies a capability in a third-party vat that the sender wants the receiver to pick up. * */ declare class ThirdPartyCapDescriptor extends Struct { static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; _adoptId(value: Orphan): void; _disownId(): Orphan; /** * Identifies the third-party host and the specific capability to accept from it. * */ get id(): Pointer; _hasId(): boolean; set id(value: Pointer); /** * A proxy for the third-party object exported by the sender. In CapTP terminology this is called * a "vine", because it is an indirect reference to the third-party object that snakes through the * sender vat. This serves two purposes: * * * Level 1 and 2 implementations that don't understand how to connect to a third party may * simply send calls to the vine. Such calls will be forwarded to the third-party by the * sender. * * * Level 3 implementations must release the vine only once they have successfully picked up the * object from the third party. This ensures that the capability is not released by the sender * prematurely. * * The sender will close the `Provide` request that it has sent to the third party as soon as * it receives either a `Call` or a `Release` message directed at the vine. * */ get vineId(): number; set vineId(value: number); toString(): string; } declare const Exception_Type: { /** * A generic problem occurred, and it is believed that if the operation were repeated without * any change in the state of the world, the problem would occur again. * * A client might respond to this error by logging it for investigation by the developer and/or * displaying it to the user. * */ readonly FAILED: 0; /** * The request was rejected due to a temporary lack of resources. * * Examples include: * - There's not enough CPU time to keep up with incoming requests, so some are rejected. * - The server ran out of RAM or disk space during the request. * - The operation timed out (took significantly longer than it should have). * * A client might respond to this error by scheduling to retry the operation much later. The * client should NOT retry again immediately since this would likely exacerbate the problem. * */ readonly OVERLOADED: 1; /** * The method failed because a connection to some necessary capability was lost. * * Examples include: * - The client introduced the server to a third-party capability, the connection to that third * party was subsequently lost, and then the client requested that the server use the dead * capability for something. * - The client previously requested that the server obtain a capability from some third party. * The server returned a capability to an object wrapping the third-party capability. Later, * the server's connection to the third party was lost. * - The capability has been revoked. Revocation does not necessarily mean that the client is * no longer authorized to use the capability; it is often used simply as a way to force the * client to repeat the setup process, perhaps to efficiently move them to a new back-end or * get them to recognize some other change that has occurred. * * A client should normally respond to this error by releasing all capabilities it is currently * holding related to the one it called and then re-creating them by restoring SturdyRefs and/or * repeating the method calls used to create them originally. In other words, disconnect and * start over. This should in turn cause the server to obtain a new copy of the capability that * it lost, thus making everything work. * * If the client receives another `disconnected` error in the process of rebuilding the * capability and retrying the call, it should treat this as an `overloaded` error: the network * is currently unreliable, possibly due to load or other temporary issues. * */ readonly DISCONNECTED: 2; /** * The server doesn't implement the requested method. If there is some other method that the * client could call (perhaps an older and/or slower interface), it should try that instead. * Otherwise, this should be treated like `failed`. * */ readonly UNIMPLEMENTED: 3; }; type Exception_Type = (typeof Exception_Type)[keyof typeof Exception_Type]; /** * **(level 0)** * * Describes an arbitrary error that prevented an operation (e.g. a call) from completing. * * Cap'n Proto exceptions always indicate that something went wrong. In other words, in a fantasy * world where everything always works as expected, no exceptions would ever be thrown. Clients * should only ever catch exceptions as a means to implement fault-tolerance, where "fault" can * mean: * - Bugs. * - Invalid input. * - Configuration errors. * - Network problems. * - Insufficient resources. * - Version skew (unimplemented functionality). * - Other logistical problems. * * Exceptions should NOT be used to flag application-specific conditions that a client is expected * to handle in an application-specific way. Put another way, in the Cap'n Proto world, * "checked exceptions" (where an interface explicitly defines the exceptions it throws and * clients are forced by the type system to handle those exceptions) do NOT make sense. * */ declare class Exception extends Struct { static readonly Type: { /** * A generic problem occurred, and it is believed that if the operation were repeated without * any change in the state of the world, the problem would occur again. * * A client might respond to this error by logging it for investigation by the developer and/or * displaying it to the user. * */ readonly FAILED: 0; /** * The request was rejected due to a temporary lack of resources. * * Examples include: * - There's not enough CPU time to keep up with incoming requests, so some are rejected. * - The server ran out of RAM or disk space during the request. * - The operation timed out (took significantly longer than it should have). * * A client might respond to this error by scheduling to retry the operation much later. The * client should NOT retry again immediately since this would likely exacerbate the problem. * */ readonly OVERLOADED: 1; /** * The method failed because a connection to some necessary capability was lost. * * Examples include: * - The client introduced the server to a third-party capability, the connection to that third * party was subsequently lost, and then the client requested that the server use the dead * capability for something. * - The client previously requested that the server obtain a capability from some third party. * The server returned a capability to an object wrapping the third-party capability. Later, * the server's connection to the third party was lost. * - The capability has been revoked. Revocation does not necessarily mean that the client is * no longer authorized to use the capability; it is often used simply as a way to force the * client to repeat the setup process, perhaps to efficiently move them to a new back-end or * get them to recognize some other change that has occurred. * * A client should normally respond to this error by releasing all capabilities it is currently * holding related to the one it called and then re-creating them by restoring SturdyRefs and/or * repeating the method calls used to create them originally. In other words, disconnect and * start over. This should in turn cause the server to obtain a new copy of the capability that * it lost, thus making everything work. * * If the client receives another `disconnected` error in the process of rebuilding the * capability and retrying the call, it should treat this as an `overloaded` error: the network * is currently unreliable, possibly due to load or other temporary issues. * */ readonly DISCONNECTED: 2; /** * The server doesn't implement the requested method. If there is some other method that the * client could call (perhaps an older and/or slower interface), it should try that instead. * Otherwise, this should be treated like `failed`. * */ readonly UNIMPLEMENTED: 3; }; static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; /** * Human-readable failure description. * */ get reason(): string; set reason(value: string); /** * The type of the error. The purpose of this enum is not to describe the error itself, but * rather to describe how the client might want to respond to the error. * */ get type(): Exception_Type; set type(value: Exception_Type); /** * OBSOLETE. Ignore. * */ get obsoleteIsCallersFault(): boolean; set obsoleteIsCallersFault(value: boolean); /** * OBSOLETE. See `type` instead. * */ get obsoleteDurability(): number; set obsoleteDurability(value: number); /** * Stack trace text from the remote server. The format is not specified. By default, * implementations do not provide stack traces; the application must explicitly enable them * when desired. * */ get trace(): string; set trace(value: string); toString(): string; } export { Accept, Bootstrap, Call, Call_SendResultsTo, Call_SendResultsTo_Which, CapDescriptor, CapDescriptor_Which, Disembargo, Disembargo_Context, Disembargo_Context_Which, Exception, Exception_Type, Finish, Join, Message, MessageTarget, MessageTarget_Which, Message_Which, Payload, PromisedAnswer, PromisedAnswer_Op, PromisedAnswer_Op_Which, Provide, Release, Resolve, Resolve_Which, Return, Return_Which, ThirdPartyCapDescriptor, _capnpFileId };