ARCHIVE/rippled
1
0
Fork 0
mirror of https://github.com/XRPLF/rippled.git synced 2025-11-20 11:05:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add missing README and TODO for all new modules

Browse Source
This commit is contained in:
Vinnie Falco
2013-11-15 11:27:26 -08:00
parent 29aa462bfd
commit 9e519af887
23 changed files with 345 additions and 194 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
Builds/VisualStudio2012/RippleD.vcxproj
View File

@@ -2088,12 +2088,16 @@
<None Include="..\..\doc\Doxyfile" />
<None Include="..\..\doc\rippled-example.cfg" />
<None Include="..\..\LICENSE" />
<None Include="..\..\src\ripple\algorithm\README.md" />
<None Include="..\..\src\ripple\algorithm\TODO.md" />
<None Include="..\..\src\ripple\beast\ripple_beastobjc.mm">
<ExcludedFromBuild Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">true</ExcludedFromBuild>
<ExcludedFromBuild Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">true</ExcludedFromBuild>
<ExcludedFromBuild Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">true</ExcludedFromBuild>
<ExcludedFromBuild Condition="'$(Configuration)|$(Platform)'=='Release|x64'">true</ExcludedFromBuild>
</None>
<None Include="..\..\src\ripple\http\README.md" />
<None Include="..\..\src\ripple\http\TODO.md" />
<None Include="..\..\src\ripple\json\impl\json_internalarray.inl" />
<None Include="..\..\src\ripple\json\impl\json_internalmap.inl" />
<None Include="..\..\src\ripple\json\impl\json_valueiterator.inl" />
@@ -2101,8 +2105,23 @@
<None Include="..\..\src\ripple\json\impl\version" />
<None Include="..\..\README.md" />
<None Include="..\..\SConstruct" />
<None Include="..\..\src\ripple\json\README.md" />
<None Include="..\..\src\ripple\json\TODO.md" />
<None Include="..\..\src\ripple\peerfinder\README.md" />
<None Include="..\..\src\ripple\peerfinder\TODO.md" />
<None Include="..\..\src\ripple\resource\README.md" />
<None Include="..\..\src\ripple\resource\TODO.md" />
<None Include="..\..\src\ripple\rpc\README.md" />
<None Include="..\..\src\ripple\rpc\TODO.md" />
<None Include="..\..\src\ripple\sitefiles\README.md" />
<None Include="..\..\src\ripple\sitefiles\TODO.md" />
<None Include="..\..\src\ripple\sslutil\README.md" />
<None Include="..\..\src\ripple\sslutil\TODO.md" />
<None Include="..\..\src\ripple\testoverlay\README.md" />
<None Include="..\..\src\ripple\testoverlay\TODO.md" />
<None Include="..\..\src\ripple\types\README.md" />
<None Include="..\..\src\ripple\types\TODO.md" />
<None Include="..\..\src\ripple\validators\TODO.md" />
<None Include="..\QtCreator\rippled.pro" />
</ItemGroup>
<ItemGroup>

57
Builds/VisualStudio2012/RippleD.vcxproj.filters
View File

@@ -2407,6 +2407,63 @@
<None Include="..\..\src\ripple\testoverlay\README.md">
<Filter>[1] Ripple\testoverlay</Filter>
</None>
<None Include="..\..\src\ripple\peerfinder\TODO.md">
<Filter>[1] Ripple\peerfinder</Filter>
</None>
<None Include="..\..\src\ripple\validators\TODO.md">
<Filter>[1] Ripple\validators</Filter>
</None>
<None Include="..\..\src\ripple\resource\TODO.md">
<Filter>[1] Ripple\resource</Filter>
</None>
<None Include="..\..\src\ripple\resource\README.md">
<Filter>[1] Ripple\resource</Filter>
</None>
<None Include="..\..\src\ripple\types\README.md">
<Filter>[1] Ripple\types</Filter>
</None>
<None Include="..\..\src\ripple\types\TODO.md">
<Filter>[1] Ripple\types</Filter>
</None>
<None Include="..\..\src\ripple\testoverlay\TODO.md">
<Filter>[1] Ripple\testoverlay</Filter>
</None>
<None Include="..\..\src\ripple\algorithm\README.md">
<Filter>[1] Ripple\algorithm</Filter>
</None>
<None Include="..\..\src\ripple\algorithm\TODO.md">
<Filter>[1] Ripple\algorithm</Filter>
</None>
<None Include="..\..\src\ripple\http\README.md">
<Filter>[1] Ripple\http</Filter>
</None>
<None Include="..\..\src\ripple\http\TODO.md">
<Filter>[1] Ripple\http</Filter>
</None>
<None Include="..\..\src\ripple\json\README.md">
<Filter>[1] Ripple\json</Filter>
</None>
<None Include="..\..\src\ripple\json\TODO.md">
<Filter>[1] Ripple\json</Filter>
</None>
<None Include="..\..\src\ripple\rpc\README.md">
<Filter>[1] Ripple\rpc</Filter>
</None>
<None Include="..\..\src\ripple\rpc\TODO.md">
<Filter>[1] Ripple\rpc</Filter>
</None>
<None Include="..\..\src\ripple\sitefiles\README.md">
<Filter>[1] Ripple\sitefiles</Filter>
</None>
<None Include="..\..\src\ripple\sitefiles\TODO.md">
<Filter>[1] Ripple\sitefiles</Filter>
</None>
<None Include="..\..\src\ripple\sslutil\README.md">
<Filter>[1] Ripple\sslutil</Filter>
</None>
<None Include="..\..\src\ripple\sslutil\TODO.md">
<Filter>[1] Ripple\sslutil</Filter>
</None>
</ItemGroup>
<ItemGroup>
<Text Include="..\..\doc\todo\NIKB_TODO.txt">

