Skill Upstash Redis

Esta skill cobre as três coisas que aplicativos serverless mais precisam do Redis: cache, sessões e limitação de taxa. O cliente se comunica com o Redis via HTTP, portanto, funciona onde uma conexão TCP de longa duração não funciona (middleware de borda, funções de curta duração). Siga as etapas em ordem; cada uma termina com um ponto de verificação.

Requisitos e limitações

• Um banco de dados Upstash Redis (serviço hospedado; preços baseados no uso com um nível gratuito). As credenciais são uma URL REST e um token da página do banco de dados.
• Variáveis de ambiente UPSTASH_REDIS_REST_URL e UPSTASH_REDIS_REST_TOKEN.
• Cada comando é uma requisição HTTP. Use batch com pipeline() ou MGET/MSET quando você emite muitos comandos por requisição; evite KEYS * em produção.
• Os valores são serializados automaticamente (objetos, arrays, números retornam como foram). Não JSON.stringify antes de set ou parseInt depois de get.

Etapa 1 — Instalar e criar um cliente por módulo

npm install @upstash/redis @upstash/ratelimit

// lib/redis.ts
import { Redis } from "@upstash/redis";

// Reads UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN
export const redis = Redis.fromEnv();

Crie o cliente no escopo do módulo, não dentro do manipulador de requisição, para que caches efêmeros e pipelines possam ser reutilizados entre invocações.

Ponto de verificação: await redis.ping() retorna "PONG".

Etapa 2 — Cache-aside com TTL

import { redis } from "@/lib/redis";

type User = { id: string; name: string; plan: "free" | "pro" };

export async function getUser(userId: string): Promise<User | null> {
  const key = `user:${userId}`;
  const cached = await redis.get<User>(key);
  if (cached) return cached;

  const user = await db.users.findById(userId); // your data source
  if (user) await redis.set(key, user, { ex: 3600 }); // 1 hour TTL
  return user;
}

export async function updateUser(userId: string, patch: Partial<User>) {
  const user = await db.users.update(userId, patch);
  await redis.set(`user:${userId}`, user, { ex: 3600 }); // write-through
  return user;
}

export async function deleteUser(userId: string) {
  await db.users.delete(userId);
  await redis.del(`user:${userId}`); // invalidate
}

Sempre defina um TTL para entradas de cache; namespace de chaves (user:123, session:abc).

Ponto de verificação: a segunda chamada para getUser retorna sem acessar o banco de dados e await redis.ttl("user:123") é positivo.

Etapa 3 — Sessões com expiração deslizante

import { redis } from "@/lib/redis";

const SESSION_TTL = 60 * 60 * 24; // 24 hours

export async function createSession(userId: string, data: Record<string, unknown>) {
  const sessionId = crypto.randomUUID();
  await redis.set(`session:${sessionId}`, { userId, ...data, createdAt: Date.now() }, { ex: SESSION_TTL });
  return sessionId;
}

export async function getSession<T = Record<string, unknown>>(sessionId: string) {
  const session = await redis.get<T>(`session:${sessionId}`);
  if (session) await redis.expire(`session:${sessionId}`, SESSION_TTL); // slide
  return session;
}

export async function destroySession(sessionId: string) {
  await redis.del(`session:${sessionId}`);
}

Armazene o ID da sessão em um cookie HttpOnly; Secure; SameSite; nunca coloque o token do Redis no código do cliente.

Ponto de verificação: getSession após createSession retorna o objeto com userId; após destroySession ele retorna null.

Etapa 4 — Limitação de taxa de um manipulador de rota

// app/api/search/route.ts (Next.js App Router; same pattern for any fetch handler)
import { Ratelimit } from "@upstash/ratelimit";
import { Redis } from "@upstash/redis";

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, "10 s"), // 10 requests per 10 seconds
  prefix: "ratelimit:search", // isolate keys per limiter
});

export async function POST(request: Request) {
  const ip = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? "anonymous";
  const { success, limit, remaining, reset } = await ratelimit.limit(ip);

  if (!success) {
    return new Response("Too Many Requests", {
      status: 429,
      headers: {
        "X-RateLimit-Limit": String(limit),
        "X-RateLimit-Remaining": String(remaining),
        "Retry-After": String(Math.max(0, Math.ceil((reset - Date.now()) / 1000))),
      },
    });
  }

  // handle the request
  return Response.json({ ok: true });
}

• Identificador: use o ID do usuário ou a chave de API quando autenticado; use o IP como fallback.

…