rpc.capnp 74.7 KB
Newer Older
Kenton Varda's avatar
Kenton Varda committed
1 2
# Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors
# Licensed under the MIT License:
3
#
Kenton Varda's avatar
Kenton Varda committed
4 5 6 7 8 9
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
10
#
Kenton Varda's avatar
Kenton Varda committed
11 12
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
13
#
Kenton Varda's avatar
Kenton Varda committed
14 15 16 17 18 19 20
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.
21 22 23 24 25 26 27 28 29 30 31

@0xb312981b2552a250;
# Recall that Cap'n Proto RPC allows messages to contain references to remote objects that
# implement interfaces.  These references are called "capabilities", because they both designate
# the remote object to use and confer permission to use it.
#
# Recall also that Cap'n Proto RPC has the feature that when a method call itself returns a
# capability, the caller can begin calling methods on that capability _before the first call has
# returned_.  The caller essentially sends a message saying "Hey server, as soon as you finish
# that previous call, do this with the result!".  Cap'n Proto's RPC protocol makes this possible.
#
32 33 34 35 36 37 38 39
# The protocol is significantly more complicated than most RPC protocols.  However, this is
# implementation complexity that underlies an easy-to-grasp higher-level model of object oriented
# programming.  That is, just like TCP is a surprisingly complicated protocol that implements a
# conceptually-simple byte stream abstraction, Cap'n Proto is a surprisingly complicated protocol
# that implements a conceptually-simple object abstraction.
#
# Cap'n Proto RPC is based heavily on CapTP, the object-capability protocol used by the E
# programming language:
40 41
#     http://www.erights.org/elib/distrib/captp/index.html
#
42 43 44 45
# Cap'n Proto RPC takes place between "vats".  A vat hosts some set of objects and talks to other
# vats through direct bilateral connections.  Typically, there is a 1:1 correspondence between vats
# and processes (in the unix sense of the word), although this is not strictly always true (one
# process could run multiple vats, or a distributed virtual vat might live across many processes).
46 47 48
#
# Cap'n Proto does not distinguish between "clients" and "servers" -- this is up to the application.
# Either end of any connection can potentially hold capabilities pointing to the other end, and
49
# can call methods on those capabilities.  In the doc comments below, we use the words "sender"
50 51
# and "receiver".  These refer to the sender and receiver of an instance of the struct or field
# being documented.  Sometimes we refer to a "third-party" which is neither the sender nor the
52
# receiver.  Documentation is generally written from the point of view of the sender.
53 54 55 56 57
#
# It is generally up to the vat network implementation to securely verify that connections are made
# to the intended vat as well as to encrypt transmitted data for privacy and integrity.  See the
# `VatNetwork` example interface near the end of this file.
#
58 59
# When a new connection is formed, the only interesting things that can be done are to send a
# `Bootstrap` (level 0) or `Accept` (level 3) message.
60 61
#
# Unless otherwise specified, messages must be delivered to the receiving application in the same
62 63 64
# order in which they were initiated by the sending application.  The goal is to support "E-Order",
# which states that two calls made on the same reference must be delivered in the order which they
# were made:
65 66 67
#     http://erights.org/elib/concurrency/partial-order.html
#
# Since the full protocol is complicated, we define multiple levels of support which an
68
# implementation may target.  For many applications, level 1 support will be sufficient.
69 70 71
# Comments in this file indicate which level requires the corresponding feature to be
# implemented.
#
72 73 74 75 76 77
# * **Level 0:** The implementation does not support object references. Only the bootstrap interface
#   can be called. At this level, the implementation does not support object-oriented protocols and
#   is similar in complexity to JSON-RPC or Protobuf services. This level should be considered only
#   a temporary stepping-stone toward level 1 as the lack of object references drastically changes
#   how protocols are designed. Applications _should not_ attempt to design their protocols around
#   the limitations of level 0 implementations.
78 79 80
#
# * **Level 1:** The implementation supports simple bilateral interaction with object references
#   and promise pipelining, but interactions between three or more parties are supported only via
81 82 83 84 85
#   proxying of objects.  E.g. if Alice (in Vat A) wants to send Bob (in Vat B) a capability
#   pointing to Carol (in Vat C), Alice must create a proxy of Carol within Vat A and send Bob a
#   reference to that; Bob cannot form a direct connection to Carol.  Level 1 implementations do
#   not support checking if two capabilities received from different vats actually point to the
#   same object ("join"), although they should be able to do this check on capabilities received
86
#   from the same vat.
87
#
88 89 90 91
# * **Level 2:** The implementation supports saving persistent capabilities -- i.e. capabilities
#   that remain valid even after disconnect, and can be restored on a future connection. When a
#   capability is saved, the requester receives a `SturdyRef`, which is a token that can be used
#   to restore the capability later.
92
#
93 94 95
# * **Level 3:** The implementation supports three-way interactions.  That is, if Alice (in Vat A)
#   sends Bob (in Vat B) a capability pointing to Carol (in Vat C), then Vat B will automatically
#   form a direct connection to Vat C rather than have requests be proxied through Vat A.
96
#
97 98
# * **Level 4:** The entire protocol is implemented, including joins (checking if two capabilities
#   are equivalent).
99 100 101 102 103
#
# Note that an implementation must also support specific networks (transports), as described in
# the "Network-specific Parameters" section below.  An implementation might have different levels
# depending on the network used.
#
104 105 106 107
# New implementations of Cap'n Proto should start out targeting the simplistic two-party network
# type as defined in `rpc-twoparty.capnp`.  With this network type, level 3 is irrelevant and
# levels 2 and 4 are much easier than usual to implement.  When such an implementation is paired
# with a container proxy, the contained app effectively gets to make full use of the proxy's
108
# network at level 4.  And since Cap'n Proto IPC is extremely fast, it may never make sense to
Kenton Varda's avatar
Kenton Varda committed
109
# bother implementing any other vat network protocol -- just use the correct container type and get
110 111
# it for free.

112
using Cxx = import "/capnp/c++.capnp";
113 114 115 116 117
$Cxx.namespace("capnp::rpc");

# ========================================================================================
# The Four Tables
#
118 119 120
# Cap'n Proto RPC connections are stateful (although an application built on Cap'n Proto could
# export a stateless interface).  As in CapTP, for each open connection, a vat maintains four state
# tables: questions, answers, imports, and exports.  See the diagram at:
121 122 123
#     http://www.erights.org/elib/distrib/captp/4tables.html
#
# The question table corresponds to the other end's answer table, and the imports table corresponds
Kenton Varda's avatar
Kenton Varda committed
124
# to the other end's exports table.
125
#
126 127 128 129 130
# The entries in each table are identified by ID numbers (defined below as 32-bit integers).  These
# numbers are always specific to the connection; a newly-established connection starts with no
# valid IDs.  Since low-numbered IDs will pack better, it is suggested that IDs be assigned like
# Unix file descriptors -- prefer the lowest-number ID that is currently available.
#
131 132 133
# IDs in the questions/answers tables are chosen by the questioner and generally represent method
# calls that are in progress.
#
Kenton Varda's avatar
Kenton Varda committed
134
# IDs in the imports/exports tables are chosen by the exporter and generally represent objects on
135 136
# which methods may be called.  Exports may be "settled", meaning the exported object is an actual
# object living in the exporter's vat, or they may be "promises", meaning the exported object is
Kenton Varda's avatar
Kenton Varda committed
137 138
# the as-yet-unknown result of an ongoing operation and will eventually be resolved to some other
# object once that operation completes.  Calls made to a promise will be forwarded to the eventual
139
# target once it is known.  The eventual replacement object does *not* get the same ID as the
Kenton Varda's avatar
Kenton Varda committed
140 141 142
# promise, as it may turn out to be an object that is already exported (so already has an ID) or
# may even live in a completely different vat (and so won't get an ID on the same export table
# at all).
143 144 145 146 147
#
# IDs can be reused over time.  To make this safe, we carefully define the lifetime of IDs.  Since
# messages using the ID could be traveling in both directions simultaneously, we must define the
# end of life of each ID _in each direction_.  The ID is only safe to reuse once it has been
# released by both sides.
Kenton Varda's avatar
Kenton Varda committed
148 149
#
# When a Cap'n Proto connection is lost, everything on the four tables is lost.  All questions are
150 151 152
# canceled and throw exceptions.  All imports become broken (all future calls to them throw
# exceptions).  All exports and answers are implicitly released.  The only things not lost are
# persistent capabilities (`SturdyRef`s).  The application must plan for this and should respond by
Kenton Varda's avatar
Kenton Varda committed
153
# establishing a new connection and restoring from these persistent capabilities.
154 155

