please support ioredis

[epubreader]

please support ioredis, ioredis is very popular

[gergokee]

node-redis is already supporting sentinel (so you don't need ioredis), i posted a solution here:
#51

But in case you'd like to use ioredis something like this will work (i used to use it with @neshca/cache-handler which fortedigital took over, but since node-redis DOES support sentinel, i don't need it anymore).

You need probably only small changes to this solution below, one thing which is missing i think from fortedigital/nextjs-cache-handler is the isImplicitTag , but other than that you can probably transform it to be compatible.

redis.mjs:

import Redis from 'ioredis';
import { getBuildId } from './index.mjs';

export const keyPrefix = process.env.APP_NAME + ':' + getBuildId() + ':';

const sharedTagsKey = '__custom_sharedTags__';

let client;

export const createClient = async () => {
	if (!client) {
		const connection = {
			host: process.env.REDIS_HOST,
			port: Number(process.env.REDIS_PORT),
		};

		client = process.env.CACHE_DRIVER === 'redis-sentinel-cache' ? new Redis({
			sentinels: [connection],
			name: 'mymaster',
			db: process.env.REDIS_CACHE_DATABASE,
		}) : new Redis(connection);

		client.on('error', (error) => {
			if (typeof process.env.NEXT_PRIVATE_DEBUG_CACHE !== 'undefined' && process.env.NEXT_PRIVATE_DEBUG_CACHE !== 'false') {
				console.error('Redis client error:', error);
			}
		});

		console.info('Connecting Redis client...');
		await waitForClientReady(client);
		console.info('Redis client connected.');
	} else {
		if (client.status !== 'ready') {
			console.info('Connecting Redis client...');
			await waitForClientReady(client);
			console.info('Redis client connected.');
		}
	}
	return client;
};

// Wait for the client to be ready, robust retry mechanism
const waitForClientReady = async (client, retries = 5, delay = 1000) => {
	await client.ping();
	for (let attempt = 0; attempt < retries; attempt++) {
		if (client.status === 'ready') {
			return;
		}
		if (attempt >= retries - 1) {
			throw new Error('Redis client is not ready after multiple attempts.');
		}
		console.warn(`Redis client not ready, retrying in ${delay}ms... (Attempt ${attempt + 1}/${retries})`);
		await new Promise(resolve => setTimeout(resolve, delay));
	}
};

function assertClientIsReady(client) {
	if (!client || client.status !== 'ready') {
		throw new Error('Redis client is not ready yet or connection is lost. Keep trying...');
	}
}

// expireAt is in seconds
export const setData = async (key, value, expireAt, tags = []) => {
	try {
		const client = await createClient();
		assertClientIsReady(client);
		const setOperation = client.set(keyPrefix + key, JSON.stringify(value));
		const expireOperation = expireAt
			? client.expireat(keyPrefix + key, Math.floor((Date.now() + (expireAt * 1000)) / 1000))
			: undefined;
		const setTagsOperation = tags.length > 0 ? client.hset(keyPrefix + sharedTagsKey, key, JSON.stringify(tags)) : undefined;
		await Promise.all([setOperation, expireOperation, setTagsOperation]);
		return { message: 'Data saved successfully: key: ' + key + ' value: ' + value };
	} catch (error) {
		return { error: 'Error saving data' };
	}
};

export const getData = async (key) => {
	try {
		const client = await createClient();
		assertClientIsReady(client);
		const result = await client.get(keyPrefix + key);
		if (!result) {
			return null;
		}
		return JSON.parse(result);
	} catch (error) {
		console.error('Error retrieving data:', error);
		return null;
	}
};

export const dataExists = async (key) => {
	try {
		const client = await createClient();
		assertClientIsReady(client);
		const exists = await client.exists(keyPrefix + key);
		return exists === 1;
	} catch (error) {
		console.error('Error checking key existence:', error);
		return false;
	}
};

