lush-cachify

A plug-and-play Express middleware to manage your Redis cache via HTTP endpoints and a modern UI.

Installation

npm install @lushdigital/lush-cachify

Usage

const express = require('express');
const { lushCachifyUI, lushCachifyWebhook } = require('@lushdigital/lush-cachify');

const app = express();
const redisUrl = 'redis://localhost:6379'; // Your Redis connection string

// Mount the UI middleware at your desired path
app.use('/cachify', lushCachifyUI({
  redisUrl,
  // Logging is off by default; enable and pass custom sinks if needed
  useLogger: true,
  logger: {
    info: console.log,
    error: console.error,
    success: console.log
  },
  // UI rate limiting is opt-in
  rateLimitWindowMs: 60,  // Window in seconds (default: 60)
  rateLimitMax: 100       // Requests per window per IP (default: 100)
}));

// Mount the webhook for tag-based cache invalidation
app.use('/webhook/cache', lushCachifyWebhook({
  removeTag: async (tag) => {
    // Your custom logic to remove cache entries by tag
    // This could involve Redis pattern matching, database queries, etc.
    console.log('Invalidating cache for tag:', tag);

    // Example: Remove Redis keys that match a tag pattern
    // const keys = await redis.keys(`*:${tag}:*`);
    // await redis.del(...keys);
  },
  // Logging off by default; enable if you want webhook logs
  useLogger: true,
  logger: {
    info: console.log,
    error: console.error,
    success: console.log
  },
  // Webhook rate limiting is ON by default; set rateLimit: true to disable
  rateLimitWindowMs: 120,  // Optional: window in seconds (default: 60)
  rateLimitMax: 200        // Optional: requests per window per IP (default: 100)
}));

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Endpoints

UI Middleware (lushCachifyUI)

• GET /search?key=pattern* — Search for keys (wildcards supported)
• GET /view/:key — View a record by key (supports JSON, RedisJSON, and all Redis types)
• DELETE /clear/:key — Delete a single record
• DELETE /clear-all — Delete all records in Redis (batched, with confirmation)
• DELETE /clear-pattern?key=pattern — Delete all records matching a pattern (batched)
• GET /healthz — Check Redis connection health

Webhook Middleware (lushCachifyWebhook)

• GET /?tags=tag1,tag2,tag3 — Invalidate cache by tags (comma-separated)
• GET /healthz — Webhook health check

Options

lushCachifyUI Options

• redisUrl (required): Your Redis connection string
• useLogger: Enable built-in logging (default: false)
• logger: Pass custom logger functions for error/info/success (used when useLogger is true)
• rateLimit: Enable built-in rate limiter (default: true).
• rateLimitWindowMs: Rate limit window in ms (default: 60)
• rateLimitMax: Requests allowed per window per IP (default: 30)

lushCachifyWebhook Options

• removeTag (required): Function that handles cache invalidation for a given tag
  • Type: (tag: string) => Promise<void> | void
  • Called for each tag when webhook is triggered
• useLogger: Enable built-in logging (default: false)
• logger: Pass custom logger functions for error/info/success (used when useLogger is true)
• rateLimit: Enable built-in rate limiter (default: true).
• rateLimitWindowMs: Rate limit window in ms (default: 60)
• rateLimitMax: Requests allowed per window per IP (default: 100)

Features

UI Features

• Modern, responsive UI (visit /cachify in your browser)
• Safe, batched deletes for large datasets
• Configurable rate limiting (30 requests/minute by default; can disable or adjust)
• Custom logger support

Webhook Features

• Tag-based cache invalidation for CMS integrations
• Batch processing of multiple tags in a single request
• Configurable rate limiting (250 requests/minute by default; can disable or adjust)
• Detailed response with success/failure status for each tag
• Health check endpoint for monitoring

Tag-Based Cache Invalidation

The webhook middleware is designed to work with content management systems that can trigger cache invalidation when content is updated. Here's how it works:

1. Setup: Implement the removeTag function to define how your application should handle cache invalidation for a specific tag
2. Integration: Configure your CMS or external system to send GET requests to your webhook endpoint when content changes
3. Invalidation: The webhook processes each tag and calls your removeTag function

Example Integration with Contentful

app.use('/webhook/contentful', lushCachifyWebhook({
  removeTag: async (tag) => {
    // Remove Redis keys that contain this content type or entry ID
    const pattern = `*:${tag}:*`;
    const keys = await redis.keys(pattern);

    if (keys.length > 0) {
      await redis.del(...keys);
      console.log(`Invalidated ${keys.length} cache entries for tag: ${tag}`);
    }
  }
}));

Then configure Contentful to send webhooks to:

https://yourapp.com/webhook/contentful?tags=blog-post,author:123,category:tech