using QuestionId = UInt32;
156 157
# **(level 0)**
#
158 159 160 161 162 163 164 165 166 167 168 169 170 171
# Identifies a question in the sender's question table (which corresponds to the receiver's answer
# table).  The questioner (caller) chooses an ID when making a call.  The ID remains valid in
# caller -> callee messages until a Finish message is sent, and remains valid in callee -> caller
# messages until a Return message is sent.

using AnswerId = QuestionId;
# **(level 0)**
#
# Identifies an answer in the sender's answer table (which corresponds to the receiver's question
# table).
#
# AnswerId is physically equivalent to QuestionId, since the question and answer tables correspond,
# but we define a separate type for documentation purposes:  we always use the type representing
# the sender's point of view.
172 173

using ExportId = UInt32;
174 175
# **(level 1)**
#
176 177 178 179 180 181 182 183 184 185 186 187 188 189 190
# Identifies an exported capability or promise in the sender's export table (which corresponds
# to the receiver's import table).  The exporter chooses an ID before sending a capability over the
# wire.  If the capability is already in the table, the exporter should reuse the same ID.  If the
# ID is a promise (as opposed to a settled capability), this must be indicated at the time the ID
# is introduced (e.g. by using `senderPromise` instead of `senderHosted` in `CapDescriptor`); in
# this case, the importer shall expect a later `Resolve` message which replaces the promise.
#
# ExportId/ImportIds are subject to reference counting.  Whenever an `ExportId` is sent over the
# wire (from the exporter to the importer), the export's reference count is incremented (unless
# otherwise specified).  The reference count is later decremented by a `Release` message.  Since
# the `Release` message can specify an arbitrary number by which to reduce the reference count, the
# importer should usually batch reference decrements and only send a `Release` when it believes the
# reference count has hit zero.  Of course, it is possible that a new reference to the export is
# in-flight at the time that the `Release` message is sent, so it is necessary for the exporter to
# keep track of the reference count on its end as well to avoid race conditions.
Kenton Varda's avatar
Kenton Varda committed
191
#
192 193 194 195 196 197
# When a connection is lost, all exports are implicitly released.  It is not possible to restore
# a connection state after disconnect (although a transport layer could implement a concept of
# persistent connections if it is transparent to the RPC layer).

using ImportId = ExportId;
# **(level 1)**
Kenton Varda's avatar
Kenton Varda committed
198
#
199 200
# Identifies an imported capability or promise in the sender's import table (which corresponds to
# the receiver's export table).
201
#
202 203 204
# ImportId is physically equivalent to ExportId, since the export and import tables correspond,
# but we define a separate type for documentation purposes:  we always use the type representing
# the sender's point of view.
Kenton Varda's avatar
Kenton Varda committed
205
#
206 207
# An `ImportId` remains valid in importer -> exporter messages until the importer has sent
# `Release` messages which (it believes) have reduced the reference count to zero.
208 209

# ========================================================================================
Kenton Varda's avatar
Kenton Varda committed
210
# Messages
211

Kenton Varda's avatar
Kenton Varda committed
212 213
struct Message {
  # An RPC connection is a bi-directional stream of Messages.
214 215

  union {
216
    unimplemented @0 :Message;
217 218 219 220
    # 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.
221 222
    #
    # For example, say `resolve` is received by a level 0 implementation (because a previous call
223 224 225
    # 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.
226 227
    #
    # For any message type that introduces a question, if the message comes back unimplemented,
228
    # the original sender may simply treat it as if the question failed with an exception.
229 230 231 232 233 234 235 236 237 238 239 240 241
    #
    # 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.

    abort @1 :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 (`isCallersFault` is true) or
    # because the sender had an internal error (`isCallersFault` is false).  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).

242
    # Level 0 features -----------------------------------------------
243

244 245 246 247
    bootstrap @8 :Bootstrap;  # Request the peer's bootstrap interface.
    call @2 :Call;            # Begin a method call.
    return @3 :Return;        # Complete a method call.
    finish @4 :Finish;        # Release a returned answer / cancel a call.
248

249
    # Level 1 features -----------------------------------------------
250

251 252
    resolve @5 :Resolve;   # Resolve a previously-sent promise.
    release @6 :Release;   # Release a capability so that the remote object can be deallocated.
253
    disembargo @13 :Disembargo;  # Lift an embargo used to enforce E-order over promise resolution.
254 255 256

    # Level 2 features -----------------------------------------------

257 258 259 260
    obsoleteSave @7 :AnyPointer;
    # 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.
261

262 263 264
    obsoleteDelete @9 :AnyPointer;
    # Obsolete way to delete a SturdyRef. This was never implemented, therefore it has been
    # reduted to AnyPointer. This operation was never implemented.
265 266 267

    # Level 3 features -----------------------------------------------

268 269
    provide @10 :Provide;  # Provide a capability to a third party.
    accept @11 :Accept;    # Accept a capability provided by a third party.
270 271 272

    # Level 4 features -----------------------------------------------

273
    join @12 :Join;        # Directly connect to the common root of two or more proxied caps.
274 275 276
  }
}

277 278
# Level 0 message types ----------------------------------------------

279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389
struct Bootstrap {
  # **(level 0)**
  #
  # Get the "bootstrap" interface exported by the remote vat.
  #
  # For level 0, 1, and 2 implementations, the "bootstrap" interface is simply the main interface
  # exported by a vat. If the vat acts as a server fielding connections from clients, then the
  # bootstrap interface defines the basic functionality available to a client when it connects.
  # The exact interface definition obviously depends on the application.
  #
  # We call this a "bootstrap" because in an ideal Cap'n Proto world, bootstrap interfaces would
  # never be used. In such a world, any time you connect to a new vat, you do so because you
  # received an introduction from some other vat (see `ThirdPartyCapId`). Thus, the first message
  # you send is `Accept`, and further communications derive from there. `Bootstrap` is not used.
  #
  # In such an ideal world, DNS itself would support Cap'n Proto -- performing a DNS lookup would
  # actually return a new Cap'n Proto capability, thus introducing you to the target system via
  # level 3 RPC. Applications would receive the capability to talk to DNS in the first place as
  # an initial endowment or part of a Powerbox interaction. Therefore, an app can form arbitrary
  # connections without ever using `Bootstrap`.
  #
  # Of course, in the real world, DNS is not Cap'n-Proto-based, and we don't want Cap'n Proto to
  # require a whole new internet infrastructure to be useful. Therefore, we offer bootstrap
  # interfaces as a way to get up and running without a level 3 introduction. Thus, bootstrap
  # interfaces are used to "bootstrap" from other, non-Cap'n-Proto-based means of service discovery,
  # such as legacy DNS.
  #
  # Note that a vat need not provide a bootstrap interface, and in fact many vats (especially those
  # acting as clients) do not. In this case, the vat should either reply to `Bootstrap` with a
  # `Return` indicating an exception, or should return a dummy capability with no methods.

  questionId @0 :QuestionId;
  # A new question ID identifying this request, which will eventually receive a Return message
  # containing the restored capability.

