251 lines
7.6 KiB
TypeScript
251 lines
7.6 KiB
TypeScript
/**
|
|
* Regional CDN (R2) cache-file URLs.
|
|
*
|
|
* Single source of truth for the backend cache writer and both UIs:
|
|
* - the backend builds the URLs it publishes in `essentialConsts.essentialUrls`
|
|
* and the object keys it uploads/purges with them;
|
|
* - the UIs prefer `essentialUrls` from the API and fall back to these same
|
|
* builders when an older backend or a persisted snapshot does not carry it.
|
|
*
|
|
* Path shapes (do not change without migrating the existing buckets):
|
|
* {assetsDomain}{apiCacheKey}/regions/{regionId}/v-{productsVersion}/{file}
|
|
* {assetsDomain}regions/{regionId}/av-{availabilityVersion}/availability.json
|
|
* {assetsDomain}regions/{regionId}/slots/v-{slotsVersion}/slots.json
|
|
*
|
|
* Availability and slots intentionally sit OUTSIDE `apiCacheKey`. A builder
|
|
* returns an empty string when a part it needs is missing, never a malformed
|
|
* partial URL.
|
|
*/
|
|
|
|
export const CACHE_FILENAMES = {
|
|
products: 'products.json',
|
|
stores: 'stores.json',
|
|
slots: 'slots.json',
|
|
availability: 'availability.json',
|
|
essentialConsts: 'essential-consts.json',
|
|
banners: 'banners.json',
|
|
} as const
|
|
|
|
export type CacheFilename = (typeof CACHE_FILENAMES)[keyof typeof CACHE_FILENAMES]
|
|
|
|
export interface CacheVersions {
|
|
products: number
|
|
availability: number
|
|
slots: number
|
|
}
|
|
|
|
export interface EssentialUrls {
|
|
productsUrl: string
|
|
storesUrl: string
|
|
bannersUrl: string
|
|
essentialConstsUrl: string
|
|
availabilityUrl: string
|
|
slotsUrl: string
|
|
/** Per-store detail URL with a `{storeId}` placeholder for the caller to replace. */
|
|
storeDetailUrlTemplate: string
|
|
}
|
|
|
|
function clean(value: string | null | undefined): string {
|
|
return typeof value === 'string' ? value.trim() : ''
|
|
}
|
|
|
|
/** Assets domain with exactly one trailing slash ('' when unavailable). */
|
|
function domainBase(assetsDomain: string | null | undefined): string {
|
|
const domain = clean(assetsDomain)
|
|
if (!domain) return ''
|
|
return domain.endsWith('/') ? domain : `${domain}/`
|
|
}
|
|
|
|
function cacheKey(apiCacheKey: string | null | undefined): string {
|
|
return clean(apiCacheKey).replace(/^\/+|\/+$/g, '')
|
|
}
|
|
|
|
function version(value: number | null | undefined): string | null {
|
|
return typeof value === 'number' && Number.isFinite(value) ? String(value) : null
|
|
}
|
|
|
|
function joinUrl(domain: string, path: string): string {
|
|
return domain && path ? `${domain}${path}` : ''
|
|
}
|
|
|
|
/* -------------------------------------------------------------------------- */
|
|
/* Object keys (bucket-relative, used for uploads) */
|
|
/* -------------------------------------------------------------------------- */
|
|
|
|
export function regionCacheObjectKey(
|
|
apiCacheKeyValue: string | null | undefined,
|
|
regionId: number,
|
|
productsVersion: number,
|
|
filename: string
|
|
): string {
|
|
const key = cacheKey(apiCacheKeyValue)
|
|
const fileVersion = version(productsVersion)
|
|
if (!key || fileVersion == null) return ''
|
|
return `${key}/regions/${regionId}/v-${fileVersion}/${filename}`
|
|
}
|
|
|
|
export function availabilityObjectKey(
|
|
regionId: number,
|
|
availabilityVersion: number
|
|
): string {
|
|
const fileVersion = version(availabilityVersion)
|
|
if (fileVersion == null) return ''
|
|
return `regions/${regionId}/av-${fileVersion}/${CACHE_FILENAMES.availability}`
|
|
}
|
|
|
|
export function slotsObjectKey(regionId: number, slotsVersion: number): string {
|
|
const fileVersion = version(slotsVersion)
|
|
if (fileVersion == null) return ''
|
|
return `regions/${regionId}/slots/v-${fileVersion}/${CACHE_FILENAMES.slots}`
|
|
}
|
|
|
|
export function storeDetailObjectKey(
|
|
apiCacheKeyValue: string | null | undefined,
|
|
regionId: number,
|
|
productsVersion: number,
|
|
storeId: number
|
|
): string {
|
|
if (!Number.isFinite(storeId)) return ''
|
|
const key = cacheKey(apiCacheKeyValue)
|
|
const fileVersion = version(productsVersion)
|
|
if (!key || fileVersion == null) return ''
|
|
return `${key}/regions/${regionId}/v-${fileVersion}/stores/${storeId}.json`
|
|
}
|
|
|
|
/* -------------------------------------------------------------------------- */
|
|
/* CDN URLs */
|
|
/* -------------------------------------------------------------------------- */
|
|
|
|
export function regionCacheUrl(
|
|
assetsDomain: string | null | undefined,
|
|
apiCacheKeyValue: string | null | undefined,
|
|
regionId: number,
|
|
productsVersion: number,
|
|
filename: string
|
|
): string {
|
|
return joinUrl(
|
|
domainBase(assetsDomain),
|
|
regionCacheObjectKey(apiCacheKeyValue, regionId, productsVersion, filename)
|
|
)
|
|
}
|
|
|
|
export function availabilityCacheUrl(
|
|
assetsDomain: string | null | undefined,
|
|
regionId: number,
|
|
availabilityVersion: number
|
|
): string {
|
|
return joinUrl(domainBase(assetsDomain), availabilityObjectKey(regionId, availabilityVersion))
|
|
}
|
|
|
|
export function slotsCacheUrl(
|
|
assetsDomain: string | null | undefined,
|
|
regionId: number,
|
|
slotsVersion: number
|
|
): string {
|
|
return joinUrl(domainBase(assetsDomain), slotsObjectKey(regionId, slotsVersion))
|
|
}
|
|
|
|
export function storeDetailCacheUrl(
|
|
assetsDomain: string | null | undefined,
|
|
apiCacheKeyValue: string | null | undefined,
|
|
regionId: number,
|
|
productsVersion: number,
|
|
storeId: number
|
|
): string {
|
|
return joinUrl(
|
|
domainBase(assetsDomain),
|
|
storeDetailObjectKey(apiCacheKeyValue, regionId, productsVersion, storeId)
|
|
)
|
|
}
|
|
|
|
export function buildStoreDetailUrlTemplate(
|
|
assetsDomain: string | null | undefined,
|
|
apiCacheKeyValue: string | null | undefined,
|
|
regionId: number,
|
|
productsVersion: number
|
|
): string {
|
|
return regionCacheUrl(
|
|
assetsDomain,
|
|
apiCacheKeyValue,
|
|
regionId,
|
|
productsVersion,
|
|
'stores/{storeId}.json'
|
|
)
|
|
}
|
|
|
|
export interface EssentialUrlsInput {
|
|
assetsDomain?: string | null
|
|
apiCacheKey?: string | null
|
|
regionId: number
|
|
versions: CacheVersions
|
|
}
|
|
|
|
/** Every URL the browsing region can read from the CDN ('' when unavailable). */
|
|
export function buildEssentialUrls(input: EssentialUrlsInput): EssentialUrls {
|
|
const { assetsDomain, apiCacheKey: apiCacheKeyValue, regionId, versions } = input
|
|
|
|
return {
|
|
productsUrl: regionCacheUrl(
|
|
assetsDomain,
|
|
apiCacheKeyValue,
|
|
regionId,
|
|
versions.products,
|
|
CACHE_FILENAMES.products
|
|
),
|
|
storesUrl: regionCacheUrl(
|
|
assetsDomain,
|
|
apiCacheKeyValue,
|
|
regionId,
|
|
versions.products,
|
|
CACHE_FILENAMES.stores
|
|
),
|
|
bannersUrl: regionCacheUrl(
|
|
assetsDomain,
|
|
apiCacheKeyValue,
|
|
regionId,
|
|
versions.products,
|
|
CACHE_FILENAMES.banners
|
|
),
|
|
essentialConstsUrl: regionCacheUrl(
|
|
assetsDomain,
|
|
apiCacheKeyValue,
|
|
regionId,
|
|
versions.products,
|
|
CACHE_FILENAMES.essentialConsts
|
|
),
|
|
availabilityUrl: availabilityCacheUrl(assetsDomain, regionId, versions.availability),
|
|
slotsUrl: slotsCacheUrl(assetsDomain, regionId, versions.slots),
|
|
storeDetailUrlTemplate: buildStoreDetailUrlTemplate(
|
|
assetsDomain,
|
|
apiCacheKeyValue,
|
|
regionId,
|
|
versions.products
|
|
),
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Look up the published URL for a cache file. Returns null when the payload has
|
|
* no usable URL for it (missing field or empty string), so callers can fall back
|
|
* to the builders above.
|
|
*/
|
|
export function cachedFileUrl(
|
|
urls: Partial<EssentialUrls> | null | undefined,
|
|
filename: string
|
|
): string | null {
|
|
if (!urls) return null
|
|
|
|
const field = (
|
|
{
|
|
[CACHE_FILENAMES.products]: 'productsUrl',
|
|
[CACHE_FILENAMES.stores]: 'storesUrl',
|
|
[CACHE_FILENAMES.banners]: 'bannersUrl',
|
|
[CACHE_FILENAMES.essentialConsts]: 'essentialConstsUrl',
|
|
[CACHE_FILENAMES.availability]: 'availabilityUrl',
|
|
[CACHE_FILENAMES.slots]: 'slotsUrl',
|
|
} as Record<string, keyof EssentialUrls>
|
|
)[filename]
|
|
|
|
const value = field ? urls[field] : null
|
|
return typeof value === 'string' && value.length > 0 ? value : null
|
|
}
|