From cf898f7ce2925c1483add86a004d3c1a9329dfbf Mon Sep 17 00:00:00 2001
From: NagyZoltanPeter <113987313+NagyZoltanPeter@users.noreply.github.com>
Date: Thu, 12 Jun 2025 14:38:10 +0200
Subject: [PATCH] Added recent extensions to REST API: /admin/v1 ... /stats and
 .../log-level endpoints.

---
 api-spec/adminapi_log_level.yaml           | 34 +++++++++++++++++
 api-spec/adminapi_peers_stats.yaml         | 14 +++++++
 api-spec/adminapi_peers_stats_example.json | 44 ++++++++++++++++++++++
 api-spec/openapi.yaml                      |  4 ++
 api-spec/schemas/apitypes.yaml             | 22 +++++++++++
 5 files changed, 118 insertions(+)
 create mode 100644 api-spec/adminapi_log_level.yaml
 create mode 100644 api-spec/adminapi_peers_stats.yaml
 create mode 100644 api-spec/adminapi_peers_stats_example.json

diff --git a/api-spec/adminapi_log_level.yaml b/api-spec/adminapi_log_level.yaml
new file mode 100644
index 0000000..835bef4
--- /dev/null
+++ b/api-spec/adminapi_log_level.yaml
@@ -0,0 +1,34 @@
+post:
+  summary: Dynamic set log level on the node
+  description: Change the log level of a Waku v2 node.
+  operationId: setLogLevel
+  tags:
+    - admin
+  parameters:
+    - in: path
+      name: logLevel
+      required: true
+      schema:
+        type: string
+        enum:
+        - "TRACE"
+        - "DEBUG"
+        - "INFO"
+        - "NOTICE"
+        - "WARN"
+        - "ERROR"
+        - "FATAL"
+      description: New log level to set for the node.
+  responses:
+    '200':
+      description: New log level Successfully applied.
+    '400':
+      description: Invalid argument.
+      content:
+        text/plain:
+          type: string
+    '503':
+      description: Service unavailable - binary is not compiled with proper flag that enables this feature.
+      content:
+        text/plain:
+          type: string
diff --git a/api-spec/adminapi_peers_stats.yaml b/api-spec/adminapi_peers_stats.yaml
new file mode 100644
index 0000000..e6042ae
--- /dev/null
+++ b/api-spec/adminapi_peers_stats.yaml
@@ -0,0 +1,14 @@
+get:
+  summary: Get statistics of available peers
+  description: Retrieve statistics of node's peer database in various grouping.
+  operationId: getPeerStats
+  tags:
+    - admin
+  responses:
+    '200':
+      description: Information about a Waku v2 node.
+      content:
+        application/json:
+          schema:
+            $ref: "./schemas/apitypes.yaml#/WakuPeerStats"
+
diff --git a/api-spec/adminapi_peers_stats_example.json b/api-spec/adminapi_peers_stats_example.json
new file mode 100644
index 0000000..9a5bb5b
--- /dev/null
+++ b/api-spec/adminapi_peers_stats_example.json
@@ -0,0 +1,44 @@
+{
+	"Sum": {
+		"Total peers": 12
+	},
+	"By Connectedness": {
+		"Connected": 10,
+		"NotConnected": 0,
+		"CannotConnect": 2,
+		"CanConnect": 0
+	},
+	"Relay peers": {
+		"0": 10,
+		"1": 10,
+		"5": 10,
+		"4": 10,
+		"6": 10,
+		"3": 10,
+		"7": 10,
+		"2": 10,
+		"Total relay peers": 8
+	},
+	"Mesh peers": {
+		"0": 4,
+		"1": 4,
+		"5": 4,
+		"4": 4,
+		"6": 4,
+		"3": 4,
+		"7": 4,
+		"2": 4,
+		"Total mesh peers": 8
+	},
+	"By Protocols": {
+		"/vac/waku/relay/2.0.0": 12,
+		"/vac/waku/filter-subscribe/2.0.0-beta1": 12,
+		"/vac/waku/filter-push/2.0.0-beta1": 6,
+		"/vac/waku/store-query/3.0.0": 12,
+		"/vac/waku/store/2.0.0-beta4": 10,
+		"/vac/waku/lightpush/3.0.0": 12,
+		"/vac/waku/lightpush/2.0.0-beta1": 10,
+		"/vac/waku/peer-exchange/2.0.0-alpha1": 0,
+		"/vac/waku/reconciliation/1.0.0": 0
+	}
+}
\ No newline at end of file
diff --git a/api-spec/openapi.yaml b/api-spec/openapi.yaml
index 756eed1..b2fe734 100644
--- a/api-spec/openapi.yaml
+++ b/api-spec/openapi.yaml
@@ -35,6 +35,8 @@ paths:
      $ref: "./debugapi_info.yaml"
   /version:
      $ref: "./debugapi_version.yaml"
+  /admin/v1/log-level/{logLevel}:
+    $ref: "./adminapi_log_level.yaml"
   /admin/v1/peers:
     $ref: "./adminapi_peers.yaml"
   /admin/v1/peer/{peerId}:
@@ -53,6 +55,8 @@ paths:
     $ref: "./adminapi_peers_mesh.yaml"
   /admin/v1/peers/mesh/on/{shardId}:
     $ref: "./adminapi_peers_mesh_on_shard.yaml"
+  /admin/v1/peers/stats:
+    $ref: "./adminapi_peers_stats.yaml"
   /admin/v1/filter/subscriptions:
     $ref: "./adminapi_filter.yaml"
   /debug/v1/info:
diff --git a/api-spec/schemas/apitypes.yaml b/api-spec/schemas/apitypes.yaml
index 3bbe04f..544b9b9 100644
--- a/api-spec/schemas/apitypes.yaml
+++ b/api-spec/schemas/apitypes.yaml
@@ -1,3 +1,25 @@
+WakuPeerStats:
+  type: object
+  properties:
+    grouping:
+      type: object
+      properties:
+        name:
+          title: string
+        value:
+          type: array
+          items:
+            type: object
+            properties:
+              title:
+                type: string
+              value:
+                type: integer
+                format: int32
+    examples:
+      peer_statistics:
+        $ref: "./adminapi_peers_stats_example.json" 
+
 WakuPeer:
   type: object
   required: