fix(errors)!: 서버 포화는 모든 전송이 공용 SERVER_BUSY 하나로 답한다

문제: 서버 쪽 상한이 찬 거절이 전송마다 다른 코드였다. web-advanced는
ADMISSION_REFUSED(503), fileserver는 instance·전송 pool 포화까지
TRANSFER_ADMISSION_REJECTED(429 RATE_LIMIT), gRPC는 RATE_LIMIT_EXCEEDED
(RESOURCE_EXHAUSTED, "요청이 너무 잦습니다")였다. client는 자기 빈도 탓인지 서버
포화인지 가를 수 없었다. web은 상태만 아는 모든 503을 REQUEST_TIMEOUT으로 답했다
(§4는 비동기 시간 초과만). §4에 OPERATION_NOT_FOUND가 없었고, fileserver 오류
code 27개 중 23개가 계약 문서에 없었으며 예시가 "data": null을 실었다. fileserver는
Retry-After를 발생만 보고 붙여, 본문이 retryable=false로 좁힌 code에도 헤더가
나갔다. gRPC Javadoc과 graphql 스냅숏 머리말이 지운 이름(WORKLOG_NOT_FOUND, spi)을
적었다.

고른 방법(리뷰 README 6절 ②):
- 공용 OperationalError.SERVER_BUSY(503, TRANSIENT_DEPENDENCY, retryable,
  Retry-After 1)를 더했다. registry 행, RetryAfterAdvisor, runbook
  server-busy.md를 같이 둔다.
- web-advanced admission 거절, gRPC call admission(UNAVAILABLE), fileserver의
  instance permit·직접 다운로드 permit·전송 pool 포화가 이 코드다. fileserver는
  같은 이름의 FileserverErrorCode.SERVER_BUSY를 두고, 이름이 같은 code의 뜻이
  같은지 FileserverExceptionTest가 이미 본다. 호출자 자기 scope의 동시 전송
  초과만 TRANSFER_ADMISSION_REJECTED 429로 남는다.
- 상태만 아는 503은 SERVER_BUSY, AsyncRequestTimeoutException만
  REQUEST_TIMEOUT이다(HttpStatusErrorCodes.forException).
- fileserver Retry-After는 본문과 같은 규칙(code와 발생이 모두 retryable)으로
  붙인다. 재시도 불가 code인 ATOMIC_PUBLISH_UNSUPPORTED를 표에서 뺐다.
- docs/fileserver/http-contract.md에 오류 code 표 전체를 두고 예시의 data:null을
  지웠다. http-contract §4에 OPERATION_NOT_FOUND와 SERVER_BUSY를 적었다.
- decisions 2.3에 결정 ①②③ 행을 더했다.
- 포화 시험의 sleep(200)을 첫 거절 신호로 바꾸고, timeout 시험이 code까지
  본다(같은 파일이라 RR9-03-20의 그 부분을 여기서 고친다).
- web-advanced 파일의 spotless 정리(앞 커밋분)를 함께 싣는다.
버린 대안: JOB_EXECUTOR_REJECTED를 재사용 — 백그라운드 job 이름이라 요청 허가
거절을 읽는 client와 runbook을 잘못 이끈다.

위험·한계: 포화 거절로 분기하던 client와 재시도 정책, WebAdvancedError
.ADMISSION_REFUSED를 참조하던 코드, 모든 503을 REQUEST_TIMEOUT으로 보던 client가
바뀐다(upgrade 안내 8·9·13).

BREAKING CHANGE: 서버 포화 코드가 SERVER_BUSY 하나다(web-advanced
ADMISSION_REFUSED 삭제, fileserver instance·pool 포화 429 → 503, gRPC
RESOURCE_EXHAUSTED → UNAVAILABLE). 상태만 아는 503은 SERVER_BUSY다. 할 일은
docs/upgrade/2026-11-round9-contracts.md.

