feat: warm-up a cache holding Linked-Wearables on boot time

Author: aleortega

src/adapters/third-party-collections-cache-warmer.ts

@@ -0,0 +1,269 @@
+import { IBaseComponent } from '@well-known-components/interfaces'
+import { AppComponents, ThirdPartyProvider } from '../types'
+
+export type ThirdPartyCollectionsCacheWarmer = IBaseComponent & {
+  warmCache(): Promise<void>
+  getStatus(): CacheWarmerStatus
+}
+
+export type CacheWarmerStatus = {
+  enabled: boolean
+  lastWarmupTime?: number
+  lastWarmupDuration?: number
+  collectionsWarmed: number
+  totalCollections: number
+  errors: string[]
+  isWarming: boolean
+}
+
+/**
+ * Cache warmer component that pre-loads third-party collections into cache
+ * on service boot and periodically refreshes them.
+ *
+ * This eliminates the cold-start penalty where the first user to request
+ * a collection triggers expensive pagination across thousands of entities.
+ */
+export async function createThirdPartyCollectionsCacheWarmer(
+  components: Pick<AppComponents, 'config' | 'logs' | 'thirdPartyProvidersStorage' | 'entitiesFetcher'>
+): Promise<ThirdPartyCollectionsCacheWarmer> {
+  const { config, logs, thirdPartyProvidersStorage, entitiesFetcher } = components
+  const logger = logs.getLogger('third-party-collections-cache-warmer')
+
+  // Configuration
+  const enabled = (await config.getString('CACHE_WARMER_ENABLED'))?.toLowerCase() === 'true' || false
+  const warmupIntervalMs = (await config.getNumber('CACHE_WARMER_INTERVAL_MS')) || 1000 * 60 * 60 * 24 // 24 hours default
+  const warmupDelayMs = (await config.getNumber('CACHE_WARMER_DELAY_MS')) || 5000 // 5 seconds delay after boot
+  const maxConcurrent = (await config.getNumber('CACHE_WARMER_MAX_CONCURRENT')) || 3 // Warm 3 collections in parallel
+
+  // State
+  let intervalId: ReturnType<typeof setInterval> | undefined
+  let isWarming = false
+  const status: CacheWarmerStatus = {
+    enabled,
+    collectionsWarmed: 0,
+    totalCollections: 0,
+    errors: [],
+    isWarming: false
+  }
+
+  /**
+   * Warm a single collection by fetching all its entities
+   */
+  async function warmCollection(provider: ThirdPartyProvider): Promise<void> {
+    const collectionId = provider.id
+    const providerName = provider.metadata?.thirdParty?.name || 'unknown'
+    const startTime = Date.now()
+
+    try {
+      logger.info('[warmCollection] Starting cache warm', {
+        collectionId,
+        providerName
+      })
+
+      // Fetch all entities - this will populate the 48h cache
+      const entities = await entitiesFetcher.fetchCollectionEntities(collectionId)
+      const duration = Date.now() - startTime
+
+      logger.info('[warmCollection] Collection warmed successfully', {
+        collectionId,
+        providerName,
+        entitiesCount: entities.length,
+        durationMs: duration
+      })
+
+      // Record metric (TODO: Uncomment when metrics are properly configured)
+      // metrics.increment('cache_warmer_collections_warmed_total', { collection: providerName })
+      // metrics.observe('cache_warmer_duration_seconds', duration / 1000, { collection: providerName })
+
+      status.collectionsWarmed++
+    } catch (error) {
+      const duration = Date.now() - startTime
+      const errorMsg = error instanceof Error ? error.message : 'Unknown error'
+
+      logger.error('[warmCollection] Failed to warm collection', {
+        collectionId,
+        providerName,
+        error: errorMsg,
+        durationMs: duration
+      })
+
+      status.errors.push(`${collectionId}: ${errorMsg}`)
+
+      // Record error metric (TODO: Uncomment when metrics are properly configured)
+      // metrics.increment('cache_warmer_errors_total', { collection: providerName })
+    }
+  }
+
+  /**
+   * Warm collections in batches with concurrency control
+   */
+  async function warmCollectionsInBatches(providers: ThirdPartyProvider[]): Promise<void> {
+    const batches: ThirdPartyProvider[][] = []
+
+    // Split providers into batches
+    for (let i = 0; i < providers.length; i += maxConcurrent) {
+      batches.push(providers.slice(i, i + maxConcurrent))
+    }
+
+    logger.info('[warmCollectionsInBatches] Processing batches', {
+      totalProviders: providers.length,
+      batchCount: batches.length,
+      maxConcurrent
+    })
+
+    // Process each batch sequentially, but items within batch in parallel
+    for (let i = 0; i < batches.length; i++) {
+      const batch = batches[i]
+      logger.debug('[warmCollectionsInBatches] Processing batch', {
+        batchNumber: i + 1,
+        batchSize: batch.length
+      })
+
+      await Promise.all(batch.map((provider) => warmCollection(provider)))
+    }
+  }
+
+  /**
+   * Main cache warming function
+   */
+  async function warmCache(): Promise<void> {
+    if (!enabled) {
+      logger.info('[warmCache] Cache warmer is disabled')
+      return
+    }
+
+    if (isWarming) {
+      logger.warn('[warmCache] Cache warming already in progress, skipping')
+      return
+    }
+
+    isWarming = true
+    status.isWarming = true
+    status.errors = []
+    status.collectionsWarmed = 0
+
+    const overallStart = Date.now()
+
+    try {
+      logger.info('[warmCache] Starting cache warmup')
+
+      // Get all third-party providers
+      const allProviders = await thirdPartyProvidersStorage.getAll()
+
+      // Filter providers with contracts (same logic as fetch-third-party-wearables)
+      const providersWithContracts = allProviders.filter(
+        (provider) => (provider.metadata.thirdParty.contracts?.length ?? 0) > 0
+      )
+
+      status.totalCollections = providersWithContracts.length
+
+      logger.info('[warmCache] Fetched third-party providers', {
+        totalProviders: allProviders.length,
+        providersWithContracts: providersWithContracts.length,
+        providersWithoutContracts: allProviders.length - providersWithContracts.length
+      })
+
+      if (providersWithContracts.length === 0) {
+        logger.warn('[warmCache] No providers with contracts found')
+        return
+      }
+
+      // Warm collections in batches
+      await warmCollectionsInBatches(providersWithContracts)
+
+      const overallDuration = Date.now() - overallStart
+      status.lastWarmupTime = overallStart
+      status.lastWarmupDuration = overallDuration
+
+      logger.info('[warmCache] Cache warmup complete', {
+        totalProviders: status.totalCollections,
+        warmedSuccessfully: status.collectionsWarmed,
+        failed: status.totalCollections - status.collectionsWarmed,
+        errorsCount: status.errors.length,
+        durationMs: overallDuration,
+        avgDurationPerCollection: Math.round(overallDuration / status.totalCollections)
+      })
+
+      // Record overall metrics (TODO: Uncomment when metrics are properly configured)
+      // metrics.observe('cache_warmer_total_duration_seconds', {}, overallDuration / 1000)
+      // metrics.increment('cache_warmer_last_warmup_timestamp', {}, overallStart / 1000)
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : 'Unknown error'
+      logger.error('[warmCache] Fatal error during cache warmup', {
+        error: errorMsg
+      })
+
+      status.errors.push(`Fatal: ${errorMsg}`)
+      // metrics.increment('cache_warmer_fatal_errors_total') // TODO: Uncomment when metrics are properly configured
+    } finally {
+      isWarming = false
+      status.isWarming = false
+    }
+  }
+
+  /**
+   * Get current cache warmer status
+   */
+  function getStatus(): CacheWarmerStatus {
+    return { ...status }
+  }
+
+  /**
+   * Start the cache warmer component
+   */
+  async function start() {
+    if (!enabled) {
+      logger.info('[start] Cache warmer is disabled via config')
+      return
+    }
+
+    logger.info('[start] Cache warmer starting', {
+      warmupIntervalMs,
+      warmupDelayMs,
+      maxConcurrent
+    })
+
+    // Initial warmup after delay
+    setTimeout(() => {
+      logger.info('[start] Starting initial cache warmup')
+      warmCache().catch((error) => {
+        logger.error('[start] Initial warmup failed', {
+          error: error instanceof Error ? error.message : 'Unknown error'
+        })
+      })
+    }, warmupDelayMs)
+
+    // Periodic warmup
+    intervalId = setInterval(() => {
+      logger.info('[start] Starting periodic cache warmup')
+      warmCache().catch((error) => {
+        logger.error('[start] Periodic warmup failed', {
+          error: error instanceof Error ? error.message : 'Unknown error'
+        })
+      })
+    }, warmupIntervalMs)
+
+    logger.info('[start] Cache warmer started successfully')
+  }
+
+  /**
+   * Stop the cache warmer component
+   */
+  async function stop() {
+    logger.info('[stop] Stopping cache warmer')
+
+    if (intervalId) {
+      clearInterval(intervalId)
+      intervalId = undefined
+    }
+
+    logger.info('[stop] Cache warmer stopped')
+  }
+
+  return {
+    start,
+    stop,
+    warmCache,
+    getStatus
+  }
+}

