RSSHub/lib/utils/cache/kv.ts

// Cloudflare Workers KV cache module

import type { KVNamespace } from '@cloudflare/workers-types';

import { config } from '@/config';

import type CacheModule from './base';
import { stringify } from './base';

let kvNamespace: KVNamespace | null = null;

const status = { available: false };

const getCacheTtlKey = (key: string) => {
    if (key.startsWith('rsshub:cacheTtl:')) {
        throw new Error('"rsshub:cacheTtl:" prefix is reserved for the internal usage, please change your cache key');
    }
    return `rsshub:cacheTtl:${key}`;
};

export const setKVNamespace = (kv: KVNamespace) => {
    kvNamespace = kv;
    status.available = true;
};

export const getKVNamespace = () => kvNamespace;

// Workers KV rejects expirationTtl values below 60 seconds
const KV_MIN_TTL = 60;
export const toKVTtl = (ttl: number) => Math.max(ttl, KV_MIN_TTL);

export default {
    init: () => {
        // KV namespace is set via setKVNamespace from Worker env binding
    },
    get: async (key: string, refresh = true) => {
        if (key && status.available && kvNamespace) {
            const cacheTtlKey = getCacheTtlKey(key);
            const [value, cacheTtl] = await Promise.all([kvNamespace.get(key), kvNamespace.get(cacheTtlKey)]);

            if (value && refresh) {
                const ttl = cacheTtl ? Number(cacheTtl) : config.cache.contentExpire;
                // Refresh TTL by re-setting the value
                // KV doesn't have a native expire refresh, so we need to re-put
                // Use waitUntil pattern in production for non-blocking refresh
                await Promise.all([kvNamespace.put(key, value, { expirationTtl: toKVTtl(ttl) }), cacheTtl ? kvNamespace.put(cacheTtlKey, cacheTtl, { expirationTtl: toKVTtl(ttl) }) : Promise.resolve()]);
            }
            return value || '';
        }
        return null;
    },
    has: async (key: string) => {
        if (key && status.available && kvNamespace) {
            const value = await kvNamespace.get(key);
            return value !== null;
        }
        return false;
    },
    set: async <T>(key: string, value?: string | T, maxAge = config.cache.contentExpire) => {
        if (!status.available || !kvNamespace) {
            return;
        }
        const stored = stringify(value);
        if (!key) {
            return;
        }

        const promises: Array<Promise<void>> = [kvNamespace.put(key, stored, { expirationTtl: toKVTtl(maxAge) })];

        if (maxAge !== config.cache.contentExpire) {
            // Store the cache ttl if it is not the default value
            promises.push(kvNamespace.put(getCacheTtlKey(key), String(maxAge), { expirationTtl: toKVTtl(maxAge) }));
        }

        await Promise.all(promises);
    },
    clients: {},
    status,
} satisfies CacheModule;