Edge Functions: 무엇인지, 언제 사용하고, 언제 사용하지 말아야 하는지

// Node.js에서는 작동하지만 엣지에서는 작동하지 않습니다
import fs from "fs";
import { createConnection } from "net";
import { execSync } from "child_process";
 
const file = fs.readFileSync("/etc/hosts");        // ❌ 파일 시스템 없음
const conn = createConnection({ port: 5432 });     // ❌ 원시 TCP 없음
const result = execSync("ls -la");                  // ❌ 자식 프로세스 없음
process.env.DATABASE_URL;                           // ⚠️  사용 가능하지만 정적, 배포 시 설정됨

// 엣지에서 모두 작동합니다
const response = await fetch("https://api.example.com/data");
const url = new URL(request.url);
const headers = new Headers({ "Content-Type": "application/json" });
const encoder = new TextEncoder();
const encoded = encoder.encode("hello");
const hash = await crypto.subtle.digest("SHA-256", encoded);
const id = crypto.randomUUID();
 
// Web Streams API
const stream = new ReadableStream({
  start(controller) {
    controller.enqueue("chunk 1");
    controller.enqueue("chunk 2");
    controller.close();
  },
});
 
// Cache API
const cache = caches.default;
await cache.put(request, response.clone());

// ❌ 엣지에서 이렇게 하지 마세요
import dayjs from "dayjs";
import * as yup from "yup";
import lodash from "lodash";
 
// ✅ 대신 이렇게 하세요 — 내장 API 사용
const date = new Date().toISOString();
const isValid = typeof input === "string" && input.length < 200;
const unique = [...new Set(items)];

// middleware.ts — 모든 요청에서 엣지에서 실행
import { NextRequest, NextResponse } from "next/server";
 
export const config = {
  matcher: ["/", "/shop/:path*"],
};
 
export function middleware(request: NextRequest) {
  const country = request.geo?.country ?? "US";
  const city = request.geo?.city ?? "Unknown";
  const region = request.geo?.region ?? "Unknown";
 
  // 국가별 스토어로 리다이렉트
  if (request.nextUrl.pathname === "/shop") {
    const storeMap: Record<string, string> = {
      DE: "/shop/eu",
      FR: "/shop/eu",
      GB: "/shop/uk",
      JP: "/shop/jp",
      TR: "/shop/tr",
    };
 
    const storePath = storeMap[country] ?? "/shop/us";
    if (request.nextUrl.pathname !== storePath) {
      return NextResponse.redirect(new URL(storePath, request.url));
    }
  }
 
  // 다운스트림 사용을 위한 지리 헤더 추가
  const response = NextResponse.next();
  response.headers.set("x-user-country", country);
  response.headers.set("x-user-city", city);
  response.headers.set("x-user-region", region);
  return response;
}

import { NextRequest, NextResponse } from "next/server";
 
export function middleware(request: NextRequest) {
  // 사용자에게 이미 변형 할당이 있는지 확인
  const existingVariant = request.cookies.get("ab-variant")?.value;
 
  if (existingVariant) {
    // 올바른 변형 페이지로 리라이트
    const url = request.nextUrl.clone();
    url.pathname = `/variants/${existingVariant}${url.pathname}`;
    return NextResponse.rewrite(url);
  }
 
  // 새 변형 할당 (50/50 분할)
  const variant = Math.random() < 0.5 ? "control" : "treatment";
 
  const url = request.nextUrl.clone();
  url.pathname = `/variants/${variant}${url.pathname}`;
 
  const response = NextResponse.rewrite(url);
  response.cookies.set("ab-variant", variant, {
    maxAge: 60 * 60 * 24 * 30, // 30일
    httpOnly: true,
    sameSite: "lax",
  });
 
  return response;
}

import { jwtVerify, importSPKI } from "jose";
import { NextRequest, NextResponse } from "next/server";
 
const PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----`;
 
export async function middleware(request: NextRequest) {
  const token = request.cookies.get("session-token")?.value;
 
  if (!token) {
    return NextResponse.redirect(new URL("/login", request.url));
  }
 
  try {
    const key = await importSPKI(PUBLIC_KEY, "RS256");
    const { payload } = await jwtVerify(token, key, {
      algorithms: ["RS256"],
      issuer: "https://auth.example.com",
    });
 
    // 사용자 정보를 헤더로 다운스트림에 전달
    const response = NextResponse.next();
    response.headers.set("x-user-id", payload.sub as string);
    response.headers.set("x-user-role", payload.role as string);
    return response;
  } catch {
    // 토큰 만료 또는 유효하지 않음
    const response = NextResponse.redirect(new URL("/login", request.url));
    response.cookies.delete("session-token");
    return response;
  }
}

import { NextRequest, NextResponse } from "next/server";
 
// 간단한 인메모리 속도 제한기 (엣지 위치별)
const rateLimitMap = new Map<string, { count: number; timestamp: number }>();
 
export function middleware(request: NextRequest) {
  const ip = request.headers.get("x-forwarded-for")?.split(",").pop()?.trim()
    ?? "unknown";
  const ua = request.headers.get("user-agent") ?? "";
 
  // 알려진 악성 봇 차단
  const badBots = ["AhrefsBot", "SemrushBot", "MJ12bot", "DotBot"];
  if (badBots.some((bot) => ua.includes(bot))) {
    return new NextResponse("Forbidden", { status: 403 });
  }
 
  // 간단한 속도 제한
  const now = Date.now();
  const windowMs = 60_000; // 1분
  const maxRequests = 100;
 
  const entry = rateLimitMap.get(ip);
  if (entry && now - entry.timestamp < windowMs) {
    entry.count++;
    if (entry.count > maxRequests) {
      return new NextResponse("Too Many Requests", {
        status: 429,
        headers: { "Retry-After": "60" },
      });
    }
  } else {
    rateLimitMap.set(ip, { count: 1, timestamp: now });
  }
 
  // 메모리 누수 방지를 위한 주기적 정리
  if (rateLimitMap.size > 10_000) {
    const cutoff = now - windowMs;
    for (const [key, val] of rateLimitMap) {
      if (val.timestamp < cutoff) rateLimitMap.delete(key);
    }
  }
 
  return NextResponse.next();
}

import { NextRequest, NextResponse } from "next/server";
 
export function middleware(request: NextRequest) {
  const response = NextResponse.next();
  const url = request.nextUrl;
 
  // 디바이스 기반 콘텐츠 협상
  const ua = request.headers.get("user-agent") ?? "";
  const isMobile = /mobile|android|iphone/i.test(ua);
  response.headers.set("x-device-type", isMobile ? "mobile" : "desktop");
 
  // 쿠키에서 피처 플래그
  const flags = request.cookies.get("feature-flags")?.value;
  if (flags) {
    response.headers.set("x-feature-flags", flags);
  }
 
  // i18n을 위한 로케일 감지
  const acceptLanguage = request.headers.get("accept-language") ?? "en";
  const preferredLocale = acceptLanguage.split(",")[0]?.split("-")[0] ?? "en";
  const supportedLocales = [
    "en", "tr", "de", "fr", "es", "pt", "ja", "ko", "it",
    "nl", "ru", "pl", "uk", "sv", "cs", "ar", "hi", "zh",
  ];
  const locale = supportedLocales.includes(preferredLocale)
    ? preferredLocale
    : "en";
 
  if (!url.pathname.startsWith(`/${locale}`) && !url.pathname.startsWith("/api")) {
    return NextResponse.redirect(new URL(`/${locale}${url.pathname}`, request.url));
  }
 
  return response;
}

// ❌ 이 패턴은 엣지에서 근본적으로 작동하지 않습니다
import { Pool } from "pg";
 
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 10, // 10개의 커넥션 풀
});
 
// 각 엣지 호출은:
// 1. 새 Pool을 생성 (호출 간 안정적으로 재사용 불가)
// 2. 데이터베이스에 TCP 연결 열기 (DB는 엣지가 아닌 us-east-1에 있음)
// 3. 데이터베이스와 TLS 핸드셰이크
// 4. 쿼리 실행
// 5. isolate가 재활용되면 연결 폐기
 
// PgBouncer 같은 커넥션 풀링 서비스를 사용하더라도
// 엣지 → 오리진 데이터베이스의 네트워크 지연은 여전히 발생

// ✅ 엣지에서 작동합니다 (HTTP 기반 데이터베이스 접근)
// 하지만 데이터베이스가 엣지 노드에서 멀면 여전히 느립니다
import { neon } from "@neondatabase/serverless";
 
export const runtime = "edge";
 
export async function GET(request: Request) {
  const sql = neon(process.env.DATABASE_URL!);
  // Neon 데이터베이스에 HTTP 요청을 보냅니다
  // 작동하지만, 지연은 데이터베이스 리전까지의 거리에 따라 달라집니다
  const posts = await sql`SELECT * FROM posts WHERE published = true LIMIT 10`;
  return Response.json(posts);
}

// ❌ 엣지에서 CPU 시간 제한을 초과합니다
export const runtime = "edge";
 
export async function POST(request: Request) {
  const data = await request.json();
 
  // 이미지 처리 — CPU 집약적
  // (sharp는 네이티브 모듈이므로 사용할 수도 없음)
  const processed = heavyImageProcessing(data.image);
 
  // PDF 생성 — CPU 집약적 + Node.js API 필요
  const pdf = generatePDF(data.content);
 
  // 대규모 데이터 변환
  const result = data.items // 100,000 항목
    .map(transform)
    .filter(validate)
    .sort(compare)
    .reduce(aggregate, {});
 
  return Response.json(result);
}

// ❌ 이 패키지들은 엣지에서 작동하지 않습니다
import bcrypt from "bcrypt";            // 네이티브 C++ 바인딩
import sharp from "sharp";              // 네이티브 C++ 바인딩
import puppeteer from "puppeteer";      // 파일 시스템 + child_process 필요
import nodemailer from "nodemailer";    // net 모듈 필요
import { readFile } from "fs/promises"; // Node.js 파일 시스템 API
import mongoose from "mongoose";         // TCP 연결 + Node.js API
 
// ✅ 엣지 호환 대안
import { hashSync } from "bcryptjs";    // 순수 JS 구현 (더 느림)
// 이미지: 별도의 서비스 또는 API 사용
// 이메일: HTTP 기반 이메일 API 사용 (Resend, SendGrid REST)
// 데이터베이스: HTTP 기반 클라이언트 사용

// ❌ 배럴 파일 임포트가 너무 많이 끌어올 수 있습니다
import { validateEmail } from "@/lib/utils";
// utils.ts가 20개의 다른 모듈에서 재내보내면, 모두 번들에 포함됩니다
 
// ✅ 소스에서 직접 임포트
import { validateEmail } from "@/lib/validators/email";

// middleware.ts — 항상 엣지에서 실행, 옵트인 불필요
import { NextRequest, NextResponse } from "next/server";
 
export function middleware(request: NextRequest) {
  // 모든 매칭 요청 전에 실행됩니다
  // 빠르게 유지하세요 — 데이터베이스 호출 없음, 무거운 연산 없음
  return NextResponse.next();
}
 
export const config = {
  // 특정 경로에서만 실행
  matcher: [
    "/((?!_next/static|_next/image|favicon.ico|robots.txt|sitemap.xml).*)",
  ],
};

// app/api/hello/route.ts
export const runtime = "edge"; // 이 한 줄이 런타임을 변경합니다
 
export async function GET(request: Request) {
  return Response.json({
    message: "엣지에서 인사드립니다",
    region: process.env.VERCEL_REGION ?? "unknown",
    timestamp: Date.now(),
  });
}

// app/dashboard/page.tsx
export const runtime = "edge";
 
export default async function DashboardPage() {
  // 기억하세요: 여기서는 Node.js API가 없습니다
  // 모든 데이터 가져오기는 fetch() 또는 엣지 호환 클라이언트를 사용해야 합니다
  const data = await fetch("https://api.example.com/dashboard", {
    headers: { Authorization: `Bearer ${process.env.API_KEY}` },
    next: { revalidate: 60 },
  }).then((r) => r.json());
 
  return (
    <main>
      <h1>대시보드</h1>
      {/* 데이터 렌더링 */}
    </main>
  );
}

// ✅ 엣지에서 사용 가능
fetch()                          // HTTP 요청
Request / Response               // 웹 표준 요청/응답
Headers                          // HTTP 헤더
URL / URLSearchParams            // URL 파싱
TextEncoder / TextDecoder        // 문자열 인코딩
crypto.subtle                    // 암호화 작업 (서명, 해싱)
crypto.randomUUID()              // UUID 생성
crypto.getRandomValues()         // 암호학적 난수
structuredClone()                // 딥 클로닝
atob() / btoa()                  // Base64 인코딩/디코딩
setTimeout() / setInterval()     // 타이머 (CPU 제한 기억)
console.log()                    // 로깅
ReadableStream / WritableStream  // 스트리밍
AbortController / AbortSignal    // 요청 취소
URLPattern                       // URL 패턴 매칭
 
// ❌ 엣지에서 사용 불가
require()                        // CommonJS (import 사용)
fs / path / os                   // Node.js 내장 모듈
process.exit()                   // 프로세스 제어
Buffer                           // 대신 Uint8Array 사용
__dirname / __filename           // import.meta.url 사용
setImmediate()                   // 웹 표준 아님

// lib/edge-auth.ts — 엣지 호환 인증 유틸리티
import { jwtVerify, SignJWT, importSPKI, importPKCS8 } from "jose";
 
const PUBLIC_KEY_PEM = process.env.JWT_PUBLIC_KEY!;
const ISSUER = "https://auth.myapp.com";
const AUDIENCE = "https://myapp.com";
 
export interface TokenPayload {
  sub: string;
  email: string;
  role: "user" | "admin" | "moderator";
  iat: number;
  exp: number;
}
 
export async function verifyToken(token: string): Promise<TokenPayload | null> {
  try {
    const publicKey = await importSPKI(PUBLIC_KEY_PEM, "RS256");
    const { payload } = await jwtVerify(token, publicKey, {
      algorithms: ["RS256"],
      issuer: ISSUER,
      audience: AUDIENCE,
      clockTolerance: 30, // 30초의 시계 오차 허용
    });
 
    return payload as unknown as TokenPayload;
  } catch {
    return null;
  }
}
 
export function isTokenExpiringSoon(payload: TokenPayload): boolean {
  const now = Math.floor(Date.now() / 1000);
  const fiveMinutes = 5 * 60;
  return payload.exp - now < fiveMinutes;
}

// middleware.ts — 인증 미들웨어
import { NextRequest, NextResponse } from "next/server";
import { verifyToken, isTokenExpiringSoon } from "./lib/edge-auth";
 
const PUBLIC_PATHS = ["/", "/login", "/register", "/api/auth/login"];
const ADMIN_PATHS = ["/admin"];
 
export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
 
  // 공개 경로는 인증 건너뛰기
  if (PUBLIC_PATHS.some((p) => pathname === p || pathname.startsWith("/api/public"))) {
    return NextResponse.next();
  }
 
  // 토큰 추출
  const token = request.cookies.get("auth-token")?.value;
  if (!token) {
    return NextResponse.redirect(new URL("/login", request.url));
  }
 
  // 토큰 검증 (순수 암호화 — 데이터베이스 호출 없음)
  const payload = await verifyToken(token);
  if (!payload) {
    const response = NextResponse.redirect(new URL("/login", request.url));
    response.cookies.delete("auth-token");
    return response;
  }
 
  // 역할 기반 접근 제어
  if (ADMIN_PATHS.some((p) => pathname.startsWith(p)) && payload.role !== "admin") {
    return NextResponse.redirect(new URL("/unauthorized", request.url));
  }
 
  // 검증된 사용자 정보를 신뢰할 수 있는 헤더로 오리진에 전달
  const response = NextResponse.next();
  response.headers.set("x-user-id", payload.sub);
  response.headers.set("x-user-email", payload.email);
  response.headers.set("x-user-role", payload.role);
 
  // 토큰 갱신이 필요한 경우 신호
  if (isTokenExpiringSoon(payload)) {
    response.headers.set("x-token-refresh", "true");
  }
 
  return response;
}

// app/api/profile/route.ts — 오리진 서버가 신뢰할 수 있는 헤더를 읽습니다
export async function GET(request: Request) {
  // 이 헤더는 JWT 검증 후 엣지 미들웨어에 의해 설정되었습니다
  // 자체 인프라에서 왔기 때문에 신뢰할 수 있습니다
  const userId = request.headers.get("x-user-id");
  const userRole = request.headers.get("x-user-role");
 
  if (!userId) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }
 
  // 이제 데이터베이스에 접근할 수 있습니다 — 오리진 서버에 있으니,
  // 커넥션 풀을 가진 데이터베이스 바로 옆입니다
  const user = await db.user.findUnique({ where: { id: userId } });
 
  return Response.json(user);
}

// app/api/products/route.ts
export const runtime = "edge";
 
export async function GET(request: Request) {
  const url = new URL(request.url);
  const category = url.searchParams.get("category") ?? "all";
 
  const products = await fetch(
    `${process.env.ORIGIN_API}/products?category=${category}`,
  ).then((r) => r.json());
 
  return Response.json(products, {
    headers: {
      // CDN에서 60초간 캐시
      // 최대 5분간 재검증하면서 오래된 것 서빙
      // 클라이언트는 10초간 캐시 가능
      "Cache-Control": "public, s-maxage=60, stale-while-revalidate=300, max-age=10",
 
      // 이 헤더로 변형하여 다른 변형이 다른 캐시 항목을 얻도록
      Vary: "Accept-Language, Accept-Encoding",
 
      // 타겟 무효화를 위한 CDN 전용 캐시 태그
      "Cache-Tag": `products,category-${category}`,
    },
  });
}

import { get } from "@vercel/edge-config";
import { NextRequest, NextResponse } from "next/server";
 
export async function middleware(request: NextRequest) {
  // Edge Config 읽기는 매우 빠릅니다 (~1ms)
  // 데이터가 모든 엣지 위치에 복제되어 있기 때문입니다
  const maintenanceMode = await get<boolean>("maintenance_mode");
 
  if (maintenanceMode) {
    return NextResponse.rewrite(new URL("/maintenance", request.url));
  }
 
  // 피처 플래그
  const features = await get<Record<string, boolean>>("feature_flags");
  if (features?.["new_pricing_page"] && request.nextUrl.pathname === "/pricing") {
    return NextResponse.rewrite(new URL("/pricing-v2", request.url));
  }
 
  // 동적 리다이렉트 (재배포 없이 리다이렉트 업데이트)
  const redirects = await get<Array<{ from: string; to: string; permanent: boolean }>>(
    "redirects",
  );
 
  if (redirects) {
    const match = redirects.find((r) => r.from === request.nextUrl.pathname);
    if (match) {
      return NextResponse.redirect(
        new URL(match.to, request.url),
        match.permanent ? 308 : 307,
      );
    }
  }
 
  return NextResponse.next();
}

// ✅ 엣지에 완벽
// - 미들웨어 (인증, 리다이렉트, 리라이트, 헤더)
// - 지리적 위치 로직
// - A/B 테스트 할당
// - 봇 탐지 / WAF 규칙
// - 캐시 친화적 API 응답
// - 피처 플래그 확인
// - CORS 프리플라이트 응답
// - 정적 데이터 변환 (DB 없음)
// - 웹훅 서명 검증
 
// ❌ Node.js 리전에 유지
// - 데이터베이스 CRUD 작업
// - 파일 업로드 / 처리
// - 이미지 조작
// - PDF 생성
// - 이메일 전송 (HTTP API 사용하되, 리전에서)
// - WebSocket 서버
// - 백그라운드 작업 / 큐
// - 네이티브 npm 패키지를 사용하는 모든 것
// - 데이터베이스 쿼리가 있는 SSR 페이지
// - 데이터베이스에 접근하는 GraphQL 리졸버
 
// 🤔 상황에 따라 다름
// - 인증 (JWT는 엣지, 세션-DB는 리전)
// - API 라우트 (DB 없으면 엣지, DB 있으면 리전)
// - 서버 렌더링 페이지 (데이터가 캐시/fetch에서 오면 엣지, DB면 리전)
// - 실시간 기능 (초기 인증은 엣지, 영구 연결은 리전)