Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

fix: titiler.xyz CORS cache breaking COG tiles on demo and HTML export (#3765)

Igor Dykhtad49a5200bfcf
diff --git a/src/common-utils/src/url.spec.ts b/src/common-utils/src/url.spec.ts
index 3a6e5563c..7f2fbf3c2 100644
--- a/src/common-utils/src/url.spec.ts
+++ b/src/common-utils/src/url.spec.ts
@@ -2,11 +2,13 @@
// Copyright contributors to the kepler.gl project
import {
+ getTitilerCorsCacheOrigin,
isCOGUrl,
isGeoTiffContentType,
isTiffMagicBytes,
probeUrlIsCOG,
- shouldProbeForCOG
+ shouldProbeForCOG,
+ withPublicTitilerCorsCacheKey
} from './url';
const NEXTGIS_COG = 'https://nextgis-web.prod.heritagewatch.ai/api/resource/2564/cog';
@@ -207,3 +209,48 @@ describe('probeUrlIsCOG', () => {
jest.useRealTimers();
});
});
+
+describe('withPublicTitilerCorsCacheKey', () => {
+ test('appends a sanitized origin token to public titiler.xyz URLs', () => {
+ const result = withPublicTitilerCorsCacheKey(TITILER_STAC, 'https://kepler.gl');
+ const parsed = new URL(result);
+ expect(parsed.hostname).toBe('titiler.xyz');
+ expect(parsed.searchParams.get('url')).toBe(NEXTGIS_COG);
+ expect(parsed.searchParams.get('kepler_origin')).toBe('https_kepler.gl');
+ });
+
+ test('does not put :// in the query value (CloudFront WAF 403s nested URLs)', () => {
+ const result = withPublicTitilerCorsCacheKey(TITILER_STAC, 'http://localhost:8080');
+ const token = new URL(result).searchParams.get('kepler_origin');
+ expect(token).toBe('http_localhost_8080');
+ expect(token).not.toContain('://');
+ });
+
+ test('leaves non-titiler URLs unchanged', () => {
+ expect(withPublicTitilerCorsCacheKey(TIF_URL, 'https://kepler.gl')).toBe(TIF_URL);
+ expect(withPublicTitilerCorsCacheKey(STAC_COLLECTION, 'https://kepler.gl')).toBe(
+ STAC_COLLECTION
+ );
+ });
+
+ test('leaves titiler URLs unchanged when origin is missing', () => {
+ expect(withPublicTitilerCorsCacheKey(TITILER_STAC, null)).toBe(TITILER_STAC);
+ expect(withPublicTitilerCorsCacheKey(TITILER_STAC, '')).toBe(TITILER_STAC);
+ });
+
+ test('overwrites a stale kepler_origin with the current origin token', () => {
+ const stale = `${TITILER_STAC}&kepler_origin=${encodeURIComponent('http://localhost:8080')}`;
+ const result = withPublicTitilerCorsCacheKey(stale, 'https://kepler.gl');
+ expect(new URL(result).searchParams.get('kepler_origin')).toBe('https_kepler.gl');
+ });
+
+ test('maps file:// and opaque origins to the null CORS origin', () => {
+ expect(getTitilerCorsCacheOrigin('file://')).toBe('null');
+ expect(getTitilerCorsCacheOrigin('null')).toBe('null');
+ expect(
+ new URL(withPublicTitilerCorsCacheKey(TITILER_STAC, 'file://')).searchParams.get(
+ 'kepler_origin'
+ )
+ ).toBe('null');
+ });
+});
diff --git a/src/common-utils/src/url.ts b/src/common-utils/src/url.ts
index 8ba5f2a5e..7c5843e7a 100644
--- a/src/common-utils/src/url.ts
+++ b/src/common-utils/src/url.ts
@@ -75,6 +75,86 @@ export const isPMTilesUrl = (url?: string | null) => url?.includes('.pmtiles');
const COG_EXTENSIONS = ['.tif', '.tiff', '.geotiff', '.geotif', '.gtiff', '.cog'];
+/** Public TiTiler instance used for COG preview in the Add Data modal. */
+const PUBLIC_TITILER_HOST = 'titiler.xyz';
+
+/**
+ * Query param used to partition CloudFront's cache for titiler.xyz.
+ * The public service echoes Access-Control-Allow-Origin and caches with
+ * `public, max-age=3600` but without Vary: Origin. A request from
+ * http://localhost:8080 (or a file:// HTML export, origin `null`) can then
+ * be served to https://kepler.gl with a mismatched CORS header.
+ *
+ * Values must not contain `://` — CloudFront's WAF 403s query strings that
+ * look like nested URLs (`kepler_origin=http://localhost:8080`).
+ */
+const PUBLIC_TITILER_CORS_CACHE_PARAM = 'kepler_origin';
+
+/** CORS origin sent by file:// documents and other opaque origins. */
+const OPAQUE_CORS_ORIGIN = 'null';
+
+function isHttpUrlOrigin(origin: string): boolean {
+ return /^https?:\/\//i.test(origin);
+}
+
+/** `http://localhost:8080` → `http_localhost_8080` */
+function sanitizeTitilerCorsCacheKey(origin: string): string {
+ return origin.replace(/:\/\//g, '_').replace(/:/g, '_');
+}
+
+/**
+ * Origin used to partition titiler.xyz CloudFront CORS caches.
+ * file:// HTML exports send `Origin: null`; use that same cache key so they
+ * do not inherit a header cached for https://kepler.gl after an npm release
+ * that includes this helper in the UMD bundle.
+ */
+export function getTitilerCorsCacheOrigin(locationOrigin?: string | null): string | null {
+ const origin =
+ locationOrigin === undefined
+ ? typeof window === 'undefined'
+ ? null
+ : window.location?.origin ?? null
+ : locationOrigin;
+
+ if (origin && isHttpUrlOrigin(origin)) {
+ return sanitizeTitilerCorsCacheKey(origin);
+ }
+ if (origin === OPAQUE_CORS_ORIGIN || (typeof origin === 'string' && origin.startsWith('file:'))) {
+ return OPAQUE_CORS_ORIGIN;
+ }
+ if (
+ locationOrigin === undefined &&
+ typeof window !== 'undefined' &&
+ window.location?.protocol === 'file:'
+ ) {
+ return OPAQUE_CORS_ORIGIN;
+ }
+ return null;
+}
+
+/**
+ * Append the current page origin to public titiler.xyz URLs so CloudFront
+ * caches CORS responses per origin. No-ops for other hosts or when origin
+ * cannot be determined (Node).
+ */
+export function withPublicTitilerCorsCacheKey(url: string, origin?: string | null): string {
+ const cacheOrigin = getTitilerCorsCacheOrigin(origin);
+ if (!url || !cacheOrigin) {
+ return url;
+ }
+
+ try {
+ const parsed = new URL(url);
+ if (parsed.hostname !== PUBLIC_TITILER_HOST) {
+ return url;
+ }
+ parsed.searchParams.set(PUBLIC_TITILER_CORS_CACHE_PARAM, cacheOrigin);
+ return parsed.toString();
+ } catch {
+ return url;
+ }
+}
+
function getUrlPathname(url: string): string {
try {
return new URL(url).pathname.toLowerCase().replace(/\/+$/, '');
diff --git a/src/components/src/hooks/use-fetch-raster-tile-metadata.ts b/src/components/src/hooks/use-fetch-raster-tile-metadata.ts
index 7fa9539f8..a3da14af2 100644
--- a/src/components/src/hooks/use-fetch-raster-tile-metadata.ts
+++ b/src/components/src/hooks/use-fetch-raster-tile-metadata.ts
@@ -6,6 +6,7 @@ import {useEffect, useState} from 'react';
import {PMTilesSource, PMTilesMetadata} from '@loaders.gl/pmtiles';
+import {withPublicTitilerCorsCacheKey} from '@kepler.gl/common-utils';
import {VectorTileMetadata} from '@kepler.gl/table';
import {JsonObjectOrArray, StacTypes} from '@kepler.gl/types';
import {RasterTileType} from '@kepler.gl/constants';
@@ -51,7 +52,7 @@ export default function useFetchJson({
const tileSource = PMTilesSource.createDataSource(url, {});
rawMetadata = await tileSource.metadata;
} else {
- const response = await fetch(url, options);
+ const response = await fetch(withPublicTitilerCorsCacheKey(url), options);
if (!response.ok) {
throw new Error(`Failed Fetch ${url}`);
}
diff --git a/src/layers/src/raster-tile/image.ts b/src/layers/src/raster-tile/image.ts
index 05a5bf178..4455c10d8 100644
--- a/src/layers/src/raster-tile/image.ts
+++ b/src/layers/src/raster-tile/image.ts
@@ -9,7 +9,7 @@ import {load, FetchError} from '@loaders.gl/core';
import {QuantizedMeshLoader} from '@loaders.gl/terrain';
import memoize from 'es-toolkit/compat/memoize';
-import {sleep} from '@kepler.gl/common-utils';
+import {sleep, withPublicTitilerCorsCacheKey} from '@kepler.gl/common-utils';
import {getLoaderOptions} from '@kepler.gl/constants';
import {getApplicationConfig} from '@kepler.gl/utils';
@@ -198,7 +198,9 @@ export async function getAssetRequest({
const requestParams = params ?? new URLSearchParams();
const requestOptions = options;
- const assetUrl = requestParams ? `${requestUrl}?${requestParams.toString()}` : requestUrl;
+ const assetUrl = withPublicTitilerCorsCacheKey(
+ requestParams ? `${requestUrl}?${requestParams.toString()}` : requestUrl
+ );
return {
url: assetUrl,
rasterServerUrl,
diff --git a/src/table/src/dataset-utils.ts b/src/table/src/dataset-utils.ts
index 01d98ed87..0a666398e 100644
--- a/src/table/src/dataset-utils.ts
+++ b/src/table/src/dataset-utils.ts
@@ -15,6 +15,7 @@ import {
VectorTileDatasetMetadata,
WMSDatasetMetadata
} from '@kepler.gl/constants';
+import {withPublicTitilerCorsCacheKey} from '@kepler.gl/common-utils';
import {
hexToRgb,
validateInputData,
@@ -234,7 +235,7 @@ async function refreshRasterTileMetadata(datasetInfo: CreateTableProps): Promise
}
} else {
// it's stac raster tiles
- const response = await fetch(metadataUrl);
+ const response = await fetch(withPublicTitilerCorsCacheKey(metadataUrl));
if (!response.ok) {
throw new Error(`Failed Fetch ${metadataUrl}`);
}