| // Copyright 2015 The Vanadium Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style |
| // license that can be found in the LICENSE file. |
| |
| // Package proxy implements a proxy for the stream layer. |
| // |
| // Each process in vanadium is uniquely identified by a routing id |
| // (naming.RoutingID). A proxy routes messages |
| // (v.io/x/ref/runtime/internal/rpc/stream/message) it receives on a network connection |
| // (net.Conn) to the network connection on which the destination process |
| // (identified by the routing id) is listening. |
| // |
| // Processes behind a NAT can use the proxy to export their services outside |
| // the NAT. |
| // Sample usage: |
| // var proxyEP naming.Endpoint // Endpoint of the proxy server |
| // var manager stream.Manager // Manager used to create and listen for VCs and Flows. |
| // ln, ep, err := manager.Listen(proxyEP.Network(), proxyEP.String()) |
| // // Now ln.Accept() will return Flows initiated by remote processes through the proxy. |
| // |
| // The proxy implemented in this package operates as follows: |
| // - When an OpenVC message is received at the proxy, the RoutingID(R) |
| // of the source endpoint is associated with the net.Conn the message |
| // was received on. |
| // - This association is used to route messages destined for R to the |
| // corresponding net.Conn |
| // - Servers can "listen" on the proxy's address by establishing a VC to the |
| // proxy. Once the VC is established, messages received at the proxy destined |
| // for the RoutingID of the server are forwarded to the net.Conn between the |
| // server and the proxy. |
| // |
| // For example, consider the following three processes: |
| // - Proxy(P) with routing id Rp |
| // - A server (S) wishing to listen on the proxy's address with routing id Rs |
| // - A client (C) wishing to connect to S through the proxy with routing id Rc. |
| // |
| // Here is a valid sequence of events that makes that possible: |
| // (1) S establishes a VC with P over a net.Conn c1 |
| // As a result, P knows that any messages intended for Rs should be |
| // forwarded on c1 |
| // (2) C connects to P over a net.Conn c2 and attempts to establish a VC with S |
| // using an OpenVC message. |
| // The source endpoint of this message contains the routing id Rc while the |
| // destination endpoint contains the routing id Rs. |
| // (3) The proxy sees this message and: |
| // (a) Forwards the message over c1 (since Rs is mapped to c1) |
| // (b) Updates its routing table so that messages intended for Rc are forwarded over c2 |
| // (4) Any messages from S intended for the client received on c1 are forwarded |
| // by the proxy over c2. |
| package proxy |
