Client-side caching for fonts and tiles

CHANGELOG.md

@@ -8,6 +8,7 @@
 ## 2.0.0
 ### New Features
 - Updating with MapLibre GL JS v4.1
+- Added client-side caching mechanism for tiles and fonts
 ### Bug Fixes
 ### Others
 - Removed `Map.loadImageAsync()` as MapLibre's `.loadImage()` is now promise based.
@@ -143,7 +144,7 @@
 ### New Features
 - The `apiKey` can now be specified in the `Map` constructor (will propagate to `config`)
 - The `language` can now be speficifed in the `Map` constructo (will **not** propagete to `config` and will apply only to this specific instance)
-- `Map` now has the method `.getSdkConfig()` to retrieve the config object. 
+- `Map` now has the method `.getSdkConfig()` to retrieve the config object.
 - `Map` now has the method `.getMaptilerSessionId()` to retrieve the MapTiler session ID
 Both `.getSdkConfig()` and `.getMaptilerSessionId()` are handy for layers or control built outside of the SDK that still need some of the configuration to interact with the server. Those components do not always have access to the internal of the SDK (especially that the config is scoped) but can access to the `Map` instance to which they are added with the implementation of the `.onAdd()` method.
 

src/Map.ts

@@ -40,6 +40,7 @@ import { FullscreenControl } from "./MLAdapters/FullscreenControl";
 
 import Minimap from "./Minimap";
 import type { MinimapOptionsInput } from "./Minimap";
+import { registerLocalCacheProtocol } from "./caching";
 
 export type LoadWithTerrainEvent = {
   type: "loadWithTerrain";
@@ -211,6 +212,10 @@ export class Map extends maplibregl.Map {
       transformRequest: combineTransformRequest(options.transformRequest),
     });
 
+    if (config.caching) {
+      registerLocalCacheProtocol();
+    }
+
     this.primaryLanguage = options.language ?? config.primaryLanguage;
     this.forceLanguageUpdate =
       this.primaryLanguage === Language.STYLE ||

src/caching.ts

