Azure compatibility, resilience and error handling questions

[fturmel]

Looking forward to v2 being released! I'm planing on testing canary next week and had a few questions.

• Is there any compatibility information related to integrating with Azure Cache for Redis and @redis/entraid yet? It looks like everything should work since the v2 handler will be using the Redis 5.x node client 🤞

• Do you have any recommendations for a readiness healthcheck implementation on k8s (AKS)? I'm specifically wondering about sharing the same Redis client between the cache handler and the healthcheck route (a simple Next.js 15 App Router GET route) vs managing two distinct Redis clients.

Thank you for your work!

[AyronK]

Hey @fturmel!

We don't use Entra ID at the moment of writing this answer so it's difficult for me to say. Although @redis/client works perfectly fine with Azure Cache for Redis. If you have questions on integration between Azure Cache for Redis and @redis/entraid I would rather go to their repositories as this package is only a Next.js proxy.

As far as I know there is no built-in way to share the same client on health-checks and cache handler. You could experiment with global scope variables, although I am not completely sure it would work. We're following a pattern of disconnect and reconnect on failure and there should not be an option to have one connection broken and the other not, if something is wrong with the server both connections would fails which is enough protection for us.

[fturmel]

Just wanted to check back in and share my experiences in a mini post-mortem.

There were no compatibility issues with Azure Cache for Redis and node-redis v5 / @redis/entraid, which is great. I also did manage to implement a shared connection with both our health check and the cache handler (see below). However, the cache handler seems to suppress errors (I think it's the abort signals?) in a way that made it very hard to deal with a few things.

Identify ACL issues

Our team put ACLs on Azure Cache, only allowing the get/set operations on a specific namespace. All cache handler operations were silently failing and we only noticed later we were consistently getting cache misses. Takeaway: the actual Redis operations required should be documented somewhere, and there should be logs when operations fail.

Resilient Redis client

The error suppression made it close to impossible to keep the Redis client working after a disconnect. It just wouldn't recover properly - it looked like it was online but all cache operations were misses. I think there are known problems around this with node-redis in general, but also the error suppression made it worst.

After lots of testing, the only approach that reliably worked was using a combination of a proxy that could self-heal properly by pinging the server before any operation. Again, I believe error suppression in the cache handler made it so that failing operations would not trigger a reconnection in the client. Our proxy code needed to actually call a failing operation (ping) on the Redis client and catch the error to actually know that it was not connected anymore and needed to manually reconnect.

This is the code to create the self-healing global instance Redis client, in case it's useful to anyone else. Hope that all these workarounds won't be needed in future releases of the cache handler!

getRedisClient.mjs

import { DefaultAzureCredential } from '@azure/identity';
import { createClient } from '@redis/client';
import { EntraIdCredentialsProviderFactory, REDIS_SCOPE_DEFAULT } from '@redis/entraid';

let manualReconnecting = false;

function createHealingProxy(client) {
  let proxy;

  const handler = {
    get(target, prop) {
      // 0) Override isReady so assertClientIsReady() in the cache handler always passes
      if (prop === 'isReady') {
        return true;
      }

      // 1) Strip out any abortSignal wrapper so we see real socket errors
      if (prop === 'withAbortSignal') {
        return () => proxy;
      }

      const orig = target[prop];
      if (typeof orig !== 'function') {
        return orig;
      }

      return async (...args) => {
        // 2) PRE‑CALL PING to catch a dead socket
        if (prop !== 'ping') {
          try {
            await target.ping();
          } catch (pingErr) {
            console.warn('🔄 Redis proxy: pre‑call ping failed, healing…', pingErr.message || pingErr);
            if (!manualReconnecting) {
              manualReconnecting = true;
              if (target.isOpen) {
                await target.disconnect().catch(() => {});
              }
              await target.connect().catch(e => console.error('❌ Redis proxy: reconnect (ping) failed', e));
              console.info('✅ Redis proxy: reconnect (ping) OK');
              manualReconnecting = false;
            }
          }
        }

        // 3) ACTUAL CALL + POST‑ERROR RETRY
        try {
          return await orig.apply(target, args);
        } catch (err) {
          const recoverable =
            err.code === 'ECONNRESET' ||
            err.message.includes('Socket closed unexpectedly') ||
            err.message.includes('The client is closed');
          if (!recoverable) throw err;

          console.warn(`🔄 Redis proxy: \`${prop}\` failed (${err.code || err.message}), healing…`);
          if (!manualReconnecting) {
            manualReconnecting = true;
            if (target.isOpen) {
              await target.disconnect().catch(() => {});
            }
            await target.connect().catch(() => {});
            console.info('✅ Redis proxy: reconnect (on‑error) OK');
            manualReconnecting = false;
          }
          return orig.apply(target, args);
        }
      };
    },
  };

  return new Proxy(client, handler);
}

export async function getRedisClient() {
  if (globalThis.__REDIS_PROXY__) {
    return globalThis.__REDIS_PROXY__;
  }

  console.warn('🛠 Creating new Redis client (singleton)…');

  const raw =
    globalThis.__REDIS_RAW__ ||
    createClient({
      url: process.env.REDIS_URI,

      credentialsProvider: EntraIdCredentialsProviderFactory.createForDefaultAzureCredential({
        credential: new DefaultAzureCredential(),
        scopes: REDIS_SCOPE_DEFAULT,
        tokenManagerConfig: { expirationRefreshRatio: 0.8 },
      }),

      pingInterval: 10_000,
      disableOfflineQueue: true,
      socket: {
        connectTimeout: 5_000,
        reconnectStrategy: () => new Error('manual only'),
        reconnectOnError: () => false,
      },
    });

  globalThis.__REDIS_RAW__ = raw;

  // lifecycle logs
  ['connect', 'ready', 'reconnecting', 'end', 'error'].forEach(evt =>
    raw.on(evt, (...args) =>
      console[evt === 'error' ? 'error' : evt === 'end' ? 'warn' : 'info'](`Redis event: ${evt}`, ...args),
    ),
  );

  // initial connect
  if (!raw.isOpen && !raw.isReady) {
    console.info('▶ raw.connect()…');
    await raw.connect().catch(e => console.error('❌ Initial connect failed', e));
    if (raw.isReady) console.info('✅ Redis is ready');
  }

  // wrap & cache the proxy
  const proxy = createHealingProxy(raw);
  globalThis.__REDIS_PROXY__ = proxy;
  return proxy;
}

unstable_cache and buffers

This might be in spec/expected, but it did take me a minute to realize what was going on. Storing a Buffer with unstable_cache requires a bit of manual work when reading it back. The cache handler returns a JSON encoded version of the buffer on cache hit, but unstable_cache is pass-thru on cache misses and will then return a Buffer. I have not had the chance to verify that this behavior is the same on Vercel's cache or with the default disk cache handler.

Simplified example to illustrate:

// getBuffer() returns a Promise<Buffer>, we wrap it with unstable_cache.
// The inferred cachedGetBuffer() return type is `Promise<Buffer<ArrayBufferLike>>`, which is incorrect.
const cachedGetBuffer = unstable_cache(async () => await getBuffer());

// cache MISS returns a Buffer
// cache HIT returns a JSON encoded buffer, which we need to manually convert
const res = (await cachedGetBuffer()) as Buffer | { type: 'Buffer'; data: number[] };
const buffer = Buffer.isBuffer(res) ? res : Buffer.from(res.data);

[AyronK]

@fturmel thanks for your feedback, we have redis resilience in our internal backlog as well and we'll be looking into this very soon, so your insights are very helpful. If we manage to make something that could fit into this package we'll be happy to share. I'll put this issue on hold, but I expect to come back with something by the end of August.