Merge pull request #498 from mDuo13/shard_crawl

crawl_shards method

content/_snippets/rippled-api-links.md

@@ -46,7 +46,9 @@
   "channel_verify",
   "connect",
   "consensus_info",
+  "crawl_shards",
   "deposit_authorized",
+  "download_shard",
   "feature",
   "fee",
   "fetch_info",

content/concepts/the-rippled-server/ledger-history/history-sharding.md

@@ -27,7 +27,8 @@ The history of all ledgers is shared by servers agreeing to keep particular rang
 ## See Also
 
 - [Configure History Sharding](configure-history-sharding.html)
-<!--{# - [download_shard method][] #}-->
+- [download_shard method][]
+- [crawl_shards method][]
 
 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}			

content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/crawl_shards.md

@@ -0,0 +1,137 @@
+# crawl_shards
+[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/CrawlShards.cpp "Source")
+
+Requests information from peer servers about which [shards of historical ledger data](history-sharding.html) they have available. [New in: rippled 1.2.0][]
+
+_The `crawl_shards` method is an [admin method](admin-rippled-methods.html) that cannot be run by unprivileged users._
+
+### Request Format
+
+An example of the request format:
+
+<!-- MULTICODE_BLOCK_START -->
+
+*WebSocket*
+
+```json
+{
+  "command": "crawl_shards",
+  "pubkey": true,
+  "limit": 0
+}
+```
+
+*JSON-RPC*
+
+```json
+{
+  "method": "crawl_shards",
+  "params": [
+    {
+      "pubkey": true,
+      "limit": 0
+    }
+  ]
+}
+```
+
+<!-- MULTICODE_BLOCK_END -->
+
+**Note:** There is no command-line syntax for this method. Use the [json method][] to access this from the command line.
+
+The request includes the following fields:
+
+| `Field`  | Type    | Description                                             |
+|:---------|:--------|:--------------------------------------------------------|
+| `pubkey` | Boolean | _(Optional)_ If `true`, the response includes the node public keys (for peer-to-peer communications) of servers that were crawled. The default is `false`. |
+| `limit`  | Number  | _(Optional)_ How many hops deep to search. The default is 0, which searches direct peers only. With a limit of `1`, searches peers' peers also. The maximum value is `3`. |
+
+**Caution:** The number of peers potentially searched grows exponentially as `limit` increases. With a limit of 2 or 3, it can take several seconds for the server to respond to the API request.
+
+
+### Response Format
+
+An example of a successful response:
+
+<!-- MULTICODE_BLOCK_START -->
+
+*WebSocket*
+
+```json
+{
+  "result": {
+    "complete_shards": "1-2,5,8-9,584,1973,2358",
+    "peers": [
+      {
+        "complete_shards": "1-2,8,47,371,464,554,653,857,1076,1402,1555,1708,1813,1867",
+        "public_key": "n9LxFZiySnfDSvfh23N94UxsFkCjWyrchTeKHcYE6tJJQL5iejb2"
+      },
+      {
+        "complete_shards": "8-9,584",
+        "ip": "192.168.1.132",
+        "public_key": "n9MN5xwYqbrj64rtfZAXQy7Y3sNxXZJeLt7Lj61a9DYEZ4SE2tQQ"
+      }
+    ]
+  },
+  "status": "success",
+  "type": "response"
+}
+```
+
+
+*JSON-RPC*
+
+```json
+200 OK
+
+{
+  "result": {
+    "complete_shards": "1-2,5,8-9,584,1973,2358",
+    "peers": [
+      {
+        "complete_shards": "1-2,8,47,371,464,554,653,857,1076,1402,1555,1708,1813,1867",
+        "public_key": "n9LxFZiySnfDSvfh23N94UxsFkCjWyrchTeKHcYE6tJJQL5iejb2"
+      },
+      {
+        "complete_shards": "8-9,584",
+        "ip": "192.168.1.132",
+        "public_key": "n9MN5xwYqbrj64rtfZAXQy7Y3sNxXZJeLt7Lj61a9DYEZ4SE2tQQ"
+      }
+    ],
+    "status": "success"
+  }
+}
+```
+
+
+<!-- MULTICODE_BLOCK_END -->
+
+The response follows the [standard format][], with a successful result containing the following fields:
+
+| `Field`           | Type   | Description                                     |
+|:------------------|:-------|:------------------------------------------------|
+| `complete_shards` | String | _(May be omitted)_ The range of [history shards](history-sharding.html) that are available on the local server. This may be an empty string, or a disjointed range. For example, `1-2,5,7-9` indicates that shards 1, 2, 5, 7, 8, and 9 are available. Omitted if this server does not have history sharding enabled. |
+| `peers`           | Array  | List of **Peer Shard Objects** (see below) describing which history shards each peer has available. |
+
+#### Peer Shard Objects
+
+Each member of the `peers` array of the response is an object that describes one server in the peer-to-peer network. The list only includes peers that have at least one complete [history shard](history-sharding.html) available. Each object in the array has the following fields:
+
+
+| `Field`   | Type   | Description                                             |
+|:----------|:-------|:--------------------------------------------------------|
+| `complete_shards` | String | The range of history shards this peer has available. This may be disjointed. For example, `1-2,5,7-9` indicates that shards 1, 2, 5, 7, 8, and 9 are available. |
+| `ip` | String | _(May be omitted)_ The IP address of the peer this object describes. This may be an IPv4 or IPv6 address. Omitted if this is a [private peer](peer-protocol.html#private-peers). |
+| `public_key` | String | _(Omitted unless the request specified `"pubkey": true`)_ The public key this peer uses for peer-to-peer communications, in the XRP Ledger's [base58 format](base58-encodings.html). |
+
+
+### Possible Errors
+
+- Any of the [universal error types][].
+- `invalidParams` - One or more required fields were omitted from the request, or a provided field was specified as the wrong data type.
+
+
+<!--{# common link defs #}-->
+{% include '_snippets/rippled-api-links.md' %}
+{% include '_snippets/tx-type-links.md' %}
+{% include '_snippets/rippled_versions.md' %}

dactyl-config.yml

@@ -1901,6 +1901,17 @@ pages:
         targets:
           - local
 
+    -   md: references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/crawl_shards.md
+        html: crawl_shards.html
+        blurb: Request information about which history shards peers have.
+        funnel: Docs
+        doc_type: References
+        supercategory: rippled API
+        category: Admin rippled Methods
+        subcategory: Logging and Data Management Methods
+        targets:
+          - local
+
     -   md: references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/download_shard.md
         html: download_shard.html
         blurb: Download a specific shard of ledger history.