  deprecatedObjectId @1 :AnyPointer;
  # ** 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 verison 0.5, use of this field is deprecated. If a service wants to export multiple
  # bootstrap interfaces, it should instead define a single bootstarp interface which 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 which
  # 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 which 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 which 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 foward 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 which 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` which, 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.
}

390
struct Call {
391 392
  # **(level 0)**
  #
Kenton Varda's avatar
Kenton Varda committed
393
  # Message type initiating a method call on a capability.
394 395 396 397

  questionId @0 :QuestionId;
  # A number, chosen by the caller, which identifies this call in future messages.  This number
  # must be different from all other calls originating from the same end of the connection (but
Kenton Varda's avatar
Kenton Varda committed
398 399
  # 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.
400
  #
Kenton Varda's avatar
Kenton Varda committed
401 402
  # A question ID can be reused once both:
  # - A matching Return has been received from the callee.
403
  # - A matching Finish has been sent from the caller.
404

Kenton Varda's avatar
Kenton Varda committed
405 406
  target @1 :MessageTarget;
  # The object that should receive this call.
407

Kenton Varda's avatar
Kenton Varda committed
408
  interfaceId @2 :UInt64;
409 410
  # The type ID of the interface being called.  Each capability may implement multiple interfaces.

Kenton Varda's avatar
Kenton Varda committed
411
  methodId @3 :UInt16;
412 413
  # The ordinal number of the method to call within the requested interface.

414 415 416 417 418 419 420 421
  allowThirdPartyTailCall @8 :Bool = false;
  # 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.

  params @4 :Payload;
  # The call parameters.  `params.content` is a struct whose fields correspond to the parameters of
  # the method.
422

423
  sendResultsTo :union {
424 425
    # Where should the return message be sent?

Kenton Varda's avatar
Kenton Varda committed
426
    caller @5 :Void;
427 428
    # Send the return message back to the caller (the usual).

429
    yourself @6 :Void;
430 431
    # **(level 1)**
    #
432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447
    # 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 `takeFromOtherAnswer` 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.
448 449 450 451 452 453 454
    #
    # For example:
    # - Alice, in Vat A, call 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'().
455 456 457
    #   Notice that bar() and bar'() are travelling in opposite directions on the same network
    #   link.
    # - The `Call` for bar'() has `sendResultsTo` set to `yourself`, with the value being the
458 459
    #   question ID originally assigned to the bar() call.
    # - Vat A receives bar'() and delivers it to Carol.
460 461 462 463 464 465 466
    # - When bar'() returns, Vat A immediately takes the results and returns them from bar().
    # - Meanwhile, Vat A sends a `Return` for bar'() to Vat B, with `resultsSentElsewhere` set in
    #   place of results.
    # - Vat A sends a `Finish` for that call to Vat B.
    # - Vat B receives the `Return` for bar'() and sends a `Return` for bar(), with
    #   `receivedFromYourself` set in place of the results.
    # - Vat B receives the `Finish` for bar() and sends a `Finish` to bar'().
467

Kenton Varda's avatar
Kenton Varda committed
468
    thirdParty @7 :RecipientId;
469 470 471 472 473 474 475 476
    # **(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
477 478 479
    # 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`.
480
  }
481 482 483
}

struct Return {
484 485
  # **(level 0)**
  #
Kenton Varda's avatar
Kenton Varda committed
486
  # Message type sent from callee to caller indicating that the call has completed.
487

488 489
  answerId @0 :AnswerId;
  # Equal to the QuestionId of the corresponding `Call` message.
490

491 492 493 494 495 496
  releaseParamCaps @1 :Bool = true;
  # 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 forgot to
  # set it they'd never notice (just silently leak caps), but if level >=1 implementations forget
  # set it false they'll quickly get errors.
497 498

  union {
499 500
    results @2 :Payload;
    # The result.
501
    #
502 503 504 505 506
    # For regular method calls, `results.content` points to the result struct.
    #
    # For a `Return` in response to an `Accept`, `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.
507 508 509 510 511

    exception @3 :Exception;
    # Indicates that the call failed and explains why.

    canceled @4 :Void;
512
    # Indicates that the call was canceled due to the caller sending a Finish message
513
    # before the call had completed.
514

515 516 517 518
    resultsSentElsewhere @5 :Void;
    # This is set when returning from a `Call` which had `sendResultsTo` set to something other
    # than `caller`.

519
    takeFromOtherQuestion @6 :QuestionId;
520 521 522 523 524
    # 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.

    acceptFromThirdParty @7 :ThirdPartyCapId;
525 526
    # **(level 3)**
    #
527 528
    # 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`.
529 530 531
  }
}

532 533 534 535 536 537
struct Finish {
  # **(level 0)**
  #
  # Message type sent from the caller to the callee to indicate:
  # 1) The questionId will no longer be used in any messages sent by the callee (no further
  #    pipelined requests).
538 539
  # 2) If the call has not returned yet, the caller no longer cares about the result.  If nothing
  #    else cares about the result either (e.g. there are no other outstanding calls pipelined on
540
  #    the result of this one) then the callee may wish to immediately cancel the operation and
541
  #    send back a Return message with "canceled" set.  However, implementations are not required
542 543
  #    to support premature cancellation -- instead, the implementation may wait until the call
  #    actually completes and send a normal `Return` message.
Kenton Varda's avatar
Kenton Varda committed
544
  #
545 546 547 548 549 550
  # TODO(someday): Should we separate (1) and implicitly releasing result capabilities?  It would be
  #   possible and useful to notify the server that it doesn't need to keep around the response to
  #   service pipeline requests even though the caller still wants to receive it / hasn't yet
  #   finished processing it.  It could also be useful to notify the server that it need not marshal
  #   the results because the caller doesn't want them anyway, even if the caller is still sending
  #   pipelined calls, although this seems less useful (just saving some bytes on the wire).
551 552

  questionId @0 :QuestionId;
553
  # ID of the call whose result is to be released.
554

555 556 557 558 559 560
  releaseResultCaps @1 :Bool = true;
  # 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 forgot to
  # set it they'd never notice (just silently leak caps), but if level >=1 implementations forget
  # set it false they'll quickly get errors.
561 562 563 564
}

# Level 1 message types ----------------------------------------------

565
struct Resolve {
566 567
  # **(level 1)**
  #
Kenton Varda's avatar
Kenton Varda committed
568
  # Message type sent to indicate that a previously-sent promise has now been resolved to some other
569
  # object (possibly another promise) -- or broken, or canceled.
570
  #
571 572 573 574 575 576 577
  # Keep in mind that it's possible for a `Resolve` to be sent to a level 0 implementation that
  # doesn't implement it.  For example, a method call or return might contain a capability in the
  # payload.  Normally this is fine even if the receiver is level 0, because they will implicitly
  # release all such capabilities on return / finish.  But if the cap happens to be a promise, then
  # a follow-up `Resolve` will be sent regardless of this release.  The level 0 receiver will reply
  # with an `unimplemented` message.  The sender (of the `Resolve`) can respond to this as if the
  # receiver had immediately released any capability to which the promise resolved.
578 579 580 581
  #
  # When implementing promise resolution, it's important to understand how embargos work and the
  # tricky case of the Tribble 4-way race condition. See the comments for the Disembargo message,
  # below.
582 583 584 585 586

  promiseId @0 :ExportId;
  # The ID of the promise to be resolved.
  #
  # Unlike all other instances of `ExportId` sent from the exporter, the `Resolve` message does
587 588 589
  # _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.
590
  #
Kenton Varda's avatar
Kenton Varda committed
591 592
  # 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
593
  # same `promiseId` is sent again before `Resolve`, still only one `Resolve` is sent.  If the
594
  # same ID is sent again later _after_ a `Resolve`, it can only be because the export's
595 596 597 598
  # 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`
599 600 601
  # 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
602
  # the receiver has no knowledge, because it already released it earlier.  In this case, the
603
  # receiver should simply release the capability to which the promise resolved.
604 605 606 607

