ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-06-15 21:58:17 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Regen docsite

Browse Source
This commit is contained in:
Clinton Alexander
2017-01-03 13:07:48 +00:00
parent e34f33785f
commit f92ef3d9cf
248 changed files with 4998 additions and 1169 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
docs/build/html/messaging.html vendored
View File

@ -1,3 +1,7 @@
<!-- If you edit this, then please make the same changes to layout_for_doc_website.html, as that is used for the web
doc site generation which we put analytics tracking on to identify any potential problem pages -->
<!DOCTYPE html>
@ -78,6 +82,11 @@
<br>
<a href="api/index.html">API reference</a>
<br>
<a href="https://discourse.corda.net">Discourse Forums</a>
<br>
<a href="http://slack.corda.net">Slack</a>
<br>
</div>
@ -107,15 +116,18 @@
<li class="toctree-l1"><a class="reference internal" href="creating-a-cordapp.html#gradle-plugins-for-cordapps">Gradle plugins for CorDapps</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-cordapp.html">The CorDapp Template</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-cordapp.html#building-the-cordapp-template">Building the CorDapp template</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-cordapp.html#running-the-sample-cordapp">Running the Sample CorDapp</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-cordapp.html#using-the-sample-cordapp">Using the sample CorDapp</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-cordapp.html#running-the-cordapp-template">Running the CorDapp template</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-cordapp.html#interacting-with-the-cordapp-template">Interacting with the CorDapp template</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial-cordapp.html#extending-the-cordapp-template">Extending the CorDapp template</a></li>
</ul>
<p class="caption"><span class="caption-text">The Corda node</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="clientrpc.html">Client RPC</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Networking and messaging</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#messaging-types">Messaging types</a></li>
<li class="toctree-l2"><a class="reference internal" href="#network-map-service">Network Map Service</a></li>
<li class="toctree-l2"><a class="reference internal" href="#message-queues">Message queues</a></li>
<li class="toctree-l2"><a class="reference internal" href="#security">Security</a></li>
<li class="toctree-l2"><a class="reference internal" href="#messaging-types">Messaging types</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="persistence.html">Persistence</a></li>
@ -165,6 +177,8 @@
<li class="toctree-l1"><a class="reference internal" href="release-notes.html">Release notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="codestyle.html">Code style guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="building-the-docs.html">Building the documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="publishing-corda.html">Publishing Corda</a></li>
<li class="toctree-l1"><a class="reference internal" href="azure-vm.html">Working with the Corda Demo on Azure Marketplace</a></li>
</ul>
<p class="caption"><span class="caption-text">Glossary</span></p>
<ul>
@ -230,14 +244,6 @@ out for alternative implementations.</p>
messaging subsystem directly. Instead you will build on top of the <a class="reference internal" href="flow-state-machines.html"><span class="doc">flow framework</span></a>,
which adds a layer on top of raw messaging to manage multi-step flows and let you think in terms of identities
rather than specific network endpoints.</p>
<div class="section" id="messaging-types">
<h2>Messaging types<a class="headerlink" href="#messaging-types" title="Permalink to this headline"></a></h2>
<p>Every <code class="docutils literal"><span class="pre">Message</span></code> object has an associated <em>topic</em> and may have a <em>session ID</em>. These are wrapped in a <code class="docutils literal"><span class="pre">TopicSession</span></code>.
An implementation of <code class="docutils literal"><span class="pre">MessagingService</span></code> can be used to create messages and send them. You can get access to the
messaging service via the <code class="docutils literal"><span class="pre">ServiceHub</span></code> object that is provided to your app. Endpoints on the network are
identified at the lowest level using <code class="docutils literal"><span class="pre">SingleMessageRecipient</span></code> which may be e.g. an IP address, or in future
versions perhaps a routing path through the network.</p>
</div>
<div class="section" id="network-map-service">
<span id="id1"></span><h2>Network Map Service<a class="headerlink" href="#network-map-service" title="Permalink to this headline"></a></h2>
<p>Supporting the messaging layer is a network map service, which is responsible for tracking public nodes on the network.</p>
@ -253,10 +259,85 @@ requested to be notified of changes.</p>
<li>Looking up nodes by service</li>
<li>Looking up node for a party</li>
<li>Suggesting a node providing a specific service, based on suitability for a contract and parties, for example suggesting
an appropriate interest rates oracle for a interest rate swap contract. Currently no recommendation logic is in place.
The code simply picks the first registered node that supports the required service.</li>
an appropriate interest rates oracle for a interest rate swap contract. Currently no recommendation logic is in place.</li>
</ul>
</div>
<div class="section" id="message-queues">
<h2>Message queues<a class="headerlink" href="#message-queues" title="Permalink to this headline"></a></h2>
<p>The node makes use of various queues for its operation. The more important ones are described below. Others are used
for maintenance and other minor purposes.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name"><code class="docutils literal"><span class="pre">p2p.inbound</span></code>:</th><td class="field-body">The node listens for messages sent from other peer nodes on this queue. Only clients who are authenticated to be
nodes on the same network are given permission to send. Messages which are routed internally are also sent to this
queue (e.g. two flows on the same node communicating with each other).</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2"><code class="docutils literal"><span class="pre">internal.peers.$identity</span></code>:</th></tr>
<tr class="field-even field"><td>&nbsp;</td><td class="field-body">These are a set of private queues only available to the node which it uses to route messages destined to other peers.
The queue name ends in the base 58 encoding of the peer&#8217;s identity key. There is at most one queue per peer. The broker
creates a bridge from this queue to the peer&#8217;s <code class="docutils literal"><span class="pre">p2p.inbound</span></code> queue, using the network map service to lookup the
peer&#8217;s network address.</td>
</tr>
<tr class="field-odd field"><th class="field-name" colspan="2"><code class="docutils literal"><span class="pre">internal.services.$identity</span></code>:</th></tr>
<tr class="field-odd field"><td>&nbsp;</td><td class="field-body">These are private queues the node may use to route messages to services. The queue name ends in the base 58 encoding
of the service&#8217;s owning identity key. There is at most one queue per service identity (but note that any one service
may have several identities). The broker creates bridges to all nodes in the network advertising the service in
question. When a session is initiated with a service counterparty the handshake is pushed onto this queue, and a
corresponding bridge is used to forward the message to an advertising peer&#8217;s p2p queue. Once a peer is picked the
session continues on as normal.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2"><code class="docutils literal"><span class="pre">internal.networkmap</span></code>:</th></tr>
<tr class="field-even field"><td>&nbsp;</td><td class="field-body">This is another private queue just for the node which functions in a similar manner to the <code class="docutils literal"><span class="pre">internal.peers.*</span></code> queues
except this is used to form a connection to the network map node. The node running the network map service is treated
differently as it provides information about the rest of the network.</td>
</tr>
<tr class="field-odd field"><th class="field-name"><code class="docutils literal"><span class="pre">rpc.requests</span></code>:</th><td class="field-body">RPC clients send their requests here, and it&#8217;s only open for sending by clients authenticated as RPC users.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2"><code class="docutils literal"><span class="pre">clients.$user.rpc.$random</span></code>:</th></tr>
<tr class="field-even field"><td>&nbsp;</td><td class="field-body">RPC clients are given permission to create a temporary queue incorporating their username (<code class="docutils literal"><span class="pre">$user</span></code>) and sole
permission to receive messages from it. RPC requests are required to include a random number (<code class="docutils literal"><span class="pre">$random</span></code>) from
which the node is able to construct the queue the user is listening on and send the response to that. This mechanism
prevents other users from being able listen in on the responses.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="security">
<h2>Security<a class="headerlink" href="#security" title="Permalink to this headline"></a></h2>
<p>Clients attempting to connect to the node&#8217;s broker fall in one of four groups:</p>
<ol class="arabic simple">
<li>Anyone connecting with the username <code class="docutils literal"><span class="pre">SystemUsers/Node</span></code> is treated as the node hosting the broker, or a logical
component of the node. The TLS certificate they provide must match the one broker has for the node. If that&#8217;s the case
they are given full access to all valid queues, otherwise they are rejected.</li>
<li>Anyone connecting with the username <code class="docutils literal"><span class="pre">SystemUsers/Peer</span></code> is treated as a peer on the same Corda network as the node. Their
TLS root CA must be the same as the node&#8217;s root CA - the root CA is the doorman of the network and having the same root CA
implies we&#8217;ve been let in by the same doorman. If they are part of the same network then they are only given permission
to send to our <code class="docutils literal"><span class="pre">p2p.inbound</span></code> queue, otherwise they are rejected.</li>
<li>Every other username is treated as a RPC user and authenticated against the node&#8217;s list of valid RPC users. If that
is successful then they are only given sufficient permission to perform RPC, otherwise they are rejected.</li>
<li>Clients connecting without a username and password are rejected.</li>
</ol>
<p>Artemis provides a feature of annotating each received message with the validated user. This allows the node&#8217;s messaging
service to provide authenticated messages to the rest of the system. For the first two client types described above the
validated user is the X.500 subject DN of the client TLS certificate and we assume the common name is the legal name of
the peer. This allows the flow framework to authentically determine the <code class="docutils literal"><span class="pre">Party</span></code> initiating a new flow. For RPC clients
the validated user is the username itself and the RPC framework uses this to determine what permissions the user has.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><code class="docutils literal"><span class="pre">Party</span></code> lookup is currently done by the legal name which isn&#8217;t guaranteed to be unique. A future version will
use the full X.500 name as it can provide additional structures for uniqueness.</p>
</div>
</div>
<div class="section" id="messaging-types">
<h2>Messaging types<a class="headerlink" href="#messaging-types" title="Permalink to this headline"></a></h2>
<p>Every <code class="docutils literal"><span class="pre">Message</span></code> object has an associated <em>topic</em> and may have a <em>session ID</em>. These are wrapped in a <code class="docutils literal"><span class="pre">TopicSession</span></code>.
An implementation of <code class="docutils literal"><span class="pre">MessagingService</span></code> can be used to create messages and send them. You can get access to the
messaging service via the <code class="docutils literal"><span class="pre">ServiceHub</span></code> object that is provided to your app. Endpoints on the network are
identified at the lowest level using <code class="docutils literal"><span class="pre">SingleMessageRecipient</span></code> which may be e.g. an IP address, or in future
versions perhaps a routing path through the network.</p>
</div>
</div>