From 6d928310f7dfcc8252587415267b2ffd30df45dd Mon Sep 17 00:00:00 2001
From: jamshale <jamiehalebc@gmail.com>
Date: Wed, 10 Apr 2024 19:50:49 +0000
Subject: [PATCH] add update via api design doc

Signed-off-by: jamshale <jamiehalebc@gmail.com>
---
 docs/design/UpgradeViaApi.md | 50 ++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 docs/design/UpgradeViaApi.md

diff --git a/docs/design/UpgradeViaApi.md b/docs/design/UpgradeViaApi.md
new file mode 100644
index 0000000000..1bd0722161
--- /dev/null
+++ b/docs/design/UpgradeViaApi.md
@@ -0,0 +1,50 @@
+# Upgrade via API Design
+
+To isolate an upgrade process and trigger it via API the following pattern was designed to handle multitenant scenarios. It includes a per instance memory singleton and an is_upgrading record in the wallet(DB) and a middleware to prevent requests during the upgrade process.
+
+```mermaid
+sequenceDiagram
+    participant A as Agent
+    participant M as Middleware
+    participant S as Singleton
+    participant W as Wallet (DB)
+
+    Note over A: Start upgrade
+    A->>M: POST /any-upgrade-path
+    M-->>S: check wallet name
+    S-->>M: 
+    M->>A: OK
+    A-->>S: add wallet name to set
+    A-->>W: update is_upgrading = true for wallet or subwallet
+
+    Note over A: Attempted Request
+    A->>M: GET /any-endpoint
+    M-->>S: check wallet name
+    S-->>M: 
+    M->>A: 503 Service Unavailable
+
+    Note over A: Agent Restart
+    A-->>W: Get is_upgrading record for wallet or all subwallets
+    W-->>A: 
+    A-->>S: Populate set with wallet names
+
+    Note over A: Attempted Request
+    A->>M: GET /any-endpoint
+    M-->>S: check wallet name
+    S-->>M: 
+    M->>A: 503 Service Unavailable
+
+    Note over A: End upgrade
+    A-->>S: Remove wallet name from set
+    A-->>W: delete is_upgrading record for wallet
+
+    Note over A: Attempted Request
+    A->>M: GET /any-endpoint
+    M-->>S: check wallet name
+    S-->>M: 
+    M->>A: OK
+```
+
+#### To use this mehanism you simply need to set the upgrading record in the wallet (DB) and add the wallet name to the singleton set. The middleware will prevent requests from being processed until the upgrade process is finished. After the upgrade process is finished you must remove the wallet name from the set and delete the upgrading record in the wallet (DB).
+
+##### An example can be found via the anoncreds upgrade `aries_cloudagent/wallet/routes.py` in the `upgrade_anoncreds` controller.
\ No newline at end of file