  union {
    cap @1 :CapDescriptor;
    # The object to which the promise resolved.
Kenton Varda's avatar
Kenton Varda committed
608 609 610 611 612 613 614 615 616
    #
    # 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 desigate 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.
617 618 619 620 621 622 623

    exception @2 :Exception;
    # Indicates that the promise was broken.
  }
}

struct Release {
624 625
  # **(level 1)**
  #
Kenton Varda's avatar
Kenton Varda committed
626
  # Message type sent to indicate that the sender is done with the given capability and the receiver
627 628
  # can free resources allocated to it.

629
  id @0 :ImportId;
630 631 632
  # What to release.

  referenceCount @1 :UInt32;
Kenton Varda's avatar
Kenton Varda committed
633 634
  # The amount by which to decrement the reference count.  The export is only actually released
  # when the reference count reaches zero.
635 636
}

637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667
struct Disembargo {
  # **(level 1)**
  #
  # Message sent to indicate that an embargo on a recently-resolved promise may now be lifted.
  #
  # Embargos are used to enforce E-order in the presence of promise resolution.  That is, if an
  # application makes two calls foo() and bar() on the same capability reference, in that order,
  # the calls should be delivered in the order in which they were made.  But if foo() is called
  # on a promise, and that promise happens to resolve before bar() is called, then the two calls
  # may travel different paths over the network, and thus could arrive in the wrong order.  In
  # this case, the call to `bar()` must be embargoed, and a `Disembargo` message must be sent along
  # the same path as `foo()` to ensure that the `Disembargo` arrives after `foo()`.  Once the
  # `Disembargo` arrives, `bar()` can then be delivered.
  #
  # There are two particular cases where embargos are important.  Consider object Alice, in Vat A,
  # who holds a promise P, pointing towards Vat B, which eventually resolves to Carol.  The two
  # cases are:
  # - Carol lives in Vat A, i.e. next to Alice.  In this case, Vat A needs to send a `Disembargo`
  #   message that echos through Vat B and back, to ensure that all pipelined calls on the promise
  #   have been delivered.
  # - Carol lives in a different Vat C.  When the promise resolves, a three-party handoff occurs
  #   (see `Provide` and `Accept`, which constitute level 3 of the protocol).  In this case, we
  #   piggyback on the state that has already been set up to handle the handoff:  the `Accept`
  #   message (from Vat A to Vat C) is embargoed, as are all pipelined messages sent to it, while
  #   a `Disembargo` message is sent from Vat A through Vat B to Vat C.  See `Accept.embargo` for
  #   an example.
  #
  # Note that in the case where Carol actually lives in Vat B (i.e., the same vat that the promise
  # already pointed at), no embargo is needed, because the pipelined calls are delivered over the
  # same path as the later direct calls.
  #
668 669 670
  # Keep in mind that promise resolution happens both in the form of Resolve messages as well as
  # Return messages (which resolve PromisedAnswers). Embargos apply in both cases.
  #
671 672 673 674 675 676 677 678
  # An alternative strategy for enforcing E-order over promise resolution could be for Vat A to
  # implement the embargo internally.  When Vat A is notified of promise resolution, it could
  # send a dummy no-op call to promise P and wait for it to complete.  Until that call completes,
  # all calls to the capability are queued locally.  This strategy works, but is pessimistic:
  # in the three-party case, it requires an A -> B -> C -> B -> A round trip before calls can start
  # being delivered directly to from Vat A to Vat C.  The `Disembargo` message allows latency to be
  # reduced.  (In the two-party loopback case, the `Disembargo` message is just a more explicit way
  # of accomplishing the same thing as a no-op call, but isn't any faster.)
679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703
  #
  # *The Tribble 4-way Race Condition*
  #
  # Any implementation of promise resolution and embargos must be aware of what we call the
  # "Tribble 4-way race condition", after Dean Tribble, who explained the problem in a lively
  # Friam meeting.
  #
  # Embargos are designed to work in the case where a two-hop path is being shortened to one hop.
  # But sometimes there are more hops. Imagine that Alice has a reference to a remote promise P1
  # which eventually resolves to _another_ remote promise P2 (in a third vat), which _at the same
  # time_ happens to resolve to Bob (in a fourth vat). In this case, we're shortening from a 3-hop
  # path (with four parties) to a 1-hop path (Alice -> Bob).
  #
  # Extending the embargo/disembargo protocol to be able to shorted multiple hops at once seems
  # difficult. Instead, we make a rule that prevents this case from coming up:
  #
  # One a promise P has been resolved to a remove object reference R, then all further messages
  # received addressed to P will be forwarded strictly to R. Even if it turns out later that R is
  # itself a promise, and has resolved to some other object Q, messages sent to P will still be
  # forwarded to R, not directly to Q (R will of course further forward the messages to Q).
  #
  # This rule does not cause a significant performance burden because once P has resolved to R, it
  # is expected that people sending messages to P will shortly start sending them to R instead and
  # drop P. P is at end-of-life anyway, so it doesn't matter if it ignores chances to further
  # optimize its path.
704

Kenton Varda's avatar
Kenton Varda committed
705 706
  target @0 :MessageTarget;
  # What is to be disembargoed.
707 708 709 710 711

  using EmbargoId = UInt32;
  # Used in `senderLoopback` and `receiverLoopback`, below.

  context :union {
Kenton Varda's avatar
Kenton Varda committed
712
    senderLoopback @1 :EmbargoId;
713 714 715 716 717 718 719 720 721 722
    # The sender is requesting a disembargo on a promise which is known to resolve back to a
    # capability hoste 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.

Kenton Varda's avatar
Kenton Varda committed
723
    receiverLoopback @2 :EmbargoId;
724 725 726
    # The receiver previously sent a `senderLoopback` Disembargo towards a promise resolving to
    # this capability, and that Disembargo is now being echoed back.

Kenton Varda's avatar
Kenton Varda committed
727
    accept @3 :Void;
728 729 730 731 732 733 734 735 736 737
    # **(level 3)**
    #
    # The sender is requesting a disembargo on a promise which is known to resolve to a third-party
    # capability which 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.

Kenton Varda's avatar
Kenton Varda committed
738
    provide @4 :QuestionId;
739 740 741 742 743 744 745 746 747 748
    # **(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.
  }
}

749 750
# Level 2 message types ----------------------------------------------

751
# See persistent.capnp.
752

753 754
# Level 3 message types ----------------------------------------------

755
struct Provide {
756
  # **(level 3)**
757
  #
Kenton Varda's avatar
Kenton Varda committed
758
  # Message type sent to indicate that the sender wishes to make a particular capability implemented
759 760 761 762 763 764 765
  # by the receiver available to a third party for direct access (without the need for the third
  # party to proxy through the sender).
  #
  # (In CapTP, `Provide` and `Accept` are methods of the global `NonceLocator` object exported by
  # every vat.  In Cap'n Proto, we bake this into the core protocol.)

  questionId @0 :QuestionId;
766
  # Question ID to be held open until the recipient has received the capability.  A result will
767
  # be returned once the third party has successfully received the capability.  The sender must
768
  # at some point send a `Finish` message as with any other call, and such a message can be
769 770
  # used to cancel the whole operation.

Kenton Varda's avatar
Kenton Varda committed
771 772
  target @1 :MessageTarget;
  # What is to be provided to the third party.
773

Kenton Varda's avatar
Kenton Varda committed
774
  recipient @2 :RecipientId;
775 776 777 778
  # Identity of the third party which is expected to pick up the capability.
}

struct Accept {
779
  # **(level 3)**
780
  #
Kenton Varda's avatar
Kenton Varda committed
781
  # Message type sent to pick up a capability hosted by the receiving vat and provided by a third
782
  # party.  The third party previously designated the capability using `Provide`.
783 784
  #
  # This message is also used to pick up a redirected return -- see `Return.redirect`.
785 786 787

