forked from baron/baron-sso
65 lines
2.8 KiB
Markdown
65 lines
2.8 KiB
Markdown
# Worksmobile API Rate Limit 정책
|
|
|
|
작성일: 2026-06-09
|
|
|
|
## 목적
|
|
|
|
Worksmobile relay worker는 외부 API 제한을 초과하지 않도록 Works API 호출에 rate limit을 적용한다.
|
|
일반 조회, 수동 enqueue, 비교 화면처럼 backend 내부 처리량이 병목이 아닌 경로는 기본 제약하지 않는다.
|
|
|
|
## 기준
|
|
|
|
- 제한 단위: API별
|
|
- 제한값: 240 requests/min
|
|
- 환산 간격: 같은 API key 기준 요청 시작 간격 250ms 이상
|
|
- API key: HTTP method + normalized path
|
|
- query string은 rate limit key에서 제외한다.
|
|
- 리소스 ID가 포함된 path segment는 `{id}`로 정규화한다.
|
|
|
|
예:
|
|
|
|
- `POST /v1.0/users`
|
|
- `PATCH /v1.0/users/{id}`
|
|
- `POST /v1.0/users/{id}/alias-emails/{id}`
|
|
- `GET /v1.0/orgunits`
|
|
- `PATCH /scim/v2/Users/{id}`
|
|
- `POST /oauth2/v2.0/token`
|
|
|
|
## 적용 범위
|
|
|
|
Backend `WorksmobileHTTPClient`는 optional limiter 주입 지점을 제공한다.
|
|
기본 client 생성자는 limiter를 갖지 않고, `WorksmobileRelayWorker`에 전달되는 client copy에만 limiter를 적용한다.
|
|
또한 Worksmobile relay worker에만 Redis leader lock을 적용해 여러 backend replica 중 하나만 outbox relay를 수행하게 한다.
|
|
|
|
적용 대상:
|
|
|
|
- Worksmobile relay worker가 수행하는 Directory API 조회/쓰기
|
|
- Worksmobile relay worker가 수행하는 SCIM API 조회/쓰기
|
|
- Worksmobile relay worker가 수행하는 OAuth token 요청
|
|
|
|
기본 제외 대상:
|
|
|
|
- admin 화면의 조회/비교 API
|
|
- 수동 sync 요청의 enqueue 단계
|
|
- Worksmobile outbox에 job을 적재하는 내부 처리
|
|
|
|
## 구현 정책
|
|
|
|
- production 기본 client는 limiter를 갖지 않는다.
|
|
- relay worker에는 limiter를 가진 client copy를 전달한다.
|
|
- relay worker는 Redis leader lock을 보유한 replica에서만 `worksmobile_outbox` ready job을 조회한다.
|
|
- leader lock은 Worksmobile relay 전용이며, 다른 relay worker나 일반 backend 작업에는 적용하지 않는다.
|
|
- leader lock 설정은 환경변수로 열지 않고 코드 상수로 고정한다.
|
|
- key: `baron:worksmobile:relay:leader`
|
|
- ttl: 30s
|
|
- 기본 limiter는 API key별 요청 시작 시각을 직렬화한다.
|
|
- context가 취소되면 대기 중인 요청은 `ctx.Err()`로 실패한다.
|
|
- 테스트나 특수 호출자는 `WorksmobileRateLimiter`를 주입해 limiter 동작을 검증하거나 대체할 수 있다.
|
|
|
|
## 운영 메모
|
|
|
|
- 현재 worker 정책은 burst를 허용하지 않는 보수적 제한이다.
|
|
- 외부 API가 `Retry-After`를 제공하는 경우, 별도 retry/backoff 정책을 추가할 수 있다.
|
|
- 여러 backend replica에서 relay worker가 동시에 시작되더라도 Redis leader lock으로 하나의 replica만 relay를 수행한다.
|
|
- Redis 연결이 초기화되지 않은 환경에서는 leader lock을 주입하지 않으며, 단일 인스턴스/dev 실행처럼 기존 방식으로 동작한다.
|