feat: introduce persistent cache for providers

[szymonmaslowski]

Context

We want to improve caching mechanism by making it persistent and therefore decrease the number of requests made to blockfrost

Proposed Solution

Allow utxo and chain history providers to use persistent cache

Important Changes Introduced

• define a contract of the cache
• enable chain history and utxo providers to use injected cache
• create persistent cache storage
  • utilizing web extension storage
  • implementing the cache contract
  • having data evicting capability

The eviction mechanism

• checks how much space is occupied by all of the collection's keys
• if the allowed (specified in the parameters) space is exceeded it removes most rarely accessed items
• the set of items to be removed is chosen based on the item's accessTime stored in metadata
• the size of items to be removed is 10% of their count.
• a fallback mechanism in case the getBytesInUse is not present - it is not present in the MDN docs neither in the polyfill lib we use (recent version)
• the fallback checks if the total count of cached items exceeded the amount provided in fallbackMaxCollectionItemsGuard parameter

Example of data managed by the persistent cache implementation. Resouce name: utxo-provider-cache.
Result of storage.local.get():

{
  utxo-provider-cache-metadata: {
    utxo-provider-cache-item-x: {
      accessTime: 1738765316652
    },
    utxo-provider-cache-item-y: {
      accessTime: 1738765316653
    },
    utxo-provider-cache-item-z: {
      accessTime: 1738765316654
    }
  },
  utxo-provider-cache-item-x: {/* data */},
  utxo-provider-cache-item-y: {/* data */},
  utxo-provider-cache-item-z: {/* data */},
  /* other stored data */
}

Reasons behind that structure:

1. Having metadata in a separate object we can safely access all the cache items for envicting.
2. Storing each item flat allows to:
   • easily count occupied size (storage.local.getBytesInUse([...allKeys]))
   • easy removal and access to particular items.

[szymonmaslowski]

I need to finish unit tests but the implementation can already get the initial reviews

[szymonmaslowski]

I parametrised only the value type. The extension storage allows only for string keys.

[szymonmaslowski]

The webextension-polyfill does not list getBytesInUse method in the storage API. With this type guard we ensure the getBytesInUse is present.

[szymonmaslowski]

In worst-case scenario we will evict an item that was accessed right before the eviction logic started - accessing and evicting happening simultaneously:

1. item X has an old accessTime
2. item X gets accessed, but its accessTime update is only scheduled
3. the eviction logic kicks in and accesses the metadata where X has old accessTime
4. X gets clasified to be evicted
5. X gets accessTime updated in the metadata
6. X gets removed.
7. X's metadata gets removed.

Another scenario: eviction starts first and simultaneously accessing happens

1. metadata with old X's accessTime queried and X classified for eviction
2. X accessed and its accessTime update scheduled
3. X removed
4. X's accessTime updated
5. X's updated metadata removed

[pczeglik-iohk]

Should we check exceeded quota before setting item, so we know we have room to insert it?
Or maybe we can do try ... catch and handle evict in catch, and after re do loaded.set in finally?

[szymonmaslowski]

We had a conversation with Piotr and agreed we dont want to catch any error here considering we are gonna have unlimited storage

[pczeglik-iohk]

Nice work @szymonmaslowski 👏

[przemyslaw-wlodek]

👏🏻 Great job @szymonmaslowski!