  questionId @0 :QuestionId;
  # A new question ID identifying this accept message, which will eventually receive a Return
788 789
  # message containing the provided capability (or the call result in the case of a redirected
  # return).
790 791 792

  provision @1 :ProvisionId;
  # Identifies the provided object to be picked up.
793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826

  embargo @2 :Bool;
  # If true, this accept shall be temporarily embargoed.  The resulting `Return` will not be sent,
  # and any pipelined calls will not be delivered, until the embargo is released.  The receiver
  # (the capability host) will expect the provider (the vat that sent the `Provide` message) to
  # eventually send a `Disembargo` message with the field `context.provide` set to the question ID
  # of the original `Provide` message.  At that point, the embargo is released and the queued
  # messages are delivered.
  #
  # For example:
  # - Alice, in Vat A, holds a promise P, which currently points toward Vat B.
  # - Alice calls foo() on P.  The `Call` message is sent to Vat B.
  # - The promise P in Vat B ends up resolving to Carol, in Vat C.
  # - Vat B sends a `Provide` message to Vat C, identifying Vat A as the recipient.
  # - Vat B sends a `Resolve` message to Vat A, indicating that the promise has resolved to a
  #   `ThirdPartyCapId` identifying Carol in Vat C.
  # - Vat A sends an `Accept` message to Vat C to pick up the capability.  Since Vat A knows that
  #   it has an outstanding call to the promise, it sets `embargo` to `true` in the `Accept`
  #   message.
  # - Vat A sends a `Disembargo` message to Vat B on promise P, with `context.accept` set.
  # - Alice makes a call bar() to promise P, which is now pointing towards Vat C.  Alice doesn't
  #   know anything about the mechanics of promise resolution happening under the hood, but she
  #   expects that bar() will be delivered after foo() because that is the order in which she
  #   initiated the calls.
  # - Vat A sends the bar() call to Vat C, as a pipelined call on the result of the `Accept` (which
  #   hasn't returned yet, due to the embargo).  Since calls to the newly-accepted capability
  #   are embargoed, Vat C does not deliver the call yet.
  # - At some point, Vat B forwards the foo() call from the beginning of this example on to Vat C.
  # - Vat B forwards the `Disembargo` from Vat A on to vat C.  It sets `context.provide` to the
  #   question ID of the `Provide` message it had sent previously.
  # - Vat C receives foo() before `ReleaseEmbargo`, thus allowing it to correctly deliver foo()
  #   before delivering bar().
  # - Vat C receives `ReleaseEmbargo` from Vat B.  It can now send a `Return` for the `Accept` from
  #   Vat A, as well as deliver bar().
827 828
}

829 830
# Level 4 message types ----------------------------------------------

831
struct Join {
832
  # **(level 4)**
833
  #
Kenton Varda's avatar
Kenton Varda committed
834 835 836 837
  # Message type sent to implement E.join(), which, given a number of capabilities which are
  # expected to be equivalent, finds the underlying object upon which they all agree and forms a
  # direct connection to it, skipping any proxies which may have been constructed by other vats
  # while transmitting the capability.  See:
838 839 840 841 842 843 844 845 846 847 848 849 850
  #     http://erights.org/elib/equality/index.html
  #
  # Note that this should only serve to bypass fully-transparent proxies -- proxies that were
  # created merely for convenience, without any intention of hiding the underlying object.
  #
  # For example, say Bob holds two capabilities hosted by Alice and Carol, but he expects that both
  # are simply proxies for a capability hosted elsewhere.  He then issues a join request, which
  # operates as follows:
  # - Bob issues Join requests on both Alice and Carol.  Each request contains a different piece
  #   of the JoinKey.
  # - Alice is proxying a capability hosted by Dana, so forwards the request to Dana's cap.
  # - Dana receives the first request and sees that the JoinKeyPart is one of two.  She notes that
  #   she doesn't have the other part yet, so she records the request and responds with a
851
  #   JoinResult.
852 853 854 855 856
  # - Alice relays the JoinAswer back to Bob.
  # - Carol is also proxying a capability from Dana, and so forwards her Join request to Dana as
  #   well.
  # - Dana receives Carol's request and notes that she now has both parts of a JoinKey.  She
  #   combines them in order to form information needed to form a secure connection to Bob.  She
857 858
  #   also responds with another JoinResult.
  # - Bob receives the responses from Alice and Carol.  He uses the returned JoinResults to
859 860 861 862 863 864 865 866 867 868 869 870 871 872 873
  #   determine how to connect to Dana and attempts to form the connection.  Since Bob and Dana now
  #   agree on a secret key which neither Alice nor Carol ever saw, this connection can be made
  #   securely even if Alice or Carol is conspiring against the other.  (If Alice and Carol are
  #   conspiring _together_, they can obviously reproduce the key, but this doesn't matter because
  #   the whole point of the join is to verify that Alice and Carol agree on what capability they
  #   are proxying.)
  #
  # If the two capabilities aren't actually proxies of the same object, then the join requests
  # will come back with conflicting `hostId`s and the join will fail before attempting to form any
  # connection.

  questionId @0 :QuestionId;
  # Question ID used to respond to this Join.  (Note that this ID only identifies one part of the
  # request for one hop; each part has a different ID and relayed copies of the request have
  # (probably) different IDs still.)
Kenton Varda's avatar
Kenton Varda committed
874
  #
875
  # The receiver will reply with a `Return` whose `results` is a JoinResult.  This `JoinResult`
Kenton Varda's avatar
Kenton Varda committed
876 877 878
  # is relayed from the joined object's host, possibly with transformation applied as needed
  # by the network.
  #
879
  # Like any return, the result must be released using a `Finish`.  However, this release
Kenton Varda's avatar
Kenton Varda committed
880
  # should not occur until the joiner has either successfully connected to the joined object.
881 882
  # Vats relaying a `Join` message similarly must not release the result they receive until the
  # return they relayed back towards the joiner has itself been released.  This allows the
Kenton Varda's avatar
Kenton Varda committed
883
  # joined object's host to detect when the Join operation is canceled before completing -- if
884
  # it receives a `Finish` for one of the join results before the joiner successfully
Kenton Varda's avatar
Kenton Varda committed
885
  # connects.  It can then free any resources it had allocated as part of the join.
886

887
  target @1 :MessageTarget;
888 889 890 891 892
  # The capability to join.

  keyPart @2 :JoinKeyPart;
  # A part of the join key.  These combine to form the complete join key which is used to establish
  # a direct connection.
893

894 895 896 897 898
  # TODO(before implementing):  Change this so that multiple parts can be sent in a single Join
  # message, so that if multiple join parts are going to cross the same connection they can be sent
  # together, so that the receive can potentially optimize its handling of them.  In the case where
  # all parts are bundled together, should the recipient be expected to simply return a cap, so
  # that the caller can immediately start pipelining to it?
899 900 901
}

# ========================================================================================
Kenton Varda's avatar
Kenton Varda committed
902
# Common structures used in messages
903

Kenton Varda's avatar
Kenton Varda committed
904 905 906 907
struct MessageTarget {
  # The target of a `Call` or other messages that target a capability.

  union {
908 909 910
    importedCap @0 :ImportId;
    # This message is to a capability or promise previously imported by the caller (exported by
    # the receiver).
Kenton Varda's avatar
Kenton Varda committed
911 912 913 914 915

    promisedAnswer @1 :PromisedAnswer;
    # This message is to a capability that is expected to be returned by another call that has not
    # yet been completed.
    #
916
    # At level 0, this is supported only for addressing the result of a previous `Main`, so that
Kenton Varda's avatar
Kenton Varda committed
917 918 919 920
    # initial startup doesn't require a round trip.
  }
}

921 922 923 924 925 926 927 928 929 930 931
struct Payload {
  # Represents some data structure that might contain capabilities.