export const deleteData = async (key) => {
	try {
		const client = await createClient();
		assertClientIsReady(client);
		const result = await client.unlink(keyPrefix + key);
		if (result === 0) {
			console.log('Key not found');
			return false;
		}
		console.log('Data deleted successfully');
		return true;
	} catch (error) {
		console.error('Error deleting datae:', error);
		return false;
	}
};

index.mjs:

import { isImplicitTag } from '@neshca/cache-handler/helpers';
import fs from 'fs';
import path from 'path';

const isProduction = process.env.NODE_ENV === 'production';

export default function createHandler({
	client,
	keyPrefix = '',
	sharedTagsKey = '__nextjs_sharedTags__',
	keyExpirationStrategy = 'EXPIREAT',
	revalidateTagQuerySize = 100,
}) {

	const MAX_INT32 = 2 ** 31 - 1;
	const TIME_ONE_YEAR = 31536000;
	const REVALIDATED_TAGS_KEY = '__revalidated_tags__';

	function assertClientIsReady() {
		if (client.status !== 'ready') {
			throw new Error('Redis client is not ready yet or connection is lost. Keep trying...');
		}
	}

	const revalidatedTagsKey = keyPrefix + REVALIDATED_TAGS_KEY;

	return {
		name: 'ioredis',
		async get(key, { implicitTags }) {
			assertClientIsReady();

			const result = await client.get(keyPrefix + key);

			if (!result) {
				return null;
			}

			const cacheValue = JSON.parse(result);

			if (!cacheValue) {
				return null;
			}

			const combinedTags = new Set([...cacheValue.tags, ...implicitTags]);

			if (combinedTags.size === 0) {
				return cacheValue;
			}

			const revalidationTimes = await client.hmget(
				revalidatedTagsKey,
				...Array.from(combinedTags),
			);

			for (const timeString of revalidationTimes) {
				if (timeString && Number.parseInt(timeString, 10) > cacheValue.lastModified) {
					await client.unlink(keyPrefix + key);

					return null;
				}
			}

			return cacheValue;
		},
		async set(key, cacheHandlerValue) {
			assertClientIsReady();

			let setOperation = null;

			let expireOperation = undefined;

			switch (keyExpirationStrategy) {
				case 'EXAT': {
				  setOperation = typeof cacheHandlerValue.lifespan?.expireAt === 'number'
						? client.set(
							keyPrefix + key,
							JSON.stringify(cacheHandlerValue),
							'EXAT',
							cacheHandlerValue.lifespan.expireAt,
						)
						: client.set(
							keyPrefix + key,
							JSON.stringify(cacheHandlerValue),
					  );
					break;
				}
				case 'EXPIREAT': {
					setOperation = client.set(keyPrefix + key, JSON.stringify(cacheHandlerValue));

					expireOperation = cacheHandlerValue.lifespan
						? client.expireat(keyPrefix + key, cacheHandlerValue.lifespan.expireAt)
						: undefined;
					break;
				}
				default: {
					throw new Error(`Invalid keyExpirationStrategy: ${keyExpirationStrategy}`);
				}
			}

			const setTagsOperation =
				cacheHandlerValue.tags.length > 0
					? client.hset(keyPrefix + sharedTagsKey, key, JSON.stringify(cacheHandlerValue.tags))
					: undefined;

			await Promise.all([setOperation, expireOperation, setTagsOperation]);
		},
		async revalidateTag(tag) {
			assertClientIsReady();

			// If the tag is an implicit tag, we need to mark it as revalidated.
			// The revalidation process is done by the CacheHandler class on the next get operation.
			if (isImplicitTag(tag)) {
				await client.hset(revalidatedTagsKey, tag, Date.now());
			}

			const tagsMap = new Map();

			let cursor = '0';

			do {
				const [newCursor, fieldsAndValues] = await client.hscan(
					keyPrefix + sharedTagsKey,
					cursor,
					'COUNT',
					revalidateTagQuerySize,
				);

				for (let i = 0; i < fieldsAndValues.length; i += 2) {
					if (fieldsAndValues[i] && fieldsAndValues[i + 1]) {
						tagsMap.set(fieldsAndValues[i], JSON.parse(fieldsAndValues[i + 1]));
					}
				}

				cursor = newCursor;
			} while (cursor !== '0');

			const keysToDelete = [];

			const tagsToDelete = [];

			for (const [key, tags] of tagsMap) {
				if (tags.includes(tag)) {
					keysToDelete.push(keyPrefix + key);
					tagsToDelete.push(key);
				}
			}

			if (keysToDelete.length === 0) {
				return;
			}

			const deleteKeysOperation = client.unlink(keysToDelete);

			const updateTagsOperation = client.hdel(
				keyPrefix + sharedTagsKey,
				...tagsToDelete,
			);

			await Promise.all([deleteKeysOperation, updateTagsOperation]);
		},
		async delete(key) {
			await client.unlink(key);
		},
	};
}


