From 05c45f6a2f463ff4f1cf864e2c20f97f9ba48064 Mon Sep 17 00:00:00 2001
From: Jean-Paul Calderone <exarkun@twistedmatrix.com>
Date: Wed, 2 Feb 2022 15:16:53 -0500
Subject: [PATCH] remove some redundancy in the specification
---
docs/source/designs/backup-recovery.rst | 38 ++++++++++++++++++++++++
src/_zkapauthorizer/backup-recovery.yaml | 9 ++----
2 files changed, 40 insertions(+), 7 deletions(-)
diff --git a/docs/source/designs/backup-recovery.rst b/docs/source/designs/backup-recovery.rst
index 0ae9921..bcd1def 100644
--- a/docs/source/designs/backup-recovery.rst
+++ b/docs/source/designs/backup-recovery.rst
@@ -296,8 +296,46 @@ The recovery process is as follows:
External Interfaces
-------------------
+Specification
+~~~~~~~~~~~~~
+
See the `OpenAPI specification <backup-recovery-openapi.html>`_.
+Sample Sessions
+~~~~~~~~~~~~~~~
+
+The expected interaction pattern involves two API calls.
+
+#. Early in the Tahoe-LAFS client node setup/configuration process,
+ configure replication:
+
+ .. code-block:: html
+
+ POST /storage-plugins/privatestorageio-zkapauthz-v1/replicate
+
+ 201 Created
+ Content-Type: application/json
+
+ {"recovery-capability": "URI:DIR-RO:xxxx"}
+
+#. After losing the Tahoe-LAFS node,
+ create a new Tahoe-LAFS client node and recover from the replica:
+
+ .. code-block:: html
+
+ POST /storage-plugins/privatestorageio-zkapauthz-v1/recover
+ Content-Type: application/json
+ Content-Length: ...
+
+ {"recovery-capability": "URI:DIR-RO:xxxx"}
+
+ 200 OK
+
+
+
+
+
+
Data Integrity
--------------
diff --git a/src/_zkapauthorizer/backup-recovery.yaml b/src/_zkapauthorizer/backup-recovery.yaml
index 6f38b2f..531f296 100644
--- a/src/_zkapauthorizer/backup-recovery.yaml
+++ b/src/_zkapauthorizer/backup-recovery.yaml
@@ -19,13 +19,8 @@ paths:
content:
application/json:
schema:
- properties:
- recovery-capability:
- type: "string"
- description: >-
- The Tahoe-LAFS read-only capability for the recovery data.
- This is the capability which can be submitted in order to
- initiate a recovery from the replica.
+ "$ref": "/components/schemas/ReplicaConfiguration"
+
responses:
"500": # INTERNAL SERVER ERROR
description: >-
--
GitLab