Build a URL Shortener: Caching với Redis

# docker-compose.yml
version: '3.8'
 
services:
  postgres:
    image: postgres:16-alpine
    container_name: url-shortener-db
    environment:
      POSTGRES_USER: urlshortener
      POSTGRES_PASSWORD: urlshortener
      POSTGRES_DB: urlshortener
    ports:
      - '5432:5432'
    volumes:
      - postgres_data:/var/lib/postgresql/data
 
  redis:
    image: redis:7-alpine
    container_name: url-shortener-redis
    ports:
      - '6379:6379'
    command: redis-server --maxmemory 128mb --maxmemory-policy allkeys-lru
    volumes:
      - redis_data:/data
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 5s
      retries: 3
 
volumes:
  postgres_data:
  redis_data:

docker compose up -d
docker compose ps  # Kiểm tra cả hai services đang chạy

docker exec -it url-shortener-redis redis-cli ping
# PONG

# .env
PORT=3000
BASE_URL=http://localhost:3000
NODE_ENV=development
 
# Database
DATABASE_URL=postgresql://urlshortener:urlshortener@localhost:5432/urlshortener
 
# Redis
REDIS_URL=redis://localhost:6379
REDIS_KEY_PREFIX=urlshort:
CACHE_TTL_SECONDS=3600
RATE_LIMIT_WINDOW_SECONDS=60
RATE_LIMIT_MAX_REQUESTS=20

// src/config/env.ts
import dotenv from 'dotenv';
dotenv.config();
 
export const env = {
  port: parseInt(process.env.PORT || '3000', 10),
  baseUrl: process.env.BASE_URL || 'http://localhost:3000',
  nodeEnv: process.env.NODE_ENV || 'development',
  databaseUrl: process.env.DATABASE_URL!,
 
  // Redis
  redisUrl: process.env.REDIS_URL || 'redis://localhost:6379',
  redisKeyPrefix: process.env.REDIS_KEY_PREFIX || 'urlshort:',
  cacheTtlSeconds: parseInt(process.env.CACHE_TTL_SECONDS || '3600', 10),
 
  // Rate limiting
  rateLimitWindowSeconds: parseInt(process.env.RATE_LIMIT_WINDOW_SECONDS || '60', 10),
  rateLimitMaxRequests: parseInt(process.env.RATE_LIMIT_MAX_REQUESTS || '20', 10),
};

npm install ioredis
npm install -D @types/ioredis

// src/config/redis.ts
import Redis from 'ioredis';
import { env } from './env';
 
let redisClient: Redis | null = null;
 
export function getRedisClient(): Redis {
  if (!redisClient) {
    redisClient = new Redis(env.redisUrl, {
      maxRetriesPerRequest: 3,
      retryStrategy(times: number) {
        if (times > 10) {
          console.error('Redis: max retry attempts reached, giving up');
          return null; // Ngừng retry
        }
        const delay = Math.min(times * 200, 2000);
        console.warn(`Redis: retrying connection in ${delay}ms (attempt ${times})`);
        return delay;
      },
      lazyConnect: false,
      enableReadyCheck: true,
    });
 
    redisClient.on('connect', () => {
      console.log('Redis: connected');
    });
 
    redisClient.on('ready', () => {
      console.log('Redis: ready to accept commands');
    });
 
    redisClient.on('error', (err) => {
      console.error('Redis: connection error', err.message);
    });
 
    redisClient.on('close', () => {
      console.warn('Redis: connection closed');
    });
  }
 
  return redisClient;
}
 
export async function closeRedisConnection(): Promise<void> {
  if (redisClient) {
    await redisClient.quit();
    redisClient = null;
    console.log('Redis: connection closed gracefully');
  }
}
 
export async function isRedisHealthy(): Promise<boolean> {
  try {
    const client = getRedisClient();
    const result = await client.ping();
    return result === 'PONG';
  } catch {
    return false;
  }
}

// src/index.ts (thêm vào shutdown handler hiện có)
import { closeRedisConnection } from './config/redis';
 
async function gracefulShutdown() {
  console.log('Shutting down gracefully...');
  await closeRedisConnection();
  // ... đóng database, HTTP server, v.v.
  process.exit(0);
}
 
