Files
clean-architecture-backend-…/docs/web/virtual-thread-profile.md
T
donghyeon-kaandClaude Opus 5.5 27f23add08 review-followup Wave 3: 설정 prefix app.* 통일(P20), Wave 3 종료
- 결정 16: `ca-skeleton.*`·`backend.graphql` 등 → `app.*`(APP_* env 키 이름 유지), selector 키 상수 하나(`CapabilitySelectors`),
  바인딩만 되던 `streaming-idle` 삭제
- `StrictSettingsBinder`가 env 오타까지 거부 — 모든 capability(graphql·websocket·mongo는 edge 제약으로 파일만 strict),
  httpclient 리플렉션 `HttpClientEnvironmentKeys` 삭제
- persistence-jpa가 `APP_DATASOURCE_PASSWORD` secret 요구를 기여(bootstrap이 JPA 스위치를 읽지 않음), Redis ACL fixture에서 pub/sub 권한 제거
- 결함 수정: SMTP 설정 env 이름 충돌(P20-new-1), `bindExcept`가 system env까지 filter(P20-new-2), graphql 빈 deployment-mode 메시지(P20-new-6)
- 통합: P30과 충돌 11건(P30의 명시적 bean 구조 유지), P30 코드의 옛 키를 app.*로, persistence-jpa 포맷
- 현황표: 소유자 결정 36(persistence-jpa 설정은 플랫폼 키만 app.persistence-jpa.*로, 공유 기능 트리 예외), 재개 문서에 일시 정지 상태

Wave 3 종료 검증: check · ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck · architectureCheck
verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest
:sample-portfolio:integrationTest :sample-portfolio:systemTest · integrationCheck · -p build-logic test ·
-p optional-platforms ci · :app-bootstrap:qualificationBootJar releaseCheck 통과

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-29 17:01:54 +09:00

3.8 KiB

The virtual-thread MVC profile

What it changes, and what it does not

Virtual threads remove the cost of a thread waiting. They do not remove the reason the waiting was bounded.

A platform-thread MVC deployment has an implicit concurrency limit — the thread pool. Nobody wrote it down as an admission policy, but it is what has been protecting the database pool, the outbound HTTP bulkhead and every downstream service from the full arrival rate.

Switching to virtual threads deletes that limit and deletes nothing that depended on it. The result is not a slow system. It is a system that accepts ten thousand concurrent requests, queues all of them on a twenty-connection pool, and times out every one — having done no useful work. The load that used to be shed at the front door is shed at the back, after the cost of accepting it.

Enabling it

The profile ships in adapter:inbound:web-advanced, which no default composition carries. Add that leaf to the service, then two settings — the profile refuses to be constructed with only one:

app:
  web:
    advanced:
      mvc-virtual-threads:
        enabled: true
        admission-limit: 100        # required
        database-pool-size: 20      # stated, and unchanged
        outbound-bulkhead: 20       # stated, and unchanged

The downstream numbers are carried in the profile because the whole point is that they did not grow. VirtualThreadProfile.admissionFitsDownstreamBudgets() reports when the admission limit exceeds them. It does not refuse — a deployment can legitimately admit more than its pool when the work is not all database-bound — but it makes the choice a choice.

The limit bounds use cases, not threads

VirtualThreadAdmissionGuard is a fair semaphore, not a pool. Bounding the threads would put the waiting back and throw away what virtual threads bought. Ten thousand virtual threads may exist while a hundred hold permits and the rest are refused at the door.

A refusal is a 503 with Retry-After, and it is the outcome the limit exists to produce. A request refused in a millisecond is strictly better for the client than the same request accepted and timed out thirty seconds later behind a full pool.

The semaphore is fair on purpose. An unfair one is faster and lets newer arrivals overtake waiting ones, which the overtaken client experiences as a random timeout.

What to watch

Signal Why
jdk.VirtualThreadPinned JFR events A synchronized block held across a blocking call pins the carrier thread. The carrier pool is bounded by CPU count, so enough pinned carriers is a deadlock — and a thread dump does not obviously show it.
Carrier pool queue depth The same problem, from the other side.
Admission rejections They should rise under load. If they do not, the limit is not being applied.
Downstream wait time The signal that admission is admitting more than the pools serve.

VirtualThreadProfile.requiredObservations() is the same list, in code.

Testing it

VirtualThreadAdmissionGuard.peakActive() exists so a load test can assert the limit was applied. It is invisible from throughput — a load test that only measures throughput passes with the guard removed, which is precisely the failure this profile guards against.

The test that matters asserts two things together: peak concurrency at or below the limit, and more threads created than the limit. Without the second, the test would pass on a deployment that never used virtual threads at all.

Rolling back

Set enabled: false, or drop the leaf. The rollback test asserts that Stable behaviour is then identical — if it is not, the feature was never optional and every deployment has it.

This is the only web Advanced capability that affects requests which do not use them, which is why its rollback test is the one that matters most.