Create IPC locking library `@matrixai/js-file-locks` to introduce RWlocks in IPC

[joshuakarp]

Specification

We'd like to investigate creating our own locking library, based off our current usage of fd-lock.

Previously we were using both proper-lockfile and fd-lock in a more conglomerated fashion. Now, we are purely using fd-lock for the Status (our refactored agent lockfile #283) and Session usage (implemented here).

Note the distinction between "locking" here. Here, we're referring to "file locking" (as per the fd prefix). For example, for the Status, we lock this status file to assert that an agent process is currently executing. Conversely, we're using async-mutex for intra-process locking (locking some resource from within a process, as opposed to between processes). Remember that we also have an existing read-write locking implementation that utilises async-mutex.

Our own library should support:

• OS-specific read-write locks
• Native promise API
• Explore the addition of POSIX locks

OS-specific read-write locks should be the initial priority, and should be seen as a basic extension of functionality from fd-lock (we can use this as a source of inspiration to copy from).

Additional context

• Original issue: Unify File Locking Across Domains #251
• Coalesce concurrent locking when writing the session token during GRPC requests Polykey-CLI#18 - Should also allow an API to check if the lock is already locked so we can enable concurrent coalescing

Tasks

1. ...
2. ...
3. ...

[CMCDragonkai]

Note that async-mutex is an in-process locking, while file locking is for inter-process locking. We would want to expose rwlocks directly from flock and equivalent in windows for this to work.

[CMCDragonkai]

The src/utils.ts is now src/utils. It's now a directory with src/utils/locks.ts which contains all locking utility functions.

Here is where the RWLock based on async-mutex is. Can be used for other locking utilities that use file locking, or more abstractions are built on top of IPC file locking or in-memory async-mutex (promise-based) locking.

[CMCDragonkai]

As discussed in #283 (comment), there's a problem with Status where it's possible for readStatus to get an "intermediate state" of the status file, such as between truncation and writing. This is not ideal, although a rare situation. Once we have IPC file-based RWlocking, then we can ensure that such reads are not interrupted such writes and no intermediate states are possible. Note that due to the way status works, this may require either 2 files breaking up status.json to 2 files: status.json and status.lock, or if we implement a rw-lock upgrade logic which must work on all platforms natively too.

[CMCDragonkai]

Just experienced the intermittent ErrorStatusParse error that comes from not having a robust IPC. But this is temporary so for now we just have to accept that it sometimes happens.

 FAIL  tests/bin/agent/start.test.ts (71.003 s)
  ● start › start in background

    ErrorStatusParse: JSON parsing failed

      115 |       statusInfo = JSON.parse(statusData);
      116 |     } catch (e) {
    > 117 |       throw new statusErrors.ErrorStatusParse('JSON parsing failed');
          |             ^
      118 |     }
      119 |     if (!statusUtils.statusValidate(statusInfo)) {
      120 |       throw new statusErrors.ErrorStatusParse('StatusInfo validation failed', {

      at Object.readStatus (src/status/Status.ts:117:13)
      at statusInfo (src/status/Status.ts:152:16)
      at poll (src/utils/utils.ts:123:18)
      at Object.waitFor (src/status/Status.ts:150:24)
      at Object.<anonymous> (tests/bin/agent/start.test.ts:142:27)

[CMCDragonkai]

I've developed a read-preferring and write-preferring in-memory RWLock for JS: https://gist.github.com/CMCDragonkai/4de5c1526fc58dac259e321db8cf5331

We may even have a general library for locking that incorporates these features.