원격으로 테스트를 실행하다가 요청 제한 테스트에서 가끔 요청이 하나 더 허용되면 머신 부하 탓으로 돌리기 쉽습니다. 하지만 실제 원인은 sleep으로 토큰이 충전될 시점을 어림잡는 데 있는 경우가 많습니다. 스레드가 몇 밀리초만 늦게 깨어나도 테스트가 경계를 넘어가기 때문입니다. iOS 요청 진입점의 토큰 버킷을 순수 상태 머신으로 분리하고 클라우드 Mac에서 명시적인 시간을 주입해야 알고리즘 오류와 스케줄링 지연을 구분할 수 있습니다.
먼저 용량과 충전 규칙 정의하기
이 글에서는 이산형 토큰 버킷을 사용합니다. 용량은 토큰 두 개이며, 250밀리초마다 하나씩 충전하고 생성 시에는 가득 채웁니다. 요청마다 지정된 수량을 차감하며, 잔량이 부족하면 대기열에 넣지 않고 즉시 거부합니다. 충전 주기는 초기화 시점부터 계산하며, 토큰을 사용해도 주기가 재설정되지 않습니다.
짧은 시간에 몰리는 요청을 제한하면서도 유휴 상태가 끝난 뒤 소수의 작업을 연속으로 실행하도록 허용하려면 이 모델이 적합합니다. 반면 임의의 슬라이딩 윈도우 안에서 정해진 횟수를 절대 넘지 않아야 한다면 토큰 버킷은 적합하지 않습니다. 두 모델은 경계에서의 동작이 다릅니다.
클라이언트 측 요청 제한은 자신이 보내는 요청의 속도만 제어하며, 서버 측 할당량 검증을 대신할 수 없습니다. 프로세스를 재시작하면 토큰이 다시 가득 차므로, 이를 기기 간 또는 프로세스 간 요청 제한이라고 설명해서도 안 됩니다.
시간은 단조 증가하는 정수 밀리초로 표현하며 달력 시간은 읽지 않습니다. 아래 구현은 이전보다 이른 시간 입력을 거부하므로, 테스트 픽스처의 오류가 상태를 조용히 바꾸는 일을 막습니다.
시간을 주입할 수 있는 코어 구현하기
코드를 TokenBucketChecks.swift로 저장합니다. 코어는 네트워크에 접근하거나 스레드를 대기시키지 않으며, 앱 생명주기에도 의존하지 않습니다. 용량과 주기는 모두 0보다 커야 합니다. 이는 생성 계약이므로 외부 설정을 먼저 검증한 뒤 인스턴스를 생성해야 합니다.
import Dispatch
import XCTest
struct TokenBucket {
let capacity: UInt64
let interval: UInt64
private(set) var tokens: UInt64
private var last: UInt64
init(capacity: UInt64, interval: UInt64, now: UInt64) {
precondition(capacity > 0 && interval > 0)
self.capacity = capacity
self.interval = interval
self.tokens = capacity
self.last = now
}
mutating func take(_ cost: UInt64 = 1, at now: UInt64) -> Bool {
guard now >= last else { return false }
let steps = (now - last) / interval
if steps > 0 {
let room = capacity - tokens
if steps >= room {
tokens = capacity
} else {
tokens += steps
}
last += steps * interval
}
guard cost > 0 && cost <= tokens else { return false }
tokens -= cost
return true
}
}
여기서는 남은 공간을 먼저 비교한 다음 토큰을 더합니다. 오랫동안 사용하지 않은 뒤 충전량을 그대로 더할 때 발생할 수 있는 오버플로를 방지하기 위해서입니다. steps * interval은 now - last를 넘지 않으므로, 기준 시각을 앞으로 이동해도 현재 입력 시각을 넘지 않습니다.
잔량이 상한에 도달하면 추가 토큰은 저장하지 않지만 충전 주기의 위상은 유지합니다. 예를 들어 249밀리초에 토큰을 사용해도 250밀리초에 충전됩니다. 이는 의도적으로 선택한 모델의 동작이며, 연속적인 평균 처리율을 정확히 보장한다는 뜻은 아닙니다.
실제 대기 대신 경계 사례로 테스트하기
다음 테스트를 같은 파일에 이어서 추가합니다. 첫 번째 테스트는 버스트 용량과 충전 경계를, 두 번째 테스트는 장시간 유휴 상태와 잘못된 입력을 확인합니다. 모든 단언은 독립적이고 해석 가능한 시점을 사용하므로 클라우드 머신의 당시 부하에 의존하지 않습니다.
final class BucketTests: XCTestCase {
func testBurstAndRefill() {
var bucket = TokenBucket(capacity: 2, interval: 250, now: 0)
XCTAssertTrue(bucket.take(at: 0))
XCTAssertTrue(bucket.take(at: 0))
XCTAssertFalse(bucket.take(at: 249))
XCTAssertTrue(bucket.take(at: 250))
XCTAssertTrue(bucket.take(at: 749))
XCTAssertTrue(bucket.take(at: 750))
XCTAssertFalse(bucket.take(at: 750))
}
func testIdleCapAndInvalidInputs() {
var bucket = TokenBucket(capacity: 2, interval: 250, now: 0)
XCTAssertTrue(bucket.take(2, at: 0))
XCTAssertTrue(bucket.take(at: 10_000))
XCTAssertTrue(bucket.take(at: 10_000))
XCTAssertFalse(bucket.take(at: 10_000))
let before = bucket.tokens
XCTAssertFalse(bucket.take(at: 9_999))
XCTAssertEqual(bucket.tokens, before)
XCTAssertFalse(bucket.take(0, at: 10_000))
XCTAssertFalse(bucket.take(3, at: 10_000))
}
}
XCTMain([
testCase([
("testBurstAndRefill", BucketTests.testBurstAndRefill),
("testIdleCapAndInvalidInputs", BucketTests.testIdleCapAndInvalidInputs)
])
])
전체 Xcode에 포함된 개발 도구로 실행합니다.
xcrun swift TokenBucketChecks.swift
검증 결과는 명령의 종료 코드로 판단해야 하며, 로그에 특정 단어가 나오는지를 성공 기준으로 삼아서는 안 됩니다. 이 스크립트는 공통 Swift 알고리즘을 검증합니다. iOS 테스트 타깃으로 옮길 때는 테스트 메서드를 유지하고 스크립트 끝의 XCTMain을 제거하여 테스트 러너가 테스트 케이스를 검색하도록 합니다.
용량이 하나인 경우, 한 번에 전체 용량을 차감하는 경우, 초기화 시각이 0이 아닌 경우, UInt64.max에 가까운 입력도 추가하는 것이 좋습니다. 실패한 테스트를 통과시키려고 “몇 밀리초의 오차는 허용”하는 식으로 기준을 느슨하게 만들지 마세요. 그러면 결정적 테스트가 다시 타이밍 테스트로 바뀝니다.
단조 시계와 직렬화된 진입점 연결하기
프로덕션 코드에서는 DispatchTime.now().uptimeNanoseconds / 1_000_000으로 밀리초를 읽을 수 있습니다. 초기화와 이후 요청에는 반드시 같은 시간 소스를 사용해야 합니다. 서버 시간, 벽시계 시간, 시작 시점을 기준으로 한 상대 카운트를 섞어서는 안 됩니다.
여러 작업이 같은 버킷을 공유한다면 시간 읽기, 충전, 차감을 하나의 actor 메서드 안에 넣고, 메서드 내부에는 await를 두지 않아야 합니다. 락을 사용하더라도 락을 획득한 뒤 시간을 읽어야 합니다. 그렇지 않으면 시간을 먼저 읽은 호출이 임계 구역에는 나중에 진입하여 시간이 역행한 것으로 판정될 수 있습니다.
일시 중단과 재생성 규칙 명확히 하기
이 글에서는 시스템 잠자기 중에도 토큰이 반드시 쌓인다고 보장하지 않습니다. 제품 요구사항상 잠자기 시간도 포함해야 한다면 그 의미에 맞는 시계를 별도로 선택하고 따로 테스트해야 합니다. 앱이 종료된 후 버킷을 다시 생성하면 잔량이 가득 찹니다. 이를 허용할 수 없다면 별도의 영속화 프로토콜이 필요하며, 잔량만 저장해서는 안 됩니다.
실패를 실행 가능한 결론으로 정리하기
변경 사항을 제출하기 전에 다음 항목을 하나씩 확인합니다. 초기 버스트 허용량이 용량과 정확히 일치하는지, 충전 1밀리초 전에는 거부되는지, 경계 시각에는 허용되는지, 여러 주기가 지나도 용량을 넘지 않는지, 비용이 0이거나 용량을 초과하는 요청이 거부되는지, 시간이 역행해도 상태가 바뀌지 않는지 확인해야 합니다.
앱에 연결한 뒤에만 실패한다면 버킷을 여러 개 생성했는지, 매 요청 전에 인스턴스를 다시 만드는지, 재시도가 동일한 진입점을 우회하는지부터 확인합니다. 테스트는 통과하지만 요청이 여전히 너무 조밀하다면 대기 시간을 늘려 차이를 가릴 것이 아니라 용량과 주기를 다시 검토해야 합니다.
마지막으로 알고리즘 테스트와 통합 테스트의 결과를 각각 기록합니다. 전자는 “상태 전이가 올바른가”에 답하고, 후자는 “모든 요청이 실제로 동일한 요청 제한 진입점을 거치는가”에 답합니다. 이 두 가지를 분리해야 원격 테스트의 재현성을 유지하고 다음 회귀 문제의 원인도 더 쉽게 찾을 수 있습니다.
자주 묻는 질문
충전 테스트에서 sleep을 피하는 이유는 무엇인가요?
sleep 이후 스레드가 정확한 시점에 다시 실행된다는 보장이 없습니다. 정수 시간을 주입하면 충전 직전, 정확한 경계와 여러 주기 경과를 확실히 검증할 수 있습니다.
이 토큰 버킷은 동시 호출에 안전한가요?
추가 보호 없이는 안전하지 않습니다. 시간 읽기, 토큰 충전과 차감을 동일한 actor 또는 잠금 안에서 하나의 직렬 작업으로 수행해야 합니다.
프로젝트에 맞는 Mac을 선택하세요
네이티브 빌드와 시뮬레이터 테스트가 필요하다면 Apple Silicon 전용 물리 Mac을 대여해 검증해 보세요. 장기간 전업으로 개발하며 한곳에서 사용할 계획이라면 직접 구매하는 방법도 비교해 볼 만합니다. 하루 단위로 먼저 사용해 보고, 꾸준히 이용할 때 월간 또는 분기 요금제를 고려해 보세요.
원격 Mac 대여