process.on('SIGTERM', gracefulShutdown);
process.on('SIGINT', gracefulShutdown);

// src/cache/keys.ts
import { env } from '../config/env';
 
const prefix = env.redisKeyPrefix;
 
export const CacheKeys = {
  /** Cache key cho URL record theo short code */
  url: (shortCode: string) => `${prefix}url:${shortCode}`,
 
  /** Cache key cho URL stats */
  urlStats: (shortCode: string) => `${prefix}stats:${shortCode}`,
 
  /** Rate limiter key theo IP address */
  rateLimit: (ip: string) => `${prefix}ratelimit:${ip}`,
 
  /** Rate limiter key theo IP + endpoint */
  rateLimitEndpoint: (ip: string, endpoint: string) =>
    `${prefix}ratelimit:${ip}:${endpoint}`,
};

urlshort:url:abc123          → cached URL record
urlshort:stats:abc123        → cached click stats
urlshort:ratelimit:192.168.1.1  → rate limit counter

// src/cache/urlCache.ts
import { getRedisClient } from '../config/redis';
import { env } from '../config/env';
import { CacheKeys } from './keys';
 
export interface CachedUrl {
  id: string;
  shortCode: string;
  originalUrl: string;
  expiresAt: string | null;
}
 
export class UrlCacheService {
  private redis = getRedisClient();
  private ttl = env.cacheTtlSeconds;
 
  /**
   * Lấy URL từ cache theo short code.
   * Trả về null nếu cache miss hoặc entry đã expire.
   */
  async get(shortCode: string): Promise<CachedUrl | null> {
    try {
      const key = CacheKeys.url(shortCode);
      const cached = await this.redis.get(key);
 
      if (!cached) {
        return null; // Cache miss
      }
 
      const parsed: CachedUrl = JSON.parse(cached);
 
      // Kiểm tra URL đã expire chưa (application-level expiry)
      if (parsed.expiresAt && new Date(parsed.expiresAt) < new Date()) {
        await this.delete(shortCode);
        return null;
      }
 
      return parsed;
    } catch (error) {
      // Cache errors không được phá app
      console.error('Cache get error:', error);
      return null;
    }
  }
 
  /**
   * Lưu URL vào cache với TTL.
   * Nếu URL có expiration riêng, dùng TTL ngắn hơn.
   */
  async set(url: CachedUrl): Promise<void> {
    try {
      const key = CacheKeys.url(url.shortCode);
      const value = JSON.stringify(url);
 
      let effectiveTtl = this.ttl;
 
      // Nếu URL expire sớm hơn cache TTL, dùng URL's expiry
      if (url.expiresAt) {
        const urlTtl = Math.floor(
          (new Date(url.expiresAt).getTime() - Date.now()) / 1000
        );
        if (urlTtl > 0) {
          effectiveTtl = Math.min(effectiveTtl, urlTtl);
        } else {
          return; // URL đã expire, không cache
        }
      }
 
      await this.redis.setex(key, effectiveTtl, value);
    } catch (error) {
      console.error('Cache set error:', error);
      // Không throw — caching là best-effort
    }
  }
 
  /**
   * Xóa URL khỏi cache (dùng cho invalidation).
   */
  async delete(shortCode: string): Promise<void> {
    try {
      const key = CacheKeys.url(shortCode);
      await this.redis.del(key);
    } catch (error) {
      console.error('Cache delete error:', error);
    }
  }
 
  /**
   * Xóa nhiều URLs khỏi cache cùng lúc.
   */
  async deleteMany(shortCodes: string[]): Promise<void> {
    if (shortCodes.length === 0) return;
 
    try {
      const keys = shortCodes.map((code) => CacheKeys.url(code));
      await this.redis.del(...keys);
    } catch (error) {
      console.error('Cache deleteMany error:', error);
    }
  }
}

// src/services/redirectService.ts
import { UrlCacheService, CachedUrl } from '../cache/urlCache';
import { prisma } from '../config/database';
 
const urlCache = new UrlCacheService();
 
