freshyo/packages/shared/region-cache-urls.ts
2026-10-25 10:30:05 +05:30

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
}