c++/src/capnp/rpc-twoparty.capnp - toolchain/capnproto - Git at Google

 # 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.
 }
	# 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.
	}