export async function resolveShortCode(shortCode: string) {
  // Bước 1: Kiểm tra cache
  const cached = await urlCache.get(shortCode);
 
  if (cached) {
    console.log(`Cache HIT for ${shortCode}`);
    return {
      id: cached.id,
      originalUrl: cached.originalUrl,
      shortCode: cached.shortCode,
      source: 'cache' as const,
    };
  }
 
  console.log(`Cache MISS for ${shortCode}`);
 
  // Bước 2: Query database
  const url = await prisma.url.findUnique({
    where: { shortCode },
    select: {
      id: true,
      shortCode: true,
      originalUrl: true,
      expiresAt: true,
      isActive: true,
    },
  });
 
  if (!url || !url.isActive) {
    return null;
  }
 
  // Kiểm tra expiration
  if (url.expiresAt && url.expiresAt < new Date()) {
    return null;
  }
 
  // Bước 3: Populate cache cho request tiếp theo
  const cacheEntry: CachedUrl = {
    id: url.id,
    shortCode: url.shortCode,
    originalUrl: url.originalUrl,
    expiresAt: url.expiresAt?.toISOString() ?? null,
  };
 
  await urlCache.set(cacheEntry);
 
  return {
    id: url.id,
    originalUrl: url.originalUrl,
    shortCode: url.shortCode,
    source: 'database' as const,
  };
}

// src/routes/redirectRoutes.ts
import { Router, Request, Response, NextFunction } from 'express';
import { resolveShortCode } from '../services/redirectService';
import { recordClick } from '../services/analyticsService';
 
const router = Router();
 
router.get('/:code', async (req: Request, res: Response, next: NextFunction) => {
  try {
    const { code } = req.params;
    const result = await resolveShortCode(code);
 
    if (!result) {
      return res.status(404).json({ error: 'Short URL not found or expired' });
    }
 
    // Record click bất đồng bộ — không block redirect
    recordClick(result.id, req).catch((err) =>
      console.error('Failed to record click:', err)
    );
 
    // Log cache performance (bỏ trong production hoặc dùng proper metrics)
    if (result.source === 'cache') {
      console.log(`Redirect ${code} served from cache`);
    }
 
    return res.redirect(302, result.originalUrl);
  } catch (error) {
    next(error);
  }
});
 
export default router;

// src/services/urlService.ts
import { UrlCacheService } from '../cache/urlCache';
 
const urlCache = new UrlCacheService();
 
export async function updateUrl(
  shortCode: string,
  updates: { originalUrl?: string; expiresAt?: Date; isActive?: boolean }
) {
  // Update trong database (source of truth)
  const updated = await prisma.url.update({
    where: { shortCode },
    data: updates,
  });
 
  // Invalidate cache — request tiếp theo sẽ re-populate
  await urlCache.delete(shortCode);
 
  return updated;
}
 
export async function deleteUrl(shortCode: string) {
  await prisma.url.delete({
    where: { shortCode },
  });
 
  // Xóa khỏi cache
  await urlCache.delete(shortCode);
}
 
export async function deactivateUrl(shortCode: string) {
  await prisma.url.update({
    where: { shortCode },
    data: { isActive: false },
  });
 
  // Xóa khỏi cache — deactivated URLs không nên resolve
  await urlCache.delete(shortCode);
}

// src/cache/urlCache.ts (enhanced set method)
 
async setWithDynamicTtl(url: CachedUrl, clickCount: number): Promise<void> {
  try {
    const key = CacheKeys.url(url.shortCode);
    const value = JSON.stringify(url);
 
    // Nhiều clicks hơn = TTL dài hơn (tối đa 24 giờ)
    let ttl: number;
    if (clickCount > 10000) {
      ttl = 86400;  // 24 giờ — viral URL
    } else if (clickCount > 1000) {
      ttl = 14400;  // 4 giờ — popular URL
    } else if (clickCount > 100) {
      ttl = 3600;   // 1 giờ — traffic vừa phải
    } else {
      ttl = 900;    // 15 phút — traffic thấp
    }
 
    // Vẫn tôn trọng URL-level expiration
    if (url.expiresAt) {
      const urlTtl = Math.floor(
        (new Date(url.expiresAt).getTime() - Date.now()) / 1000
      );
      if (urlTtl > 0) {
        ttl = Math.min(ttl, urlTtl);
      } else {
        return;
      }
    }
 
    await this.redis.setex(key, ttl, value);
  } catch (error) {
    console.error('Cache set error:', error);
  }
}

