API 속도 제한의 핵심 가치

디지털 인프라에서 API(Application Programming Interface)는 시스템 간 통신을 연결하는 중추적인 역할을 수행합니다. Papermark와 같은 오픈소스 문서 공유 플랫폼에서 API의 안정성은 곧 사용자의 신뢰도와 직결됩니다. 트래픽이 급증하거나 악의적인 요청이 유입될 때, 시스템을 보호하는 가장 강력한 방어 기제 중 하나가 바로 속도 제한(Rate Limiting)입니다. 이는 특정 시간 동안 클라이언트가 보낼 수 있는 요청 수를 제어하여 서버 과부하를 방지하고 공정한 리소스 배분을 보장합니다.

대표적인 속도 제한 알고리즘

• 고정 윈도우 카운터 (Fixed Window Counter): 정해진 시간 단위(예: 1분) 내에 요청 수를 카운트합니다. 구현이 단순하지만 윈도우 경계 시점에 트래픽이 몰릴 수 있다는 단점이 있습니다.
• 슬라이딩 윈도우 로그 (Sliding Window Log): 모든 요청의 타임스탬프를 기록하여 정밀하게 제어합니다. 정확도는 높지만 메모리 소비량이 큽니다.
• 토큰 버킷 (Token Bucket): 일정한 속도로 버킷에 토큰이 채워지며, 요청마다 토큰을 소모합니다. 순간적인 대량 트래픽(Burst)을 유연하게 처리할 수 있어 가장 널리 사용됩니다.
• 리키 버킷 (Leaky Bucket): 요청이 일정한 속도로 처리되도록 강제하여 트래픽의 변동성을 최소화하고 평탄화합니다.

Papermark를 위한 API 속도 제한 구현 전략

Papermark의 기술 스택인 Next.js와 TypeScript 환경에서는 Redis와 같은 인메모리 데이터베이스를 활용한 미들웨어를 구축하는 것이 효율적입니다. 다음은 클라이언트 식별자별로 다른 정책을 적용하는 미들웨어 구성 예시입니다.

// lib/security/rate-limiter.ts
import { NextRequest, NextResponse } from 'next/server';
import Redis from 'ioredis';

const redisStore = new Redis(process.env.REDIS_URL || 'redis://127.0.0.1:6379');

const QUOTA_POLICIES = {
  GUEST: { interval: 60, limit: 30 },
  STANDARD: { interval: 60, limit: 150 },
  PREMIUM: { interval: 60, limit: 500 },
};

async function resolveClientKey(req: NextRequest): Promise<string> {
  const authHeader = req.headers.get('authorization');
  if (authHeader) return `user:${authHeader.split(' ')[1]}`;
  
  const forwardIp = req.headers.get('x-forwarded-for');
  return `ip:${forwardIp || 'anonymous'}`;
}

export async function rateLimitMiddleware(req: NextRequest) {
  const clientKey = await resolveClientKey(req);
  const policy = clientKey.startsWith('user:') ? QUOTA_POLICIES.STANDARD : QUOTA_POLICIES.GUEST;
  
  const currentTimestamp = Math.floor(Date.now() / 1000);
  const bucketKey = `api_limit:${clientKey}:${Math.floor(currentTimestamp / policy.interval)}`;

  const requestCount = await redisStore.incr(bucketKey);
  
  if (requestCount === 1) {
    await redisStore.expire(bucketKey, policy.interval);
  }

  const headers = {
    'X-RateLimit-Max': policy.limit.toString(),
    'X-RateLimit-Remaining': Math.max(0, policy.limit - requestCount).toString(),
  };

  if (requestCount > policy.limit) {
    return new NextResponse(
      JSON.stringify({ message: '요청 한도를 초과했습니다. 잠시 후 다시 시도하세요.' }),
      { 
        status: 429, 
        headers: { ...headers, 'Retry-After': policy.interval.toString() } 
      }
    );
  }

  return NextResponse.next({ headers });
}

효율적인 속도 제한 정책 설계

단순히 모든 사용자에게 동일한 제한을 적용하는 것보다, 서비스 모델에 따른 차등화된 정책 수립이 필요합니다.

클라이언트 측의 429 오류 대응 로직

서버가 429(Too Many Requests) 상태 코드를 반환할 때, 클라이언트는 이를 우아하게 처리해야 합니다. 단순히 오류를 표시하는 대신 지수 백오프(Exponential Backoff) 알고리즘을 사용한 재시도 로직을 구현하는 것이 권장됩니다.

async function executeApiRequest(url, payload, attempt = 0) {
  const MAX_RETRIES = 3;
  
  try {
    const response = await fetch(url, {
      method: 'POST',
      body: JSON.stringify(payload)
    });

    if (response.status === 429) {
      if (attempt < MAX_RETRIES) {
        const waitTime = Math.pow(2, attempt) * 1000;
        console.warn(`한도 초과. ${waitTime}ms 후 재시도합니다.`);
        await new Promise(res => setTimeout(res, waitTime));
        return executeApiRequest(url, payload, attempt + 1);
      }
    }
    return response.json();
  } catch (error) {
    console.error('API 호출 실패:', error);
  }
}

모니터링 및 성능 최적화

속도 제한 시스템 구축 이후에는 지속적인 분석이 수반되어야 합니다.

• 지표 추적: 어떤 엔드포인트에서 429 오류가 가장 빈번하게 발생하는지 파악하여 정책을 조정합니다.
• 알림 설정: 특정 IP나 사용자가 비정상적으로 높은 빈도로 제한을 초과할 경우 보안 팀에 알림을 전송합니다.
• 동적 한도 조정: 서버 부하가 적은 시간대에는 한도를 일시적으로 높여 사용자 경험을 개선할 수 있습니다.

정교하게 설계된 API 속도 제한은 시스템 리소스를 보호할 뿐만 아니라, 비정상적인 트래픽 패턴을 감지하는 보안 센서의 역할도 수행합니다. Papermark 서비스의 성장에 발맞춰 이러한 메커니즘을 고도화해 나가는 것이 중요합니다.