dashboard: show writer trees

2 files changed, 44 insertions, 0 deletions

diff --git a/docs/dashboard.md b/docs/dashboard.md
index 1fe51dc..fa74104 100644
--- a/docs/dashboard.md
+++ b/docs/dashboard.md
@@ -138,6 +138,15 @@ pulls its ends together only a little when stretched, and doesn't push them apar
 round trips change, the map moves to the new lengths smoothly. Clicked again, it's
 static, the nodes staying where they are. The choice is kept in the browser.
 
+`tree: off`, next, switched to `tree: on`, shows a writer's tree ([`peers.md`](peers.md)): of the node in
+focus, else of this node. A chevron on the line from each member's parent to it, at its
+middle and in the colour of the line in use, points the way the writer's changes go; a member without one gets them by
+announcement. The node computes the tree as every node does, from the member list and
+whom each member reaches, which it takes from the links members report (a member that
+reports none counts as reaching its neighbours by the member list): asked for when the
+writer in focus changes and every 10 s (`GET /admin/dashboard/tree`). The choice is
+kept in the browser.
+
 Hovering over a node or a link highlights it and shows a tooltip: for a link, each of
 its lines with transport, direct or relayed, round trip, and how long ago it was
 measured.
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 03f75d9..a15339a 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -799,6 +799,41 @@ paths:
       responses:
         '204':
           description: Done.
+  /admin/dashboard/tree:
+    get:
+      tags: [Admin]
+      summary: A writer's tree
+      description: |
+        The tree a writer's changes pass on along (`swarm::tree`), as this node computes
+        it from the member list and the links members report (whom each reaches; one
+        that reports none counts as reaching its neighbours by the member list): each
+        member's parent, `null` for one without (it gets the writer's changes by
+        announcement). Only with the `dashboard` cargo feature.
+      parameters:
+        - name: writer
+          in: query
+          required: true
+          schema:
+            type: string
+          description: The writer's node ID.
+      responses:
+        '200':
+          description: The tree.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [writer, parents]
+                properties:
+                  writer:
+                    type: string
+                  parents:
+                    type: object
+                    description: By member's node ID, its parent's, or null.
+                    additionalProperties:
+                      type: [string, 'null']
+        '404':
+          description: The writer isn't in the member list (or it isn't known yet).
   /admin/dashboard/events:
     get:
       tags: [Admin]