Merge pull request #6155 from Jiloc/feat/rpc-health-v3

feat: /v3/health RPC

Author: Jiloc

CHANGELOG.md

@@ -5,13 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to the versioning scheme outlined in the [README.md](README.md).
 
+## Unreleased
+
+### Added
+
+- Added a new RPC endpoint `/v3/health` to query the node's health status. The endpoint returns a 200 status code with relevant synchronization information (including the node's current Stacks tip height, the maximum Stacks tip height among its neighbors, and the difference between these two). A user can use the `difference_from_max_peer` value to decide what is a good threshold for them before considering the node out of sync. The endpoint returns a 500 status code if the query cannot retrieve viable data.
+
 ## [3.1.0.0.11]
 
 - Hotfix for p2p stack misbehavior in mempool syncing conditions
 
 ## [3.1.0.0.10]
 
 ### Added
+
 - Persisted tracking of StackerDB slot versions for mining. This improves miner p2p performance.
 
 ## [3.1.0.0.9]

docs/rpc-endpoints.md

@@ -129,7 +129,7 @@ non-canonical headers will be returned instead.
 ### GET /v2/accounts/[Principal]
 
 Get the account data for the provided principal.
-The principal string is either a Stacks address or a Contract identifier (e.g., 
+The principal string is either a Stacks address or a Contract identifier (e.g.,
 `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`
 
 Returns JSON data in the form:
@@ -157,7 +157,7 @@ JSON object _without_ the `balance_proof` or `nonce_proof` fields.
 
 Attempt to vetch a data var from a contract. The contract is identified with [Stacks Address] and
  [Contract Name] in the URL path. The variable is identified with [Var Name].
- 
+
 Returns JSON data in the form:
 
 ```json
@@ -202,7 +202,7 @@ Returns JSON data in the form:
 Where data is the metadata formatted as a JSON string.
 
 ### GET /v2/constant_val/[Stacks Address]/[Contract Name]/[Constant Name]
-Attempt to fetch a constant from a contract. The contract is identified with [Stacks Address] and 
+Attempt to fetch a constant from a contract. The contract is identified with [Stacks Address] and
  [Contract Name] in the URL path. The constant is identified with [Constant Name].
 
 Returns JSON data in the form:
@@ -219,7 +219,7 @@ Where data is the hex serialization of the constant value.
 
 Attempt to fetch data from a contract data map. The contract is identified with [Stacks Address] and
  [Contract Name] in the URL path. The map is identified with [Map Name].
- 
+
 The _key_ to lookup in the map is supplied via the POST body. This should be supplied as the hex string
 serialization of the key (which should be a Clarity value). Note, this is a _JSON_ string atom.
 
@@ -539,8 +539,8 @@ data.
 
 This will return 404 if the block does not exist.
 
-This endpoint also accepts a querystring parameter `?tip=` which when supplied 
-will return the block relative to the specified tip allowing the querying of 
+This endpoint also accepts a querystring parameter `?tip=` which when supplied
+will return the block relative to the specified tip allowing the querying of
 sibling blocks (same height, different tip) too.
 
 ### GET /v3/tenures/[Block ID]
@@ -595,3 +595,13 @@ This feature requires enabling of transaction indexing by setting the `txindex`
 
 This will return 404 if the transaction does not exist and 501 (Not Implemented) if
 transaction indexing is not enabled.
+
+
+### GET /v3/health
+
+Determine node's synchronization health, comparing the node's current Stacks tip height
+with the maximum Stacks tip height observed among its connected peers.
+If there are no valid initial peers or data for the node to determine this information, this endpoint returns an error. The endpoint returns the node's current Stacks tip height, the maximum Stacks tip height observed among its connected peers, and the difference between these two heights.
+A user can utilize the `difference_from_max_peer` to establish their own criteria for determining if a node is out of sync.
+
+See OpenAPI [spec](./rpc/openapi.yaml) for details.

docs/rpc/api/core-node/get-health-error.example.json

@@ -0,0 +1,3 @@
+{
+  "error": "No viable bootstrap peers found, unable to determine health"
+}

docs/rpc/api/core-node/get-health-error.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "Error response when GET request to query node health fails",
+  "title": "ServerError",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "error"
+  ],
+  "properties": {
+    "error": {
+      "type": "string"
+    }
+  }
+}

docs/rpc/api/core-node/get-health.example.json

@@ -0,0 +1,5 @@
+{
+  "difference_from_max_peer": 0,
+  "max_stacks_height_of_neighbors": 12345,
+  "node_stacks_tip_height": 12345
+}

docs/rpc/api/core-node/get-health.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "GET request to query node health",
+  "title": "GetHealthResponse",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "difference_from_max_peer",
+    "max_stacks_height_of_neighbors",
+    "node_stacks_tip_height"
+  ],
+  "properties": {
+    "difference_from_max_peer": {
+      "type": "integer",
+      "description": "The difference in height between the node and its most advanced neighbor."
+    },
+    "max_stacks_height_of_neighbors": {
+      "type": "integer",
+      "description": "The max Stacks height of the node's most advanced neighbor."
+    },
+    "node_stacks_tip_height": {
+      "type": "integer",
+      "description": "The Stacks height of this node."
+    }
+  }
+}

docs/rpc/openapi.yaml

@@ -895,3 +895,36 @@ paths:
           description: Transaction indexing not enabled
           content:
             application/text-plain: {}
+
+  /v3/health:
+    get:
+      summary: Query the health of the node.
+      description: |
+        Get node health information.
+        A node is considered healthy if its Stacks tip height matches the maximum Stacks tip height observed among its connected peers.
+        This endpoint returns:
+        - `difference_from_max_peer`: The difference in Stacks height between this node and its most advanced peer.
+        - `max_stacks_height_of_neighbors`: The maximum Stacks height observed among the node's connected peers.
+        - `node_stacks_tip_height`: The current Stacks tip height of this node.
+      tags:
+        - Info
+      operationId: get_health
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: ./api/core-node/get-health.schema.json
+              example:
+                $ref: ./api/core-node/get-health.example.json
+        500:
+          description: |
+            Failed to query for health (e.g., no data or no valid peers to query from).
+            Only the `error` field will be set in this case, providing a message about the failure.
+          content:
+            application/json:
+              schema:
+                $ref: ./api/core-node/get-health-error.schema.json
+              example:
+                $ref: ./api/core-node/get-health-error.example.json