Files
clean-architecture-backend-…/docs/httpclient/env-fields.yaml
T
DongHyeonka e38c949c2f docs(httpclient): HTTP client 문서를 한국어로 옮기고 숫자 복사를 없앤다
문제: docs/httpclient 아래 살아 있는 문서 9개가 영어였다(language 예외).
repository-adaptation.md는 registry의 leaf 수를 「exactly 19 leaf identities」로, Spring
Boot 버전을 4.0.8로 옮겨 적었다(number 예외 두 줄). 같은 문서가 testkit을 `testkit`
source set이라고 했지만 1절 표와 실제 코드는 `testFixtures`다.

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·설정 key·예외·metric·위반 코드·표 구조는
원문으로 둔다. scripts/verify-httpclient-docs.py가 코드에서 뽑는 이름이 모두 문서에 남는다.
leaf 수는 registry(src/config/architecture/modules.json)를, 버전은
src/gradle/libs.versions.toml의 `springBoot`를 가리킨다. 등급 이름(Stable, Default,
Restricted, Internal, Experimental)은 꼬리표라 원문으로 둔다. env-fields.yaml은 머리 주석만
옮겼다. HttpClientPlatformEnvManifestTest는 주석을 읽지 않는다(`- field:`·`env:` 줄만).
configuration-reference.md의 「Three of these」 뒤 목록이 다섯이라 「아래 코드들」로 고쳤다.

버린 대안: 리뷰 번호(RR-03-14 등)를 걷어 내기. 이 작업은 번역이고 내용 감사는 다음 리뷰 몫이라
날짜와 함께 그대로 둔다.

위험·한계: 내용 감사는 하지 않았다.

검증: python3 scripts/check-docs.py rc=0(이 폴더 예외 줄 0).
python3 scripts/verify-httpclient-docs.py PASS(코드에서 뽑은 이름 156개 모두 문서에 있음).
2026-11-07 17:29:57 +09:00

174 lines
9.3 KiB
YAML

