feat: support cache expiration & improve admin speed (#313)

Author: atinux

docs/content/1.docs/2.features/cache.md

@@ -79,14 +79,18 @@ It is important to note that the `event` argument should always be the first arg
 [Read more about this in the Nitro docs](https://nitro.unjs.io/guide/cache#edge-workers).
 ::
 
-## Cache Keys and Invalidation
+## Cache Invalidation
 
 When using the `defineCachedFunction` or `defineCachedEventHandler` functions, the cache key is generated using the following pattern:
 
 ```ts
 `${options.group}:${options.name}:${options.getKey(...args)}.json`
 ```
 
+The defaults are:
+- `group`: `'nitro'`
+- `name`: `'handlers'` for api routes and `'functions'` for server functions
+
 For example, the following function:
 
 ```ts
@@ -114,3 +118,11 @@ await useStorage('cache').removeItem('nitro:functions:getAccessToken:default.jso
 ::note{to="https://nitro.unjs.io/guide/cache"}
 Read more about Nitro Cache.
 ::
+
+## Cache Expiration
+
+As NuxtHub leverages Cloudflare Workers KV to store your cache entries, we leverage the [`expiration` property](https://developers.cloudflare.com/kv/api/write-key-value-pairs/#expiring-keys) of the KV binding to handle the cache expiration.
+
+::note
+If you set an expiration (`maxAge`) lower than `60` seconds, NuxtHub will set the KV entry expiration to `60` seconds in the future (Cloudflare KV limitation) so it can be removed automatically.
+::

playground/server/api/cached.ts

@@ -1,7 +1,15 @@
-export default cachedEventHandler(async () => {
+const test = defineCachedFunction((_event) => {
+  return 'test'
+}, {
+  getKey: () => 'test'
+})
+
+export default cachedEventHandler(async (event) => {
   return {
-    now: Date.now()
+    now: Date.now(),
+    test: test(event)
   }
 }, {
-  maxAge: 10
+  maxAge: 10,
+  swr: true
 })

playground/server/api/cf.ts

@@ -0,0 +1,18 @@
+export default eventHandler(async () => {
+  const event = useEvent()
+
+  const { isEUCountry, continent, city, timezone, country, region, latitude, longitude, botManagement } = event.context.cf
+  const ip = getHeader(event, 'cf-connecting-ip') || getRequestIP(event, { xForwardedFor: true })
+  return {
+    continent,
+    isEUCountry,
+    country,
+    region,
+    city,
+    timezone,
+    latitude,
+    longitude,
+    botManagement,
+    ip
+  }
+})

src/features.ts

@@ -2,13 +2,12 @@ import { execSync } from 'node:child_process'
 import type { Nuxt } from '@nuxt/schema'
 import { logger, addImportsDir, addServerImportsDir, addServerScanDir, createResolver } from '@nuxt/kit'
 import { joinURL } from 'ufo'
-import { join } from 'pathe'
 import { defu } from 'defu'
 import { $fetch } from 'ofetch'
 import { addDevToolsCustomTabs } from './utils/devtools'
 
 const log = logger.withTag('nuxt:hub')
-const { resolve } = createResolver(import.meta.url)
+const { resolve, resolvePath } = createResolver(import.meta.url)
 
 export interface HubConfig {
   remote: string | boolean
@@ -149,20 +148,20 @@ export async function setupBrowser(nuxt: Nuxt) {
   addServerImportsDir(resolve('./runtime/browser/server/utils'))
 }
 
-export function setupCache(nuxt: Nuxt) {
+export async function setupCache(nuxt: Nuxt) {
   // Add Server caching (Nitro)
+  const driver = await resolvePath('./runtime/cache/driver')
   nuxt.options.nitro = defu(nuxt.options.nitro, {
     storage: {
       cache: {
-        driver: 'cloudflare-kv-binding',
-        binding: 'CACHE',
-        base: 'cache'
+        driver,
+        binding: 'CACHE'
       }
     },
     devStorage: {
       cache: {
-        driver: 'fs',
-        base: join(nuxt.options.rootDir, '.data/cache')
+        driver,
+        binding: 'CACHE'
       }
     }
   })
@@ -343,7 +342,7 @@ export async function setupRemote(_nuxt: Nuxt, hub: HubConfig) {
   const availableStorages = Object.keys(remoteManifest?.storage || {}).filter(k => hub[k as keyof typeof hub] && remoteManifest?.storage[k])
   if (availableStorages.length > 0) {
     const storageDescriptions = availableStorages.map((storage) => {
-      if (storage === 'vectorize' && hub.vectorize) {
+      if (storage === 'vectorize' && Object.keys(hub.vectorize || {}).length) {
         const indexes = Object.keys(remoteManifest!.storage.vectorize!).join(', ')
         return `\`${storage} (${indexes})\``
       }

src/module.ts

@@ -107,7 +107,7 @@ export default defineNuxtModule<ModuleOptions>({
     hub.analytics && setupAnalytics(nuxt)
     hub.blob && setupBlob(nuxt)
     hub.browser && await setupBrowser(nuxt)
-    hub.cache && setupCache(nuxt)
+    hub.cache && await setupCache(nuxt)
     hub.database && setupDatabase(nuxt)
     hub.kv && setupKV(nuxt)
     Object.keys(hub.vectorize!).length && setupVectorize(nuxt, hub)
@@ -143,18 +143,10 @@ export default defineNuxtModule<ModuleOptions>({
     if (hub.remote) {
       await setupRemote(nuxt, hub)
       vectorizeRemoteCheck(hub)
-      return
-    }
-
-    // Add node:stream to unenv external (only for Cloudflare Pages/Workers)
-    if (!nuxt.options.nitro.unenv.external.includes('node:stream')) {
-      nuxt.options.nitro.unenv.external.push('node:stream')
     }
 
-    // Folowing lines are only executed when remote storage is disabled
-
     // Production mode without remote storage
-    if (!nuxt.options.dev) {
+    if (!hub.remote && !nuxt.options.dev) {
       // Make sure to fallback to cloudflare-pages preset
       let preset = nuxt.options.nitro.preset = nuxt.options.nitro.preset || 'cloudflare-pages'
       // Support also cloudflare_module
@@ -170,6 +162,11 @@ export default defineNuxtModule<ModuleOptions>({
       nuxt.options.nitro.commands.preview = 'npx nuxthub preview'
       nuxt.options.nitro.commands.deploy = 'npx nuxthub deploy'
 
+      // Add node:stream to unenv external (only for Cloudflare Pages/Workers)
+      if (!nuxt.options.nitro.unenv.external.includes('node:stream')) {
+        nuxt.options.nitro.unenv.external.push('node:stream')
+      }
+
       // Add the env middleware
       nuxt.options.nitro.handlers ||= []
       nuxt.options.nitro.handlers.unshift({
@@ -178,9 +175,11 @@ export default defineNuxtModule<ModuleOptions>({
       })
     }
 
-    // Local development without remote connection
+    // Local development
     if (nuxt.options.dev) {
-      log.info(`Using local storage from \`${hub.dir}\``)
+      if (!hub.remote) {
+        log.info(`Using local storage from \`${hub.dir}\``)
+      }
 
       // Create the hub.dir directory
       const hubDir = join(rootDir, hub.dir)
@@ -201,7 +200,7 @@ export default defineNuxtModule<ModuleOptions>({
         await writeFile(gitignorePath, `${gitignore ? gitignore + '\n' : gitignore}.data`, 'utf-8')
       }
 
-      const needWrangler = Boolean(hub.analytics || hub.blob || hub.database || hub.kv)
+      const needWrangler = Boolean(hub.analytics || hub.blob || hub.database || hub.kv || hub.cache)
       // const needWrangler = Boolean(hub.analytics || hub.blob || hub.database || hub.kv || Object.keys(hub.bindings.hyperdrive).length > 0)
       if (needWrangler) {
         // Generate the wrangler.toml file

src/runtime/base/server/utils/hooks.ts

@@ -1,5 +1,4 @@
 import { createHooks } from 'hookable'
-import { useRuntimeConfig } from '#imports'
 
 export interface HubHooks {
   'bindings:ready': () => void
@@ -28,8 +27,7 @@ export const hubHooks = createHooks<HubHooks>()
  * @see https://hub.nuxt.com/docs/recipes/hooks#onhubready
  */
 export function onHubReady(cb: HubHooks['bindings:ready']) {
-  const hub = useRuntimeConfig().hub
-  if (import.meta.dev && !hub.remote) {
+  if (import.meta.dev) {
     return hubHooks.hookOnce('bindings:ready', cb)
   }
   cb()

src/runtime/cache/driver.mjs

@@ -0,0 +1,43 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { defineDriver } from 'unstorage'
+import cloudflareKVBindingDriver from 'unstorage/drivers/cloudflare-kv-binding'
+import { getContext } from 'unctx'
+
+export const nitroAsyncContext = getContext('nitro-app', {
+  asyncContext: true,
+  AsyncLocalStorage
+})
+
+export default defineDriver((driverOpts) => {
+  const driver = cloudflareKVBindingDriver(driverOpts)
+
+  return {
+    name: 'nuxthub-cache',
+    ...driver,
+    setItem(key, value, options) {
+      const event = nitroAsyncContext.tryUse()?.event
+      // TODO: remove this if once Nitro 2.10 is out with Nuxt version
+      // As this does not support properly swr (as expiration should not be used)
+      // Fallback to expires value ({"expires":1729118447040,...})
+      if (!options.ttl && typeof value === 'string') {
+        const expires = value.match(/^\{"expires":(\d+),/)?.[1]
+        if (expires) {
+          options.ttl = Math.round((Number(expires) - Date.now()) / 1000)
+        }
+      }
+      if (options.ttl) {
+        // Make sure to have a ttl of at least 60 seconds (Cloudflare KV limitation)
+        options.ttl = Math.max(options.ttl, 60)
+      }
+
+      options.metadata = {
+        ttl: options.ttl,
+        mtime: Date.now(),
+        size: value.length,
+        path: event?.path,
+        ...options.metadata
+      }
+      return driver.setItem(key, value, options)
+    }
+  }
+})

src/runtime/cache/plugins/cache.ts

@@ -1,7 +1,6 @@
 import { eventHandler, getRouterParam, createError, sendNoContent } from 'h3'
 import { requireNuxtHubAuthorization } from '../../../../../utils/auth'
 import { requireNuxtHubFeature } from '../../../../../utils/features'
-// @ts-expect-error useStorage not yet typed
 import { useStorage } from '#imports'
 
 export default eventHandler(async (event) => {

src/runtime/cache/server/api/_hub/cache/[...key].delete.ts

@@ -2,50 +2,69 @@ import ms from 'ms'
 import { eventHandler, getRouterParam } from 'h3'
 import { requireNuxtHubAuthorization } from '../../../../../utils/auth'
 import { requireNuxtHubFeature } from '../../../../../utils/features'
-// @ts-expect-error useStorage not yet typed
+import { hubCacheBinding } from '../../../utils/cache'
 import { useStorage } from '#imports'
 
 export default eventHandler(async (event) => {
   await requireNuxtHubAuthorization(event)
   requireNuxtHubFeature('cache')
 
-  const key = getRouterParam(event, 'key') || ''
+  const keyOrPrefix = (getRouterParam(event, 'key') || '').replace(/\//g, ':')
   // If ends with an extension
-  if (/\.[a-z0-9]{2,5}$/i.test(key)) {
-    const item = await useStorage('cache').getItem(key)
+  if (/\.[a-z0-9]{2,5}$/i.test(keyOrPrefix)) {
+    const item = await useStorage('cache').getItem(keyOrPrefix)
     if (item) {
       return item
     }
     // Ignore if item is not found, treat the key as a prefix and look for children
   }
-  const storage = useStorage(`cache:${key}`)
-  const keys = await storage.getKeys()
+  const prefix = `${keyOrPrefix}:`
+  const binding = hubCacheBinding()
+  const keys = []
+  let cursor = undefined
+  do {
+    const res = await binding.list({ prefix, cursor })
+
+    keys.push(...res.keys)
+    cursor = (res.list_complete ? undefined : res.cursor)
+  } while (cursor)
 
   const stats = {
     groups: {} as Record<string, number>,
     cache: [] as any[]
   }
 
-  await Promise.all(keys.map(async (key: string) => {
+  await Promise.all(keys.map(async ({ name, metadata }) => {
+    const key = name.slice(prefix.length)
     if (key.includes(':')) {
       const k = key.split(':')[0]
       stats.groups[k] = (stats.groups[k] || 0) + 1
       return
     }
-    const item = await storage.getItem(key)
-    if (!item) return
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const { value, ...meta } = item
 
+    // Fallback to read from storage if metadata is not available
+    if (!metadata) {
+      const item = await useStorage('cache').getItem(name)
+      if (!item) return
+
+      metadata = {
+        size: JSON.stringify(item).length,
+        mtime: item.mtime,
+        expires: item.expires
+      }
+    }
+
+    if (!metadata.expires && metadata.ttl) {
+      metadata.expires = metadata.mtime + (metadata.ttl * 1000)
+    }
     const entry = {
       key,
-      ...meta,
-      size: JSON.stringify(item).length
+      ...metadata
     }
     try {
-      entry.duration = ms(meta.expires - meta.mtime, { long: true })
+      entry.duration = ms(metadata.expires - metadata.mtime, { long: true })
     } catch (err) {
-      entry.duration = 'unknown'
+      entry.duration = 'never'
     }
     stats.cache.push(entry)
   }))