Refs: RR9-03-06, RR9-03-07, RR9-03-11, RR9-03-12, RR9-03-15, RR9-03-16, RR9-03-20
This commit is contained in:
DongHyeonka
2026-11-13 04:47:03 +09:00
parent 7b5b4c6983
commit 697e62e8cb
32 changed files with 244 additions and 81 deletions
@@ -17,10 +17,10 @@ import dev.caskeleton.shared.error.Category;
* servlet transport, the reactive transport and the Nginx delegation path cannot answer the same
* failure three different ways.
*
* <p>{@code UNAUTHENTICATED}, {@code PRECONDITION_FAILED} and {@code UNSUPPORTED_MEDIA_TYPE} share
* their name with an {@code OperationalError}; they are kept here so the failure context stays one
* enum, and {@code FileserverExceptionTest} pins that each means exactly what the operational code
* means on the wire (category, status, retryability).
* <p>{@code UNAUTHENTICATED}, {@code PRECONDITION_FAILED}, {@code UNSUPPORTED_MEDIA_TYPE} and
* {@code SERVER_BUSY} share their name with an {@code OperationalError}; they are kept here so the
* failure context stays one enum, and {@code FileserverExceptionTest} pins that each means exactly
* what the operational code means on the wire (category, status, retryability).
*/
public enum FileserverErrorCode implements ApiErrorCode {
BAD_REQUEST(400, Category.VALIDATION, false),
@@ -42,6 +42,7 @@ public enum FileserverErrorCode implements ApiErrorCode {
MALWARE_DETECTED(422, Category.DATA_INTEGRITY, false),
INVALID_PATH(422, Category.VALIDATION, false),
PATH_OUTSIDE_NAMESPACE(422, Category.VALIDATION, false),
// The caller's own transfers fill its scope's permits: the caller's rate, so 429.
TRANSFER_ADMISSION_REJECTED(429, Category.RATE_LIMIT, true),
// tus checksum extension status: one request's bytes did not match the checksum the client sent
// for them. The chunk is rolled back before its offset commits, so the upload stays resumable.
@@ -52,6 +53,9 @@ public enum FileserverErrorCode implements ApiErrorCode {
AMBIGUOUS_COMPLETION(500, Category.DATA_INTEGRITY, false),
ATOMIC_PUBLISH_UNSUPPORTED(503, Category.PERMANENT_DEPENDENCY, false),
STORAGE_UNAVAILABLE(503, Category.TRANSIENT_DEPENDENCY, true),
// The instance's permits or its transfer pool are full: server saturation, the shared code every
// transport answers it with (decisions 2.3, 2026-11-12).
SERVER_BUSY(503, Category.TRANSIENT_DEPENDENCY, true),
TRANSFER_TIMEOUT(504, Category.TRANSIENT_DEPENDENCY, true),
STORAGE_FULL(507, Category.TRANSIENT_DEPENDENCY, false);
@@ -15,9 +15,11 @@ import java.util.concurrent.atomic.AtomicBoolean;
* In-process admission control backed by bounded semaphores.
*
* <p>The failure vocabulary is deliberately distinct so a client can tell a permanent policy denial
* from a transient one: an exhausted pool is {@code STORAGE_FULL}, and running out of concurrency
* permits — for the caller's scope or for the whole instance — is a retryable admission rejection.
* Stored bytes over a quota ({@code QUOTA_EXCEEDED}) are decided by the quota service, not here.
* from a transient one: an exhausted pool is {@code STORAGE_FULL}; running out of the caller's own
* scope permits is a retryable {@code TRANSFER_ADMISSION_REJECTED} (429, the caller's rate);
* running out of the whole instance's permits is the shared server-saturation {@code SERVER_BUSY}
* (503). Stored bytes over a quota ({@code QUOTA_EXCEEDED}) are decided by the quota service, not
* here.
*/
public final class TransferAdmissionController {
@@ -74,7 +76,7 @@ public final class TransferAdmissionController {
scopePermits.release();
throw new FileserverException(
"instance upload permits are exhausted",
FileserverFailureContext.of(FileserverErrorCode.TRANSFER_ADMISSION_REJECTED, true));
FileserverFailureContext.of(FileserverErrorCode.SERVER_BUSY, true));
}
return new SemaphorePermit(scopePermits, instanceUploads);
}
@@ -83,7 +85,7 @@ public final class TransferAdmissionController {
if (!directDownloads.tryAcquire()) {
throw new FileserverException(
"instance direct download permits are exhausted",
FileserverFailureContext.of(FileserverErrorCode.TRANSFER_ADMISSION_REJECTED, true));
FileserverFailureContext.of(FileserverErrorCode.SERVER_BUSY, true));
}
return new SemaphorePermit(directDownloads);
}
@@ -119,7 +119,12 @@ class TransferAdmissionControllerTest {
assertThatThrownBy(() -> narrow.acquireUpload(scope("tenant-b"), 10))
.isInstanceOf(FileserverException.class)
.satisfies(
failure -> assertThat(((FileserverException) failure).context().retryable()).isTrue());
failure -> {
assertThat(((FileserverException) failure).context().retryable()).isTrue();
assertThat(((FileserverException) failure).context().code())
.as("the whole instance is full: server saturation, not the caller's rate")
.isEqualTo(FileserverErrorCode.SERVER_BUSY);
});
held.close();
TransferPermit afterRelease = narrow.acquireUpload(scope("tenant-b"), 10);
@@ -197,7 +202,9 @@ class TransferAdmissionControllerTest {
TransferPermit download = narrow.acquireDirectDownload(scope("tenant-a"));
assertThatThrownBy(() -> narrow.acquireDirectDownload(scope("tenant-a")))
.isInstanceOf(FileserverException.class);
.isInstanceOf(FileserverException.class)
.extracting(failure -> ((FileserverException) failure).context().code())
.isEqualTo(FileserverErrorCode.SERVER_BUSY);
assertThat(narrow.acquireUpload(scope("tenant-a"), 10).isHeld()).isTrue();
download.close();