Support sharing vault locks and transactions across RPC calls

[tegefaulkes]

Specification

With the work being done on the MatrixAI/Polykey-CLI#32 . We're starting to run into a common problem. Each of the Unix style commands have some commonality between them. Such as reading and writing entire file trees and their contents. So it makes sense to break them down into common plumbing style handlers for doing parts or each commands operations on vaults.

A clear example of this is the ls command in MatrixAI/Polykey-CLI#245. Where we can get just the file tree from the globWalk utility as one RPC call. And if needed we can get the file tree contents of files with a separate RPC call. The main problem here is that currently can't share the locking or transaction between these RPC calls.To fix this we need to create an RPC handler and add support to the vaults domain for this.

There are two levels of locking we need. The vault level locking where we get access to the vault we wish to use. And the EFS level locking where we call read or write. The vault.write is a more complex form of this since it locks and does some modification when done. This can all be handled within a ResourceAcquire pattern.

To address this we need to do the following.

1. Implement ResourceAcquire support for VaultManager and VaultInternal. We need to access the ResourceAcquire for getting a lock of the vaults and making reads/writes to vaults. This is required for allowing us to acquire the resources we need and keep them in an object map for later use.
2. Implement an object map pattern in VaultManager that allows acquiring the vault and read/write resources and then returns a resource ID that can be used to access the resource. I'm a bit fuzzy on how the two layers of locks will interact here so there may be complications. If no resourceID is provided then create a new one. If a resourceID is provided then use the existing on in the map for that id. If not resource exists for that ID then throw an error. If all uses of the resource are released then release the resource.
3. Create a RPC wrapper for getting the resource. This should be pretty simple but note that the resource must be held for the duration of the RPC call. To that end it must be a ClientHandler RPC handler.
4. RPC calls such as the one wrapping the globWalk utility and the one wrapping the content serialise need to optionally take the resource ID. If no id is provided then they will acquire their own lock separately. If a ID is provided then they will share the lock and transaction of the vault between the calls.

Additional context

• Related: Incorporate Unix Commands to Secrets Subcommand - pk secrets * Polykey-CLI#32
• Related: Implement secrets ls command Polykey-CLI#245

Tasks

1. Expose ResourceAcquire support in VaultManager.
2. Expose ResourceAcquire support in VaultInternal.
3. Add resource object map manager functionality to VaultManager for acquiring and reusing locks and transactions.
4. Create RPC handlers for exposing the needed functionality.
5. Update plumbing RPC handlers for secret Unix commands to use this new resource functionality.

[linear]

ENG-389 Support sharing vault locks and transactions across RPC calls

[CMCDragonkai]

Did you review the js-async-locks and js-resources capabilities?

[tegefaulkes]

I didn't review them but they haven't changed since I last used them AFAIK.

[CMCDragonkai]

This may need to be understood in the context of the new Unix commands then.