src/components.ts

@@ -42,6 +42,7 @@ import { createThirdPartyItemChecker } from './ports/ownership-checker/third-par
 import { createParcelRightsComponent } from './adapters/parcel-rights-fetcher'
 import { fetchNameOwner } from './logic/fetch-elements/fetch-name-owner'
 import { fetchAllPermissions } from './logic/fetch-elements/fetch-permissions'
+import { createThirdPartyCollectionsCacheWarmer } from './adapters/third-party-collections-cache-warmer'
 
 // Initialize all the components of the app
 export async function initComponents(
@@ -194,6 +195,14 @@ export async function initComponents(
     l2ThirdPartyItemChecker
   })
 
+  // Create cache warmer component
+  const thirdPartyCollectionsCacheWarmer = await createThirdPartyCollectionsCacheWarmer({
+    config,
+    logs,
+    thirdPartyProvidersStorage,
+    entitiesFetcher
+  })
+
   return {
     config,
     logs,
@@ -230,6 +239,7 @@ export async function initComponents(
     l1ThirdPartyItemChecker,
     l2ThirdPartyItemChecker,
     marketplaceApiFetcher,
-    nameOwnerFetcher
+    nameOwnerFetcher,
+    thirdPartyCollectionsCacheWarmer
   }
 }

src/metrics.ts