// src/middleware/rateLimiter.ts
import { Request, Response, NextFunction } from 'express';
import { getRedisClient } from '../config/redis';
import { CacheKeys } from '../cache/keys';
import { env } from '../config/env';
 
interface RateLimitConfig {
  windowSeconds: number;
  maxRequests: number;
  keyGenerator?: (req: Request) => string;
  message?: string;
}
 
const defaultConfig: RateLimitConfig = {
  windowSeconds: env.rateLimitWindowSeconds,
  maxRequests: env.rateLimitMaxRequests,
  message: 'Too many requests. Please try again later.',
};
 
export function rateLimiter(config: Partial<RateLimitConfig> = {}) {
  const {
    windowSeconds,
    maxRequests,
    keyGenerator,
    message,
  } = { ...defaultConfig, ...config };
 
  return async (req: Request, res: Response, next: NextFunction) => {
    const redis = getRedisClient();
 
    // Tạo unique key cho client này
    const clientId = keyGenerator
      ? keyGenerator(req)
      : getClientIp(req);
 
    const key = CacheKeys.rateLimit(clientId);
    const now = Date.now();
    const windowStart = now - windowSeconds * 1000;
 
    try {
      // Dùng Redis pipeline cho atomicity và performance
      const pipeline = redis.pipeline();
 
      // Bước 1: Xóa expired entries (cũ hơn window start)
      pipeline.zremrangebyscore(key, 0, windowStart);
 
      // Bước 2: Đếm entries hiện tại trong window
      pipeline.zcard(key);
 
      // Bước 3: Thêm request hiện tại
      pipeline.zadd(key, now.toString(), `${now}:${Math.random()}`);
 
      // Bước 4: Set expiry trên key (cleanup)
      pipeline.expire(key, windowSeconds);
 
      const results = await pipeline.exec();
 
      if (!results) {
        // Pipeline fail — cho phép request (fail open)
        return next();
      }
 
      // Result index 1 là ZCARD result (count trước khi thêm)
      const currentCount = results[1][1] as number;
 
      if (currentCount >= maxRequests) {
        // Xóa request vừa thêm (không nên tính)
        await redis.zremrangebyscore(key, now, now);
 
        // Tính retry-after
        const oldestEntry = await redis.zrange(key, 0, 0, 'WITHSCORES');
        const retryAfter = oldestEntry.length >= 2
          ? Math.ceil((parseInt(oldestEntry[1]) + windowSeconds * 1000 - now) / 1000)
          : windowSeconds;
 
        res.set({
          'X-RateLimit-Limit': maxRequests.toString(),
          'X-RateLimit-Remaining': '0',
          'X-RateLimit-Reset': Math.ceil((now + retryAfter * 1000) / 1000).toString(),
          'Retry-After': retryAfter.toString(),
        });
 
        return res.status(429).json({
          error: message,
          retryAfter,
        });
      }
 
      // Set rate limit headers cho successful requests
      res.set({
        'X-RateLimit-Limit': maxRequests.toString(),
        'X-RateLimit-Remaining': (maxRequests - currentCount - 1).toString(),
        'X-RateLimit-Reset': Math.ceil((now + windowSeconds * 1000) / 1000).toString(),
      });
 
      next();
    } catch (error) {
      console.error('Rate limiter error:', error);
      // Fail open — nếu Redis chết, vẫn cho phép request
      next();
    }
  };
}
 
function getClientIp(req: Request): string {
  const forwarded = req.headers['x-forwarded-for'];
  if (typeof forwarded === 'string') {
    return forwarded.split(',')[0].trim();
  }
  return req.ip || req.socket.remoteAddress || 'unknown';
}

// src/app.ts
import express from 'express';
import { rateLimiter } from './middleware/rateLimiter';
import urlRoutes from './routes/urlRoutes';
import redirectRoutes from './routes/redirectRoutes';
 
