cannam@147: # Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors cannam@147: # Licensed under the MIT License: cannam@147: # cannam@147: # Permission is hereby granted, free of charge, to any person obtaining a copy cannam@147: # of this software and associated documentation files (the "Software"), to deal cannam@147: # in the Software without restriction, including without limitation the rights cannam@147: # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell cannam@147: # copies of the Software, and to permit persons to whom the Software is cannam@147: # furnished to do so, subject to the following conditions: cannam@147: # cannam@147: # The above copyright notice and this permission notice shall be included in cannam@147: # all copies or substantial portions of the Software. cannam@147: # cannam@147: # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR cannam@147: # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, cannam@147: # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE cannam@147: # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER cannam@147: # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, cannam@147: # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN cannam@147: # THE SOFTWARE. cannam@147: cannam@147: @0xb312981b2552a250; cannam@147: # Recall that Cap'n Proto RPC allows messages to contain references to remote objects that cannam@147: # implement interfaces. These references are called "capabilities", because they both designate cannam@147: # the remote object to use and confer permission to use it. cannam@147: # cannam@147: # Recall also that Cap'n Proto RPC has the feature that when a method call itself returns a cannam@147: # capability, the caller can begin calling methods on that capability _before the first call has cannam@147: # returned_. The caller essentially sends a message saying "Hey server, as soon as you finish cannam@147: # that previous call, do this with the result!". Cap'n Proto's RPC protocol makes this possible. cannam@147: # cannam@147: # The protocol is significantly more complicated than most RPC protocols. However, this is cannam@147: # implementation complexity that underlies an easy-to-grasp higher-level model of object oriented cannam@147: # programming. That is, just like TCP is a surprisingly complicated protocol that implements a cannam@147: # conceptually-simple byte stream abstraction, Cap'n Proto is a surprisingly complicated protocol cannam@147: # that implements a conceptually-simple object abstraction. cannam@147: # cannam@147: # Cap'n Proto RPC is based heavily on CapTP, the object-capability protocol used by the E cannam@147: # programming language: cannam@147: # http://www.erights.org/elib/distrib/captp/index.html cannam@147: # cannam@147: # Cap'n Proto RPC takes place between "vats". A vat hosts some set of objects and talks to other cannam@147: # vats through direct bilateral connections. Typically, there is a 1:1 correspondence between vats cannam@147: # and processes (in the unix sense of the word), although this is not strictly always true (one cannam@147: # process could run multiple vats, or a distributed virtual vat might live across many processes). cannam@147: # cannam@147: # Cap'n Proto does not distinguish between "clients" and "servers" -- this is up to the application. cannam@147: # Either end of any connection can potentially hold capabilities pointing to the other end, and cannam@147: # can call methods on those capabilities. In the doc comments below, we use the words "sender" cannam@147: # and "receiver". These refer to the sender and receiver of an instance of the struct or field cannam@147: # being documented. Sometimes we refer to a "third-party" that is neither the sender nor the cannam@147: # receiver. Documentation is generally written from the point of view of the sender. cannam@147: # cannam@147: # It is generally up to the vat network implementation to securely verify that connections are made cannam@147: # to the intended vat as well as to encrypt transmitted data for privacy and integrity. See the cannam@147: # `VatNetwork` example interface near the end of this file. cannam@147: # cannam@147: # When a new connection is formed, the only interesting things that can be done are to send a cannam@147: # `Bootstrap` (level 0) or `Accept` (level 3) message. cannam@147: # cannam@147: # Unless otherwise specified, messages must be delivered to the receiving application in the same cannam@147: # order in which they were initiated by the sending application. The goal is to support "E-Order", cannam@147: # which states that two calls made on the same reference must be delivered in the order which they cannam@147: # were made: cannam@147: # http://erights.org/elib/concurrency/partial-order.html cannam@147: # cannam@147: # Since the full protocol is complicated, we define multiple levels of support that an cannam@147: # implementation may target. For many applications, level 1 support will be sufficient. cannam@147: # Comments in this file indicate which level requires the corresponding feature to be cannam@147: # implemented. cannam@147: # cannam@147: # * **Level 0:** The implementation does not support object references. Only the bootstrap interface cannam@147: # can be called. At this level, the implementation does not support object-oriented protocols and cannam@147: # is similar in complexity to JSON-RPC or Protobuf services. This level should be considered only cannam@147: # a temporary stepping-stone toward level 1 as the lack of object references drastically changes cannam@147: # how protocols are designed. Applications _should not_ attempt to design their protocols around cannam@147: # the limitations of level 0 implementations. cannam@147: # cannam@147: # * **Level 1:** The implementation supports simple bilateral interaction with object references cannam@147: # and promise pipelining, but interactions between three or more parties are supported only via cannam@147: # proxying of objects. E.g. if Alice (in Vat A) wants to send Bob (in Vat B) a capability cannam@147: # pointing to Carol (in Vat C), Alice must create a proxy of Carol within Vat A and send Bob a cannam@147: # reference to that; Bob cannot form a direct connection to Carol. Level 1 implementations do cannam@147: # not support checking if two capabilities received from different vats actually point to the cannam@147: # same object ("join"), although they should be able to do this check on capabilities received cannam@147: # from the same vat. cannam@147: # cannam@147: # * **Level 2:** The implementation supports saving persistent capabilities -- i.e. capabilities cannam@147: # that remain valid even after disconnect, and can be restored on a future connection. When a cannam@147: # capability is saved, the requester receives a `SturdyRef`, which is a token that can be used cannam@147: # to restore the capability later. cannam@147: # cannam@147: # * **Level 3:** The implementation supports three-way interactions. That is, if Alice (in Vat A) cannam@147: # sends Bob (in Vat B) a capability pointing to Carol (in Vat C), then Vat B will automatically cannam@147: # form a direct connection to Vat C rather than have requests be proxied through Vat A. cannam@147: # cannam@147: # * **Level 4:** The entire protocol is implemented, including joins (checking if two capabilities cannam@147: # are equivalent). cannam@147: # cannam@147: # Note that an implementation must also support specific networks (transports), as described in cannam@147: # the "Network-specific Parameters" section below. An implementation might have different levels cannam@147: # depending on the network used. cannam@147: # cannam@147: # New implementations of Cap'n Proto should start out targeting the simplistic two-party network cannam@147: # type as defined in `rpc-twoparty.capnp`. With this network type, level 3 is irrelevant and cannam@147: # levels 2 and 4 are much easier than usual to implement. When such an implementation is paired cannam@147: # with a container proxy, the contained app effectively gets to make full use of the proxy's cannam@147: # network at level 4. And since Cap'n Proto IPC is extremely fast, it may never make sense to cannam@147: # bother implementing any other vat network protocol -- just use the correct container type and get cannam@147: # it for free. cannam@147: cannam@147: using Cxx = import "/capnp/c++.capnp"; cannam@147: $Cxx.namespace("capnp::rpc"); cannam@147: cannam@147: # ======================================================================================== cannam@147: # The Four Tables cannam@147: # cannam@147: # Cap'n Proto RPC connections are stateful (although an application built on Cap'n Proto could cannam@147: # export a stateless interface). As in CapTP, for each open connection, a vat maintains four state cannam@147: # tables: questions, answers, imports, and exports. See the diagram at: cannam@147: # http://www.erights.org/elib/distrib/captp/4tables.html cannam@147: # cannam@147: # The question table corresponds to the other end's answer table, and the imports table corresponds cannam@147: # to the other end's exports table. cannam@147: # cannam@147: # The entries in each table are identified by ID numbers (defined below as 32-bit integers). These cannam@147: # numbers are always specific to the connection; a newly-established connection starts with no cannam@147: # valid IDs. Since low-numbered IDs will pack better, it is suggested that IDs be assigned like cannam@147: # Unix file descriptors -- prefer the lowest-number ID that is currently available. cannam@147: # cannam@147: # IDs in the questions/answers tables are chosen by the questioner and generally represent method cannam@147: # calls that are in progress. cannam@147: # cannam@147: # IDs in the imports/exports tables are chosen by the exporter and generally represent objects on cannam@147: # which methods may be called. Exports may be "settled", meaning the exported object is an actual cannam@147: # object living in the exporter's vat, or they may be "promises", meaning the exported object is cannam@147: # the as-yet-unknown result of an ongoing operation and will eventually be resolved to some other cannam@147: # object once that operation completes. Calls made to a promise will be forwarded to the eventual cannam@147: # target once it is known. The eventual replacement object does *not* get the same ID as the cannam@147: # promise, as it may turn out to be an object that is already exported (so already has an ID) or cannam@147: # may even live in a completely different vat (and so won't get an ID on the same export table cannam@147: # at all). cannam@147: # cannam@147: # IDs can be reused over time. To make this safe, we carefully define the lifetime of IDs. Since cannam@147: # messages using the ID could be traveling in both directions simultaneously, we must define the cannam@147: # end of life of each ID _in each direction_. The ID is only safe to reuse once it has been cannam@147: # released by both sides. cannam@147: # cannam@147: # When a Cap'n Proto connection is lost, everything on the four tables is lost. All questions are cannam@147: # canceled and throw exceptions. All imports become broken (all future calls to them throw cannam@147: # exceptions). All exports and answers are implicitly released. The only things not lost are cannam@147: # persistent capabilities (`SturdyRef`s). The application must plan for this and should respond by cannam@147: # establishing a new connection and restoring from these persistent capabilities. cannam@147: cannam@147: using QuestionId = UInt32; cannam@147: # **(level 0)** cannam@147: # cannam@147: # Identifies a question in the sender's question table (which corresponds to the receiver's answer cannam@147: # table). The questioner (caller) chooses an ID when making a call. The ID remains valid in cannam@147: # caller -> callee messages until a Finish message is sent, and remains valid in callee -> caller cannam@147: # messages until a Return message is sent. cannam@147: cannam@147: using AnswerId = QuestionId; cannam@147: # **(level 0)** cannam@147: # cannam@147: # Identifies an answer in the sender's answer table (which corresponds to the receiver's question cannam@147: # table). cannam@147: # cannam@147: # AnswerId is physically equivalent to QuestionId, since the question and answer tables correspond, cannam@147: # but we define a separate type for documentation purposes: we always use the type representing cannam@147: # the sender's point of view. cannam@147: cannam@147: using ExportId = UInt32; cannam@147: # **(level 1)** cannam@147: # cannam@147: # Identifies an exported capability or promise in the sender's export table (which corresponds cannam@147: # to the receiver's import table). The exporter chooses an ID before sending a capability over the cannam@147: # wire. If the capability is already in the table, the exporter should reuse the same ID. If the cannam@147: # ID is a promise (as opposed to a settled capability), this must be indicated at the time the ID cannam@147: # is introduced (e.g. by using `senderPromise` instead of `senderHosted` in `CapDescriptor`); in cannam@147: # this case, the importer shall expect a later `Resolve` message that replaces the promise. cannam@147: # cannam@147: # ExportId/ImportIds are subject to reference counting. Whenever an `ExportId` is sent over the cannam@147: # wire (from the exporter to the importer), the export's reference count is incremented (unless cannam@147: # otherwise specified). The reference count is later decremented by a `Release` message. Since cannam@147: # the `Release` message can specify an arbitrary number by which to reduce the reference count, the cannam@147: # importer should usually batch reference decrements and only send a `Release` when it believes the cannam@147: # reference count has hit zero. Of course, it is possible that a new reference to the export is cannam@147: # in-flight at the time that the `Release` message is sent, so it is necessary for the exporter to cannam@147: # keep track of the reference count on its end as well to avoid race conditions. cannam@147: # cannam@147: # When a connection is lost, all exports are implicitly released. It is not possible to restore cannam@147: # a connection state after disconnect (although a transport layer could implement a concept of cannam@147: # persistent connections if it is transparent to the RPC layer). cannam@147: cannam@147: using ImportId = ExportId; cannam@147: # **(level 1)** cannam@147: # cannam@147: # Identifies an imported capability or promise in the sender's import table (which corresponds to cannam@147: # the receiver's export table). cannam@147: # cannam@147: # ImportId is physically equivalent to ExportId, since the export and import tables correspond, cannam@147: # but we define a separate type for documentation purposes: we always use the type representing cannam@147: # the sender's point of view. cannam@147: # cannam@147: # An `ImportId` remains valid in importer -> exporter messages until the importer has sent cannam@147: # `Release` messages that (it believes) have reduced the reference count to zero. cannam@147: cannam@147: # ======================================================================================== cannam@147: # Messages cannam@147: cannam@147: struct Message { cannam@147: # An RPC connection is a bi-directional stream of Messages. cannam@147: cannam@147: union { cannam@147: unimplemented @0 :Message; cannam@147: # The sender previously received this message from the peer but didn't understand it or doesn't cannam@147: # yet implement the functionality that was requested. So, the sender is echoing the message cannam@147: # back. In some cases, the receiver may be able to recover from this by pretending the sender cannam@147: # had taken some appropriate "null" action. cannam@147: # cannam@147: # For example, say `resolve` is received by a level 0 implementation (because a previous call cannam@147: # or return happened to contain a promise). The level 0 implementation will echo it back as cannam@147: # `unimplemented`. The original sender can then simply release the cap to which the promise cannam@147: # had resolved, thus avoiding a leak. cannam@147: # cannam@147: # For any message type that introduces a question, if the message comes back unimplemented, cannam@147: # the original sender may simply treat it as if the question failed with an exception. cannam@147: # cannam@147: # In cases where there is no sensible way to react to an `unimplemented` message (without cannam@147: # resource leaks or other serious problems), the connection may need to be aborted. This is cannam@147: # a gray area; different implementations may take different approaches. cannam@147: cannam@147: abort @1 :Exception; cannam@147: # Sent when a connection is being aborted due to an unrecoverable error. This could be e.g. cannam@147: # because the sender received an invalid or nonsensical message (`isCallersFault` is true) or cannam@147: # because the sender had an internal error (`isCallersFault` is false). The sender will shut cannam@147: # down the outgoing half of the connection after `abort` and will completely close the cannam@147: # connection shortly thereafter (it's up to the sender how much of a time buffer they want to cannam@147: # offer for the client to receive the `abort` before the connection is reset). cannam@147: cannam@147: # Level 0 features ----------------------------------------------- cannam@147: cannam@147: bootstrap @8 :Bootstrap; # Request the peer's bootstrap interface. cannam@147: call @2 :Call; # Begin a method call. cannam@147: return @3 :Return; # Complete a method call. cannam@147: finish @4 :Finish; # Release a returned answer / cancel a call. cannam@147: cannam@147: # Level 1 features ----------------------------------------------- cannam@147: cannam@147: resolve @5 :Resolve; # Resolve a previously-sent promise. cannam@147: release @6 :Release; # Release a capability so that the remote object can be deallocated. cannam@147: disembargo @13 :Disembargo; # Lift an embargo used to enforce E-order over promise resolution. cannam@147: cannam@147: # Level 2 features ----------------------------------------------- cannam@147: cannam@147: obsoleteSave @7 :AnyPointer; cannam@147: # Obsolete request to save a capability, resulting in a SturdyRef. This has been replaced cannam@147: # by the `Persistent` interface defined in `persistent.capnp`. This operation was never cannam@147: # implemented. cannam@147: cannam@147: obsoleteDelete @9 :AnyPointer; cannam@147: # Obsolete way to delete a SturdyRef. This operation was never implemented. cannam@147: cannam@147: # Level 3 features ----------------------------------------------- cannam@147: cannam@147: provide @10 :Provide; # Provide a capability to a third party. cannam@147: accept @11 :Accept; # Accept a capability provided by a third party. cannam@147: cannam@147: # Level 4 features ----------------------------------------------- cannam@147: cannam@147: join @12 :Join; # Directly connect to the common root of two or more proxied caps. cannam@147: } cannam@147: } cannam@147: cannam@147: # Level 0 message types ---------------------------------------------- cannam@147: cannam@147: struct Bootstrap { cannam@147: # **(level 0)** cannam@147: # cannam@147: # Get the "bootstrap" interface exported by the remote vat. cannam@147: # cannam@147: # For level 0, 1, and 2 implementations, the "bootstrap" interface is simply the main interface cannam@147: # exported by a vat. If the vat acts as a server fielding connections from clients, then the cannam@147: # bootstrap interface defines the basic functionality available to a client when it connects. cannam@147: # The exact interface definition obviously depends on the application. cannam@147: # cannam@147: # We call this a "bootstrap" because in an ideal Cap'n Proto world, bootstrap interfaces would cannam@147: # never be used. In such a world, any time you connect to a new vat, you do so because you cannam@147: # received an introduction from some other vat (see `ThirdPartyCapId`). Thus, the first message cannam@147: # you send is `Accept`, and further communications derive from there. `Bootstrap` is not used. cannam@147: # cannam@147: # In such an ideal world, DNS itself would support Cap'n Proto -- performing a DNS lookup would cannam@147: # actually return a new Cap'n Proto capability, thus introducing you to the target system via cannam@147: # level 3 RPC. Applications would receive the capability to talk to DNS in the first place as cannam@147: # an initial endowment or part of a Powerbox interaction. Therefore, an app can form arbitrary cannam@147: # connections without ever using `Bootstrap`. cannam@147: # cannam@147: # Of course, in the real world, DNS is not Cap'n-Proto-based, and we don't want Cap'n Proto to cannam@147: # require a whole new internet infrastructure to be useful. Therefore, we offer bootstrap cannam@147: # interfaces as a way to get up and running without a level 3 introduction. Thus, bootstrap cannam@147: # interfaces are used to "bootstrap" from other, non-Cap'n-Proto-based means of service discovery, cannam@147: # such as legacy DNS. cannam@147: # cannam@147: # Note that a vat need not provide a bootstrap interface, and in fact many vats (especially those cannam@147: # acting as clients) do not. In this case, the vat should either reply to `Bootstrap` with a cannam@147: # `Return` indicating an exception, or should return a dummy capability with no methods. cannam@147: cannam@147: questionId @0 :QuestionId; cannam@147: # A new question ID identifying this request, which will eventually receive a Return message cannam@147: # containing the restored capability. cannam@147: cannam@147: deprecatedObjectId @1 :AnyPointer; cannam@147: # ** DEPRECATED ** cannam@147: # cannam@147: # A Vat may export multiple bootstrap interfaces. In this case, `deprecatedObjectId` specifies cannam@147: # which one to return. If this pointer is null, then the default bootstrap interface is returned. cannam@147: # cannam@147: # As of verison 0.5, use of this field is deprecated. If a service wants to export multiple cannam@147: # bootstrap interfaces, it should instead define a single bootstarp interface that has methods cannam@147: # that return each of the other interfaces. cannam@147: # cannam@147: # **History** cannam@147: # cannam@147: # In the first version of Cap'n Proto RPC (0.4.x) the `Bootstrap` message was called `Restore`. cannam@147: # At the time, it was thought that this would eventually serve as the way to restore SturdyRefs cannam@147: # (level 2). Meanwhile, an application could offer its "main" interface on a well-known cannam@147: # (non-secret) SturdyRef. cannam@147: # cannam@147: # Since level 2 RPC was not implemented at the time, the `Restore` message was in practice only cannam@147: # used to obtain the main interface. Since most applications had only one main interface that cannam@147: # they wanted to restore, they tended to designate this with a null `objectId`. cannam@147: # cannam@147: # Unfortunately, the earliest version of the EZ RPC interfaces set a precedent of exporting cannam@147: # multiple main interfaces by allowing them to be exported under string names. In this case, cannam@147: # `objectId` was a Text value specifying the name. cannam@147: # cannam@147: # All of this proved problematic for several reasons: cannam@147: # cannam@147: # - The arrangement assumed that a client wishing to restore a SturdyRef would know exactly what cannam@147: # machine to connect to and would be able to immediately restore a SturdyRef on connection. cannam@147: # However, in practice, the ability to restore SturdyRefs is itself a capability that may cannam@147: # require going through an authentication process to obtain. Thus, it makes more sense to cannam@147: # define a "restorer service" as a full Cap'n Proto interface. If this restorer interface is cannam@147: # offered as the vat's bootstrap interface, then this is equivalent to the old arrangement. cannam@147: # cannam@147: # - Overloading "Restore" for the purpose of obtaining well-known capabilities encouraged the cannam@147: # practice of exporting singleton services with string names. If singleton services are desired, cannam@147: # it is better to have one main interface that has methods that can be used to obtain each cannam@147: # service, in order to get all the usual benefits of schemas and type checking. cannam@147: # cannam@147: # - Overloading "Restore" also had a security problem: Often, "main" or "well-known" cannam@147: # capabilities exported by a vat are in fact not public: they are intended to be accessed only cannam@147: # by clients who are capable of forming a connection to the vat. This can lead to trouble if cannam@147: # the client itself has other clients and wishes to foward some `Restore` requests from those cannam@147: # external clients -- it has to be very careful not to allow through `Restore` requests cannam@147: # addressing the default capability. cannam@147: # cannam@147: # For example, consider the case of a sandboxed Sandstorm application and its supervisor. The cannam@147: # application exports a default capability to its supervisor that provides access to cannam@147: # functionality that only the supervisor is supposed to access. Meanwhile, though, applications cannam@147: # may publish other capabilities that may be persistent, in which case the application needs cannam@147: # to field `Restore` requests that could come from anywhere. These requests of course have to cannam@147: # pass through the supervisor, as all communications with the outside world must. But, the cannam@147: # supervisor has to be careful not to honor an external request addressing the application's cannam@147: # default capability, since this capability is privileged. Unfortunately, the default cannam@147: # capability cannot be given an unguessable name, because then the supervisor itself would not cannam@147: # be able to address it! cannam@147: # cannam@147: # As of Cap'n Proto 0.5, `Restore` has been renamed to `Bootstrap` and is no longer planned for cannam@147: # use in restoring SturdyRefs. cannam@147: # cannam@147: # Note that 0.4 also defined a message type called `Delete` that, like `Restore`, addressed a cannam@147: # SturdyRef, but indicated that the client would not restore the ref again in the future. This cannam@147: # operation was never implemented, so it was removed entirely. If a "delete" operation is desired, cannam@147: # it should exist as a method on the same interface that handles restoring SturdyRefs. However, cannam@147: # the utility of such an operation is questionable. You wouldn't be able to rely on it for cannam@147: # garbage collection since a client could always disappear permanently without remembering to cannam@147: # delete all its SturdyRefs, thus leaving them dangling forever. Therefore, it is advisable to cannam@147: # design systems such that SturdyRefs never represent "owned" pointers. cannam@147: # cannam@147: # For example, say a SturdyRef points to an image file hosted on some server. That image file cannam@147: # should also live inside a collection (a gallery, perhaps) hosted on the same server, owned by cannam@147: # a user who can delete the image at any time. If the user deletes the image, the SturdyRef cannam@147: # stops working. On the other hand, if the SturdyRef is discarded, this has no effect on the cannam@147: # existence of the image in its collection. cannam@147: } cannam@147: cannam@147: struct Call { cannam@147: # **(level 0)** cannam@147: # cannam@147: # Message type initiating a method call on a capability. cannam@147: cannam@147: questionId @0 :QuestionId; cannam@147: # A number, chosen by the caller, that identifies this call in future messages. This number cannam@147: # must be different from all other calls originating from the same end of the connection (but cannam@147: # may overlap with question IDs originating from the opposite end). A fine strategy is to use cannam@147: # sequential question IDs, but the recipient should not assume this. cannam@147: # cannam@147: # A question ID can be reused once both: cannam@147: # - A matching Return has been received from the callee. cannam@147: # - A matching Finish has been sent from the caller. cannam@147: cannam@147: target @1 :MessageTarget; cannam@147: # The object that should receive this call. cannam@147: cannam@147: interfaceId @2 :UInt64; cannam@147: # The type ID of the interface being called. Each capability may implement multiple interfaces. cannam@147: cannam@147: methodId @3 :UInt16; cannam@147: # The ordinal number of the method to call within the requested interface. cannam@147: cannam@147: allowThirdPartyTailCall @8 :Bool = false; cannam@147: # Indicates whether or not the receiver is allowed to send a `Return` containing cannam@147: # `acceptFromThirdParty`. Level 3 implementations should set this true. Otherwise, the callee cannam@147: # will have to proxy the return in the case of a tail call to a third-party vat. cannam@147: cannam@147: params @4 :Payload; cannam@147: # The call parameters. `params.content` is a struct whose fields correspond to the parameters of cannam@147: # the method. cannam@147: cannam@147: sendResultsTo :union { cannam@147: # Where should the return message be sent? cannam@147: cannam@147: caller @5 :Void; cannam@147: # Send the return message back to the caller (the usual). cannam@147: cannam@147: yourself @6 :Void; cannam@147: # **(level 1)** cannam@147: # cannam@147: # Don't actually return the results to the sender. Instead, hold on to them and await cannam@147: # instructions from the sender regarding what to do with them. In particular, the sender cannam@147: # may subsequently send a `Return` for some other call (which the receiver had previously made cannam@147: # to the sender) with `takeFromOtherQuestion` set. The results from this call are then used cannam@147: # as the results of the other call. cannam@147: # cannam@147: # When `yourself` is used, the receiver must still send a `Return` for the call, but sets the cannam@147: # field `resultsSentElsewhere` in that `Return` rather than including the results. cannam@147: # cannam@147: # This feature can be used to implement tail calls in which a call from Vat A to Vat B ends up cannam@147: # returning the result of a call from Vat B back to Vat A. cannam@147: # cannam@147: # In particular, the most common use case for this feature is when Vat A makes a call to a cannam@147: # promise in Vat B, and then that promise ends up resolving to a capability back in Vat A. cannam@147: # Vat B must forward all the queued calls on that promise back to Vat A, but can set `yourself` cannam@147: # in the calls so that the results need not pass back through Vat B. cannam@147: # cannam@147: # For example: cannam@147: # - Alice, in Vat A, call foo() on Bob in Vat B. cannam@147: # - Alice makes a pipelined call bar() on the promise returned by foo(). cannam@147: # - Later on, Bob resolves the promise from foo() to point at Carol, who lives in Vat A (next cannam@147: # to Alice). cannam@147: # - Vat B dutifully forwards the bar() call to Carol. Let us call this forwarded call bar'(). cannam@147: # Notice that bar() and bar'() are travelling in opposite directions on the same network cannam@147: # link. cannam@147: # - The `Call` for bar'() has `sendResultsTo` set to `yourself`, with the value being the cannam@147: # question ID originally assigned to the bar() call. cannam@147: # - Vat A receives bar'() and delivers it to Carol. cannam@147: # - When bar'() returns, Vat A immediately takes the results and returns them from bar(). cannam@147: # - Meanwhile, Vat A sends a `Return` for bar'() to Vat B, with `resultsSentElsewhere` set in cannam@147: # place of results. cannam@147: # - Vat A sends a `Finish` for that call to Vat B. cannam@147: # - Vat B receives the `Return` for bar'() and sends a `Return` for bar(), with cannam@147: # `receivedFromYourself` set in place of the results. cannam@147: # - Vat B receives the `Finish` for bar() and sends a `Finish` to bar'(). cannam@147: cannam@147: thirdParty @7 :RecipientId; cannam@147: # **(level 3)** cannam@147: # cannam@147: # The call's result should be returned to a different vat. The receiver (the callee) expects cannam@147: # to receive an `Accept` message from the indicated vat, and should return the call's result cannam@147: # to it, rather than to the sender of the `Call`. cannam@147: # cannam@147: # This operates much like `yourself`, above, except that Carol is in a separate Vat C. `Call` cannam@147: # messages are sent from Vat A -> Vat B and Vat B -> Vat C. A `Return` message is sent from cannam@147: # Vat B -> Vat A that contains `acceptFromThirdParty` in place of results. When Vat A sends cannam@147: # an `Accept` to Vat C, it receives back a `Return` containing the call's actual result. Vat C cannam@147: # also sends a `Return` to Vat B with `resultsSentElsewhere`. cannam@147: } cannam@147: } cannam@147: cannam@147: struct Return { cannam@147: # **(level 0)** cannam@147: # cannam@147: # Message type sent from callee to caller indicating that the call has completed. cannam@147: cannam@147: answerId @0 :AnswerId; cannam@147: # Equal to the QuestionId of the corresponding `Call` message. cannam@147: cannam@147: releaseParamCaps @1 :Bool = true; cannam@147: # If true, all capabilities that were in the params should be considered released. The sender cannam@147: # must not send separate `Release` messages for them. Level 0 implementations in particular cannam@147: # should always set this true. This defaults true because if level 0 implementations forget to cannam@147: # set it they'll never notice (just silently leak caps), but if level >=1 implementations forget cannam@147: # to set it to false they'll quickly get errors. cannam@147: cannam@147: union { cannam@147: results @2 :Payload; cannam@147: # The result. cannam@147: # cannam@147: # For regular method calls, `results.content` points to the result struct. cannam@147: # cannam@147: # For a `Return` in response to an `Accept`, `results` contains a single capability (rather cannam@147: # than a struct), and `results.content` is just a capability pointer with index 0. A `Finish` cannam@147: # is still required in this case. cannam@147: cannam@147: exception @3 :Exception; cannam@147: # Indicates that the call failed and explains why. cannam@147: cannam@147: canceled @4 :Void; cannam@147: # Indicates that the call was canceled due to the caller sending a Finish message cannam@147: # before the call had completed. cannam@147: cannam@147: resultsSentElsewhere @5 :Void; cannam@147: # This is set when returning from a `Call` that had `sendResultsTo` set to something other cannam@147: # than `caller`. cannam@147: cannam@147: takeFromOtherQuestion @6 :QuestionId; cannam@147: # The sender has also sent (before this message) a `Call` with the given question ID and with cannam@147: # `sendResultsTo.yourself` set, and the results of that other call should be used as the cannam@147: # results here. cannam@147: cannam@147: acceptFromThirdParty @7 :ThirdPartyCapId; cannam@147: # **(level 3)** cannam@147: # cannam@147: # The caller should contact a third-party vat to pick up the results. An `Accept` message cannam@147: # sent to the vat will return the result. This pairs with `Call.sendResultsTo.thirdParty`. cannam@147: # It should only be used if the corresponding `Call` had `allowThirdPartyTailCall` set. cannam@147: } cannam@147: } cannam@147: cannam@147: struct Finish { cannam@147: # **(level 0)** cannam@147: # cannam@147: # Message type sent from the caller to the callee to indicate: cannam@147: # 1) The questionId will no longer be used in any messages sent by the callee (no further cannam@147: # pipelined requests). cannam@147: # 2) If the call has not returned yet, the caller no longer cares about the result. If nothing cannam@147: # else cares about the result either (e.g. there are no other outstanding calls pipelined on cannam@147: # the result of this one) then the callee may wish to immediately cancel the operation and cannam@147: # send back a Return message with "canceled" set. However, implementations are not required cannam@147: # to support premature cancellation -- instead, the implementation may wait until the call cannam@147: # actually completes and send a normal `Return` message. cannam@147: # cannam@147: # TODO(someday): Should we separate (1) and implicitly releasing result capabilities? It would be cannam@147: # possible and useful to notify the server that it doesn't need to keep around the response to cannam@147: # service pipeline requests even though the caller still wants to receive it / hasn't yet cannam@147: # finished processing it. It could also be useful to notify the server that it need not marshal cannam@147: # the results because the caller doesn't want them anyway, even if the caller is still sending cannam@147: # pipelined calls, although this seems less useful (just saving some bytes on the wire). cannam@147: cannam@147: questionId @0 :QuestionId; cannam@147: # ID of the call whose result is to be released. cannam@147: cannam@147: releaseResultCaps @1 :Bool = true; cannam@147: # If true, all capabilities that were in the results should be considered released. The sender cannam@147: # must not send separate `Release` messages for them. Level 0 implementations in particular cannam@147: # should always set this true. This defaults true because if level 0 implementations forget to cannam@147: # set it they'll never notice (just silently leak caps), but if level >=1 implementations forget cannam@147: # set it false they'll quickly get errors. cannam@147: } cannam@147: cannam@147: # Level 1 message types ---------------------------------------------- cannam@147: cannam@147: struct Resolve { cannam@147: # **(level 1)** cannam@147: # cannam@147: # Message type sent to indicate that a previously-sent promise has now been resolved to some other cannam@147: # object (possibly another promise) -- or broken, or canceled. cannam@147: # cannam@147: # Keep in mind that it's possible for a `Resolve` to be sent to a level 0 implementation that cannam@147: # doesn't implement it. For example, a method call or return might contain a capability in the cannam@147: # payload. Normally this is fine even if the receiver is level 0, because they will implicitly cannam@147: # release all such capabilities on return / finish. But if the cap happens to be a promise, then cannam@147: # a follow-up `Resolve` may be sent regardless of this release. The level 0 receiver will reply cannam@147: # with an `unimplemented` message, and the sender (of the `Resolve`) can respond to this as if the cannam@147: # receiver had immediately released any capability to which the promise resolved. cannam@147: # cannam@147: # When implementing promise resolution, it's important to understand how embargos work and the cannam@147: # tricky case of the Tribble 4-way race condition. See the comments for the Disembargo message, cannam@147: # below. cannam@147: cannam@147: promiseId @0 :ExportId; cannam@147: # The ID of the promise to be resolved. cannam@147: # cannam@147: # Unlike all other instances of `ExportId` sent from the exporter, the `Resolve` message does cannam@147: # _not_ increase the reference count of `promiseId`. In fact, it is expected that the receiver cannam@147: # will release the export soon after receiving `Resolve`, and the sender will not send this cannam@147: # `ExportId` again until it has been released and recycled. cannam@147: # cannam@147: # When an export ID sent over the wire (e.g. in a `CapDescriptor`) is indicated to be a promise, cannam@147: # this indicates that the sender will follow up at some point with a `Resolve` message. If the cannam@147: # same `promiseId` is sent again before `Resolve`, still only one `Resolve` is sent. If the cannam@147: # same ID is sent again later _after_ a `Resolve`, it can only be because the export's cannam@147: # reference count hit zero in the meantime and the ID was re-assigned to a new export, therefore cannam@147: # this later promise does _not_ correspond to the earlier `Resolve`. cannam@147: # cannam@147: # If a promise ID's reference count reaches zero before a `Resolve` is sent, the `Resolve` cannam@147: # message may or may not still be sent (the `Resolve` may have already been in-flight when cannam@147: # `Release` was sent, but if the `Release` is received before `Resolve` then there is no longer cannam@147: # any reason to send a `Resolve`). Thus a `Resolve` may be received for a promise of which cannam@147: # the receiver has no knowledge, because it already released it earlier. In this case, the cannam@147: # receiver should simply release the capability to which the promise resolved. cannam@147: cannam@147: union { cannam@147: cap @1 :CapDescriptor; cannam@147: # The object to which the promise resolved. cannam@147: # cannam@147: # The sender promises that from this point forth, until `promiseId` is released, it shall cannam@147: # simply forward all messages to the capability designated by `cap`. This is true even if cannam@147: # `cap` itself happens to desigate another promise, and that other promise later resolves -- cannam@147: # messages sent to `promiseId` shall still go to that other promise, not to its resolution. cannam@147: # This is important in the case that the receiver of the `Resolve` ends up sending a cannam@147: # `Disembargo` message towards `promiseId` in order to control message ordering -- that cannam@147: # `Disembargo` really needs to reflect back to exactly the object designated by `cap` even cannam@147: # if that object is itself a promise. cannam@147: cannam@147: exception @2 :Exception; cannam@147: # Indicates that the promise was broken. cannam@147: } cannam@147: } cannam@147: cannam@147: struct Release { cannam@147: # **(level 1)** cannam@147: # cannam@147: # Message type sent to indicate that the sender is done with the given capability and the receiver cannam@147: # can free resources allocated to it. cannam@147: cannam@147: id @0 :ImportId; cannam@147: # What to release. cannam@147: cannam@147: referenceCount @1 :UInt32; cannam@147: # The amount by which to decrement the reference count. The export is only actually released cannam@147: # when the reference count reaches zero. cannam@147: } cannam@147: cannam@147: struct Disembargo { cannam@147: # **(level 1)** cannam@147: # cannam@147: # Message sent to indicate that an embargo on a recently-resolved promise may now be lifted. cannam@147: # cannam@147: # Embargos are used to enforce E-order in the presence of promise resolution. That is, if an cannam@147: # application makes two calls foo() and bar() on the same capability reference, in that order, cannam@147: # the calls should be delivered in the order in which they were made. But if foo() is called cannam@147: # on a promise, and that promise happens to resolve before bar() is called, then the two calls cannam@147: # may travel different paths over the network, and thus could arrive in the wrong order. In cannam@147: # this case, the call to `bar()` must be embargoed, and a `Disembargo` message must be sent along cannam@147: # the same path as `foo()` to ensure that the `Disembargo` arrives after `foo()`. Once the cannam@147: # `Disembargo` arrives, `bar()` can then be delivered. cannam@147: # cannam@147: # There are two particular cases where embargos are important. Consider object Alice, in Vat A, cannam@147: # who holds a promise P, pointing towards Vat B, that eventually resolves to Carol. The two cannam@147: # cases are: cannam@147: # - Carol lives in Vat A, i.e. next to Alice. In this case, Vat A needs to send a `Disembargo` cannam@147: # message that echos through Vat B and back, to ensure that all pipelined calls on the promise cannam@147: # have been delivered. cannam@147: # - Carol lives in a different Vat C. When the promise resolves, a three-party handoff occurs cannam@147: # (see `Provide` and `Accept`, which constitute level 3 of the protocol). In this case, we cannam@147: # piggyback on the state that has already been set up to handle the handoff: the `Accept` cannam@147: # message (from Vat A to Vat C) is embargoed, as are all pipelined messages sent to it, while cannam@147: # a `Disembargo` message is sent from Vat A through Vat B to Vat C. See `Accept.embargo` for cannam@147: # an example. cannam@147: # cannam@147: # Note that in the case where Carol actually lives in Vat B (i.e., the same vat that the promise cannam@147: # already pointed at), no embargo is needed, because the pipelined calls are delivered over the cannam@147: # same path as the later direct calls. cannam@147: # cannam@147: # Keep in mind that promise resolution happens both in the form of Resolve messages as well as cannam@147: # Return messages (which resolve PromisedAnswers). Embargos apply in both cases. cannam@147: # cannam@147: # An alternative strategy for enforcing E-order over promise resolution could be for Vat A to cannam@147: # implement the embargo internally. When Vat A is notified of promise resolution, it could cannam@147: # send a dummy no-op call to promise P and wait for it to complete. Until that call completes, cannam@147: # all calls to the capability are queued locally. This strategy works, but is pessimistic: cannam@147: # in the three-party case, it requires an A -> B -> C -> B -> A round trip before calls can start cannam@147: # being delivered directly to from Vat A to Vat C. The `Disembargo` message allows latency to be cannam@147: # reduced. (In the two-party loopback case, the `Disembargo` message is just a more explicit way cannam@147: # of accomplishing the same thing as a no-op call, but isn't any faster.) cannam@147: # cannam@147: # *The Tribble 4-way Race Condition* cannam@147: # cannam@147: # Any implementation of promise resolution and embargos must be aware of what we call the cannam@147: # "Tribble 4-way race condition", after Dean Tribble, who explained the problem in a lively cannam@147: # Friam meeting. cannam@147: # cannam@147: # Embargos are designed to work in the case where a two-hop path is being shortened to one hop. cannam@147: # But sometimes there are more hops. Imagine that Alice has a reference to a remote promise P1 cannam@147: # that eventually resolves to _another_ remote promise P2 (in a third vat), which _at the same cannam@147: # time_ happens to resolve to Bob (in a fourth vat). In this case, we're shortening from a 3-hop cannam@147: # path (with four parties) to a 1-hop path (Alice -> Bob). cannam@147: # cannam@147: # Extending the embargo/disembargo protocol to be able to shorted multiple hops at once seems cannam@147: # difficult. Instead, we make a rule that prevents this case from coming up: cannam@147: # cannam@147: # One a promise P has been resolved to a remove object reference R, then all further messages cannam@147: # received addressed to P will be forwarded strictly to R. Even if it turns out later that R is cannam@147: # itself a promise, and has resolved to some other object Q, messages sent to P will still be cannam@147: # forwarded to R, not directly to Q (R will of course further forward the messages to Q). cannam@147: # cannam@147: # This rule does not cause a significant performance burden because once P has resolved to R, it cannam@147: # is expected that people sending messages to P will shortly start sending them to R instead and cannam@147: # drop P. P is at end-of-life anyway, so it doesn't matter if it ignores chances to further cannam@147: # optimize its path. cannam@147: cannam@147: target @0 :MessageTarget; cannam@147: # What is to be disembargoed. cannam@147: cannam@147: using EmbargoId = UInt32; cannam@147: # Used in `senderLoopback` and `receiverLoopback`, below. cannam@147: cannam@147: context :union { cannam@147: senderLoopback @1 :EmbargoId; cannam@147: # The sender is requesting a disembargo on a promise that is known to resolve back to a cannam@147: # capability hosted by the sender. As soon as the receiver has echoed back all pipelined calls cannam@147: # on this promise, it will deliver the Disembargo back to the sender with `receiverLoopback` cannam@147: # set to the same value as `senderLoopback`. This value is chosen by the sender, and since cannam@147: # it is also consumed be the sender, the sender can use whatever strategy it wants to make sure cannam@147: # the value is unambiguous. cannam@147: # cannam@147: # The receiver must verify that the target capability actually resolves back to the sender's cannam@147: # vat. Otherwise, the sender has committed a protocol error and should be disconnected. cannam@147: cannam@147: receiverLoopback @2 :EmbargoId; cannam@147: # The receiver previously sent a `senderLoopback` Disembargo towards a promise resolving to cannam@147: # this capability, and that Disembargo is now being echoed back. cannam@147: cannam@147: accept @3 :Void; cannam@147: # **(level 3)** cannam@147: # cannam@147: # The sender is requesting a disembargo on a promise that is known to resolve to a third-party cannam@147: # capability that the sender is currently in the process of accepting (using `Accept`). cannam@147: # The receiver of this `Disembargo` has an outstanding `Provide` on said capability. The cannam@147: # receiver should now send a `Disembargo` with `provide` set to the question ID of that cannam@147: # `Provide` message. cannam@147: # cannam@147: # See `Accept.embargo` for an example. cannam@147: cannam@147: provide @4 :QuestionId; cannam@147: # **(level 3)** cannam@147: # cannam@147: # The sender is requesting a disembargo on a capability currently being provided to a third cannam@147: # party. The question ID identifies the `Provide` message previously sent by the sender to cannam@147: # this capability. On receipt, the receiver (the capability host) shall release the embargo cannam@147: # on the `Accept` message that it has received from the third party. See `Accept.embargo` for cannam@147: # an example. cannam@147: } cannam@147: } cannam@147: cannam@147: # Level 2 message types ---------------------------------------------- cannam@147: cannam@147: # See persistent.capnp. cannam@147: cannam@147: # Level 3 message types ---------------------------------------------- cannam@147: cannam@147: struct Provide { cannam@147: # **(level 3)** cannam@147: # cannam@147: # Message type sent to indicate that the sender wishes to make a particular capability implemented cannam@147: # by the receiver available to a third party for direct access (without the need for the third cannam@147: # party to proxy through the sender). cannam@147: # cannam@147: # (In CapTP, `Provide` and `Accept` are methods of the global `NonceLocator` object exported by cannam@147: # every vat. In Cap'n Proto, we bake this into the core protocol.) cannam@147: cannam@147: questionId @0 :QuestionId; cannam@147: # Question ID to be held open until the recipient has received the capability. A result will be cannam@147: # returned once the third party has successfully received the capability. The sender must at some cannam@147: # point send a `Finish` message as with any other call, and that message can be used to cancel the cannam@147: # whole operation. cannam@147: cannam@147: target @1 :MessageTarget; cannam@147: # What is to be provided to the third party. cannam@147: cannam@147: recipient @2 :RecipientId; cannam@147: # Identity of the third party that is expected to pick up the capability. cannam@147: } cannam@147: cannam@147: struct Accept { cannam@147: # **(level 3)** cannam@147: # cannam@147: # Message type sent to pick up a capability hosted by the receiving vat and provided by a third cannam@147: # party. The third party previously designated the capability using `Provide`. cannam@147: # cannam@147: # This message is also used to pick up a redirected return -- see `Return.redirect`. cannam@147: cannam@147: questionId @0 :QuestionId; cannam@147: # A new question ID identifying this accept message, which will eventually receive a Return cannam@147: # message containing the provided capability (or the call result in the case of a redirected cannam@147: # return). cannam@147: cannam@147: provision @1 :ProvisionId; cannam@147: # Identifies the provided object to be picked up. cannam@147: cannam@147: embargo @2 :Bool; cannam@147: # If true, this accept shall be temporarily embargoed. The resulting `Return` will not be sent, cannam@147: # and any pipelined calls will not be delivered, until the embargo is released. The receiver cannam@147: # (the capability host) will expect the provider (the vat that sent the `Provide` message) to cannam@147: # eventually send a `Disembargo` message with the field `context.provide` set to the question ID cannam@147: # of the original `Provide` message. At that point, the embargo is released and the queued cannam@147: # messages are delivered. cannam@147: # cannam@147: # For example: cannam@147: # - Alice, in Vat A, holds a promise P, which currently points toward Vat B. cannam@147: # - Alice calls foo() on P. The `Call` message is sent to Vat B. cannam@147: # - The promise P in Vat B ends up resolving to Carol, in Vat C. cannam@147: # - Vat B sends a `Provide` message to Vat C, identifying Vat A as the recipient. cannam@147: # - Vat B sends a `Resolve` message to Vat A, indicating that the promise has resolved to a cannam@147: # `ThirdPartyCapId` identifying Carol in Vat C. cannam@147: # - Vat A sends an `Accept` message to Vat C to pick up the capability. Since Vat A knows that cannam@147: # it has an outstanding call to the promise, it sets `embargo` to `true` in the `Accept` cannam@147: # message. cannam@147: # - Vat A sends a `Disembargo` message to Vat B on promise P, with `context.accept` set. cannam@147: # - Alice makes a call bar() to promise P, which is now pointing towards Vat C. Alice doesn't cannam@147: # know anything about the mechanics of promise resolution happening under the hood, but she cannam@147: # expects that bar() will be delivered after foo() because that is the order in which she cannam@147: # initiated the calls. cannam@147: # - Vat A sends the bar() call to Vat C, as a pipelined call on the result of the `Accept` (which cannam@147: # hasn't returned yet, due to the embargo). Since calls to the newly-accepted capability cannam@147: # are embargoed, Vat C does not deliver the call yet. cannam@147: # - At some point, Vat B forwards the foo() call from the beginning of this example on to Vat C. cannam@147: # - Vat B forwards the `Disembargo` from Vat A on to vat C. It sets `context.provide` to the cannam@147: # question ID of the `Provide` message it had sent previously. cannam@147: # - Vat C receives foo() before `Disembargo`, thus allowing it to correctly deliver foo() cannam@147: # before delivering bar(). cannam@147: # - Vat C receives `Disembargo` from Vat B. It can now send a `Return` for the `Accept` from cannam@147: # Vat A, as well as deliver bar(). cannam@147: } cannam@147: cannam@147: # Level 4 message types ---------------------------------------------- cannam@147: cannam@147: struct Join { cannam@147: # **(level 4)** cannam@147: # cannam@147: # Message type sent to implement E.join(), which, given a number of capabilities that are cannam@147: # expected to be equivalent, finds the underlying object upon which they all agree and forms a cannam@147: # direct connection to it, skipping any proxies that may have been constructed by other vats cannam@147: # while transmitting the capability. See: cannam@147: # http://erights.org/elib/equality/index.html cannam@147: # cannam@147: # Note that this should only serve to bypass fully-transparent proxies -- proxies that were cannam@147: # created merely for convenience, without any intention of hiding the underlying object. cannam@147: # cannam@147: # For example, say Bob holds two capabilities hosted by Alice and Carol, but he expects that both cannam@147: # are simply proxies for a capability hosted elsewhere. He then issues a join request, which cannam@147: # operates as follows: cannam@147: # - Bob issues Join requests on both Alice and Carol. Each request contains a different piece cannam@147: # of the JoinKey. cannam@147: # - Alice is proxying a capability hosted by Dana, so forwards the request to Dana's cap. cannam@147: # - Dana receives the first request and sees that the JoinKeyPart is one of two. She notes that cannam@147: # she doesn't have the other part yet, so she records the request and responds with a cannam@147: # JoinResult. cannam@147: # - Alice relays the JoinAswer back to Bob. cannam@147: # - Carol is also proxying a capability from Dana, and so forwards her Join request to Dana as cannam@147: # well. cannam@147: # - Dana receives Carol's request and notes that she now has both parts of a JoinKey. She cannam@147: # combines them in order to form information needed to form a secure connection to Bob. She cannam@147: # also responds with another JoinResult. cannam@147: # - Bob receives the responses from Alice and Carol. He uses the returned JoinResults to cannam@147: # determine how to connect to Dana and attempts to form the connection. Since Bob and Dana now cannam@147: # agree on a secret key that neither Alice nor Carol ever saw, this connection can be made cannam@147: # securely even if Alice or Carol is conspiring against the other. (If Alice and Carol are cannam@147: # conspiring _together_, they can obviously reproduce the key, but this doesn't matter because cannam@147: # the whole point of the join is to verify that Alice and Carol agree on what capability they cannam@147: # are proxying.) cannam@147: # cannam@147: # If the two capabilities aren't actually proxies of the same object, then the join requests cannam@147: # will come back with conflicting `hostId`s and the join will fail before attempting to form any cannam@147: # connection. cannam@147: cannam@147: questionId @0 :QuestionId; cannam@147: # Question ID used to respond to this Join. (Note that this ID only identifies one part of the cannam@147: # request for one hop; each part has a different ID and relayed copies of the request have cannam@147: # (probably) different IDs still.) cannam@147: # cannam@147: # The receiver will reply with a `Return` whose `results` is a JoinResult. This `JoinResult` cannam@147: # is relayed from the joined object's host, possibly with transformation applied as needed cannam@147: # by the network. cannam@147: # cannam@147: # Like any return, the result must be released using a `Finish`. However, this release cannam@147: # should not occur until the joiner has either successfully connected to the joined object. cannam@147: # Vats relaying a `Join` message similarly must not release the result they receive until the cannam@147: # return they relayed back towards the joiner has itself been released. This allows the cannam@147: # joined object's host to detect when the Join operation is canceled before completing -- if cannam@147: # it receives a `Finish` for one of the join results before the joiner successfully cannam@147: # connects. It can then free any resources it had allocated as part of the join. cannam@147: cannam@147: target @1 :MessageTarget; cannam@147: # The capability to join. cannam@147: cannam@147: keyPart @2 :JoinKeyPart; cannam@147: # A part of the join key. These combine to form the complete join key, which is used to establish cannam@147: # a direct connection. cannam@147: cannam@147: # TODO(before implementing): Change this so that multiple parts can be sent in a single Join cannam@147: # message, so that if multiple join parts are going to cross the same connection they can be sent cannam@147: # together, so that the receive can potentially optimize its handling of them. In the case where cannam@147: # all parts are bundled together, should the recipient be expected to simply return a cap, so cannam@147: # that the caller can immediately start pipelining to it? cannam@147: } cannam@147: cannam@147: # ======================================================================================== cannam@147: # Common structures used in messages cannam@147: cannam@147: struct MessageTarget { cannam@147: # The target of a `Call` or other messages that target a capability. cannam@147: cannam@147: union { cannam@147: importedCap @0 :ImportId; cannam@147: # This message is to a capability or promise previously imported by the caller (exported by cannam@147: # the receiver). cannam@147: cannam@147: promisedAnswer @1 :PromisedAnswer; cannam@147: # This message is to a capability that is expected to be returned by another call that has not cannam@147: # yet been completed. cannam@147: # cannam@147: # At level 0, this is supported only for addressing the result of a previous `Bootstrap`, so cannam@147: # that initial startup doesn't require a round trip. cannam@147: } cannam@147: } cannam@147: cannam@147: struct Payload { cannam@147: # Represents some data structure that might contain capabilities. cannam@147: cannam@147: content @0 :AnyPointer; cannam@147: # Some Cap'n Proto data structure. Capability pointers embedded in this structure index into cannam@147: # `capTable`. cannam@147: cannam@147: capTable @1 :List(CapDescriptor); cannam@147: # Descriptors corresponding to the cap pointers in `content`. cannam@147: } cannam@147: cannam@147: struct CapDescriptor { cannam@147: # **(level 1)** cannam@147: # cannam@147: # When an application-defined type contains an interface pointer, that pointer contains an index cannam@147: # into the message's capability table -- i.e. the `capTable` part of the `Payload`. Each cannam@147: # capability in the table is represented as a `CapDescriptor`. The runtime API should not reveal cannam@147: # the CapDescriptor directly to the application, but should instead wrap it in some kind of cannam@147: # callable object with methods corresponding to the interface that the capability implements. cannam@147: # cannam@147: # Keep in mind that `ExportIds` in a `CapDescriptor` are subject to reference counting. See the cannam@147: # description of `ExportId`. cannam@147: cannam@147: union { cannam@147: none @0 :Void; cannam@147: # There is no capability here. This `CapDescriptor` should not appear in the payload content. cannam@147: # A `none` CapDescriptor can be generated when an application inserts a capability into a cannam@147: # message and then later changes its mind and removes it -- rewriting all of the other cannam@147: # capability pointers may be hard, so instead a tombstone is left, similar to the way a removed cannam@147: # struct or list instance is zeroed out of the message but the space is not reclaimed. cannam@147: # Hopefully this is unusual. cannam@147: cannam@147: senderHosted @1 :ExportId; cannam@147: # A capability newly exported by the sender. This is the ID of the new capability in the cannam@147: # sender's export table (receiver's import table). cannam@147: cannam@147: senderPromise @2 :ExportId; cannam@147: # A promise that the sender will resolve later. The sender will send exactly one Resolve cannam@147: # message at a future point in time to replace this promise. Note that even if the same cannam@147: # `senderPromise` is received multiple times, only one `Resolve` is sent to cover all of cannam@147: # them. If `senderPromise` is released before the `Resolve` is sent, the sender (of this cannam@147: # `CapDescriptor`) may choose not to send the `Resolve` at all. cannam@147: cannam@147: receiverHosted @3 :ImportId; cannam@147: # A capability (or promise) previously exported by the receiver (imported by the sender). cannam@147: cannam@147: receiverAnswer @4 :PromisedAnswer; cannam@147: # A capability expected to be returned in the results of a currently-outstanding call posed cannam@147: # by the sender. cannam@147: cannam@147: thirdPartyHosted @5 :ThirdPartyCapDescriptor; cannam@147: # **(level 3)** cannam@147: # cannam@147: # A capability that lives in neither the sender's nor the receiver's vat. The sender needs cannam@147: # to form a direct connection to a third party to pick up the capability. cannam@147: # cannam@147: # Level 1 and 2 implementations that receive a `thirdPartyHosted` may simply send calls to its cannam@147: # `vine` instead. cannam@147: } cannam@147: } cannam@147: cannam@147: struct PromisedAnswer { cannam@147: # **(mostly level 1)** cannam@147: # cannam@147: # Specifies how to derive a promise from an unanswered question, by specifying the path of fields cannam@147: # to follow from the root of the eventual result struct to get to the desired capability. Used cannam@147: # to address method calls to a not-yet-returned capability or to pass such a capability as an cannam@147: # input to some other method call. cannam@147: # cannam@147: # Level 0 implementations must support `PromisedAnswer` only for the case where the answer is cannam@147: # to a `Bootstrap` message. In this case, `path` is always empty since `Bootstrap` always returns cannam@147: # a raw capability. cannam@147: cannam@147: questionId @0 :QuestionId; cannam@147: # ID of the question (in the sender's question table / receiver's answer table) whose answer is cannam@147: # expected to contain the capability. cannam@147: cannam@147: transform @1 :List(Op); cannam@147: # Operations / transformations to apply to the result in order to get the capability actually cannam@147: # being addressed. E.g. if the result is a struct and you want to call a method on a capability cannam@147: # pointed to by a field of the struct, you need a `getPointerField` op. cannam@147: cannam@147: struct Op { cannam@147: union { cannam@147: noop @0 :Void; cannam@147: # Does nothing. This member is mostly defined so that we can make `Op` a union even cannam@147: # though (as of this writing) only one real operation is defined. cannam@147: cannam@147: getPointerField @1 :UInt16; cannam@147: # Get a pointer field within a struct. The number is an index into the pointer section, NOT cannam@147: # a field ordinal, so that the receiver does not need to understand the schema. cannam@147: cannam@147: # TODO(someday): We could add: cannam@147: # - For lists, the ability to address every member of the list, or a slice of the list, the cannam@147: # result of which would be another list. This is useful for implementing the equivalent of cannam@147: # a SQL table join (not to be confused with the `Join` message type). cannam@147: # - Maybe some ability to test a union. cannam@147: # - Probably not a good idea: the ability to specify an arbitrary script to run on the cannam@147: # result. We could define a little stack-based language where `Op` specifies one cannam@147: # "instruction" or transformation to apply. Although this is not a good idea cannam@147: # (over-engineered), any narrower additions to `Op` should be designed as if this cannam@147: # were the eventual goal. cannam@147: } cannam@147: } cannam@147: } cannam@147: cannam@147: struct ThirdPartyCapDescriptor { cannam@147: # **(level 3)** cannam@147: # cannam@147: # Identifies a capability in a third-party vat that the sender wants the receiver to pick up. cannam@147: cannam@147: id @0 :ThirdPartyCapId; cannam@147: # Identifies the third-party host and the specific capability to accept from it. cannam@147: cannam@147: vineId @1 :ExportId; cannam@147: # A proxy for the third-party object exported by the sender. In CapTP terminology this is called cannam@147: # a "vine", because it is an indirect reference to the third-party object that snakes through the cannam@147: # sender vat. This serves two purposes: cannam@147: # cannam@147: # * Level 1 and 2 implementations that don't understand how to connect to a third party may cannam@147: # simply send calls to the vine. Such calls will be forwarded to the third-party by the cannam@147: # sender. cannam@147: # cannam@147: # * Level 3 implementations must release the vine once they have successfully picked up the cannam@147: # object from the third party. This ensures that the capability is not released by the sender cannam@147: # prematurely. cannam@147: # cannam@147: # The sender will close the `Provide` request that it has sent to the third party as soon as cannam@147: # it receives either a `Call` or a `Release` message directed at the vine. cannam@147: } cannam@147: cannam@147: struct Exception { cannam@147: # **(level 0)** cannam@147: # cannam@147: # Describes an arbitrary error that prevented an operation (e.g. a call) from completing. cannam@147: # cannam@147: # Cap'n Proto exceptions always indicate that something went wrong. In other words, in a fantasy cannam@147: # world where everything always works as expected, no exceptions would ever be thrown. Clients cannam@147: # should only ever catch exceptions as a means to implement fault-tolerance, where "fault" can cannam@147: # mean: cannam@147: # - Bugs. cannam@147: # - Invalid input. cannam@147: # - Configuration errors. cannam@147: # - Network problems. cannam@147: # - Insufficient resources. cannam@147: # - Version skew (unimplemented functionality). cannam@147: # - Other logistical problems. cannam@147: # cannam@147: # Exceptions should NOT be used to flag application-specific conditions that a client is expected cannam@147: # to handle in an application-specific way. Put another way, in the Cap'n Proto world, cannam@147: # "checked exceptions" (where an interface explicitly defines the exceptions it throws and cannam@147: # clients are forced by the type system to handle those exceptions) do NOT make sense. cannam@147: cannam@147: reason @0 :Text; cannam@147: # Human-readable failure description. cannam@147: cannam@147: type @3 :Type; cannam@147: # The type of the error. The purpose of this enum is not to describe the error itself, but cannam@147: # rather to describe how the client might want to respond to the error. cannam@147: cannam@147: enum Type { cannam@147: failed @0; cannam@147: # A generic problem occurred, and it is believed that if the operation were repeated without cannam@147: # any change in the state of the world, the problem would occur again. cannam@147: # cannam@147: # A client might respond to this error by logging it for investigation by the developer and/or cannam@147: # displaying it to the user. cannam@147: cannam@147: overloaded @1; cannam@147: # The request was rejected due to a temporary lack of resources. cannam@147: # cannam@147: # Examples include: cannam@147: # - There's not enough CPU time to keep up with incoming requests, so some are rejected. cannam@147: # - The server ran out of RAM or disk space during the request. cannam@147: # - The operation timed out (took significantly longer than it should have). cannam@147: # cannam@147: # A client might respond to this error by scheduling to retry the operation much later. The cannam@147: # client should NOT retry again immediately since this would likely exacerbate the problem. cannam@147: cannam@147: disconnected @2; cannam@147: # The method failed because a connection to some necessary capability was lost. cannam@147: # cannam@147: # Examples include: cannam@147: # - The client introduced the server to a third-party capability, the connection to that third cannam@147: # party was subsequently lost, and then the client requested that the server use the dead cannam@147: # capability for something. cannam@147: # - The client previously requested that the server obtain a capability from some third party. cannam@147: # The server returned a capability to an object wrapping the third-party capability. Later, cannam@147: # the server's connection to the third party was lost. cannam@147: # - The capability has been revoked. Revocation does not necessarily mean that the client is cannam@147: # no longer authorized to use the capability; it is often used simply as a way to force the cannam@147: # client to repeat the setup process, perhaps to efficiently move them to a new back-end or cannam@147: # get them to recognize some other change that has occurred. cannam@147: # cannam@147: # A client should normally respond to this error by releasing all capabilities it is currently cannam@147: # holding related to the one it called and then re-creating them by restoring SturdyRefs and/or cannam@147: # repeating the method calls used to create them originally. In other words, disconnect and cannam@147: # start over. This should in turn cause the server to obtain a new copy of the capability that cannam@147: # it lost, thus making everything work. cannam@147: # cannam@147: # If the client receives another `disconnencted` error in the process of rebuilding the cannam@147: # capability and retrying the call, it should treat this as an `overloaded` error: the network cannam@147: # is currently unreliable, possibly due to load or other temporary issues. cannam@147: cannam@147: unimplemented @3; cannam@147: # The server doesn't implement the requested method. If there is some other method that the cannam@147: # client could call (perhaps an older and/or slower interface), it should try that instead. cannam@147: # Otherwise, this should be treated like `failed`. cannam@147: } cannam@147: cannam@147: obsoleteIsCallersFault @1 :Bool; cannam@147: # OBSOLETE. Ignore. cannam@147: cannam@147: obsoleteDurability @2 :UInt16; cannam@147: # OBSOLETE. See `type` instead. cannam@147: } cannam@147: cannam@147: # ======================================================================================== cannam@147: # Network-specific Parameters cannam@147: # cannam@147: # Some parts of the Cap'n Proto RPC protocol are not specified here because different vat networks cannam@147: # may wish to use different approaches to solving them. For example, on the public internet, you cannam@147: # may want to authenticate vats using public-key cryptography, but on a local intranet with trusted cannam@147: # infrastructure, you may be happy to authenticate based on network address only, or some other cannam@147: # lightweight mechanism. cannam@147: # cannam@147: # To accommodate this, we specify several "parameter" types. Each type is defined here as an cannam@147: # alias for `AnyPointer`, but a specific network will want to define a specific set of types to use. cannam@147: # All vats in a vat network must agree on these parameters in order to be able to communicate. cannam@147: # Inter-network communication can be accomplished through "gateways" that perform translation cannam@147: # between the primitives used on each network; these gateways may need to be deeply stateful, cannam@147: # depending on the translations they perform. cannam@147: # cannam@147: # For interaction over the global internet between parties with no other prior arrangement, a cannam@147: # particular set of bindings for these types is defined elsewhere. (TODO(someday): Specify where cannam@147: # these common definitions live.) cannam@147: # cannam@147: # Another common network type is the two-party network, in which one of the parties typically cannam@147: # interacts with the outside world entirely through the other party. In such a connection between cannam@147: # Alice and Bob, all objects that exist on Bob's other networks appear to Alice as if they were cannam@147: # hosted by Bob himself, and similarly all objects on Alice's network (if she even has one) appear cannam@147: # to Bob as if they were hosted by Alice. This network type is interesting because from the point cannam@147: # of view of a simple application that communicates with only one other party via the two-party cannam@147: # protocol, there are no three-party interactions at all, and joins are unusually simple to cannam@147: # implement, so implementing at level 4 is barely more complicated than implementing at level 1. cannam@147: # Moreover, if you pair an app implementing the two-party network with a container that implements cannam@147: # some other network, the app can then participate on the container's network just as if it cannam@147: # implemented that network directly. The types used by the two-party network are defined in cannam@147: # `rpc-twoparty.capnp`. cannam@147: # cannam@147: # The things that we need to parameterize are: cannam@147: # - How to store capabilities long-term without holding a connection open (mostly level 2). cannam@147: # - How to authenticate vats in three-party introductions (level 3). cannam@147: # - How to implement `Join` (level 4). cannam@147: # cannam@147: # Persistent references cannam@147: # --------------------- cannam@147: # cannam@147: # **(mostly level 2)** cannam@147: # cannam@147: # We want to allow some capabilities to be stored long-term, even if a connection is lost and later cannam@147: # recreated. ExportId is a short-term identifier that is specific to a connection, so it doesn't cannam@147: # help here. We need a way to specify long-term identifiers, as well as a strategy for cannam@147: # reconnecting to a referenced capability later. cannam@147: # cannam@147: # Three-party interactions cannam@147: # ------------------------ cannam@147: # cannam@147: # **(level 3)** cannam@147: # cannam@147: # In cases where more than two vats are interacting, we have situations where VatA holds a cannam@147: # capability hosted by VatB and wants to send that capability to VatC. This can be accomplished cannam@147: # by VatA proxying requests on the new capability, but doing so has two big problems: cannam@147: # - It's inefficient, requiring an extra network hop. cannam@147: # - If VatC receives another capability to the same object from VatD, it is difficult for VatC to cannam@147: # detect that the two capabilities are really the same and to implement the E "join" operation, cannam@147: # which is necessary for certain four-or-more-party interactions, such as the escrow pattern. cannam@147: # See: http://www.erights.org/elib/equality/grant-matcher/index.html cannam@147: # cannam@147: # Instead, we want a way for VatC to form a direct, authenticated connection to VatB. cannam@147: # cannam@147: # Join cannam@147: # ---- cannam@147: # cannam@147: # **(level 4)** cannam@147: # cannam@147: # The `Join` message type and corresponding operation arranges for a direct connection to be formed cannam@147: # between the joiner and the host of the joined object, and this connection must be authenticated. cannam@147: # Thus, the details are network-dependent. cannam@147: cannam@147: using SturdyRef = AnyPointer; cannam@147: # **(level 2)** cannam@147: # cannam@147: # Identifies a persisted capability that can be restored in the future. How exactly a SturdyRef cannam@147: # is restored to a live object is specified along with the SturdyRef definition (i.e. not by cannam@147: # rpc.capnp). cannam@147: # cannam@147: # Generally a SturdyRef needs to specify three things: cannam@147: # - How to reach the vat that can restore the ref (e.g. a hostname or IP address). cannam@147: # - How to authenticate the vat after connecting (e.g. a public key fingerprint). cannam@147: # - The identity of a specific object hosted by the vat. Generally, this is an opaque pointer whose cannam@147: # format is defined by the specific vat -- the client has no need to inspect the object ID. cannam@147: # It is important that the objec ID be unguessable if the object is not public (and objects cannam@147: # should almost never be public). cannam@147: # cannam@147: # The above are only suggestions. Some networks might work differently. For example, a private cannam@147: # network might employ a special restorer service whose sole purpose is to restore SturdyRefs. cannam@147: # In this case, the entire contents of SturdyRef might be opaque, because they are intended only cannam@147: # to be forwarded to the restorer service. cannam@147: cannam@147: using ProvisionId = AnyPointer; cannam@147: # **(level 3)** cannam@147: # cannam@147: # The information that must be sent in an `Accept` message to identify the object being accepted. cannam@147: # cannam@147: # In a network where each vat has a public/private key pair, this could simply be the public key cannam@147: # fingerprint of the provider vat along with the question ID used in the `Provide` message sent from cannam@147: # that provider. cannam@147: cannam@147: using RecipientId = AnyPointer; cannam@147: # **(level 3)** cannam@147: # cannam@147: # The information that must be sent in a `Provide` message to identify the recipient of the cannam@147: # capability. cannam@147: # cannam@147: # In a network where each vat has a public/private key pair, this could simply be the public key cannam@147: # fingerprint of the recipient. (CapTP also calls for a nonce to identify the object. In our cannam@147: # case, the `Provide` message's `questionId` can serve as the nonce.) cannam@147: cannam@147: using ThirdPartyCapId = AnyPointer; cannam@147: # **(level 3)** cannam@147: # cannam@147: # The information needed to connect to a third party and accept a capability from it. cannam@147: # cannam@147: # In a network where each vat has a public/private key pair, this could be a combination of the cannam@147: # third party's public key fingerprint, hints on how to connect to the third party (e.g. an IP cannam@147: # address), and the question ID used in the corresponding `Provide` message sent to that third party cannam@147: # (used to identify which capability to pick up). cannam@147: cannam@147: using JoinKeyPart = AnyPointer; cannam@147: # **(level 4)** cannam@147: # cannam@147: # A piece of a secret key. One piece is sent along each path that is expected to lead to the same cannam@147: # place. Once the pieces are combined, a direct connection may be formed between the sender and cannam@147: # the receiver, bypassing any men-in-the-middle along the paths. See the `Join` message type. cannam@147: # cannam@147: # The motivation for Joins is discussed under "Supporting Equality" in the "Unibus" protocol cannam@147: # sketch: http://www.erights.org/elib/distrib/captp/unibus.html cannam@147: # cannam@147: # In a network where each vat has a public/private key pair and each vat forms no more than one cannam@147: # connection to each other vat, Joins will rarely -- perhaps never -- be needed, as objects never cannam@147: # need to be transparently proxied and references to the same object sent over the same connection cannam@147: # have the same export ID. Thus, a successful join requires only checking that the two objects cannam@147: # come from the same connection and have the same ID, and then completes immediately. cannam@147: # cannam@147: # However, in networks where two vats may form more than one connection between each other, or cannam@147: # where proxying of objects occurs, joins are necessary. cannam@147: # cannam@147: # Typically, each JoinKeyPart would include a fixed-length data value such that all value parts cannam@147: # XOR'd together forms a shared secret that can be used to form an encrypted connection between cannam@147: # the joiner and the joined object's host. Each JoinKeyPart should also include an indication of cannam@147: # how many parts to expect and a hash of the shared secret (used to match up parts). cannam@147: cannam@147: using JoinResult = AnyPointer; cannam@147: # **(level 4)** cannam@147: # cannam@147: # Information returned as the result to a `Join` message, needed by the joiner in order to form a cannam@147: # direct connection to a joined object. This might simply be the address of the joined object's cannam@147: # host vat, since the `JoinKey` has already been communicated so the two vats already have a shared cannam@147: # secret to use to authenticate each other. cannam@147: # cannam@147: # The `JoinResult` should also contain information that can be used to detect when the Join cannam@147: # requests ended up reaching different objects, so that this situation can be detected easily. cannam@147: # This could be a simple matter of including a sequence number -- if the joiner receives two cannam@147: # `JoinResult`s with sequence number 0, then they must have come from different objects and the cannam@147: # whole join is a failure. cannam@147: cannam@147: # ======================================================================================== cannam@147: # Network interface sketch cannam@147: # cannam@147: # The interfaces below are meant to be pseudo-code to illustrate how the details of a particular cannam@147: # vat network might be abstracted away. They are written like Cap'n Proto interfaces, but in cannam@147: # practice you'd probably define these interfaces manually in the target programming language. A cannam@147: # Cap'n Proto RPC implementation should be able to use these interfaces without knowing the cannam@147: # definitions of the various network-specific parameters defined above. cannam@147: cannam@147: # interface VatNetwork { cannam@147: # # Represents a vat network, with the ability to connect to particular vats and receive cannam@147: # # connections from vats. cannam@147: # # cannam@147: # # Note that methods returning a `Connection` may return a pre-existing `Connection`, and the cannam@147: # # caller is expected to find and share state with existing users of the connection. cannam@147: # cannam@147: # # Level 0 features ----------------------------------------------- cannam@147: # cannam@147: # connect(vatId :VatId) :Connection; cannam@147: # # Connect to the given vat. The transport should return a promise that does not cannam@147: # # resolve until authentication has completed, but allows messages to be pipelined in before cannam@147: # # that; the transport either queues these messages until authenticated, or sends them encrypted cannam@147: # # such that only the authentic vat would be able to decrypt them. The latter approach avoids a cannam@147: # # round trip for authentication. cannam@147: # cannam@147: # accept() :Connection; cannam@147: # # Wait for the next incoming connection and return it. Only connections formed by cannam@147: # # connect() are returned by this method. cannam@147: # cannam@147: # # Level 4 features ----------------------------------------------- cannam@147: # cannam@147: # newJoiner(count :UInt32) :NewJoinerResponse; cannam@147: # # Prepare a new Join operation, which will eventually lead to forming a new direct connection cannam@147: # # to the host of the joined capability. `count` is the number of capabilities to join. cannam@147: # cannam@147: # struct NewJoinerResponse { cannam@147: # joinKeyParts :List(JoinKeyPart); cannam@147: # # Key parts to send in Join messages to each capability. cannam@147: # cannam@147: # joiner :Joiner; cannam@147: # # Used to establish the final connection. cannam@147: # } cannam@147: # cannam@147: # interface Joiner { cannam@147: # addJoinResult(result :JoinResult) :Void; cannam@147: # # Add a JoinResult received in response to one of the `Join` messages. All `JoinResult`s cannam@147: # # returned from all paths must be added before trying to connect. cannam@147: # cannam@147: # connect() :ConnectionAndProvisionId; cannam@147: # # Try to form a connection to the joined capability's host, verifying that it has received cannam@147: # # all of the JoinKeyParts. Once the connection is formed, the caller should send an `Accept` cannam@147: # # message on it with the specified `ProvisionId` in order to receive the final capability. cannam@147: # } cannam@147: # cannam@147: # acceptConnectionFromJoiner(parts :List(JoinKeyPart), paths :List(VatPath)) cannam@147: # :ConnectionAndProvisionId; cannam@147: # # Called on a joined capability's host to receive the connection from the joiner, once all cannam@147: # # key parts have arrived. The caller should expect to receive an `Accept` message over the cannam@147: # # connection with the given ProvisionId. cannam@147: # } cannam@147: # cannam@147: # interface Connection { cannam@147: # # Level 0 features ----------------------------------------------- cannam@147: # cannam@147: # send(message :Message) :Void; cannam@147: # # Send the message. Returns successfully when the message (and all preceding messages) has cannam@147: # # been acknowledged by the recipient. cannam@147: # cannam@147: # receive() :Message; cannam@147: # # Receive the next message, and acknowledges receipt to the sender. Messages are received in cannam@147: # # the order in which they are sent. cannam@147: # cannam@147: # # Level 3 features ----------------------------------------------- cannam@147: # cannam@147: # introduceTo(recipient :Connection) :IntroductionInfo; cannam@147: # # Call before starting a three-way introduction, assuming a `Provide` message is to be sent on cannam@147: # # this connection and a `ThirdPartyCapId` is to be sent to `recipient`. cannam@147: # cannam@147: # struct IntroductionInfo { cannam@147: # sendToRecipient :ThirdPartyCapId; cannam@147: # sendToTarget :RecipientId; cannam@147: # } cannam@147: # cannam@147: # connectToIntroduced(capId :ThirdPartyCapId) :ConnectionAndProvisionId; cannam@147: # # Given a ThirdPartyCapId received over this connection, connect to the third party. The cannam@147: # # caller should then send an `Accept` message over the new connection. cannam@147: # cannam@147: # acceptIntroducedConnection(recipientId :RecipientId) :Connection; cannam@147: # # Given a RecipientId received in a `Provide` message on this `Connection`, wait for the cannam@147: # # recipient to connect, and return the connection formed. Usually, the first message received cannam@147: # # on the new connection will be an `Accept` message. cannam@147: # } cannam@147: # cannam@147: # struct ConnectionAndProvisionId { cannam@147: # # **(level 3)** cannam@147: # cannam@147: # connection :Connection; cannam@147: # # Connection on which to issue `Accept` message. cannam@147: # cannam@147: # provision :ProvisionId; cannam@147: # # `ProvisionId` to send in the `Accept` message. cannam@147: # }