Chris@50: # Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors
Chris@50: # Licensed under the MIT License:
Chris@50: #
Chris@50: # Permission is hereby granted, free of charge, to any person obtaining a copy
Chris@50: # of this software and associated documentation files (the "Software"), to deal
Chris@50: # in the Software without restriction, including without limitation the rights
Chris@50: # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
Chris@50: # copies of the Software, and to permit persons to whom the Software is
Chris@50: # furnished to do so, subject to the following conditions:
Chris@50: #
Chris@50: # The above copyright notice and this permission notice shall be included in
Chris@50: # all copies or substantial portions of the Software.
Chris@50: #
Chris@50: # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
Chris@50: # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
Chris@50: # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
Chris@50: # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
Chris@50: # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
Chris@50: # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
Chris@50: # THE SOFTWARE.
Chris@50: 
Chris@50: @0xa184c7885cdaf2a1;
Chris@50: # This file defines the "network-specific parameters" in rpc.capnp to support a network consisting
Chris@50: # of two vats.  Each of these vats may in fact be in communication with other vats, but any
Chris@50: # capabilities they forward must be proxied.  Thus, to each end of the connection, all capabilities
Chris@50: # received from the other end appear to live in a single vat.
Chris@50: #
Chris@50: # Two notable use cases for this model include:
Chris@50: # - Regular client-server communications, where a remote client machine (perhaps living on an end
Chris@50: #   user's personal device) connects to a server.  The server may be part of a cluster, and may
Chris@50: #   call on other servers in the cluster to help service the user's request.  It may even obtain
Chris@50: #   capabilities from these other servers which it passes on to the user.  To simplify network
Chris@50: #   common traversal problems (e.g. if the user is behind a firewall), it is probably desirable to
Chris@50: #   multiplex all communications between the server cluster and the client over the original
Chris@50: #   connection rather than form new ones.  This connection should use the two-party protocol, as
Chris@50: #   the client has no interest in knowing about additional servers.
Chris@50: # - Applications running in a sandbox.  A supervisor process may execute a confined application
Chris@50: #   such that all of the confined app's communications with the outside world must pass through
Chris@50: #   the supervisor.  In this case, the connection between the confined app and the supervisor might
Chris@50: #   as well use the two-party protocol, because the confined app is intentionally prevented from
Chris@50: #   talking to any other vat anyway.  Any external resources will be proxied through the supervisor,
Chris@50: #   and so to the contained app will appear as if they were hosted by the supervisor itself.
Chris@50: #
Chris@50: # Since there are only two vats in this network, there is never a need for three-way introductions,
Chris@50: # so level 3 is free.  Moreover, because it is never necessary to form new connections, the
Chris@50: # two-party protocol can be used easily anywhere where a two-way byte stream exists, without regard
Chris@50: # to where that byte stream goes or how it was initiated.  This makes the two-party runtime library
Chris@50: # highly reusable.
Chris@50: #
Chris@50: # Joins (level 4) _could_ be needed in cases where one or both vats are participating in other
Chris@50: # networks that use joins.  For instance, if Alice and Bob are speaking through the two-party
Chris@50: # protocol, and Bob is also participating on another network, Bob may send Alice two or more
Chris@50: # proxied capabilities which, unbeknownst to Bob at the time, are in fact pointing at the same
Chris@50: # remote object.  Alice may then request to join these capabilities, at which point Bob will have
Chris@50: # to forward the join to the other network.  Note, however, that if Alice is _not_ participating on
Chris@50: # any other network, then Alice will never need to _receive_ a Join, because Alice would always
Chris@50: # know when two locally-hosted capabilities are the same and would never export a redundant alias
Chris@50: # to Bob.  So, Alice can respond to all incoming joins with an error, and only needs to implement
Chris@50: # outgoing joins if she herself desires to use this feature.  Also, outgoing joins are relatively
Chris@50: # easy to implement in this scenario.
Chris@50: #
Chris@50: # What all this means is that a level 4 implementation of the confined network is barely more
Chris@50: # complicated than a level 2 implementation.  However, such an implementation allows the "client"
Chris@50: # or "confined" app to access the server's/supervisor's network with equal functionality to any
Chris@50: # native participant.  In other words, an application which implements only the two-party protocol
Chris@50: # can be paired with a proxy app in order to participate in any network.
Chris@50: #
Chris@50: # So, when implementing Cap'n Proto in a new language, it makes sense to implement only the
Chris@50: # two-party protocol initially, and then pair applications with an appropriate proxy written in
Chris@50: # C++, rather than implement other parameterizations of the RPC protocol directly.
Chris@50: 
Chris@50: using Cxx = import "/capnp/c++.capnp";
Chris@50: $Cxx.namespace("capnp::rpc::twoparty");
Chris@50: 
Chris@50: # Note: SturdyRef is not specified here. It is up to the application to define semantics of
Chris@50: # SturdyRefs if desired.
Chris@50: 
Chris@50: enum Side {
Chris@50:   server @0;
Chris@50:   # The object lives on the "server" or "supervisor" end of the connection. Only the
Chris@50:   # server/supervisor knows how to interpret the ref; to the client, it is opaque.
Chris@50:   #
Chris@50:   # Note that containers intending to implement strong confinement should rewrite SturdyRefs
Chris@50:   # received from the external network before passing them on to the confined app. The confined
Chris@50:   # app thus does not ever receive the raw bits of the SturdyRef (which it could perhaps
Chris@50:   # maliciously leak), but instead receives only a thing that it can pass back to the container
Chris@50:   # later to restore the ref. See:
Chris@50:   # http://www.erights.org/elib/capability/dist-confine.html
Chris@50: 
Chris@50:   client @1;
Chris@50:   # The object lives on the "client" or "confined app" end of the connection. Only the client
Chris@50:   # knows how to interpret the ref; to the server/supervisor, it is opaque. Most clients do not
Chris@50:   # actually know how to persist capabilities at all, so use of this is unusual.
Chris@50: }
Chris@50: 
Chris@50: struct VatId {
Chris@50:   side @0 :Side;
Chris@50: }
Chris@50: 
Chris@50: struct ProvisionId {
Chris@50:   # Only used for joins, since three-way introductions never happen on a two-party network.
Chris@50: 
Chris@50:   joinId @0 :UInt32;
Chris@50:   # The ID from `JoinKeyPart`.
Chris@50: }
Chris@50: 
Chris@50: struct RecipientId {}
Chris@50: # Never used, because there are only two parties.
Chris@50: 
Chris@50: struct ThirdPartyCapId {}
Chris@50: # Never used, because there is no third party.
Chris@50: 
Chris@50: struct JoinKeyPart {
Chris@50:   # Joins in the two-party case are simplified by a few observations.
Chris@50:   #
Chris@50:   # First, on a two-party network, a Join only ever makes sense if the receiving end is also
Chris@50:   # connected to other networks.  A vat which is not connected to any other network can safely
Chris@50:   # reject all joins.
Chris@50:   #
Chris@50:   # Second, since a two-party connection bisects the network -- there can be no other connections
Chris@50:   # between the networks at either end of the connection -- if one part of a join crosses the
Chris@50:   # connection, then _all_ parts must cross it.  Therefore, a vat which is receiving a Join request
Chris@50:   # off some other network which needs to be forwarded across the two-party connection can
Chris@50:   # collect all the parts on its end and only forward them across the two-party connection when all
Chris@50:   # have been received.
Chris@50:   #
Chris@50:   # For example, imagine that Alice and Bob are vats connected over a two-party connection, and
Chris@50:   # each is also connected to other networks.  At some point, Alice receives one part of a Join
Chris@50:   # request off her network.  The request is addressed to a capability that Alice received from
Chris@50:   # Bob and is proxying to her other network.  Alice goes ahead and responds to the Join part as
Chris@50:   # if she hosted the capability locally (this is important so that if not all the Join parts end
Chris@50:   # up at Alice, the original sender can detect the failed Join without hanging).  As other parts
Chris@50:   # trickle in, Alice verifies that each part is addressed to a capability from Bob and continues
Chris@50:   # to respond to each one.  Once the complete set of join parts is received, Alice checks if they
Chris@50:   # were all for the exact same capability.  If so, she doesn't need to send anything to Bob at
Chris@50:   # all.  Otherwise, she collects the set of capabilities (from Bob) to which the join parts were
Chris@50:   # addressed and essentially initiates a _new_ Join request on those capabilities to Bob.  Alice
Chris@50:   # does not forward the Join parts she received herself, but essentially forwards the Join as a
Chris@50:   # whole.
Chris@50:   #
Chris@50:   # On Bob's end, since he knows that Alice will always send all parts of a Join together, he
Chris@50:   # simply waits until he's received them all, then performs a join on the respective capabilities
Chris@50:   # as if it had been requested locally.
Chris@50: 
Chris@50:   joinId @0 :UInt32;
Chris@50:   # A number identifying this join, chosen by the sender.  May be reused once `Finish` messages are
Chris@50:   # sent corresponding to all of the `Join` messages.
Chris@50: 
Chris@50:   partCount @1 :UInt16;
Chris@50:   # The number of capabilities to be joined.
Chris@50: 
Chris@50:   partNum @2 :UInt16;
Chris@50:   # Which part this request targets -- a number in the range [0, partCount).
Chris@50: }
Chris@50: 
Chris@50: struct JoinResult {
Chris@50:   joinId @0 :UInt32;
Chris@50:   # Matches `JoinKeyPart`.
Chris@50: 
Chris@50:   succeeded @1 :Bool;
Chris@50:   # All JoinResults in the set will have the same value for `succeeded`.  The receiver actually
Chris@50:   # implements the join by waiting for all the `JoinKeyParts` and then performing its own join on
Chris@50:   # them, then going back and answering all the join requests afterwards.
Chris@50: 
Chris@50:   cap @2 :AnyPointer;
Chris@50:   # One of the JoinResults will have a non-null `cap` which is the joined capability.
Chris@50:   #
Chris@50:   # TODO(cleanup):  Change `AnyPointer` to `Capability` when that is supported.
Chris@50: }