const app = express();
app.use(express.json());
 
// Global rate limit: 100 requests/phút/IP
app.use(rateLimiter({
  windowSeconds: 60,
  maxRequests: 100,
}));
 
// Rate limit chặt hơn cho URL creation
app.use('/api/shorten', rateLimiter({
  windowSeconds: 60,
  maxRequests: 10,
  keyGenerator: (req) => `create:${getClientIp(req)}`,
  message: 'URL creation rate limit exceeded. Max 10 URLs per minute.',
}));
 
// API routes
app.use('/api', urlRoutes);
 
// Redirect route (ít strict hơn — cần nhanh)
app.use('/', redirectRoutes);
 
export default app;

# Lưu URL với 1-hour TTL
SET urlshort:url:abc123 '{"id":"1","shortCode":"abc123","originalUrl":"https://example.com"}' EX 3600
 
# Lấy ra
GET urlshort:url:abc123
 
# Xóa (invalidation)
DEL urlshort:url:abc123
 
# Kiểm tra TTL còn lại
TTL urlshort:url:abc123

# Thêm request timestamp (score = timestamp, member = unique ID)
ZADD urlshort:ratelimit:192.168.1.1 1711036800000 "1711036800000:0.42"
 
# Xóa expired entries (cũ hơn 60 giây)
ZREMRANGEBYSCORE urlshort:ratelimit:192.168.1.1 0 1711036740000
 
# Đếm requests trong window hiện tại
ZCARD urlshort:ratelimit:192.168.1.1
 
# Set key expiry để cleanup
EXPIRE urlshort:ratelimit:192.168.1.1 60

// src/routes/healthRoutes.ts
import { Router, Request, Response } from 'express';
import { isRedisHealthy } from '../config/redis';
import { prisma } from '../config/database';
 
const router = Router();
 
router.get('/health', async (_req: Request, res: Response) => {
  const [redisOk, dbOk] = await Promise.all([
    isRedisHealthy(),
    prisma.$queryRaw`SELECT 1`.then(() => true).catch(() => false),
  ]);
 
  const status = redisOk && dbOk ? 'healthy' : 'degraded';
 
  res.status(redisOk && dbOk ? 200 : 503).json({
    status,
    services: {
      redis: redisOk ? 'connected' : 'disconnected',
      database: dbOk ? 'connected' : 'disconnected',
    },
    timestamp: new Date().toISOString(),
  });
});
 
export default router;

// scripts/benchmark-cache.ts
import { resolveShortCode } from '../src/services/redirectService';
import { getRedisClient } from '../src/config/redis';
 
async function benchmark(shortCode: string, iterations: number) {
  const redis = getRedisClient();
 
  // Warm up — request đầu tiên populate cache
  await resolveShortCode(shortCode);
 
  // Benchmark có cache
  const cacheStart = performance.now();
  for (let i = 0; i < iterations; i++) {
    await resolveShortCode(shortCode);
  }
  const cacheTime = performance.now() - cacheStart;
 
  // Xóa cache
  await redis.flushdb();
 
  // Benchmark không cache (mọi request đều hit DB)
  const dbStart = performance.now();
  for (let i = 0; i < iterations; i++) {
    await resolveShortCode(shortCode);
    await redis.flushdb(); // Xóa sau mỗi lần để force DB hit
  }
  const dbTime = performance.now() - dbStart;
 
  console.log(`\n--- Benchmark Results (${iterations} iterations) ---`);
  console.log(`Có cache:      ${(cacheTime / iterations).toFixed(2)}ms avg`);
  console.log(`Không cache:   ${(dbTime / iterations).toFixed(2)}ms avg`);
  console.log(`Speedup:       ${(dbTime / cacheTime).toFixed(1)}x nhanh hơn`);
  console.log(`Cache hit rate: ~${((1 - 1/iterations) * 100).toFixed(0)}%`);
}
 
benchmark('abc123', 1000);

// src/cache/urlCache.ts — thêm vào UrlCacheService
 