export const getBuildId = () => {
	if (!isProduction) {
		return '';
	}
	const buildIdPath = path.join(process.cwd(), '.next', 'BUILD_ID');
	return fs.readFileSync(buildIdPath, 'utf8').trim();
};

cache-handler.mjs:

import { CacheHandler } from '@neshca/cache-handler';
import createLruHandler from '@neshca/cache-handler/local-lru';

import createIORedisHandler from './index.mjs';

CacheHandler.onCreation(async () => {
	const { createClient, keyPrefix } = await import('./redis.mjs');
	const client = await createClient();

	let handler;

	if (client.status === 'ready') {
		// Create the `redis-stack` Handler if the client is available and connected.
		handler = createIORedisHandler({
			client,
			keyPrefix: keyPrefix,
		});
	} else {
		// Fallback to LRU handler if Redis client is not available.
		// The application will still work, but the cache will be in memory only and not shared.
		handler = createLruHandler();
		console.warn('Falling back to LRU handler because Redis client is not available.');
	}

	return {
		handlers: [handler],
		ttl: { defaultStaleAge: 86400, estimateExpireAge: (staleAge) => staleAge * 2 },
	};
});

export default CacheHandler;

[AyronK]

(i used to use it with @neshca/cache-handler which fortedigital took over, but since node-redis DOES support sentinel, i don't need it anymore).

@gergokee there's an old draft that I started, but I didn't have time to setup a testing environment with redis sentinel. Are you able to share your setup for using sentinel with node-redis and this package?

Draft PR: #66
Issue: #51

EDIT: I see you already responded there! Thanks.

[gergokee]

Yes @AyronK i shared it in #51 , we are already using in production (only since last week though), i'll update it if there are any issues but it seems like it is working perfectly :)

ps.: there might be a little too much unnecessary code there (if-s else-s etc, but i added them to make it 100% stable, maybe you or somebody can review and filter out what's not needed: client.isReady and client.isOpen logic)

[themitvp]

I adjusted my cache-handler.mjs to support ioredis, but I had to do a dirty hack to overwrite the isReady because you are using that internally and if we don't do that then the instrumented handler will basically not work as it will think that the connection is not working because isReady will be undefined. You can see my code below.

So @AyronK maybe we can simply make some adjustments so we can use ioredis, I am happy to do a PR, but wanted to ask if you see any issues before proceeding?

import Redis from 'ioredis'
import { PHASE_PRODUCTION_BUILD } from 'next/constants.js'
import { CacheHandler } from '@fortedigital/nextjs-cache-handler'
import createLruHandler from '@fortedigital/nextjs-cache-handler/local-lru'
import createRedisHandler from '@fortedigital/nextjs-cache-handler/redis-strings'

function createInstrumentedHandler(handler) {
  return {
    name: (handler.name || 'redis-strings') + '-instrumented',

    async get(key, ctx) {
      const start = performance.now()
      const data = await handler.get(key, ctx)
      const durationMs = performance.now() - start
      const kind = data?.value?.kind || 'UNKNOWN'

      console.log(`[cache] Redis GET for key: ${key} took ${durationMs.toFixed(2)}ms kind ${kind}`)

      return data
    },

    async set(key, data) {
      const start = performance.now()
      await handler.set(key, data)
      const durationMs = performance.now() - start
      const kind = data?.value?.kind || 'UNKNOWN'

      console.log(`[cache] Redis SET for key: ${key} took ${durationMs.toFixed(2)}ms kind ${kind}`)
    },
    async revalidateTag(tag) {
      return handler.revalidateTag(tag)
    },

    resetRequestCache: handler.resetRequestCache?.bind(handler),
  }
}

CacheHandler.onCreation(async () => {
  // Return singleton if already created
  if (global.cacheHandlerConfig) {
    return global.cacheHandlerConfig
  }

  // Dev: use in-memory Least Recently Used (LRU) only (no Redis needed locally)
  if (process.env.NODE_ENV === 'development') {
    const lruCache = createLruHandler()
    global.cacheHandlerConfig = { handlers: [lruCache] }
    return global.cacheHandlerConfig
  }

  // Build Phase: Don't connect
  if (PHASE_PRODUCTION_BUILD === process.env.NEXT_PHASE) {
    return { handlers: [createLruHandler()] }
  }

  // Prod: Singleton Redis
  if (!global.redisClientInstance) {
    try {
      redisClient = new Redis({
        host: process.env.REDIS_HOST,
        port: 6379,
        password: process.env.REDIS_SECRET,
        db: 0,
        // K8s Optimizations
        connectTimeout: 10000,
        maxRetriesPerRequest: 2, // Fail fast if Redis is truly down
        enableOfflineQueue: true, // Queue requests while reconnecting
        retryStrategy(times) {
          const delay = Math.min(times * 50, 2000)
          return delay // Reconnect with backoff
        },
      })

      // Polyfill 'isReady' and 'isOpen' for compatibility as they are not in ioredis
      Object.defineProperties(redisClient, {
        isReady: {
          get() {
            return this.status === 'ready'
          },
        },
        isOpen: {
          get() {
            return this.status === 'ready'
          },
        },
      })

      redisClient.on('error', (err) => {
        if (typeof process.env.NEXT_PRIVATE_DEBUG_CACHE !== 'undefined') {
          console.warn('[cache] Redis error', err.message)
        }
      })
      global.redisClientInstance = redisClient
      console.info('[cache] Redis client initialized')
    } catch (error) {
      console.warn('[cache] Failed to initialize Redis:', error)
    }
  }

  const redisClient = global.redisClientInstance

  // 3. Fallback if client failed to initialize completely
  if (!redisClient) {
    return { handlers: [createLruHandler()] }
  }

  redisClient.on('connect', () => console.log('[cache] ioredis: Connection established'))
  redisClient.on('reconnecting', () => console.log('[cache] ioredis: Reconnecting...'))

  const redisCacheHandler = createRedisHandler({
    client: redisClient,
    keyPrefix: 'web:',
  })

  global.cacheHandlerConfig = {
    handlers: [createInstrumentedHandler(redisCacheHandler)],
  }

  return global.cacheHandlerConfig
})

export default CacheHandler

[AyronK]

@themitvp nice! I wouldn't go with a polyfill as the client interfaces are from two different packages, but rather make a proxy/adapter for the ioredis to match the interface we require in createRedisHandler. Just to make it type safe, especially when upgrading package versions.

I am suprised it works with so few changes, how is it possible, is Redis from ioredis type aligned with the RedisClient interface from node-redis? Or am I missing something?

I you want you can publish a draft PR using our internal functions etc. I currently don't have time to implement it myself, but I would be happy to oversee and support you if you're willing to help.

[themitvp]

@AyronK agree, I also only did the polyfill to test if it would work at all. I just opened a draft PR #179, where I implemented it as a proxy as you suggested.
And yes, many of the types are not aligned out of the box, but previously I only checked if the set and get worked, didn't try with the other ones, where it would probably not work 😅

Please review when you have time, then we can discuss next steps 🙌

[AyronK]

Done in 2.5.0 thanks to @themitvp. I will publish in Next16 alpha shortly after.