scheduled background functions

Author: tannerlinsley

netlify.toml

@@ -3,41 +3,4 @@ command = "vite build"
 publish = "dist/client"
 
 [functions]
-  directory = "netlify/functions"
-
-# Scheduled + Background Function Pattern
-#
-# The pattern for long-running cron jobs:
-# 1. Scheduled function (30s timeout) runs on cron schedule
-# 2. It invokes the background function via HTTP
-# 3. Returns immediately (202)
-# 4. Background function (15 min timeout) does the actual work
-#
-# Background functions are identified by the `-background` suffix in the filename.
-# They can also be invoked manually from the admin panel.
-
-# Scheduled function: Stats cache refresh (runs every 6 hours)
-[functions."scheduled/refresh-stats-cache"]
-schedule = "0 */6 * * *"
-
-# Scheduled function: GitHub release sync (runs every 6 hours)
-[functions."scheduled/sync-github-releases"]
-schedule = "0 */6 * * *"
-
-# Background Functions (invoked by scheduled functions or manually)
-#
-# 1. refresh-stats-cache-background.ts
-#    - Refreshes NPM and GitHub stats cache for the entire TanStack org
-#    - ~10-20 minutes to complete (200+ packages)
-#    - Invoked by: scheduled/refresh-stats-cache
-#    - Manual: POST /.netlify/functions/refresh-stats-cache-background
-#    - Authorization: Bearer YOUR_CRON_SECRET
-#
-# 2. sync-github-releases-background.ts
-#    - Syncs GitHub releases from all TanStack repos to the feed
-#    - ~1-5 minutes to complete
-#    - Invoked by: scheduled/sync-github-releases
-#    - Manual: POST /.netlify/functions/sync-github-releases-background
-#    - Authorization: Bearer YOUR_CRON_SECRET
-#
-# Note: Both functions require CRON_SECRET environment variable for authentication
+  directory = "netlify/functions"

netlify/functions/refresh-stats-cache-background.ts