  content @0 :AnyPointer;
  # Some Cap'n Proto data structure.  Capability pointers embedded in this structure index into
  # `capTable`.

  capTable @1 :List(CapDescriptor);
  # Descriptors corresponding to the cap pointers in `content`.
}

932
struct CapDescriptor {
933 934
  # **(level 1)**
  #
935 936 937 938 939
  # When an application-defined type contains an interface pointer, that pointer contains an index
  # into the message's capability table -- i.e. the `capTable` part of the `Payload`.  Each
  # capability in the table is represented as a `CapDescriptor`.  The runtime API should not reveal
  # the CapDescriptor directly to the application, but should instead wrap it in some kind of
  # callable object with methods corresponding to the interface that the capability implements.
940 941 942 943 944
  #
  # Keep in mind that `ExportIds` in a `CapDescriptor` are subject to reference counting.  See the
  # description of `ExportId`.

  union {
945 946 947 948 949 950 951 952 953
    none @0 :Void;
    # There is no capability here.  This `CapDescriptor` should not appear in the payload content.
    # A `none` CapDescriptor can be generated when an application inserts a capability into a
    # message and then later changes its mind and removes it -- rewriting all of the other
    # capability pointers may be hard, so instead a tombstone is left, similar to the way a removed
    # struct or list instance is zeroed out of the message but the space is not reclaimed.
    # Hopefully this is unusual.

    senderHosted @1 :ExportId;
Kenton Varda's avatar
Kenton Varda committed
954 955
    # A capability newly exported by the sender.  This is the ID of the new capability in the
    # sender's export table (receiver's import table).
956

957
    senderPromise @2 :ExportId;
958
    # A promise which the sender will resolve later.  The sender will send exactly one Resolve
959 960
    # message at a future point in time to replace this promise.  Note that even if the same
    # `senderPromise` is received multiple times, only one `Resolve` is sent to cover all of
961 962
    # them.  If `senderPromise` is released before the `Resolve` is sent, the sender (of this
    # `CapDescriptor`) may choose not to send the `Resolve` at all.
963

964 965
    receiverHosted @3 :ImportId;
    # A capability (or promise) previously exported by the receiver (imported by the sender).
966

967
    receiverAnswer @4 :PromisedAnswer;
968
    # A capability expected to be returned in the results of a currently-outstanding call posed
969 970
    # by the sender.

971
    thirdPartyHosted @5 :ThirdPartyCapDescriptor;
972
    # **(level 3)**
Kenton Varda's avatar
Kenton Varda committed
973
    #
974 975
    # A capability that lives in neither the sender's nor the receiver's vat.  The sender needs
    # to form a direct connection to a third party to pick up the capability.
976 977 978
    #
    # Level 1 and 2 implementations that receive a `thirdPartyHosted` may simply send calls to its
    # `vine` instead.
979 980 981 982
  }
}

struct PromisedAnswer {
983 984
  # **(mostly level 1)**
  #
Kenton Varda's avatar
Kenton Varda committed
985
  # Specifies how to derive a promise from an unanswered question, by specifying the path of fields
986
  # to follow from the root of the eventual result struct to get to the desired capability.  Used
Kenton Varda's avatar
Kenton Varda committed
987 988
  # to address method calls to a not-yet-returned capability or to pass such a capability as an
  # input to some other method call.
989 990
  #
  # Level 0 implementations must support `PromisedAnswer` only for the case where the answer is
991
  # to a `Bootstrap` message.  In this case, `path` is always empty since `Bootstrap` always returns
992
  # a raw capability.
Kenton Varda's avatar
Kenton Varda committed
993

994
  questionId @0 :QuestionId;
Kenton Varda's avatar
Kenton Varda committed
995 996
  # ID of the question (in the sender's question table / receiver's answer table) whose answer is
  # expected to contain the capability.
997

998
  transform @1 :List(Op);
999 1000
  # Operations / transformations to apply to the result in order to get the capability actually
  # being addressed.  E.g. if the result is a struct and you want to call a method on a capability
1001 1002 1003
  # pointed to by a field of the struct, you need a `getPointerField` op.

  struct Op {
1004 1005
    union {
      noop @0 :Void;
1006 1007
      # Does nothing.  This member is mostly defined so that we can make `Op` a union even
      # though (as of this writing) only one real operation is defined.
1008

1009 1010 1011
      getPointerField @1 :UInt16;
      # Get a pointer field within a struct.  The number is an index into the pointer section, NOT
      # a field ordinal, so that the receiver does not need to understand the schema.
1012 1013 1014

      # TODO(someday):  We could add:
      # - For lists, the ability to address every member of the list, or a slice of the list, the
1015
      #   result of which would be another list.  This is useful for implementing the equivalent of
1016
      #   a SQL table join (not to be confused with the `Join` message type).
1017
      # - Maybe some ability to test a union.
1018
      # - Probably not a good idea:  the ability to specify an arbitrary script to run on the
1019
      #   result.  We could define a little stack-based language where `Op` specifies one
1020
      #   "instruction" or transformation to apply.  Although this is not a good idea
1021
      #   (over-engineered), any narrower additions to `Op` should be designed as if this
1022 1023 1024
      #   were the eventual goal.
    }
  }
1025 1026 1027
}

struct ThirdPartyCapDescriptor {
1028
  # **(level 3)**
Kenton Varda's avatar
Kenton Varda committed
1029
  #
1030 1031 1032 1033 1034 1035
  # Identifies a capability in a third-party vat which the sender wants the receiver to pick up.

  id @0 :ThirdPartyCapId;
  # Identifies the third-party host and the specific capability to accept from it.

  vineId @1 :ExportId;
1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049
  # A proxy for the third-party object exported by the sender.  In CapTP terminology this is called
  # a "vine", because it is an indirect reference to the third-party object that snakes through the
  # sender vat.  This serves two purposes:
  #
  # * Level 1 and 2 implementations that don't understand how to connect to a third party may
  #   simply send calls to the vine.  Such calls will be forwarded to the third-party by the
  #   sender.
  #
  # * Level 3 implementations must release the vine once they have successfully picked up the
  #   object from the third party.  This ensures that the capability is not released by the sender
  #   prematurely.
  #
  # The sender will close the `Provide` request that it has sent to the third party as soon as
  # it receives either a `Call` or a `Release` message directed at the vine.
1050 1051 1052
}

struct Exception {
1053 1054 1055
  # **(level 0)**
  #
  # Describes an arbitrary error that prevented an operation (e.g. a call) from completing.
1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072
  #
  # Cap'n Proto exceptions always indicate that something went wrong. In other words, in a fantasy
  # world where everything always works as expected, no exceptions would ever be thrown. Clients
  # should only ever catch exceptions as a means to implement fault-tolerance, where "fault" can
  # mean:
  # - Bugs.
  # - Invalid input.
  # - Configuration errors.
  # - Network probles.
  # - Insufficient resources.
  # - Version skew (unimplemented functionality).
  # - Other logistical problems.
  #
  # Exceptions should NOT be used to flag application-specific conditions that a client is expected
  # to handle in an application-specific way. Put another way, in the Cap'n Proto world,
  # "checked exceptions" (where an interface explicitly defines the exceptions it throws and
  # clients are forced by the type system to handle those exceptions) do NOT make sense.
1073

1074 1075 1076
  reason @0 :Text;
  # Human-readable failure description.

1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128
  type @3 :Type;
  # The type of the error. The purpose of this enum is not to describe the error itself, but
  # rather to describe how the client might want to respond to the error.

  enum Type {
    failed @0;
    # A generic problem occurred, and it is believed that if the operation were repeated without
    # any change in the state of the world, the problem would occur again.
    #
    # A client might respond to this error by logging it for investigation by the developer and/or
    # displaying it to the user.