3
src/ripple/algorithm/README.md Normal file
View File

@@ -0,0 +1,3 @@
# Algorithm
Various utility classes

5
src/ripple/algorithm/TODO.md Normal file
View File

@@ -0,0 +1,5 @@
# Algorithm TODO
- Rethink the CycledSet (and cousin AgedCache). Make each element part
of an intrusive linked list, add a DiscreteClock data member, and
perform aging on each insertion or sweep rather than once in a while.

6
src/ripple/http/README.md Normal file
View File

@@ -0,0 +1,6 @@
# HTTP Server
A generic HTTP server. This is used for doing asynchronous RPC
currently, although it could be expanded to perform more activities
such as reporting to the elastic load balancer or providing server
statistics.

1
src/ripple/http/TODO.md Normal file
View File

@@ -0,0 +1 @@
# HTTP Server TODO

3
src/ripple/json/README.md Normal file
View File

@@ -0,0 +1,3 @@
# JSON
Third party library to do JSON operations.

7
src/ripple/json/TODO.md Normal file
View File

@@ -0,0 +1,7 @@
# JSON TODO
- Investigate other third party libraries, especially those that are
proven hardened against attacks, or perform better
- Implement canonical JSON API to do signing

191
src/ripple/peerfinder/README.md
View File

@@ -30,3 +30,194 @@ The PeerFinder module has these responsibilities:
</td>
</tr>
</table>
### Exposition
(Formerly in Manager.cpp, needs to be reformatted and tidied)
PeerFinder
----------
Implements the logic for announcing and discovering IP addresses for
for connecting into the Ripple network.
Introduction
------------
Each Peer (a computer running rippled) on the Ripple network requires a certain
number of connections to other peers. These connections form an "overlay
network." When a new peer wants to join the network, they need a robust source
of network addresses (IP addresses) in order to establish outgoing connections.
Once they have joined the network, they need a method of announcing their
availaibility of accepting incoming connections.
The Ripple network, like all peer to peer networks, defines a "directed graph"
where each node represents a computer running the rippled software, and each
vertex indicates a network connection. The direction of the connection tells
us whether it is an outbound or inbound connection (from the perspective of
a particular node).
Fact #1:
The total inbound and outbound connections of any overlay must be equal.
This follows that for each node that has an established outbound connection,
there must exist another node that has received the corresponding inbound
connection.
When a new peer joins the network it may or may not wish to receive inbound
connections. Some peers are unable to accept incoming connections for various.
For security reasons they may be behind a firewall that blocks accept requests.
The administers may decide they don't want the connection traffic. Or they
may wish to connect only to specific peers. Or they may simply be misconfigured.
If a peer decides that it wishes to receive incoming connections, it needs
a method to announce its IP address and port number, the features that it
offers (for example, that it also services client requests), and the number
of available connection slots. This is to handle the case where the peer
reaches its desired number of peer connections, but may still want to inform
the network that it will service clients. It may also be desired to indicate
the number of free client slots.
Once a peer is connected to the network we need a way both to inform our
neighbors of our status with respect to accepting connections, and also to
learn about new fresh addresses to connect to. For this we will define the
mtENDPOINTS message.
"Bootstrap Strategy"
--------------------
Nouns:
bootstrap_ip
numeric IPAddress
bootstrap_domain
domain name / port combinations, resolution only
bootstrap_url
URL leading to a text file, with a series of entries.
ripple.txt
Separately parsed entity outside of PeerFinder that can provide
bootstrap_ip, bootstrap_domain, and bootstrap_url items.
The process of obtaining the initial peer connections for accessing the Ripple
peer to peer network, when there are no current connections, is called
"bootstrapping." The algorithm is as follows:
1. If ( unusedLiveEndpoints.count() > 0
OR activeConnectionAttempts.count() > 0)
Try addresses from unusedLiveEndpoints
return;
2. If ( domainNames.count() > 0 AND (
unusedBootstrapIPs.count() == 0
OR activeNameResolutions.count() > 0) )
ForOneOrMore (DomainName that hasn't been resolved recently)
Contact DomainName and add entries to the unusedBootstrapIPs
return;
3. If (unusedBootstrapIPs.count() > 0)
Try addresses from unusedBootstrapIPs
return;
4. Try entries from [ips]
5. Try entries from [ips_urls]
6. Increment generation number and go to 1
- Keep a map of all current outgoing connection attempts
"Connection Strategy"
---------------------
This is the overall strategy a peer uses to maintain its position in the Ripple
network graph
We define these values:
peerCount (calculated)
The number of currently connected and established peers
outCount (calculated)
The number of peers in PeerCount that are outbound connections.
MinOutCount (hard-coded constant)
The minimum number of OutCount we want. This also puts a floor
on PeerCount. This protects against sybil attacks and makes
sure that ledgers can get retrieved reliably.
10 is the proposed value.
MaxPeerCount (a constant set in the rippled.cfg)
The maximum number of peer connections, inbound or outbound,
that a peer wishes to maintain. Setting MaxPeerCount equal to
or below MinOutCount would disallow incoming connections.
OutPercent (a baked-in program constant for now)
The peer's target value for OutCount. When the value of OutCount
is below this number, the peer will employ the Outgoing Strategy
to raise its value of OutCount. This value is initially a constant
in the program, defined by the developers. However, it
may be changed through the consensus process.
15% is a proposed value.
However, lets consider the case where OutDesired is exactly equal to MaxPeerCount / 2.
In this case, a stable state will be reached when every peer is full, and
has exactly the same number of inbound and outbound connections. The problem
here is that there are now no available incoming connection slots. No new
peers can enter the network.
Lets consider the case where OutDesired is exactly equal to (MaxPeerCount / 2) - 1.
The stable state for this network (assuming all peers can accept incoming) will
leave us with network degree equal to MaxPeerCount - 2, with all peers having two
available incoming connection slots. The global number of incoming connection slots
will be equal to twice the number of nodes on the network. While this might seem to
be a desirable outcome, note that the connectedness (degree of the overlay) plays
a large part in determining the levels of traffic and ability to receive validations
from desired nodes. Having every node with available incoming connections also
means that entries in pong caches will continually fall out with new values and
information will become less useful.
For this reason, we advise that the value of OutDesired be fractional. Upon startup,
a node will use its node ID (its 160 bit unique ID) to decide whether to round the
value of OutDesired up or down. Using this method, we can precisely control the
global number of available incoming connection slots.
"Outgoing Strategy"
-------------------
This is the method a peer uses to establish outgoing connections into the
Ripple network.
A peer whose PeerCount is zero will use these steps:
1. Attempt addresses from a local database of addresses
2. Attempt addresses from a set of "well known" domains in rippled.cfg
This is the method used by a peer that is already connected to the Ripple network,
to adjust the number of outgoing connections it is maintaining.
"Incoming Strategy"
------------------------------
This is the method used by a peer to announce its ability and desire to receive
incoming connections both for the purpose of obtaining additional peer connections
and also for receiving requests from clients.
Overlay Network
http://en.wikipedia.org/wiki/Overlay_network
Directed Graph
http://en.wikipedia.org/wiki/Directed_graph
References:
Gnutella 0.6 Protocol
2.2.2 Ping (0x00)
2.2.3 Pong (0x01)
2.2.4 Use of Ping and Pong messages
2.2.4.1 A simple pong caching scheme
2.2.4.2 Other pong caching schemes
http://rfc-gnutella.sourceforge.net/src/rfc-0_6-draft.html
Revised Gnutella Ping Pong Scheme
By Christopher Rohrs and Vincent Falco
http://rfc-gnutella.sourceforge.net/src/pong-caching.html

4
src/ripple/peerfinder/TODO.md Normal file
View File

@@ -0,0 +1,4 @@
# PeerFinder TODO
- Add TestOverlay unit test that passes mtENDPOINTs messages
around and enforces connection policy using a custom Callback.

194
src/ripple/peerfinder/impl/Manager.cpp
View File

@@ -17,200 +17,6 @@
*/
//==============================================================================
/*
PeerFinder
----------
Implements the logic for announcing and discovering IP addresses for
for connecting into the Ripple network.
Introduction
------------
Each Peer (a computer running rippled) on the Ripple network requires a certain
number of connections to other peers. These connections form an "overlay
network." When a new peer wants to join the network, they need a robust source
of network addresses (IP addresses) in order to establish outgoing connections.
Once they have joined the network, they need a method of announcing their
availaibility of accepting incoming connections.
The Ripple network, like all peer to peer networks, defines a "directed graph"
where each node represents a computer running the rippled software, and each
vertex indicates a network connection. The direction of the connection tells
us whether it is an outbound or inbound connection (from the perspective of
a particular node).
Fact #1:
The total inbound and outbound connections of any overlay must be equal.
This follows that for each node that has an established outbound connection,
there must exist another node that has received the corresponding inbound
connection.
When a new peer joins the network it may or may not wish to receive inbound
connections. Some peers are unable to accept incoming connections for various.
For security reasons they may be behind a firewall that blocks accept requests.
The administers may decide they don't want the connection traffic. Or they
may wish to connect only to specific peers. Or they may simply be misconfigured.
If a peer decides that it wishes to receive incoming connections, it needs
a method to announce its IP address and port number, the features that it
offers (for example, that it also services client requests), and the number
of available connection slots. This is to handle the case where the peer
reaches its desired number of peer connections, but may still want to inform
the network that it will service clients. It may also be desired to indicate
the number of free client slots.
Once a peer is connected to the network we need a way both to inform our
neighbors of our status with respect to accepting connections, and also to
learn about new fresh addresses to connect to. For this we will define the
mtENDPOINTS message.
"Bootstrap Strategy"
--------------------
Nouns:
bootstrap_ip
numeric IPAddress
bootstrap_domain
domain name / port combinations, resolution only
bootstrap_url
URL leading to a text file, with a series of entries.
ripple.txt
Separately parsed entity outside of PeerFinder that can provide
bootstrap_ip, bootstrap_domain, and bootstrap_url items.
The process of obtaining the initial peer connections for accessing the Ripple
peer to peer network, when there are no current connections, is called
"bootstrapping." The algorithm is as follows:
1. If ( unusedLiveEndpoints.count() > 0
OR activeConnectionAttempts.count() > 0)
Try addresses from unusedLiveEndpoints
return;
2. If ( domainNames.count() > 0 AND (
unusedBootstrapIPs.count() == 0
OR activeNameResolutions.count() > 0) )
ForOneOrMore (DomainName that hasn't been resolved recently)
Contact DomainName and add entries to the unusedBootstrapIPs
return;
3. If (unusedBootstrapIPs.count() > 0)
Try addresses from unusedBootstrapIPs
return;
4. Try entries from [ips]
5. Try entries from [ips_urls]
6. Increment generation number and go to 1
- Keep a map of all current outgoing connection attempts
"Connection Strategy"
---------------------
This is the overall strategy a peer uses to maintain its position in the Ripple
network graph
We define these values:
peerCount (calculated)
The number of currently connected and established peers
outCount (calculated)
The number of peers in PeerCount that are outbound connections.
MinOutCount (hard-coded constant)
The minimum number of OutCount we want. This also puts a floor
on PeerCount. This protects against sybil attacks and makes
sure that ledgers can get retrieved reliably.
10 is the proposed value.
MaxPeerCount (a constant set in the rippled.cfg)
The maximum number of peer connections, inbound or outbound,
that a peer wishes to maintain. Setting MaxPeerCount equal to
or below MinOutCount would disallow incoming connections.
OutPercent (a baked-in program constant for now)
The peer's target value for OutCount. When the value of OutCount
is below this number, the peer will employ the Outgoing Strategy
to raise its value of OutCount. This value is initially a constant
in the program, defined by the developers. However, it
may be changed through the consensus process.
15% is a proposed value.
However, lets consider the case where OutDesired is exactly equal to MaxPeerCount / 2.
In this case, a stable state will be reached when every peer is full, and
has exactly the same number of inbound and outbound connections. The problem
here is that there are now no available incoming connection slots. No new
peers can enter the network.
Lets consider the case where OutDesired is exactly equal to (MaxPeerCount / 2) - 1.
The stable state for this network (assuming all peers can accept incoming) will
leave us with network degree equal to MaxPeerCount - 2, with all peers having two
available incoming connection slots. The global number of incoming connection slots
will be equal to twice the number of nodes on the network. While this might seem to
be a desirable outcome, note that the connectedness (degree of the overlay) plays
a large part in determining the levels of traffic and ability to receive validations
from desired nodes. Having every node with available incoming connections also
means that entries in pong caches will continually fall out with new values and
information will become less useful.
For this reason, we advise that the value of OutDesired be fractional. Upon startup,
a node will use its node ID (its 160 bit unique ID) to decide whether to round the
value of OutDesired up or down. Using this method, we can precisely control the
global number of available incoming connection slots.
"Outgoing Strategy"
-------------------
This is the method a peer uses to establish outgoing connections into the
Ripple network.
A peer whose PeerCount is zero will use these steps:
1. Attempt addresses from a local database of addresses
2. Attempt addresses from a set of "well known" domains in rippled.cfg
This is the method used by a peer that is already connected to the Ripple network,
to adjust the number of outgoing connections it is maintaining.
"Incoming Strategy"
------------------------------
This is the method used by a peer to announce its ability and desire to receive
incoming connections both for the purpose of obtaining additional peer connections
and also for receiving requests from clients.
Terms
Overlay Network
http://en.wikipedia.org/wiki/Overlay_network
Directed Graph
http://en.wikipedia.org/wiki/Directed_graph
References:
Gnutella 0.6 Protocol
2.2.2 Ping (0x00)
2.2.3 Pong (0x01)
2.2.4 Use of Ping and Pong messages
2.2.4.1 A simple pong caching scheme
2.2.4.2 Other pong caching schemes
http://rfc-gnutella.sourceforge.net/src/rfc-0_6-draft.html
Revised Gnutella Ping Pong Scheme
By Christopher Rohrs and Vincent Falco
http://rfc-gnutella.sourceforge.net/src/pong-caching.html
*/
namespace ripple {
namespace PeerFinder {

1
src/ripple/resource/TODO.md Normal file
View File

@@ -0,0 +1 @@
# ResourceManager TODO

3
src/ripple/rpc/README.md Normal file
View File

@@ -0,0 +1,3 @@
# RPC
New code to generalize the operation of RPC commands

6
src/ripple/rpc/TODO.md Normal file
View File

@@ -0,0 +1,6 @@
# RPC TODO
- Redo the interface to actually work correctly for the existing
use-cases that the old code supports. Specifically that RPC commands
can be issued for a particular context like a websocket connection
or other subscriber.

4
src/ripple/sitefiles/README.md Normal file
View File

@@ -0,0 +1,4 @@
# SiteFiles
A central module that manages the download of local and remote ripple.txt files
and allows other code modules to access the sections.

9
src/ripple/sitefiles/TODO.md Normal file
View File

@@ -0,0 +1,9 @@
# SiteFiles TODO
- UnitTest
- Use it in more places
- Process the local file

4
src/ripple/sslutil/README.md Normal file
View File

@@ -0,0 +1,4 @@
# SSLUtil
This module exposes the OpenSSL headers and provides utilities to
operate with OpenSSL / BIGNUM objects.

1
src/ripple/sslutil/TODO.md Normal file
View File

@@ -0,0 +1 @@
# SSLUtil TODO

6
src/ripple/testoverlay/TODO.md Normal file
View File

@@ -0,0 +1,6 @@
# TestOverlay TODO
- Add documentation
- Fix the templates to be sane, use derivation and virtual instead of
compile time polymorphism

3
src/ripple/types/README.md Normal file
View File

@@ -0,0 +1,3 @@
# Types
Provides various types that are specific to the Ripple payment network.

7
src/ripple/types/TODO.md Normal file
View File

@@ -0,0 +1,7 @@
# Types TODO
- Replace uint128, uint160, uint256 with solid types
- Clean up and optimize Base58 conversions
- Generalize AgedHistory to use a DiscreteClock and not have two maps

1
src/ripple/validators/TODO.md Normal file
View File

@@ -0,0 +1 @@
# Validators TODO

4
src/ripple/validators/impl/Manager.cpp
View File

@@ -169,6 +169,7 @@ public:
//
// Manager
//
//--------------------------------------------------------------------------
void addStrings (String name, std::vector <std::string> const& strings)
{
@@ -245,6 +246,7 @@ public:
//
// Stoppable
//
//--------------------------------------------------------------------------
void onPrepare ()
{
@@ -290,6 +292,7 @@ public:
//
// PropertyStream
//
//--------------------------------------------------------------------------
void onWrite (PropertyStream::Map& map)
{
@@ -319,6 +322,7 @@ public:
//
// ManagerImp
//
//--------------------------------------------------------------------------
void init ()
{