@@ -7,21 +7,21 @@ import {
 import { setCachedGitHubStats } from '~/utils/stats-db.server'
 
 /**
- * Netlify Background Function - Refresh org-level stats cache
+ * Netlify Background + Scheduled Function - Refresh org-level stats cache
  *
- * Background functions are identified by the `-background` suffix in the filename.
- * They have a 15-minute timeout (vs 30 seconds for regular functions) and return
- * a 202 response immediately while processing continues in the background.
+ * This function combines both background and scheduled execution:
+ * - Can be invoked via HTTP POST (returns 202 immediately, runs in background)
+ * - Can be triggered on a schedule (runs automatically via cron)
+ *
+ * Background functions have a 15-minute timeout (vs 30 seconds for regular functions)
+ * and return a 202 response immediately while processing continues in the background.
  *
  * This function refreshes pre-aggregated stats for the TanStack organization:
  * - GitHub: stars, contributors, dependents
  * - NPM: total downloads across all packages (including legacy packages)
  *
- * Invocation:
- *   POST https://tanstack.com/.netlify/functions/refresh-stats-cache-background
- *   Authorization: Bearer YOUR_CRON_SECRET
- *
- * Can be triggered manually from the admin panel.
+ * Scheduled: Runs automatically every 6 hours (configured via export config)
+ * Only called by Netlify's scheduler - not publicly accessible
  * Timeout: 15 minutes
  * Concurrency: 8 packages at a time, 500ms delay between packages
  *
@@ -33,36 +33,7 @@ export const handler: Handler = async (
   event: HandlerEvent,
   context: HandlerContext
 ) => {
-  console.log(
-    '[refresh-stats-cache-background] Starting background stats refresh...'
-  )
-
-  // Check authentication
-  const cronSecret = process.env.CRON_SECRET
-  const authHeader = event.headers.authorization || event.headers.Authorization
-
-  if (!cronSecret) {
-    console.error('[refresh-stats-cache-background] CRON_SECRET not configured')
-    return {
-      statusCode: 500,
-      body: JSON.stringify({
-        error: 'CRON_SECRET not configured',
-      }),
-    }
-  }
-
-  // Extract token from "Bearer TOKEN" format
-  const providedSecret = authHeader?.replace(/^Bearer\s+/i, '')
-
-  if (providedSecret !== cronSecret) {
-    console.error('[refresh-stats-cache-background] Invalid authentication')
-    return {
-      statusCode: 401,
-      body: JSON.stringify({
-        error: 'Invalid authentication',
-      }),
-    }
-  }
+  console.log('[refresh-stats-cache-background] Starting stats refresh...')
 
   const startTime = Date.now()
 
@@ -200,3 +171,13 @@ export const handler: Handler = async (
     }
   }
 }
+
+/**
+ * Netlify function configuration
+ * - type: 'experimental-background' enables background execution (15 min timeout, returns 202 immediately)
+ * - schedule: Cron expression for scheduled execution (runs every 6 hours)
+ */
+export const config = {
+  type: 'experimental-background' as const,
+  schedule: '0 */6 * * *', // Every 6 hours
+}

netlify/functions/scheduled/refresh-stats-cache.ts

@@ -2,22 +2,22 @@ import type { Handler, HandlerEvent, HandlerContext } from '@netlify/functions'
 import { syncGitHubReleases } from '~/server/feed/github.functions'
 
 /**
- * Netlify Background Function - Sync GitHub releases
+ * Netlify Background + Scheduled Function - Sync GitHub releases
  *
- * Background functions are identified by the `-background` suffix in the filename.
- * They have a 15-minute timeout (vs 30 seconds for regular functions) and return
- * a 202 response immediately while processing continues in the background.
+ * This function combines both background and scheduled execution:
+ * - Can be invoked via HTTP POST (returns 202 immediately, runs in background)
+ * - Can be triggered on a schedule (runs automatically via cron)
+ *
+ * Background functions have a 15-minute timeout (vs 30 seconds for regular functions)
+ * and return a 202 response immediately while processing continues in the background.
  *
  * This function syncs GitHub releases from all TanStack repos:
  * - Fetches new releases since last sync
  * - Creates/updates feed items in the database
  * - Marks releases as synced to avoid duplicates
  *
- * Invocation:
- *   POST https://tanstack.com/.netlify/functions/sync-github-releases-background
- *   Authorization: Bearer YOUR_CRON_SECRET
- *
- * Triggered by: .github/workflows/sync-github-releases.yml (hourly cron)
+ * Scheduled: Runs automatically every 6 hours (configured via export config)
+ * Only called by Netlify's scheduler - not publicly accessible
  * Timeout: 15 minutes
  */
 export const handler: Handler = async (
@@ -28,35 +28,6 @@ export const handler: Handler = async (
     '[sync-github-releases-background] Starting GitHub release sync...'
   )
 
-  // Check authentication
-  const cronSecret = process.env.CRON_SECRET
-  const authHeader = event.headers.authorization || event.headers.Authorization
-
-  if (!cronSecret) {
-    console.error(
-      '[sync-github-releases-background] CRON_SECRET not configured'
-    )
-    return {
-      statusCode: 500,
-      body: JSON.stringify({
-        error: 'CRON_SECRET not configured',
-      }),
-    }
-  }
-
-  // Extract token from "Bearer TOKEN" format
-  const providedSecret = authHeader?.replace(/^Bearer\s+/i, '')
-
-  if (providedSecret !== cronSecret) {
-    console.error('[sync-github-releases-background] Invalid authentication')
-    return {
-      statusCode: 401,
-      body: JSON.stringify({
-        error: 'Invalid authentication',
-      }),
-    }
-  }
-
   const startTime = Date.now()
 
   try {
@@ -103,3 +74,13 @@ export const handler: Handler = async (
     }
   }
 }
+
+/**
+ * Netlify function configuration
+ * - type: 'experimental-background' enables background execution (15 min timeout, returns 202 immediately)
+ * - schedule: Cron expression for scheduled execution (runs every 6 hours)
+ */
+export const config = {
+  type: 'experimental-background' as const,
+  schedule: '0 */6 * * *', // Every 6 hours
+}