async getWithLock(shortCode: string): Promise<CachedUrl | null> {
  // Thử cache trước
  const cached = await this.get(shortCode);
  if (cached) return cached;
 
  // Thử acquire lock
  const lockKey = `${CacheKeys.url(shortCode)}:lock`;
  const acquired = await this.redis.set(lockKey, '1', 'EX', 5, 'NX');
 
  if (acquired) {
    // Có lock — fetch từ DB và populate cache
    // (caller xử lý DB query và gọi this.set())
    return null; // Signal: "bạn cần fetch từ DB"
  }
 
  // Ai đó đang giữ lock — chờ chút rồi retry từ cache
  await new Promise((resolve) => setTimeout(resolve, 50));
  return this.get(shortCode);
}

// ĐÚNG: invalidate sau update
await prisma.url.update({ where: { shortCode }, data: { originalUrl: newUrl } });
await urlCache.delete(shortCode);
 
// SAI: update cache trực tiếp (risk inconsistency)
await urlCache.set({ ...existing, originalUrl: newUrl });
await prisma.url.update({ where: { shortCode }, data: { originalUrl: newUrl } });

// ĐÚNG
pipeline.expire(key, windowSeconds);
 
// SAI — key tồn tại vĩnh viễn
// (không gọi EXPIRE)

// ĐÚNG
const url = await prisma.url.findUnique({ where: { shortCode } });
if (url) {
  await urlCache.set(toCachedUrl(url)); // Chỉ cache nếu tìm thấy
}
 
// SAI
try {
  const url = await prisma.url.findUnique({ where: { shortCode } });
  await urlCache.set(url); // Cache null khi not-found!
} catch (error) {
  await urlCache.set(null); // Cache errors!
}

url-shortener/
├── src/
│   ├── cache/
│   │   ├── keys.ts              # Cache key generators
│   │   └── urlCache.ts          # URL cache service
│   ├── config/
│   │   ├── env.ts               # Environment variables
│   │   ├── database.ts          # Prisma client
│   │   └── redis.ts             # Redis client + connection mgmt
│   ├── middleware/
│   │   ├── errorHandler.ts      # Error handling
│   │   ├── rateLimiter.ts       # Sliding window rate limiter
│   │   └── validateRequest.ts   # Request validation
│   ├── routes/
│   │   ├── healthRoutes.ts      # Health check endpoint
│   │   ├── redirectRoutes.ts    # Redirect có cache
│   │   └── urlRoutes.ts         # URL CRUD endpoints
│   ├── services/
│   │   ├── analyticsService.ts  # Click tracking
│   │   ├── redirectService.ts   # Resolve short codes (cache-aside)
│   │   └── urlService.ts        # URL CRUD với invalidation
│   ├── types/
│   │   └── url.ts
│   ├── app.ts
│   └── index.ts
├── docker-compose.yml           # PostgreSQL + Redis
├── .env
└── package.json

# Kết nối Redis
docker exec -it url-shortener-redis redis-cli
 
# Xem tất cả keys
KEYS urlshort:*
 
# Kiểm tra cached URL
GET urlshort:url:abc123
 
# Kiểm tra TTL còn lại
TTL urlshort:url:abc123
 
# Monitor tất cả Redis commands real-time (hữu ích cho debugging)
MONITOR
 
# Kiểm tra memory usage
INFO memory
 
# Kiểm tra rate limit entries cho một IP
ZRANGE urlshort:ratelimit:127.0.0.1 0 -1 WITHSCORES

# Gửi 25 requests nhanh — sẽ nhận 429 sau request 20
for i in $(seq 1 25); do
  echo "Request $i: $(curl -s -o /dev/null -w '%{http_code}' http://localhost:3000/api/shorten -X POST -H 'Content-Type: application/json' -d '{"url":"https://example.com"}')"
done

Request 1: 201
Request 2: 201
...
Request 20: 201
Request 21: 429
Request 22: 429
...

# Request đầu tiên — cache miss (chậm hơn)
time curl -o /dev/null -s http://localhost:3000/abc123
 
# Request thứ hai — cache hit (nhanh hơn)
time curl -o /dev/null -s http://localhost:3000/abc123