comparison win64-msvc/include/capnp/rpc-twoparty.capnp @ 47:d93140aac40b

Current Capnp libs and headers from git

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