@@ -22,6 +22,36 @@ export const metricDeclarations = {
     help: 'Third Party Provider fetch assets request duration in seconds.',
     type: IMetricsComponent.HistogramType,
     labelNames: ['id']
+  },
+  cache_warmer_collections_warmed_total: {
+    help: 'Total number of collections successfully warmed by the cache warmer',
+    type: IMetricsComponent.CounterType,
+    labelNames: ['collection']
+  },
+  cache_warmer_duration_seconds: {
+    help: 'Duration of cache warming per collection in seconds',
+    type: IMetricsComponent.HistogramType,
+    labelNames: ['collection']
+  },
+  cache_warmer_errors_total: {
+    help: 'Total number of cache warming errors',
+    type: IMetricsComponent.CounterType,
+    labelNames: ['collection']
+  },
+  cache_warmer_fatal_errors_total: {
+    help: 'Total number of fatal cache warming errors',
+    type: IMetricsComponent.CounterType,
+    labelNames: []
+  },
+  cache_warmer_total_duration_seconds: {
+    help: 'Total duration of full cache warmup cycle in seconds',
+    type: IMetricsComponent.HistogramType,
+    labelNames: []
+  },
+  cache_warmer_last_warmup_timestamp: {
+    help: 'Unix timestamp of the last successful cache warmup',
+    type: IMetricsComponent.GaugeType,
+    labelNames: []
   }
 }
 

src/types.ts

@@ -38,6 +38,7 @@ import { AlchemyNftFetcher } from './adapters/alchemy-nft-fetcher'
 import { ThirdPartyItemChecker } from './ports/ownership-checker/third-party-item-checker'
 import { ParcelRightsFetcher } from './adapters/parcel-rights-fetcher'
 import { MarketplaceApiFetcher } from './adapters/marketplace-api-fetcher'
+import { ThirdPartyCollectionsCacheWarmer } from './adapters/third-party-collections-cache-warmer'
 
 export type GlobalContext = {
   components: BaseComponents
@@ -80,6 +81,7 @@ export type BaseComponents = {
   l2ThirdPartyItemChecker: ThirdPartyItemChecker
   marketplaceApiFetcher?: MarketplaceApiFetcher
   nameOwnerFetcher: ElementsFetcher<NameOwner>
+  thirdPartyCollectionsCacheWarmer: ThirdPartyCollectionsCacheWarmer
 }
 
 // components used in runtime