    overloaded @1;
    # The request was rejected due to a temporary lack of resources.
    #
    # Examples include:
    # - There's not enough CPU time to keep up with incoming requests, so some are rejected.
    # - The server ran out of RAM or disk space during the request.
    # - The operation timed out (took significantly longer than it should have).
    #
    # A client might respond to this error by scheduling to retry the operation much later. The
    # client should NOT retry again immediately since this would likely exacerbate the problem.

    disconnected @2;
    # The method failed because a connection to some necessary capability was lost.
    #
    # Examples include:
    # - The client introduced the server to a third-party capability, the connection to that third
    #   party was subsequently lost, and then the client requested that the server use the dead
    #   capability for something.
    # - The client previously requested that the server obtain a capability from some third party.
    #   The server returned a capability to an object wrapping the third-party capability. Later,
    #   the server's connection to the third party was lost.
    # - The capability has been revoked. Revocation does not necessarily mean that the client is
    #   no longer authorized to use the capability; it is often used simply as a way to force the
    #   client to repeat the setup process, perhaps to efficiently move them to a new back-end or
    #   get them to recognize some other change that has occurred.
    #
    # A client should normally respond to this error by releasing all capabilities it is currently
    # holding related to the one it called and then re-creating them by restoring SturdyRefs and/or
    # repeating the method calls used to create them originally. In other words, disconnect and
    # start over. This should in turn cause the server to obtain a new copy of the capability that
    # it lost, thus making everything work.
    #
    # If the client receives another `disconnencted` error in the process of rebuilding the
    # capability and retrying the call, it should treat this as an `overloaded` error: the network
    # is currently unreliable, possibly due to load or other temporary issues.

    unimplemented @3;
    # The server doesn't implement the requested method. If there is some other method that the
    # client could call (perhaps an older and/or slower interface), it should try that instead.
    # Otherwise, this should be treated like `serverError`.
Kenton Varda's avatar
Kenton Varda committed
1129
  }
1130 1131 1132 1133 1134 1135

  obsoleteIsCallersFault @1 :Bool;
  # OBSOLETE. Ignore.

  obsoleteDurability @2 :UInt16;
  # OBSOLETE. See `type` instead.
1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147
}

# ========================================================================================
# Network-specific Parameters
#
# Some parts of the Cap'n Proto RPC protocol are not specified here because different vat networks
# may wish to use different approaches to solving them.  For example, on the public internet, you
# may want to authenticate vats using public-key cryptography, but on a local intranet with trusted
# infrastructure, you may be happy to authenticate based on network address only, or some other
# lightweight mechanism.
#
# To accommodate this, we specify several "parameter" types.  Each type is defined here as an
1148
# alias for `AnyPointer`, but a specific network will want to define a specific set of types to use.
1149 1150 1151 1152 1153 1154
# All vats in a vat network must agree on these parameters in order to be able to communicate.
# Inter-network communication can be accomplished through "gateways" that perform translation
# between the primitives used on each network; these gateways may need to be deeply stateful,
# depending on the translations they perform.
#
# For interaction over the global internet between parties with no other prior arrangement, a
1155
# particular set of bindings for these types is defined elsewhere.  (TODO(someday): Specify where
1156 1157
# these common definitions live.)
#
1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169
# Another common network type is the two-party network, in which one of the parties typically
# interacts with the outside world entirely through the other party.  In such a connection between
# Alice and Bob, all objects that exist on Bob's other networks appear to Alice as if they were
# hosted by Bob himself, and similarly all objects on Alice's network (if she even has one) appear
# to Bob as if they were hosted by Alice.  This network type is interesting because from the point
# of view of a simple application that communicates with only one other party via the two-party
# protocol, there are no three-party interactions at all, and joins are unusually simple to
# implement, so implementing at level 4 is barely more complicated than implementing at level 1.
# Moreover, if you pair an app implementing the two-party network with a container that implements
# some other network, the app can then participate on the container's network just as if it
# implemented that network directly.  The types used by the two-party network are defined in
# `rpc-twoparty.capnp`.
1170 1171
#
# The things which we need to parameterize are:
1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184
# - How to store capabilities long-term without holding a connection open (mostly level 2).
# - How to authenticate vats in three-party introductions (level 3).
# - How to implement `Join` (level 4).
#
# Persistent references
# ---------------------
#
# **(mostly level 2)**
#
# We want to allow some capabilities to be stored long-term, even if a connection is lost and later
# recreated.  ExportId is a short-term identifier that is specific to a connection, so it doesn't
# help here.  We need a way to specify long-term identifiers, as well as a strategy for
# reconnecting to a referenced capability later.
1185 1186 1187 1188
#
# Three-party interactions
# ------------------------
#
1189
# **(level 3)**
1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204
#
# In cases where more than two vats are interacting, we have situations where VatA holds a
# capability hosted by VatB and wants to send that capability to VatC.  This can be accomplished
# by VatA proxying requests on the new capability, but doing so has two big problems:
# - It's inefficient, requiring an extra network hop.
# - If VatC receives another capability to the same object from VatD, it is difficult for VatC to
#   detect that the two capabilities are really the same and to implement the E "join" operation,
#   which is necessary for certain four-or-more-party interactions, such as the escrow pattern.
#   See:  http://www.erights.org/elib/equality/grant-matcher/index.html
#
# Instead, we want a way for VatC to form a direct, authenticated connection to VatB.
#
# Join
# ----
#
1205
# **(level 4)**
1206
#
Kenton Varda's avatar
Kenton Varda committed
1207
# The `Join` message type and corresponding operation arranges for a direct connection to be formed
1208 1209 1210
# between the joiner and the host of the joined object, and this connection must be authenticated.
# Thus, the details are network-dependent.

1211
using SturdyRef = AnyPointer;
1212 1213
# **(level 2)**
#
1214 1215 1216
# Identifies a persisted capability that can be restored in the future. How exactly a SturdyRef
# is restored to a live object is specified along with the SturdyRef definition (i.e. not by
# rpc.capnp).
1217
#
1218 1219 1220 1221 1222 1223 1224
# Generally a SturdyRef needs to specify three things:
# - How to reach the vat that can restore the ref (e.g. a hostname or IP address).
# - How to authenticate the vat after connecting (e.g. a public key fingerprint).
# - The identity of a specific object hosted by the vat. Generally, this is an opaque pointer whose
#   format is defined by the specific vat -- the client has no need to inspect the object ID.
#   It is important that the objec ID be unguessable if the object is not public (and objects
#   should almost never be public).
1225
#
1226 1227 1228 1229
# The above are only suggestions. Some networks might work differently. For example, a private
# network might employ a special restorer service whose sole purpose is to restore SturdyRefs.
# In this case, the entire contents of SturdyRef might be opaque, because they are intended only
# to be forwarded to the restorer service.
1230

1231
using ProvisionId = AnyPointer;
1232
# **(level 3)**
1233
#
Kenton Varda's avatar
Kenton Varda committed
1234
# The information which must be sent in an `Accept` message to identify the object being accepted.
1235 1236
#
# In a network where each vat has a public/private key pair, this could simply be the public key
1237
# fingerprint of the provider vat along with the question ID used in the `Provide` message sent from
1238 1239
# that provider.

1240
using RecipientId = AnyPointer;
1241
# **(level 3)**
1242
#
Kenton Varda's avatar
Kenton Varda committed
1243
# The information which must be sent in a `Provide` message to identify the recipient of the
1244 1245 1246
# capability.
#
# In a network where each vat has a public/private key pair, this could simply be the public key
1247 1248
# fingerprint of the recipient.  (CapTP also calls for a nonce to identify the object.  In our
# case, the `Provide` message's `questionId` can serve as the nonce.)
1249

1250
using ThirdPartyCapId = AnyPointer;
1251
# **(level 3)**
1252 1253 1254 1255 1256
#
# The information needed to connect to a third party and accept a capability from it.
#
# In a network where each vat has a public/private key pair, this could be a combination of the
# third party's public key fingerprint, hints on how to connect to the third party (e.g. an IP
Kenton Varda's avatar
Kenton Varda committed
1257
# address), and the question ID used in the corresponding `Provide` mesasge sent to that third party
1258 1259
# (used to identify which capability to pick up).

