blob-cache.ts 8.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230
  1. import isElectron from "is-electron";
  2. const blobCacheNames = [
  3. "thumbs",
  4. "face-crops",
  5. // Desktop app only
  6. "files",
  7. ] as const;
  8. /**
  9. * Namespaces into which our blob caches are divided
  10. *
  11. * Note that namespaces are just arbitrary (but predefined) strings to split the
  12. * cached data into "folders", so to speak.
  13. * */
  14. export type BlobCacheNamespace = (typeof blobCacheNames)[number];
  15. /**
  16. * A namespaced blob cache.
  17. *
  18. * This cache is suitable for storing large amounts of data (entire files).
  19. *
  20. * To obtain a cache for a given namespace, use {@link openCache}. To clear all
  21. * cached data (e.g. during logout), use {@link clearCaches}.
  22. *
  23. * [Note: Caching files]
  24. *
  25. * The underlying implementation of the cache is different depending on the
  26. * runtime environment.
  27. *
  28. * * The preferred implementation, and the one that is used when we're running
  29. * in a browser, is to use the standard [Web
  30. * Cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache).
  31. *
  32. * * However when running under Electron (when this code runs as part of our
  33. * desktop app), a custom OPFS based cache is used instead. This is because
  34. * Electron currently doesn't support using standard Web Cache API for data
  35. * served by a custom protocol handler (See this
  36. * [issue](https://github.com/electron/electron/issues/35033), and the
  37. * underlying restriction that comes from
  38. * [Chromium](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/modules/cache_storage/cache.cc;l=83-87?q=%22Request%20scheme%20%27%22&ss=chromium))
  39. *
  40. * [OPFS](https://web.dev/articles/origin-private-file-system) stands for Origin
  41. * Private File System. It is a recent API that allows a web site to store
  42. * reasonably large amounts of data. One option (that may still become possible
  43. * in the future) was to always use OPFS for caching instead of this dual
  44. * implementation, however currently [Safari does not support writing to OPFS
  45. * outside of web
  46. * workers](https://webkit.org/blog/12257/the-file-system-access-api-with-origin-private-file-system/)
  47. * ([the WebKit bug](https://bugs.webkit.org/show_bug.cgi?id=231706)), so it's
  48. * not trivial to use this as a full on replacement of the Web Cache in the
  49. * browser. So for now we go with this split implementation.
  50. *
  51. * See also: [Note: Increased disk cache for the desktop app].
  52. */
  53. export interface BlobCache {
  54. /**
  55. * Get the data corresponding to {@link key} (if found) from the cache.
  56. */
  57. get: (key: string) => Promise<Blob | undefined>;
  58. match: (key: string) => Promise<Response | undefined>;
  59. /**
  60. * Add the given {@link key}-value ({@link blob}) pair to the cache.
  61. */
  62. put2: (key: string, blob: Blob) => Promise<void>;
  63. put: (key: string, data: Response) => Promise<void>;
  64. /**
  65. * Delete the blob corresponding to the given {@link key}.
  66. *
  67. * The returned promise resolves to `true` if a cache entry was found,
  68. * otherwise it resolves to `false`.
  69. * */
  70. delete: (key: string) => Promise<boolean>;
  71. }
  72. /**
  73. * Return the {@link BlobCache} corresponding to the given {@link name}.
  74. *
  75. * @param name One of the arbitrary but predefined namespaces of type
  76. * {@link BlobCacheNamespace} which group related data and allow us to use the
  77. * same key across namespaces.
  78. */
  79. export const openCache = async (
  80. name: BlobCacheNamespace,
  81. ): Promise<BlobCache> =>
  82. isElectron() ? openOPFSCacheWeb(name) : openWebCache(name);
  83. /**
  84. * [Note: ArrayBuffer vs Blob vs Uint8Array]
  85. *
  86. * ArrayBuffers are in memory, while blobs are unreified, and can directly point
  87. * to on disk objects too.
  88. *
  89. * If we are just passing data around without necessarily needing to manipulate
  90. * it, and we already have a blob, it's best to just pass that blob. Further,
  91. * blobs also retains the file's encoding information , and are thus a layer
  92. * above array buffers which are just raw byte sequences.
  93. *
  94. * ArrayBuffers are not directly manipulatable, which is where some sort of a
  95. * typed array or a data view comes into the picture. The typed `Uint8Array` is
  96. * a common way.
  97. *
  98. * To convert from ArrayBuffer to Uint8Array,
  99. *
  100. * new Uint8Array(arrayBuffer)
  101. *
  102. * Blobs are immutable, but a usual scenario is storing an entire file in a
  103. * blob, and when the need comes to display it, we can obtain a URL for it using
  104. *
  105. * URL.createObjectURL(blob)
  106. *
  107. * Also note that a File is a Blob!
  108. *
  109. * To convert from a Blob to ArrayBuffer
  110. *
  111. * await blob.arrayBuffer()
  112. *
  113. * Refs:
  114. * - https://github.com/yigitunallar/arraybuffer-vs-blob
  115. * - https://stackoverflow.com/questions/11821096/what-is-the-difference-between-an-arraybuffer-and-a-blob
  116. */
  117. /** An implementation of {@link BlobCache} using Web Cache APIs */
  118. const openWebCache = async (name: BlobCacheNamespace) => {
  119. const cache = await caches.open(name);
  120. return {
  121. get: async (key: string) => {
  122. const res = await cache.match(key);
  123. console.log("found cache hit", key, res);
  124. return await res?.blob();
  125. },
  126. match: (key: string) => {
  127. return cache.match(key);
  128. },
  129. put2: (key: string, blob: Blob) => cache.put(key, new Response(blob)),
  130. put: (key: string, data: Response) => {
  131. return cache.put(key, data);
  132. },
  133. delete: (key: string) => {
  134. return cache.delete(key);
  135. },
  136. };
  137. };
  138. /** An implementation of {@link BlobCache} using OPFS */
  139. const openOPFSCacheWeb = async (name: BlobCacheNamespace) => {
  140. // While all major browsers support OPFS now, their implementations still
  141. // have various quirks. However, we don't need to handle all possible cases
  142. // and can just instead use the APIs and guarantees Chromium provides since
  143. // this code will only run in our Electron app (which'll use Chromium as the
  144. // renderer).
  145. //
  146. // So for our purpose, these can serve as the doc for what's available:
  147. // https://web.dev/articles/origin-private-file-system
  148. const cache = await caches.open(name);
  149. const root = await navigator.storage.getDirectory();
  150. const _caches = await root.getDirectoryHandle("cache", { create: true });
  151. // eslint-disable-next-line @typescript-eslint/no-unused-vars
  152. const _cache = await _caches.getDirectoryHandle(name, { create: true });
  153. return {
  154. get: async (key: string) => {
  155. try {
  156. const fileHandle = await _cache.getFileHandle(key);
  157. return await fileHandle.getFile();
  158. } catch (e) {
  159. if (e instanceof DOMException && e.name == "NotFoundError")
  160. return undefined;
  161. throw e;
  162. }
  163. },
  164. match: (key: string) => {
  165. return cache.match(key);
  166. },
  167. put2: async (key: string, blob: Blob) => {
  168. const fileHandle = await _cache.getFileHandle(key, {
  169. create: true,
  170. });
  171. const writable = await fileHandle.createWritable();
  172. await writable.write(blob);
  173. await writable.close();
  174. },
  175. put: async (key: string, data: Response) => {
  176. await cache.put(key, data);
  177. },
  178. delete: (key: string) => {
  179. // try {
  180. // await _cache.removeEntry(key);
  181. // return true;
  182. // } catch (e) {
  183. // if (e instanceof DOMException && e.name == "NotFoundError")
  184. // return false;
  185. // throw e;
  186. // }
  187. return cache.delete(key);
  188. },
  189. };
  190. };
  191. export async function cached(
  192. cacheName: BlobCacheNamespace,
  193. id: string,
  194. get: () => Promise<Blob>,
  195. ): Promise<Blob> {
  196. const cache = await openCache(cacheName);
  197. const cachedBlob = await cache.get(id);
  198. if (cachedBlob) return cachedBlob;
  199. const blob = await get();
  200. await cache.put2(id, blob);
  201. return blob;
  202. }
  203. /**
  204. * Delete all cached data.
  205. *
  206. * Meant for use during logout, to reset the state of the user's account.
  207. */
  208. export const clearCaches = async () =>
  209. isElectron() ? clearOPFSCaches() : clearWebCaches();
  210. export const clearWebCaches = async () => {
  211. await Promise.all(blobCacheNames.map((name) => caches.delete(name)));
  212. };
  213. export const clearOPFSCaches = async () => {
  214. const root = await navigator.storage.getDirectory();
  215. await root.removeEntry("cache", { recursive: true });
  216. };