@@ -0,0 +1,147 @@
+import {
+  GetResourceResponse,
+  RequestParameters,
+  ResourceType,
+  addProtocol,
+} from "maplibre-gl";
+import { config } from ".";
+import { defaults } from "./defaults";
+
+const LOCAL_CACHE_PROTOCOL_SOURCE = "localcache_source";
+const LOCAL_CACHE_PROTOCOL_DATA = "localcache";
+const LOCAL_CACHE_NAME = "maptiler_sdk";
+
+const CACHE_LIMIT_ITEMS = 1000;
+const CACHE_LIMIT_CHECK_INTERVAL = 100;
+
+export function localCacheTransformRequest(
+  reqUrl: URL,
+  resourceType?: ResourceType,
+): string {
+  if (
+    config.caching &&
+    config.session &&
+    reqUrl.host === defaults.maptilerApiHost
+  ) {
+    if (resourceType == "Source") {
+      return reqUrl.href.replace(
+        "https://",
+        `${LOCAL_CACHE_PROTOCOL_SOURCE}://`,
+      );
+    } else if (resourceType == "Tile" || resourceType == "Glyphs") {
+      return reqUrl.href.replace("https://", `${LOCAL_CACHE_PROTOCOL_DATA}://`);
+    }
+  }
+  return reqUrl.href;
+}
+
+let cacheInstance: Cache;
+
+async function getCache() {
+  if (!cacheInstance) {
+    cacheInstance = await caches.open(LOCAL_CACHE_NAME);
+  }
+  return cacheInstance;
+}
+
+let cachePutCounter = 0;
+async function limitCache() {
+  const cache = await getCache();
+  const keys = await cache.keys();
+  const toPurge = keys.slice(0, Math.max(keys.length - CACHE_LIMIT_ITEMS, 0));
+  for (const key of toPurge) {
+    cache.delete(key);
+  }
+}
+
+export function registerLocalCacheProtocol() {
+  addProtocol(
+    LOCAL_CACHE_PROTOCOL_SOURCE,
+    async (
+      params: RequestParameters,
+      abortController: AbortController,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ): Promise<GetResourceResponse<any>> => {
+      if (!params.url) throw new Error("");
+
+      params.url = params.url.replace(
+        `${LOCAL_CACHE_PROTOCOL_SOURCE}://`,
+        "https://",
+      );
+
+      const requestInit: RequestInit = params;
+      requestInit.signal = abortController.signal;
+      const response = await fetch(params.url, requestInit);
+      const json = await response.json();
+
+      // move `Last-Modified` to query so it propagates to tile URLs
+      json.tiles[0] +=
+        "&last-modified=" + response.headers.get("Last-Modified");
+
+      return {
+        data: json,
+        cacheControl: response.headers.get("Cache-Control"),
+        expires: response.headers.get("Expires"),
+      };
+    },
+  );
+  addProtocol(
+    LOCAL_CACHE_PROTOCOL_DATA,
+    async (
+      params: RequestParameters,
+      abortController: AbortController,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ): Promise<GetResourceResponse<any>> => {
+      if (!params.url) throw new Error("");
+
+      params.url = params.url.replace(
+        `${LOCAL_CACHE_PROTOCOL_DATA}://`,
+        "https://",
+      );
+
+      const url = new URL(params.url);
+
+      const cacheableUrl = new URL(url);
+      cacheableUrl.searchParams.delete("mtsid");
+      cacheableUrl.searchParams.delete("key");
+      const cacheKey = cacheableUrl.toString();
+
+      const fetchableUrl = new URL(url);
+      fetchableUrl.searchParams.delete("last-modified");
+      const fetchUrl = fetchableUrl.toString();
+
+      const respond = async (
+        response: Response,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      ): Promise<GetResourceResponse<any>> => {
+        return {
+          data: await response.arrayBuffer(),
+          cacheControl: response.headers.get("Cache-Control"),
+          expires: response.headers.get("Expires"),
+        };
+      };
+
+      const cache = await getCache();
+      const cacheMatch = await cache.match(cacheKey);
+
+      if (cacheMatch) {
+        return respond(cacheMatch);
+      } else {
+        const requestInit: RequestInit = params;
+        requestInit.signal = abortController.signal;
+        const response = await fetch(fetchUrl, requestInit);
+        if (response.status >= 200 && response.status < 300) {
+          cache.put(cacheKey, response.clone()).catch(() => {
+            // "DOMException: Cache.put() was aborted"
+            // can happen here because the response is not done streaming yet
+          });
+          if (++cachePutCounter > CACHE_LIMIT_CHECK_INTERVAL) {
+            limitCache();
+            cachePutCounter = 0;
+          }
+        }
+        return respond(response);
+      }
+    },
+  );
+}

src/config.ts

@@ -31,6 +31,13 @@ class SdkConfig extends EventEmitter {
    */
   session = true;
 
+  /**
+   * Enables client-side caching of requests for tiles and fonts.
+   * The cached requests persist multiple browser sessions and will be reused when possible.
+   * Works only for requests to the MapTiler Cloud API when sessions are enabled.
+   */
+  caching = true;
+
   /**
    * Unit to be used
    */

src/tools.ts

@@ -7,6 +7,7 @@ import type {
 import { defaults } from "./defaults";
 import { config } from "./config";
 import { MAPTILER_SESSION_ID } from "./config";
+import { localCacheTransformRequest } from "./caching";
 
 export function enableRTL() {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -59,9 +60,7 @@ export function DOMremove(node: HTMLElement) {
  */
 export function maptilerCloudTransformRequest(
   url: string,
-  // keep incase we need it in the future
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  _resourceType?: ResourceType,
+  resourceType?: ResourceType,
 ): RequestParameters {
   let reqUrl = null;
 
@@ -87,7 +86,7 @@ export function maptilerCloudTransformRequest(
   }
 
   return {
-    url: reqUrl.href,
+    url: localCacheTransformRequest(reqUrl, resourceType),
   };
 }
 
@@ -104,14 +103,14 @@ export function combineTransformRequest(
   ): RequestParameters {
     if (userDefinedRTF !== undefined) {
       const rp = userDefinedRTF(url, resourceType);
-      const rp2 = maptilerCloudTransformRequest(rp?.url ?? "");
+      const rp2 = maptilerCloudTransformRequest(rp?.url ?? "", resourceType);
 
       return {
         ...rp,
         ...rp2,
       };
     } else {
-      return maptilerCloudTransformRequest(url);
+      return maptilerCloudTransformRequest(url, resourceType);
     }
   };
 }