1260
using JoinKeyPart = AnyPointer;
1261 1262
# **(level 4)**
#
1263 1264
# A piece of a secret key.  One piece is sent along each path that is expected to lead to the same
# place.  Once the pieces are combined, a direct connection may be formed between the sender and
Kenton Varda's avatar
Kenton Varda committed
1265
# the receiver, bypassing any men-in-the-middle along the paths.  See the `Join` message type.
1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283
#
# The motivation for Joins is discussed under "Supporting Equality" in the "Unibus" protocol
# sketch: http://www.erights.org/elib/distrib/captp/unibus.html
#
# In a network where each vat has a public/private key pair and each vat forms no more than one
# connection to each other vat, Joins will rarely -- perhaps never -- be needed, as objects never
# need to be transparently proxied and references to the same object sent over the same connection
# have the same export ID.  Thus, a successful join requires only checking that the two objects
# come from the same connection and have the same ID, and then completes immediately.
#
# However, in networks where two vats may form more than one connection between each other, or
# where proxying of objects occurs, joins are necessary.
#
# Typically, each JoinKeyPart would include a fixed-length data value such that all value parts
# XOR'd together forms a shared secret which can be used to form an encrypted connection between
# the joiner and the joined object's host.  Each JoinKeyPart should also include an indication of
# how many parts to expect and a hash of the shared secret (used to match up parts).

1284
using JoinResult = AnyPointer;
1285 1286
# **(level 4)**
#
1287
# Information returned as the result to a `Join` message, needed by the joiner in order to form a
Kenton Varda's avatar
Kenton Varda committed
1288 1289 1290
# direct connection to a joined object.  This might simply be the address of the joined object's
# host vat, since the `JoinKey` has already been communicated so the two vats already have a shared
# secret to use to authenticate each other.
1291
#
1292
# The `JoinResult` should also contain information that can be used to detect when the Join
1293 1294
# requests ended up reaching different objects, so that this situation can be detected easily.
# This could be a simple matter of including a sequence number -- if the joiner receives two
1295
# `JoinResult`s with sequence number 0, then they must have come from different objects and the
1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306
# whole join is a failure.

# ========================================================================================
# Network interface sketch
#
# The interfaces below are meant to be pseudo-code to illustrate how the details of a particular
# vat network might be abstracted away.  They are written like Cap'n Proto interfaces, but in
# practice you'd probably define these interfaces manually in the target programming language.  A
# Cap'n Proto RPC implementation should be able to use these interfaces without knowing the
# definitions of the various network-specific parameters defined above.

Kenton Varda's avatar
Kenton Varda committed
1307
# interface VatNetwork {
1308 1309 1310 1311 1312 1313
#   # Represents a vat network, with the ability to connect to particular vats and receive
#   # connections from vats.
#   #
#   # Note that methods returning a `Connection` may return a pre-existing `Connection`, and the
#   # caller is expected to find and share state with existing users of the connection.
#
1314
#   # Level 0 features -----------------------------------------------
1315
#
1316 1317
#   connect(vatId :VatId) :Connection;
#   # Connect to the given vat.  The transport should return a promise which does not
1318 1319 1320 1321
#   # resolve until authentication has completed, but allows messages to be pipelined in before
#   # that; the transport either queues these messages until authenticated, or sends them encrypted
#   # such that only the authentic vat would be able to decrypt them.  The latter approach avoids a
#   # round trip for authentication.
1322
#
1323
#   accept() :Connection;
1324
#   # Wait for the next incoming connection and return it.  Only connections formed by
1325
#   # connect() are returned by this method.
1326
#
1327
#   # Level 4 features -----------------------------------------------
1328
#
1329
#   newJoiner(count :UInt32) :NewJoinerResponse;
1330 1331 1332 1333 1334
#   # Prepare a new Join operation, which will eventually lead to forming a new direct connection
#   # to the host of the joined capability.  `count` is the number of capabilities to join.
#
#   struct NewJoinerResponse {
#     joinKeyParts :List(JoinKeyPart);
Kenton Varda's avatar
Kenton Varda committed
1335
#     # Key parts to send in Join messages to each capability.
1336 1337 1338 1339 1340 1341
#
#     joiner :Joiner;
#     # Used to establish the final connection.
#   }
#
#   interface Joiner {
1342 1343
#     addJoinResult(result :JoinResult) :Void;
#     # Add a JoinResult received in response to one of the `Join` messages.  All `JoinResult`s
Kenton Varda's avatar
Kenton Varda committed
1344
#     # returned from all paths must be added before trying to connect.
1345 1346 1347 1348
#
#     connect() :ConnectionAndProvisionId;
#     # Try to form a connection to the joined capability's host, verifying that it has received
#     # all of the JoinKeyParts.  Once the connection is formed, the caller should send an `Accept`
Kenton Varda's avatar
Kenton Varda committed
1349
#     # message on it with the specified `ProvisionId` in order to receive the final capability.
1350 1351
#   }
#
1352
#   acceptConnectionFromJoiner(parts :List(JoinKeyPart), paths :List(VatPath))
1353 1354
#       :ConnectionAndProvisionId;
#   # Called on a joined capability's host to receive the connection from the joiner, once all
Kenton Varda's avatar
Kenton Varda committed
1355
#   # key parts have arrived.  The caller should expect to receive an `Accept` message over the
1356 1357 1358 1359
#   # connection with the given ProvisionId.
# }
#
# interface Connection {
1360
#   # Level 0 features -----------------------------------------------
1361
#
Kenton Varda's avatar
Kenton Varda committed
1362 1363 1364
#   send(message :Message) :Void;
#   # Send the message.  Returns successfully when the message (and all preceding messages) has
#   # been acknowledged by the recipient.
1365
#
Kenton Varda's avatar
Kenton Varda committed
1366 1367 1368
#   receive() :Message;
#   # Receive the next message, and acknowledges receipt to the sender.  Messages are received in
#   # the order in which they are sent.
1369
#
1370
#   # Level 3 features -----------------------------------------------
1371 1372
#
#   introduceTo(recipient :Connection) :IntroductionInfo;
Kenton Varda's avatar
Kenton Varda committed
1373
#   # Call before starting a three-way introduction, assuming a `Provide` message is to be sent on
1374 1375 1376 1377 1378 1379 1380
#   # this connection and a `ThirdPartyCapId` is to be sent to `recipient`.
#
#   struct IntroductionInfo {
#     sendToRecipient :ThirdPartyCapId;
#     sendToTarget :RecipientId;
#   }
#
1381
#   connectToIntroduced(capId :ThirdPartyCapId) :ConnectionAndProvisionId;
1382
#   # Given a ThirdPartyCapId received over this connection, connect to the third party.  The
Kenton Varda's avatar
Kenton Varda committed
1383
#   # caller should then send an `Accept` message over the new connection.
1384
#
1385
#   acceptIntroducedConnection(recipientId :RecipientId) :Connection;
Kenton Varda's avatar
Kenton Varda committed
1386 1387 1388
#   # Given a RecipientId received in a `Provide` message on this `Connection`, wait for the
#   # recipient to connect, and return the connection formed.  Usually, the first message received
#   # on the new connection will be an `Accept` message.
1389 1390
# }
#
1391
# struct ConnectionAndProvisionId {
1392 1393
#   # **(level 3)**
#
1394
#   connection :Connection;
Kenton Varda's avatar
Kenton Varda committed
1395
#   # Connection on which to issue `Accept` message.
1396 1397
#
#   provision :ProvisionId;
Kenton Varda's avatar
Kenton Varda committed
1398
#   # `ProvisionId` to send in the `Accept` message.
1399
# }