Document and cleanup ledger advance logic

* Don't acquire if validated ledger is old
* Don't try to publish if no valid ledger
* Update README.md file

src/ripple/app/ledger/LedgerMaster.cpp

@@ -935,7 +935,8 @@ public:
             {
                 if (!standalone_ && !getApp().getFeeTrack().isLoadedLocal() &&
                     (getApp().getJobQueue().getJobCount(jtPUBOLDLEDGER) < 10) &&
-                    (mValidLedgerSeq == mPubLedgerSeq))
+                    (mValidLedgerSeq == mPubLedgerSeq) &&
+                    (getValidatedLedgerAge() < 60))
                 { // We are in sync, so can acquire
                     std::uint32_t missing;
                     {
@@ -1071,7 +1072,11 @@ public:
         std::list<Ledger::pointer> ret;
 
         WriteLog (lsTRACE, LedgerMaster) << "findNewLedgersToPublish<";
-        if (!mPubLedger)
+        if (mValidLedger.empty ())
+        {
+            // No valid ledger, nothing to do
+        }
+        else if (! mPubLedger)
         {
             WriteLog (lsINFO, LedgerMaster) << "First published ledger will be " << mValidLedgerSeq;
             ret.push_back (mValidLedger.get ());

src/ripple/app/ledger/README.md

@@ -397,6 +397,39 @@ are occupied by the exchange rate.
 
 ---
 
+# Ledger Publication #
+
+## Overview ##
+
+The Ripple server permits clients to subscribe to a continuous stream of
+fully-validated ledgers. The publication code maintains this stream.
+
+The server attempts to maintain this continuous stream unless it falls
+too far behind, in which case it jumps to the current fully-validated
+ledger and then attempts to resume a continuous stream.
+
+## Implementation ##
+
+LedgerMaster::doAdvance is invoked when work may need to be done to
+publish ledgers to clients. This code loops until it cannot make further
+progress.
+
+LedgerMaster::findNewLedgersToPublish is called first. If the last
+fully-valid ledger's sequence number is greater than the last published
+ledger's sequence number, it attempts to publish those ledgers, retrieving
+them if needed.
+
+If there are no new ledgers to publish, doAdvance determines if it can
+backfill history. If the publication is not caught up, bakfilling is not
+attempted to conserve resources.
+
+If history can be backfilled, the missing ledger with the highest
+sequence number is retrieved first. If a historical ledger is retrieved,
+and its predecessor is in the database, tryFill is invoked to update
+the list of resident ledgers.
+
+---
+
 # The Ledger Cleaner #
 
 ## Overview ##