Merge pull request #31 from coinbase/patrick/partial-sync-status

Support Pre-Query Status

api.json

@@ -1003,6 +1003,32 @@
           }
         }
       },
+     "SyncStatus": {
+       "description":"SyncStatus is used to provide additional context about an implementation's sync status. It is often used to indicate that an implementation is healthy when it cannot be queried  until some sync phase occurs. If an implementation is immediately queryable, this model is often not populated.",
+       "type":"object",
+       "required": [
+         "current_index"
+        ],
+       "properties": {
+         "current_index": {
+           "description":"CurrentIndex is the index of the last synced block in the current stage.",
+           "type":"integer",
+           "format":"int64",
+           "example": 100
+          },
+         "target_index": {
+           "description":"TargetIndex is the index of the block that the implementation is attempting to sync to in the current stage.",
+           "type":"integer",
+           "format":"int64",
+           "example": 150
+          },
+         "stage": {
+           "description":"Stage is the phase of the sync process.",
+           "type":"string",
+           "example":"header sync"
+          }
+        }
+      },
      "Peer": {
        "description":"A Peer is a representation of a node's peer.",
        "type":"object",
@@ -1457,7 +1483,7 @@
         }
       },
      "NetworkStatusResponse": {
-       "description":"NetworkStatusResponse contains basic information about the node's view of a blockchain network. If a Rosetta implementation prunes historical state, it should populate the optional `oldest_block_identifier` field with the oldest block available to query. If this is not populated, it is assumed that the `genesis_block_identifier` is the oldest queryable block.",
+       "description":"NetworkStatusResponse contains basic information about the node's view of a blockchain network. It is assumed that any BlockIdentifier.Index less than or equal to CurrentBlockIdentifier.Index can be queried. If a Rosetta implementation prunes historical state, it should populate the optional `oldest_block_identifier` field with the oldest block available to query. If this is not populated, it is assumed that the `genesis_block_identifier` is the oldest queryable block. If a Rosetta implementation performs some pre-sync before it is possible to query blocks, sync_status should be populated so that clients can still monitor healthiness. Without this field, it may appear that the implementation is stuck syncing and needs to be terminated.",
        "type":"object",
        "required": [
          "current_block_identifier",
@@ -1478,6 +1504,9 @@
          "oldest_block_identifier": {
            "$ref":"#/components/schemas/BlockIdentifier"
           },
+         "sync_status": {
+           "$ref":"#/components/schemas/SyncStatus"
+          },
          "peers": {
            "type":"array",
            "items": {

api.yaml

@@ -590,6 +590,8 @@ components:
       $ref: 'models/Amount.yaml'
     Currency:
       $ref: 'models/Currency.yaml'
+    SyncStatus:
+      $ref: 'models/SyncStatus.yaml'
     Peer:
       $ref: 'models/Peer.yaml'
     Version:
@@ -807,13 +809,20 @@ components:
     NetworkStatusResponse:
       description: |
         NetworkStatusResponse contains basic information about the node's
-        view of a blockchain network.
+        view of a blockchain network. It is assumed that any BlockIdentifier.Index
+        less than or equal to CurrentBlockIdentifier.Index can be queried.
 
         If a Rosetta implementation prunes historical state, it should
         populate the optional `oldest_block_identifier` field with the
         oldest block available to query. If this is not populated,
         it is assumed that the `genesis_block_identifier` is the oldest
         queryable block.
+
+        If a Rosetta implementation performs some pre-sync before it is
+        possible to query blocks, sync_status should be populated so that
+        clients can still monitor healthiness. Without this field, it may
+        appear that the implementation is stuck syncing and needs to be
+        terminated.
       type: object
       required:
         - current_block_identifier
@@ -829,6 +838,8 @@ components:
           $ref: '#/components/schemas/BlockIdentifier'
         oldest_block_identifier:
           $ref: '#/components/schemas/BlockIdentifier'
+        sync_status:
+          $ref: '#/components/schemas/SyncStatus'
         peers:
           type: array
           items:

models/SyncStatus.yaml

@@ -0,0 +1,45 @@
+# Copyright 2020 Coinbase, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+description: |
+  SyncStatus is used to provide additional context about an
+  implementation's sync status. It is often used to indicate
+  that an implementation is healthy when it cannot be queried 
+  until some sync phase occurs.
+
+  If an implementation is immediately queryable, this model is
+  often not populated.
+type: object
+required:
+  - current_index
+properties:
+  current_index:
+    description: |
+      CurrentIndex is the index of the last synced block in the
+      current stage.
+    type: integer
+    format: int64
+    example: 100 
+  target_index:
+    description: |
+      TargetIndex is the index of the block that the implementation
+      is attempting to sync to in the current stage.
+    type: integer
+    format: int64
+    example: 150 
+  stage:
+    description: |
+      Stage is the phase of the sync process.
+    type: string
+    example: "header sync"