# HTTP Client 플랫폼 — Java 필드 경로에서 환경 변수 template로의 대응.
#
# 정본은 HttpClientPlatformSettings다. HttpClientPlatformEnvManifestTest가 record 트리에서 이 목록을 만들어
# 양쪽 방향으로 어긋나면 실패하고, 공용 엄격 binder는 어떤 필드도 가리키지 않는 APP_HTTPCLIENT_ 변수가
# 있으면 시작을 거부한다. 그래서 항목 없이 더한 필드, 필드 이름이 바뀐 항목, 배포의 오타 변수가 모두
# 조용히 넘어가지 않고 실패한다.
#
# `N`과 `M`은 글자 그대로가 아니라 list index다. `N`은 바깥 list, `M`은 그 안의 list다.
# 첫 client의 `app.httpclient.clients[N].base-url`은 APP_HTTPCLIENT_CLIENTS_0_BASE_URL로,
# `clients[N].allowed-hosts[M]`은 APP_HTTPCLIENT_CLIENTS_0_ALLOWED_HOSTS_0으로 준다.
#
# docs/registries/env-keys.yaml에 등록하고 src/.env에 담는 것은 APP_HTTPCLIENT_ENABLED뿐이다. 배포와
# 상관없는 값을 가진 유일한 key이고, 세 방향을 대조하는 :app-bootstrap:verifyEnvKeys 게이트가 표현할 수
# 있는 유일한 key다. 아래 나머지는 모두 배포마다 다르고 환경에 직접 준다. index를 단 client를
# application.yml에 template로 두면 모든 배포에 이름 없는 client가 생기고, settings의 묶음 검증이 그것을
# 거부한다.
#
# 이 파일은 docs/registries가 아니라 HTTP Client 문서 옆에 있다. docs/registries는 행 schema
# (행마다 owner_branch/compatibility_impact/required_test)가 고정된 계약 registry만 받는, 닫힌 쪽으로
# 실패하는 목록이다. 필드-변수 대응은 그 모양이 아니고, 받아들이려면 게이트를 맞추는 대신 풀어야 했다.
#
# secret은 값이 아니라 참조로 준다. authentication.secret-reference, tls.*-material-reference,
# proxy.credential-provider는 secret backend가 푸는 재료의 이름이다. 재료 자체를 이 변수에 넣으면
# 이 변수들이 있는 이유인 간접화가 무너진다.
fields:
- field: enabled
env: APP_HTTPCLIENT_ENABLED
- field: rotation-drain-timeout
env: APP_HTTPCLIENT_ROTATION_DRAIN_TIMEOUT
- field: clients[N].name
env: APP_HTTPCLIENT_CLIENTS_N_NAME
- field: clients[N].mode
env: APP_HTTPCLIENT_CLIENTS_N_MODE
- field: clients[N].base-url
env: APP_HTTPCLIENT_CLIENTS_N_BASE_URL
- field: clients[N].allowed-hosts[M]
env: APP_HTTPCLIENT_CLIENTS_N_ALLOWED_HOSTS_M
- field: clients[N].allowed-ports[M]
env: APP_HTTPCLIENT_CLIENTS_N_ALLOWED_PORTS_M
- field: clients[N].transport
env: APP_HTTPCLIENT_CLIENTS_N_TRANSPORT
- field: clients[N].protocols[M]
env: APP_HTTPCLIENT_CLIENTS_N_PROTOCOLS_M
- field: clients[N].pool.max-total-connections
env: APP_HTTPCLIENT_CLIENTS_N_POOL_MAX_TOTAL_CONNECTIONS
- field: clients[N].pool.max-connections-per-route
env: APP_HTTPCLIENT_CLIENTS_N_POOL_MAX_CONNECTIONS_PER_ROUTE
- field: clients[N].pool.max-pending-acquires
env: APP_HTTPCLIENT_CLIENTS_N_POOL_MAX_PENDING_ACQUIRES
- field: clients[N].pool.pending-acquire-timeout
env: APP_HTTPCLIENT_CLIENTS_N_POOL_PENDING_ACQUIRE_TIMEOUT
- field: clients[N].pool.max-idle-time
env: APP_HTTPCLIENT_CLIENTS_N_POOL_MAX_IDLE_TIME
- field: clients[N].pool.max-life-time
env: APP_HTTPCLIENT_CLIENTS_N_POOL_MAX_LIFE_TIME
- field: clients[N].pool.validate-after-inactivity
env: APP_HTTPCLIENT_CLIENTS_N_POOL_VALIDATE_AFTER_INACTIVITY
- field: clients[N].pool.requires-route-pool
env: APP_HTTPCLIENT_CLIENTS_N_POOL_REQUIRES_ROUTE_POOL
- field: clients[N].pool.requires-bounded-pending-queue
env: APP_HTTPCLIENT_CLIENTS_N_POOL_REQUIRES_BOUNDED_PENDING_QUEUE
- field: clients[N].timeout.dns
env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_DNS
- field: clients[N].timeout.connect
env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_CONNECT
- field: clients[N].timeout.tls-handshake
env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_TLS_HANDSHAKE
- field: clients[N].timeout.response-header
env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_RESPONSE_HEADER
- field: clients[N].timeout.read-idle
env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_READ_IDLE
- field: clients[N].timeout.total-call
env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_TOTAL_CALL
- field: clients[N].redirect.enabled
env: APP_HTTPCLIENT_CLIENTS_N_REDIRECT_ENABLED
- field: clients[N].redirect.max-hops
env: APP_HTTPCLIENT_CLIENTS_N_REDIRECT_MAX_HOPS
- field: clients[N].redirect.allow-cross-origin
env: APP_HTTPCLIENT_CLIENTS_N_REDIRECT_ALLOW_CROSS_ORIGIN
- field: clients[N].request.max-body-bytes
env: APP_HTTPCLIENT_CLIENTS_N_REQUEST_MAX_BODY_BYTES
- field: clients[N].request.compression
env: APP_HTTPCLIENT_CLIENTS_N_REQUEST_COMPRESSION
- field: clients[N].response.max-wire-bytes
env: APP_HTTPCLIENT_CLIENTS_N_RESPONSE_MAX_WIRE_BYTES
- field: clients[N].response.max-decoded-bytes
env: APP_HTTPCLIENT_CLIENTS_N_RESPONSE_MAX_DECODED_BYTES
- field: clients[N].response.allowed-content-types[M]
env: APP_HTTPCLIENT_CLIENTS_N_RESPONSE_ALLOWED_CONTENT_TYPES_M
- field: clients[N].authentication.type
env: APP_HTTPCLIENT_CLIENTS_N_AUTHENTICATION_TYPE
- field: clients[N].authentication.registration-id
env: APP_HTTPCLIENT_CLIENTS_N_AUTHENTICATION_REGISTRATION_ID
- field: clients[N].authentication.scopes[M]
env: APP_HTTPCLIENT_CLIENTS_N_AUTHENTICATION_SCOPES_M
- field: clients[N].authentication.audience
env: APP_HTTPCLIENT_CLIENTS_N_AUTHENTICATION_AUDIENCE
- field: clients[N].authentication.header-name
env: APP_HTTPCLIENT_CLIENTS_N_AUTHENTICATION_HEADER_NAME
- field: clients[N].authentication.secret-reference
env: APP_HTTPCLIENT_CLIENTS_N_AUTHENTICATION_SECRET_REFERENCE
- field: clients[N].retry.policy
env: APP_HTTPCLIENT_CLIENTS_N_RETRY_POLICY
- field: clients[N].retry.max-attempts
env: APP_HTTPCLIENT_CLIENTS_N_RETRY_MAX_ATTEMPTS
- field: clients[N].retry.base-backoff
env: APP_HTTPCLIENT_CLIENTS_N_RETRY_BASE_BACKOFF
- field: clients[N].retry.max-backoff
env: APP_HTTPCLIENT_CLIENTS_N_RETRY_MAX_BACKOFF
- field: clients[N].retry.jitter
env: APP_HTTPCLIENT_CLIENTS_N_RETRY_JITTER
- field: clients[N].retry.retry-after
env: APP_HTTPCLIENT_CLIENTS_N_RETRY_RETRY_AFTER
- field: clients[N].retry.budget
env: APP_HTTPCLIENT_CLIENTS_N_RETRY_BUDGET
- field: clients[N].observability.full-url-recording
env: APP_HTTPCLIENT_CLIENTS_N_OBSERVABILITY_FULL_URL_RECORDING
- field: clients[N].observability.body-logging
env: APP_HTTPCLIENT_CLIENTS_N_OBSERVABILITY_BODY_LOGGING
- field: clients[N].tls.profile-id
env: APP_HTTPCLIENT_CLIENTS_N_TLS_PROFILE_ID
- field: clients[N].tls.protocols[M]
env: APP_HTTPCLIENT_CLIENTS_N_TLS_PROTOCOLS_M
- field: clients[N].tls.hostname-verification
env: APP_HTTPCLIENT_CLIENTS_N_TLS_HOSTNAME_VERIFICATION
- field: clients[N].tls.trust-all
env: APP_HTTPCLIENT_CLIENTS_N_TLS_TRUST_ALL
- field: clients[N].tls.allow-plain-http
env: APP_HTTPCLIENT_CLIENTS_N_TLS_ALLOW_PLAIN_HTTP
- field: clients[N].tls.trust-material-reference
env: APP_HTTPCLIENT_CLIENTS_N_TLS_TRUST_MATERIAL_REFERENCE
- field: clients[N].tls.key-material-reference
env: APP_HTTPCLIENT_CLIENTS_N_TLS_KEY_MATERIAL_REFERENCE
- field: clients[N].proxy.enabled
env: APP_HTTPCLIENT_CLIENTS_N_PROXY_ENABLED
- field: clients[N].proxy.host
env: APP_HTTPCLIENT_CLIENTS_N_PROXY_HOST
- field: clients[N].proxy.port
env: APP_HTTPCLIENT_CLIENTS_N_PROXY_PORT
- field: clients[N].proxy.type
env: APP_HTTPCLIENT_CLIENTS_N_PROXY_TYPE
- field: clients[N].proxy.credential-provider
env: APP_HTTPCLIENT_CLIENTS_N_PROXY_CREDENTIAL_PROVIDER
- field: clients[N].proxy.import-ambient-no-proxy
env: APP_HTTPCLIENT_CLIENTS_N_PROXY_IMPORT_AMBIENT_NO_PROXY
- field: clients[N].experimental-acknowledgement
env: APP_HTTPCLIENT_CLIENTS_N_EXPERIMENTAL_ACKNOWLEDGEMENT
- field: clients[N].circuit-breaker.failure-rate-threshold
env: APP_HTTPCLIENT_CLIENTS_N_CIRCUIT_BREAKER_FAILURE_RATE_THRESHOLD
- field: clients[N].circuit-breaker.minimum-number-of-calls
env: APP_HTTPCLIENT_CLIENTS_N_CIRCUIT_BREAKER_MINIMUM_NUMBER_OF_CALLS
- field: clients[N].circuit-breaker.sliding-window-size
env: APP_HTTPCLIENT_CLIENTS_N_CIRCUIT_BREAKER_SLIDING_WINDOW_SIZE
- field: clients[N].circuit-breaker.wait-duration-in-open-state
env: APP_HTTPCLIENT_CLIENTS_N_CIRCUIT_BREAKER_WAIT_DURATION_IN_OPEN_STATE
- field: clients[N].circuit-breaker.permitted-calls-in-half-open-state
env: APP_HTTPCLIENT_CLIENTS_N_CIRCUIT_BREAKER_PERMITTED_CALLS_IN_HALF_OPEN_STATE
- field: dynamic-targets[N].name
env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_NAME
- field: dynamic-targets[N].allowed-schemes[M]
env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_ALLOWED_SCHEMES_M
- field: dynamic-targets[N].allowed-ports[M]
env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_ALLOWED_PORTS_M
- field: dynamic-targets[N].allowed-host-suffixes[M]
env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_ALLOWED_HOST_SUFFIXES_M
- field: dynamic-targets[N].allowed-hosts[M]
env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_ALLOWED_HOSTS_M
- field: dynamic-targets[N].max-redirect-hops
env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_MAX_REDIRECT_HOPS
- field: dynamic-targets[N].trace-propagation
env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_TRACE_PROPAGATION
- field: dynamic-targets[N].blocked-cidrs[M]
env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_BLOCKED_CIDRS_M