UNPKG

@stryke/capnp

Version:

A package to assist in running the Cap'n Proto compiler and creating Cap'n Proto serialization protocol schemas.

1,274 lines (1,273 loc) 160 kB
import { MessagePort as MessagePort$1 } from 'node:worker_threads'; import { ParsedCommandLine } from 'typescript'; export declare enum ListElementSize { VOID = 0, BIT = 1, BYTE = 2, BYTE_2 = 3, BYTE_4 = 4, BYTE_8 = 5, POINTER = 6, COMPOSITE = 7 } /** * A simple object that describes the size of a struct. */ export declare class ObjectSize { readonly dataByteLength: number; readonly pointerLength: number; /** * Creates a new ObjectSize instance. * * @param dataByteLength - The number of bytes in the data section of the struct * @param pointerLength - The number of pointers in the pointer section of the struct */ constructor(dataByteLength: number, pointerLength: number); toString(): string; } export interface _PointerCtor { readonly displayName: string; } export interface PointerCtor<T extends Pointer> { readonly _capnp: _PointerCtor; new (segment: Segment, byteOffset: number, depthLimit?: number): T; } export declare enum PointerType { STRUCT = 0, LIST = 1, FAR = 2, OTHER = 3 } export interface _Pointer { compositeIndex?: number; compositeList: boolean; /** * A number that is decremented as nested pointers are traversed. When this hits zero errors will be thrown. */ depthLimit: number; } /** * A pointer referencing a single byte location in a segment. This is typically used for Cap'n Proto pointers, but is * also sometimes used to reference an offset to a pointer's content or tag words. */ export declare class Pointer<T extends _Pointer = _Pointer> { static readonly _capnp: _PointerCtor; readonly _capnp: T; /** Offset, in bytes, from the start of the segment to the beginning of this pointer. */ byteOffset: number; /** * The starting segment for this pointer's data. In the case of a far pointer, the actual content this pointer is * referencing will be in another segment within the same message. */ segment: Segment; constructor(segment: Segment, byteOffset: number, depthLimit?: number); [Symbol.toStringTag](): string; toString(): string; } export interface _ListCtor { readonly compositeSize?: ObjectSize; readonly displayName: string; readonly size: ListElementSize; } export interface ListCtor<T> { readonly _capnp: _ListCtor; new (segment: Segment, byteOffset: number, depthLimit?: number): List<T>; } export type ArrayCb<T, RT = boolean> = (this: any, value: T, index: number, array: T[]) => RT; /** * A generic list class. Implements Filterable, */ export declare class List<T> extends Pointer implements Array<T> { #private; static readonly _capnp: _ListCtor; [n: number]: T; constructor(segment: Segment, byteOffset: number, depthLimit?: number); get length(): number; toArray(): T[]; get(_index: number): T; set(_index: number, _value: T): void; at(index: number): T; concat(other: T[]): T[]; some(cb: ArrayCb<T>, _this?: any): boolean; filter(cb: ArrayCb<T>, _this?: any): T[]; find(cb: ArrayCb<T>, _this?: any): T | undefined; findIndex(cb: (v: T, i: number, arr: T[]) => boolean, _this?: any): number; forEach(cb: ArrayCb<T, void>, _this?: any): void; map<U>(cb: ArrayCb<T, U>, _this?: any): U[]; flatMap<U>(cb: ArrayCb<T, U | U[]>, _this?: any): U[]; every<S extends T>(cb: (v: T, i: number) => v is S, t?: any): this is S[]; reduce(cb: (p: T, c: T, i: number, a: T[]) => T, initialValue?: T): T; reduceRight(cb: (p: T, c: T, i: number, a: T[]) => T, initialValue?: T): T; slice(start?: number, end?: number): T[]; join(separator?: string): string; toReversed(): T[]; toSorted(compareFn?: ((a: T, b: T) => number) | undefined): T[]; toSpliced(start: number, deleteCount: number, ...items: T[]): T[]; fill(value: T, start?: number, end?: number): this; copyWithin(target: number, start: number, end?: number): this; keys(): ArrayIterator<number>; values(): ArrayIterator<T>; entries(): ArrayIterator<[ number, T ]>; flat<A, D extends number = 1>(this: A, depth?: D): FlatArray<A, D>[]; with(index: number, value: T): T[]; includes(_searchElement: T, _fromIndex?: number): boolean; findLast(_cb: unknown, _thisArg?: unknown): T | undefined; findLastIndex(_cb: (v: T, i: number, a: T[]) => unknown, _t?: any): number; indexOf(_searchElement: T, _fromIndex?: number): number; lastIndexOf(_searchElement: T, _fromIndex?: number): number; pop(): T | undefined; push(..._items: T[]): number; reverse(): T[]; shift(): T | undefined; unshift(..._items: T[]): number; splice(_start: unknown, _deleteCount?: unknown, ..._rest: unknown[]): T[]; sort(_fn?: ((a: T, b: T) => number) | undefined): this; get [Symbol.unscopables](): { [x: number]: boolean | undefined; length?: boolean | undefined; toString?: boolean | undefined; toLocaleString?: boolean | undefined; pop?: boolean | undefined; push?: boolean | undefined; concat?: boolean | undefined; join?: boolean | undefined; reverse?: boolean | undefined; shift?: boolean | undefined; slice?: boolean | undefined; sort?: boolean | undefined; splice?: boolean | undefined; unshift?: boolean | undefined; indexOf?: boolean | undefined; lastIndexOf?: boolean | undefined; every?: boolean | undefined; some?: boolean | undefined; forEach?: boolean | undefined; map?: boolean | undefined; filter?: boolean | undefined; reduce?: boolean | undefined; reduceRight?: boolean | undefined; find?: boolean | undefined; findIndex?: boolean | undefined; fill?: boolean | undefined; copyWithin?: boolean | undefined; entries?: boolean | undefined; keys?: boolean | undefined; values?: boolean | undefined; includes?: boolean | undefined; flatMap?: boolean | undefined; flat?: boolean | undefined; at?: boolean | undefined; findLast?: boolean | undefined; findLastIndex?: boolean | undefined; toReversed?: boolean | undefined; toSorted?: boolean | undefined; toSpliced?: boolean | undefined; with?: boolean | undefined; [Symbol.iterator]?: boolean | undefined; readonly [Symbol.unscopables]?: boolean | undefined; }; [Symbol.iterator](): ArrayIterator<T>; toJSON(): unknown; toString(): string; toLocaleString(_locales?: unknown, _options?: unknown): string; [Symbol.toStringTag](): string; static [Symbol.toStringTag](): string; } 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; }; export type Message_Which = (typeof Message_Which)[keyof typeof Message_Which]; declare class Message$1 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<Message$1>): void; _disownUnimplemented(): Orphan<Message$1>; /** * 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$1; _hasUnimplemented(): boolean; _initUnimplemented(): Message$1; get _isUnimplemented(): boolean; set unimplemented(value: Message$1); _adoptAbort(value: Orphan<Exception>): void; _disownAbort(): Orphan<Exception>; /** * 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<Bootstrap>): void; _disownBootstrap(): Orphan<Bootstrap>; /** * Request the peer's bootstrap interface. * */ get bootstrap(): Bootstrap; _hasBootstrap(): boolean; _initBootstrap(): Bootstrap; get _isBootstrap(): boolean; set bootstrap(value: Bootstrap); _adoptCall(value: Orphan<Call$1>): void; _disownCall(): Orphan<Call$1>; /** * Begin a method call. * */ get call(): Call$1; _hasCall(): boolean; _initCall(): Call$1; get _isCall(): boolean; set call(value: Call$1); _adoptReturn(value: Orphan<Return>): void; _disownReturn(): Orphan<Return>; /** * Complete a method call. * */ get return(): Return; _hasReturn(): boolean; _initReturn(): Return; get _isReturn(): boolean; set return(value: Return); _adoptFinish(value: Orphan<Finish>): void; _disownFinish(): Orphan<Finish>; /** * Release a returned answer / cancel a call. * */ get finish(): Finish; _hasFinish(): boolean; _initFinish(): Finish; get _isFinish(): boolean; set finish(value: Finish); _adoptResolve(value: Orphan<Resolve>): void; _disownResolve(): Orphan<Resolve>; /** * Resolve a previously-sent promise. * */ get resolve(): Resolve; _hasResolve(): boolean; _initResolve(): Resolve; get _isResolve(): boolean; set resolve(value: Resolve); _adoptRelease(value: Orphan<Release>): void; _disownRelease(): Orphan<Release>; /** * 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<Disembargo>): void; _disownDisembargo(): Orphan<Disembargo>; /** * 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<Pointer>): void; _disownObsoleteSave(): Orphan<Pointer>; /** * 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<Pointer>): void; _disownObsoleteDelete(): Orphan<Pointer>; /** * 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<Provide>): void; _disownProvide(): Orphan<Provide>; /** * Provide a capability to a third party. * */ get provide(): Provide; _hasProvide(): boolean; _initProvide(): Provide; get _isProvide(): boolean; set provide(value: Provide); _adoptAccept(value: Orphan<Accept>): void; _disownAccept(): Orphan<Accept>; /** * 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<Join>): void; _disownJoin(): Orphan<Join>; /** * 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; } 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<Pointer>): void; _disownDeprecatedObjectId(): Orphan<Pointer>; /** * ** 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; }; export type Call_SendResultsTo_Which = (typeof Call_SendResultsTo_Which)[keyof typeof Call_SendResultsTo_Which]; 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<Pointer>): void; _disownThirdParty(): Orphan<Pointer>; /** * **(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; } declare class Call$1 extends Struct { static readonly _capnp: { displayName: string; id: string; size: ObjectSize; defaultAllowThirdPartyTailCall: DataView<ArrayBufferLike>; defaultNoPromisePipelining: DataView<ArrayBufferLike>; defaultOnlyPromisePipeline: DataView<ArrayBufferLike>; }; /** * 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<MessageTarget>): void; _disownTarget(): Orphan<MessageTarget>; /** * 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<Payload>): void; _disownParams(): Orphan<Payload>; /** * 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; }; export type Return_Which = (typeof Return_Which)[keyof typeof Return_Which]; 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<ArrayBufferLike>; defaultNoFinishNeeded: DataView<ArrayBufferLike>; }; /** * 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<Payload>): void; _disownResults(): Orphan<Payload>; /** * 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<Exception>): void; _disownException(): Orphan<Exception>; /** * 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<Pointer>): void; _disownAcceptFromThirdParty(): Orphan<Pointer>; /** * **(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; } declare class Finish extends Struct { static readonly _capnp: { displayName: string; id: string; size: ObjectSize; defaultReleaseResultCaps: DataView<ArrayBufferLike>; defaultRequireEarlyCancellationWorkaround: DataView<ArrayBufferLike>; }; /** * 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; }; export type Resolve_Which = (typeof Resolve_Which)[keyof typeof Resolve_Which]; 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<CapDescriptor>): void; _disownCap(): Orphan<CapDescriptor>; /** * 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<Exception>): void; _disownException(): Orphan<Exception>; /** * 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; } 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; }; export 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; } declare class Disembargo extends Struct { static readonly _capnp: { displayName: string; id: string; size: ObjectSize; }; _adoptTarget(value: Orphan<MessageTarget>): void; _disownTarget(): Orphan<MessageTarget>; /** * 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; } 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<MessageTarget>): void; _disownTarget(): Orphan<MessageTarget>; /** * What is to be provided to the third party. * */ get target(): MessageTarget; _hasTarget(): boolean; _initTarget(): MessageTarget; set target(value: MessageTarget); _adoptRecipient(value: Orphan<Pointer>): void; _disownRecipient(): Orphan<Pointer>; /** * Identity of the third party that is expected to pick up the capability. * */ get recipient(): Pointer; _hasRecipient(): boolean; set recipient(value: Pointer); toString(): string; } 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<Pointer>): void; _disownProvision(): Orphan<Pointer>; /** * 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