docs: added description and diagram to VaultInternal.request()

[ci skip]
MatrixAI · May 15, 2024 · 6d3b493 · 6d3b493
1 parent 16c840d
commit 6d3b493
Show file tree

Hide file tree

Showing 2 changed files with 39 additions and 2 deletions.
diff --git a/src/git/http.ts b/src/git/http.ts
@@ -140,7 +140,7 @@ async function* advertiseRefGenerator({
   // "0000"
   yield gitUtils.FLUSH_PACKET_BUFFER;
   // Ref_list
-  yield* referenceList(objectGenerator, capabilityList);
+  yield* referenceListGenerator(objectGenerator, capabilityList);
   // "0000"
   yield gitUtils.FLUSH_PACKET_BUFFER;
 }
@@ -161,7 +161,7 @@ async function* advertiseRefGenerator({
  * cap-list        =  capability *(SP capability)
  * ```
  */
-async function* referenceList(
+async function* referenceListGenerator(
   objectGenerator: AsyncGenerator<[Reference, ObjectId], void, void>,
   capabilities: CapabilityList,
 ): AsyncGenerator<Buffer, void, void> {

diff --git a/src/vaults/VaultInternal.ts b/src/vaults/VaultInternal.ts
@@ -766,6 +766,43 @@ class VaultInternal {
     return commitIdLatest;
   }
 
+  /**
+   * Creates a request arrow function that implements an api that `isomorphic-git` expects to use when making a http
+   * request. It makes RPC calls to `vaultsGitInfoGet` for the ref advertisement phase and `vaultsGitPackGet` for the
+   * git pack phase.
+   *
+   * `vaultsGitInfoGet` wraps a call to `gitHttp.advertiseRefGenerator` and `vaultsGitPackGet` to
+   * `gitHttp.generatePackRequest`.
+   *
+   * ```
+   *                                  ┌─────────┐    ┌───────────────────────────┐
+   *                                  │         │    │                           │
+   *  ┌──────────────────────┐        │  RPC    │    │                           │
+   *  │                      │        │         │    │ *advertiseRefGenerator()  │
+   *  │                      ├────────┼─────────┼────►                           │
+   *  │     vault.request()  │        │         │    │                           │
+   *  │                      │        │         │    └────┬──────────────────────┘
+   *  │                      ├──┐     │         │         │
+   *  │                      │  │     │         │    ┌────▼──────────────────────┐
+   *  └──────────────────────┘  │     │         │    │                           │
+   *                            │     │         │    │ *referenceListGenerator() │
+   *                            │     │         │    │                           │
+   *                            │     │         │    └───────────────────────────┘
+   *                            │     │         │
+   *                            │     │         │    ┌───────────────────────────┐
+   *                            └─────┼─────────┼────┤                           │
+   *                                  │         │    │ *generatePackRequest()    │
+   *                                  │         │    │                           │
+   *                                  │         │    └────┬──────────────────────┘
+   *                                  └─────────┘         │
+   *                                                 ┌────▼──────────────────────┐
+   *                                                 │                           │
+   *                                                 │ *generatePackData()       │
+   *                                                 │                           │
+   *                                                 └───────────────────────────┘
+   *
+   * ```
+   */
   protected async request(
     client: RPCClient<typeof agentClientManifest>,
     vaultNameOrId: VaultId | VaultName,