feat: add CDN cache purging for Storage files

Author: maximseshuk

README.md

@@ -9,15 +9,17 @@ Built on top of `@payloadcms/plugin-cloud-storage` for easy integration with Pay
 ## Table of Contents
 
 - [Features](#features)
-- [Performance Recommendation](#⚡-performance-recommendation)
+- [Performance Recommendation](#-performance-recommendation)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Configuration](#configuration)
   - [Collections](#collections-configuration)
   - [Storage](#storage-configuration)
   - [Stream](#stream-configuration)
+  - [Cache Purging](#cache-purging-configuration)
   - [Admin Thumbnails](#admin-thumbnail-configuration)
   - [Access Control](#access-control-configuration)
+- [CDN Cache Management](#cdn-cache-management)
 - [Getting API Keys](#getting-api-keys)
 - [Storage Regions](#storage-regions)
 - [Examples](#examples)
@@ -28,6 +30,7 @@ Built on top of `@payloadcms/plugin-cloud-storage` for easy integration with Pay
 - Handle videos with Bunny Stream (HLS, MP4, thumbnails)
 - Show thumbnails in your admin panel
 - Control access via Payload or direct CDN links
+- Automatic CDN cache purging for updated files
 
 ## ⚡ Performance Recommendation
 
@@ -157,6 +160,29 @@ stream: {
 
 **Important**: Video support is always available, even without Bunny Stream configured. If Bunny Stream is disabled, video files will simply be uploaded to Bunny Storage like any other file type. Bunny Stream just provides enhanced video features (streaming, adaptive bitrates, thumbnails).
 
+### Cache Purging Configuration
+
+Enable automatic CDN cache purging for storage files (not applicable to Stream):
+
+```typescript
+purge: {
+  // Enable cache purging
+  enabled: true,
+  
+  // Your Bunny API key
+  apiKey: string,
+  
+  // Optional: wait for purge to complete (default: false)
+  async?: boolean
+}
+```
+
+When enabled, the plugin will automatically purge the CDN cache after:
+- File uploads
+- File deletions
+
+This ensures that visitors always see the most up-to-date version of your files, which is especially important when replacing existing files (e.g., during image cropping operations).
+
 ### Admin Thumbnail Configuration
 
 Control thumbnails in your admin panel:
@@ -177,6 +203,8 @@ adminThumbnail: {
 }
 ```
 
+When `appendTimestamp` is enabled (or using the default setting), the plugin automatically adds a timestamp parameter to image URLs in the admin panel. This ensures that when files are updated, the admin UI always shows the latest version without browser caching issues.
+
 The `queryParams` option is particularly useful when used with Bunny's Image Optimizer service, allowing you to resize, crop, and optimize images on-the-fly.
 
 ### Access Control Configuration
@@ -207,6 +235,47 @@ When `disablePayloadAccessControl: true`:
 - Faster delivery but open access
 - No need for MP4 fallback
 
+## CDN Cache Management
+
+There are two approaches to managing the CDN cache for your Bunny Storage files:
+
+### Option 1: Automatic Cache Purging
+
+You can enable automatic cache purging whenever files are uploaded or deleted:
+
+```typescript
+purge: {
+  enabled: true,
+  apiKey: process.env.BUNNY_API_KEY,
+  async: false // Wait for purge to complete (default: false)
+}
+```
+
+This is the most comprehensive approach as it ensures the CDN cache is immediately purged when files change, making the updated content available to all visitors.
+
+### Option 2: Timestamp-Based Cache Busting
+
+For the admin panel specifically, you can use timestamp-based cache busting:
+
+1. First, configure the plugin to add timestamps to image URLs:
+
+```typescript
+adminThumbnail: {
+  appendTimestamp: true
+}
+```
+
+2. In your Bunny Pull Zone settings:
+   - Go to the "Caching" section
+   - Enable "Vary Cache" for "URL Query String"
+   - Add "t" to the "Query String Vary Parameters" list
+
+This approach only affects how images are displayed in the admin panel and doesn't purge the actual CDN cache. It appends a timestamp parameter (`?t=1234567890`) to image URLs, causing Bunny CDN to treat each timestamped URL as a unique cache entry.
+
+Choose the approach that best fits your needs:
+- Use **automatic cache purging** for immediate updates everywhere
+- Use **timestamp-based cache busting** for a simpler setup that only affects the admin panel
+
 ## Getting API Keys
 
 ### Bunny Storage API Key
@@ -233,6 +302,16 @@ To find your Bunny Stream API key:
 5. Find "CDN Hostname" for your `hostname` setting (like "vz-example-123.b-cdn.net")
 6. The "API Key" is found at the bottom of the page
 
+### Bunny API Key
+
+To find your Bunny API key (used for cache purging):
+
+1. Go to your Bunny.net dashboard
+2. Click on your account in the top-right corner
+3. Select "Account settings" from the dropdown menu
+4. Click on "API" in the sidebar menu
+5. Copy the API key displayed on the page
+
 ## Storage Regions
 
 Choose where to store your files. If you don't pick a region, the default storage location is used.
@@ -281,6 +360,28 @@ bunnyStorage({
 })
 ```
 
+### With Cache Purging Enabled
+
+```typescript
+bunnyStorage({
+  collections: {
+    media: true,
+  },
+  options: {
+    storage: {
+      apiKey: process.env.BUNNY_STORAGE_API_KEY,
+      hostname: 'storage.example.b-cdn.net',
+      zoneName: 'my-zone',
+    },
+    purge: {
+      enabled: true,
+      apiKey: process.env.BUNNY_API_KEY,
+      async: false, // Wait for purge to complete
+    },
+  },
+})
+```
+
 ### With Bunny Stream & Direct CDN Access
 
 ```typescript
@@ -304,6 +405,10 @@ bunnyStorage({
       libraryId: '123456',
       thumbnailTime: 5000, // 5 seconds in milliseconds
     },
+    purge: {
+      enabled: true,
+      apiKey: process.env.BUNNY_API_KEY,
+    },
   },
 })
 ```
@@ -332,6 +437,10 @@ bunnyStorage({
       mp4Fallback: { enabled: true }, // Required with access control
       thumbnailTime: 5000, // 5 seconds in milliseconds
     },
+    purge: {
+      enabled: true,
+      apiKey: process.env.BUNNY_API_KEY,
+    },
   },
 })
 ```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seshuk/payload-storage-bunny",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Payload storage adapter for Bunny.net",
   "author": "Maxim Seshuk",
   "license": "MIT",

src/generateURL.ts

@@ -10,6 +10,6 @@ export const getGenerateURL = ({ storage, stream }: BunnyAdapterOptions): Genera
       return `https://${stream.hostname}/${data.bunnyVideoId}/playlist.m3u8`
     }
 
-    return `https://${storage.hostname}/${posix.join(prefix, filename)}`
+    return `https://${storage.hostname}/${encodeURI(posix.join(prefix, filename))}`
   }
 }

src/handleDelete.ts

@@ -6,13 +6,24 @@ import { APIError } from 'payload'
 
 import type { BunnyAdapterOptions } from './types.js'
 
-import { getStorageUrl, getVideoFromDoc } from './utils.js'
+import { getGenerateURL } from './generateURL.js'
+import { getStorageUrl, getVideoFromDoc, purgeBunnyCache } from './utils.js'
 
-export const getHandleDelete = ({ storage, stream }: BunnyAdapterOptions): HandleDelete => {
-  return async ({ doc, filename, req }) => {
+export const getHandleDelete = ({ purge, storage, stream }: BunnyAdapterOptions): HandleDelete => {
+  return async ({ collection, doc, filename, req }) => {
     try {
       const video = getVideoFromDoc(doc, filename)
 
+      let fileUrl: null | string = null
+      if (!video && purge && purge.enabled) {
+        fileUrl = await getGenerateURL({ storage, stream })({
+          collection,
+          data: doc,
+          filename,
+          prefix: doc.prefix || '',
+        })
+      }
+
       if (stream && video) {
         await ky.delete(
           `https://video.bunnycdn.com/library/${stream.libraryId}/videos/${video.videoId}`,
@@ -37,6 +48,10 @@ export const getHandleDelete = ({ storage, stream }: BunnyAdapterOptions): Handl
             timeout: 120000,
           },
         )
+
+        if (purge && purge.enabled && fileUrl) {
+          await purgeBunnyCache(fileUrl, purge, req)
+        }
       }
     } catch (err) {
       if (err instanceof HTTPError) {

src/handleUpload.ts

@@ -6,12 +6,13 @@ import { APIError } from 'payload'
 
 import type { BunnyAdapterOptions } from './types.js'
 
-import { getStorageUrl } from './utils.js'
+import { getGenerateURL } from './generateURL.js'
+import { getStorageUrl, purgeBunnyCache } from './utils.js'
 
 type Args = { prefix?: string } & BunnyAdapterOptions
 
-export const getHandleUpload = ({ prefix, storage, stream }: Args): HandleUpload => {
-  return async ({ data, file, req }) => {
+export const getHandleUpload = ({ prefix, purge, storage, stream }: Args): HandleUpload => {
+  return async ({ collection, data, file, req }) => {
     data.url = null
     data.thumbnailURL = null
 
@@ -57,6 +58,11 @@ export const getHandleUpload = ({ prefix, storage, stream }: Args): HandleUpload
 
         data.filename = fileName
         data.bunnyVideoId = null
+
+        if (purge && purge.enabled) {
+          const url = await getGenerateURL({ storage, stream })({ collection, data, filename: fileName, prefix: prefix || '' })
+          await purgeBunnyCache(url, purge, req)
+        }
       }
 
       return data

src/types.ts

@@ -8,6 +8,11 @@ export type AdminThumbnailOptions = {
 
 export type BunnyAdapterOptions = {
   adminThumbnail?: AdminThumbnailOptions | boolean
+  purge?: {
+    apiKey: string
+    async?: boolean
+    enabled: boolean
+  }
   storage: {
     apiKey: string
     hostname: string

src/utils.ts

@@ -1,6 +1,8 @@
-import type { TypeWithID } from 'payload'
+import type { PayloadRequest, TypeWithID } from 'payload'
 
-import type { BunnyStorageOptions, BunnyVideoMeta } from './types.js'
+import ky, { HTTPError } from 'ky'
+
+import type { BunnyAdapterOptions, BunnyStorageOptions, BunnyVideoMeta } from './types.js'
 
 export const getStorageUrl = (region: string | undefined) => {
   if (!region) {
@@ -42,6 +44,14 @@ export const validateOptions = (
     errors.push('Hostname in storage settings cannot contain "storage.bunnycdn.com"')
   }
 
+  if (storageOptions.options.purge) {
+    const { purge } = storageOptions.options
+
+    if (purge.enabled && !purge.apiKey) {
+      errors.push('When purge is enabled, an API key must be provided')
+    }
+  }
+
   if (storageOptions.options.stream) {
     const collectionsWithAccessControl = Object.entries(storageOptions.collections).filter(([_, collection]) =>
       typeof collection === 'object' &&
@@ -64,4 +74,53 @@ export const validateOptions = (
       `Bunny Storage configuration error: ${errors.join('; ')}. Please refer to the documentation: https://github.com/maximseshuk/payload-storage-bunny`,
     )
   }
+}
+
+export const purgeBunnyCache = async (
+  url: string,
+  options: BunnyAdapterOptions['purge'],
+  req?: PayloadRequest,
+): Promise<boolean> => {
+  if (!options || !options.enabled) {
+    return false
+  }
+
+  try {
+    await ky.post('https://api.bunny.net/purge', {
+      headers: {
+        AccessKey: options.apiKey,
+      },
+      searchParams: {
+        async: options.async || false,
+        url,
+      },
+      timeout: 30000,
+    })
+
+    return true
+  } catch (err) {
+    if (req) {
+      if (err instanceof HTTPError) {
+        const errorResponse = await err.response.text()
+
+        req.payload.logger.error({
+          action: 'Cache purge',
+          error: {
+            response: errorResponse,
+            status: err.response.status,
+            statusText: err.response.statusText,
+          },
+          url,
+        })
+      } else {
+        req.payload.logger.error({
+          action: 'Cache purge',
+          error: err,
+          url,
+        })
+      }
+    }
+
+    return false
+  }
 }