[SGLang] wait-for-jobs에 ETag conditional request 도입으로 API rate limit 절약

PR 링크: sgl-project/sglang#21345 상태: Merged | 변경: +62 / -8

들어가며

SGLang의 CI 파이프라인은 다단계(stage-a, stage-b, stage-c) 구조로, 이전 stage의 모든 job이 완료될 때까지 wait-for-jobs action이 폴링한다. 기존에는 매 폴링마다 github.paginate(listJobsForWorkflowRun)을 호출하여 GitHub API rate limit(5,000/hour)을 소비했다. 폴링 간격이 120초였는데, 장시간 테스트에서 rate limit에 근접하는 문제가 있었다.

이 PR은 HTTP ETag를 활용하여 데이터가 변경되지 않았을 때 304 응답을 받아 rate limit을 전혀 소비하지 않도록 한다.

핵심 코드 분석

ETag 기반 Conditional Request

Before:

for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const jobs = await github.paginate(
        github.rest.actions.listJobsForWorkflowRun, { ... }
    );
    // 매번 rate limit 1회 소비
}

After:

let lastEtag = '';
let lastJobs = null;

async function fetchJobs() {
    const params = { ..., headers: {} };
    if (lastEtag) {
        params.headers['if-none-match'] = lastEtag;
    }

    try {
        const response = await github.request(url, params);
        apiCalls++;
        lastEtag = response.headers.etag || '';
        lastJobs = response.data.jobs;
        return { jobs: lastJobs, cached: false };
    } catch (err) {
        if (err.status === 304 && lastJobs) {
            cachedCalls++;
            return { jobs: lastJobs, cached: true };
        }
        throw err;
    }
}

폴링 간격 단축

poll-interval-seconds:
    default: '60'  # 120초 -> 60초

ETag 덕분에 변경이 없으면 rate limit 비용이 0이므로 폴링 간격을 절반으로 줄여 더 빠르게 상태 변화를 감지할 수 있다.

Rate Limit 모니터링 로그

console.log(`[rate-limit] ${rateRemaining}/${rateLimit} remaining ` +
    `(ETag: ${lastEtag ? 'sent' : 'none'}) | ` +
    `this session: ${apiCalls} paid, ${cachedCalls} free`);

왜 이게 좋은가

1. Rate limit 절약: Job 상태가 변경되지 않은 동안(대부분의 시간) API 호출 비용이 0이다. 실제 환경에서 50-80%의 호출이 304가 될 것으로 예상된다.
2. 빠른 감지: 폴링 간격을 60초로 줄여 job 완료를 최대 1분 더 빨리 감지한다.
3. Pagination 주의: 100개 이상 job이 있으면 ETag를 무효화하는 안전 처리가 포함되어 있다.

정리

HTTP ETag는 REST API에서 가장 기본적인 캐싱 메커니즘이지만, CI 자동화에서 활용하는 경우는 드물다. 이 PR은 단순한 HTTP 헤더 활용으로 rate limit 문제를 근본적으로 해결하면서 폴링 빈도까지 높인 영리한 개선이다.

참고 자료

• GitHub REST API - Conditional Requests
• HTTP ETag

---

이 글은 AI(Claude)의 도움을 받아 작성되었습니다. 코드 분석과 해석에서 오류가 있을 수 있으니, 정확한 내용은 원본 PR을 참고해주세요.