fix(scripts)!: httpclient 문서 검사가 설정 필드를 절과 표 위치로 대조한다 #88

Merged
donghyeon.kang merged 3 commits from fix/httpclient-docs-field-match into main 2026-11-21 21:12:03 +00:00
4 changed files with 378 additions and 26 deletions
@@ -24,6 +24,15 @@
`HTTPCLIENT_ACTIVE_WITHOUT_CLIENTS`로 시작이 실패한다. 부를 대상이 없는 플랫폼도 아무 호출자도 닿을 수 없는
transport provider와 gateway를 쥐고 있기 때문이다.
## 인증서 교체 뒤 비우기
| 속성 | 타입 | 기본값 | 환경 변수 |
|---|---|---|---|
| `app.httpclient.rotation-drain-timeout` | duration | `30s` | `APP_HTTPCLIENT_ROTATION_DRAIN_TIMEOUT` |
인증서를 교체하면 새 런타임 세대가 호출을 받는다. 내린 세대는 이 시간 동안 진행 중인 호출을 마저 끝내고, 시간이
지나면 남은 호출이 있어도 pool을 닫는다. 음수면 시작이 실패한다.
## 환경 변수로 client 선언하기
client는 이름을 key로 한 map이 아니라, 자기 `name`을 가진 index 목록이다. map key는 환경 변수 이름의 한 조각이
@@ -0,0 +1,27 @@
# 업그레이드 안내 — 2026-11 HTTP client 문서 검사의 설정 필드 대조
- 범위: release workflow의 `httpclient-documentation` job이 부르는 `scripts/verify-httpclient-docs.py`. 설정 필드를
마지막 마디 낱말이 아니라 설정 참조 문서의 절과 표 위치로 대조하고, 코드에서 뽑은 이름이 0개인 종류를 실패로 본다.
운영 코드, 설정 키, manifest 형식은 그대로다.
- 근거: 2026-11-22 리뷰 발견 REV-BE-0013. `enabled`·`name`·`type`처럼 흔한 이름의 새 필드가 문서 없이 release를
통과했다. 코드의 설정 이름이 문서에 있어야 한다는 것은 이 스크립트가 이미 지키던 규칙이다.
## 1. 누가 읽나
이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 HTTP client를 싣고 `app.httpclient` 아래
설정 필드를 더했거나 `docs/httpclient/configuration-reference.md`의 절·표를 고친 서비스다.
## 2. 할 일
| # | 할 일 | 안 하면 | 해당 서비스 |
| --- | --- | --- | --- |
| 1 | 더한 설정 필드마다 `docs/httpclient/configuration-reference.md`의 속성 표(머리 첫 칸이 `속성`인 표)에 행을 둔다. 첫 칸에 필드 이름을 코드 표기로 쓰고, 행은 필드가 속한 절 아래에 둔다. `clients[N]` 바로 아래 필드는 `app.httpclient.clients[N]` 절의 표에, 묶음 아래 필드는 그 묶음 이름의 `###` 절(`tls` 아래 `enabled`면 `tls` 절)에 둔다. 절 제목이 묶음 여럿을 이름 대면 첫 칸에 `redirect.enabled`처럼 묶음까지 쓴다. 최상위 필드는 `app.httpclient.<이름>`으로 쓴다 | release의 `httpclient-documentation` job이 `configuration property '<경로>' exists in code but is not documented in a configuration-reference.md table under its section`으로 실패한다. 전에는 필드의 마지막 마디 낱말이 `docs/httpclient`의 아홉 문서 어디에든 있으면 통과했다 | `app.httpclient` 필드를 더한 서비스 |
| 2 | 「지운 설정」 표나 설명 표에만 적힌 key를 되살렸으면 그 key를 자기 절의 속성 표로 옮긴다. 머리 첫 칸이 `속성`이 아닌 표(`지운 key`, `끝낸 것`)는 필드를 문서화한 것으로 세지 않는다 | 1번과 같은 실패 | 지운 key를 되살린 서비스 |
| 3 | 할 일 없음. 숫자가 든 `TransportType` 상수(`HTTP3` 꼴)도 이제 대조한다. 그런 상수를 더했으면 문서에 이름을 적는다 | `transport '<상수>' exists in code but is not documented`로 실패한다. 전에는 그 상수를 뽑지 못해 대조하지 않았다 | transport를 더한 서비스 |
| 4 | 할 일 없음. 다섯 종류(예외·지표·시작 위반 코드·설정 필드·transport) 중 코드에서 뽑은 이름이 0개인 종류가 있으면 실패한다. 출처 파일을 고쳐 쓰다 추출 꼴(두 칸 들여쓴 enum 상수, manifest의 `- field:` 행 등)이 달라졌으면 출처를 맞춘다 | `no <종류> found in the code`로 실패한다. 전에는 아무것도 대조하지 않고 통과했다 | 그 출처 파일을 고쳐 쓴 서비스 |
## 3. 바뀌지 않은 것
- 설정 필드를 뺀 네 종류는 전처럼 아홉 문서를 이은 글에서 이름을 찾는다.
- manifest(`docs/httpclient/env-fields.yaml`)의 형식과 release workflow의 job은 그대로다.
- 검사는 한 방향이다. 문서에 있지만 코드에 없는 이름은 실패가 아니다.
+230 -8
View File
@@ -8,6 +8,7 @@ from __future__ import annotations
import importlib.util
import io
import sys
import tempfile
import unittest
from contextlib import redirect_stdout
from pathlib import Path
@@ -19,26 +20,247 @@ sys.modules["verify_httpclient_docs"] = verify_httpclient_docs
_spec.loader.exec_module(verify_httpclient_docs)
# A configuration reference shaped like the real one: property tables (header `속성`) under block
# and group headings, plus a removed-key table and an explanatory table that name settings without
# documenting them. The cases below use it instead of the real reference, so a service that adds and
# documents `clients[N].tls.enabled` does not turn them red.
REFERENCE = """\
## `app.httpclient.clients[N]`
| 속성 | 타입 | 기본값 | 비고 |
|---|---|---|---|
| `allowed-hosts` | list | 비어 있음 | |
### 지운 설정
| 지운 key | 이유 |
|---|---|
| `timeout.request-write-idle` | |
| `app.httpclient.clients[N].timeout.proxy-connect` | |
### `circuit-breaker`
| 끝낸 것 | Breaker | 이유 |
|---|---|---|
| `total-call` | 실패로 기록한다 | |
### `redirect`, `request`, `response`
| 속성 | 기본값 | 뜻 |
|---|---|---|
| `redirect.enabled` | `false` | |
### `tls`
| 속성 | 기본값 | 뜻 |
|---|---|---|
| `profile-id` | — | |
### `proxy`와 `observability`
| 속성 | 기본값 | 뜻 |
|---|---|---|
| `proxy.enabled` | `false` | |
"""
def run_main() -> tuple[int, str]:
output = io.StringIO()
with redirect_stdout(output):
rc = verify_httpclient_docs.main()
return rc, output.getvalue()
class HttpclientDocsTest(unittest.TestCase):
# No case runs the verifier over the real tree and expects 0: that is the release workflow's
# check, and this suite runs in the pull-request gate (documentCheck).
def setUp(self) -> None:
self._workdir = tempfile.TemporaryDirectory()
self.workdir = Path(self._workdir.name)
self._saved = {
name: getattr(verify_httpclient_docs, name)
for name in ("ENV_FIELD_MANIFEST", "TRANSPORT_TYPE", "read_docs", "read_configuration_reference")
if hasattr(verify_httpclient_docs, name)
}
def tearDown(self) -> None:
for name, value in self._saved.items():
setattr(verify_httpclient_docs, name, value)
self._workdir.cleanup()
def use_manifest(self, *fields: str) -> None:
manifest = self.workdir / "env-fields.yaml"
entries = "".join(f" - field: {field}\n env: APP_HTTPCLIENT_TEST_ONLY\n" for field in fields)
manifest.write_text("fields:\n" + entries, encoding="utf-8")
verify_httpclient_docs.ENV_FIELD_MANIFEST = manifest
def use_reference(self, text: str) -> None:
# The reference also joins the documentation the other kinds are searched in, as the real
# one does.
read_docs = self._saved["read_docs"]
verify_httpclient_docs.read_docs = lambda: read_docs() + "\n" + text
verify_httpclient_docs.read_configuration_reference = lambda: text
def test_a_metric_missing_from_the_documentation_fails_naming_it(self) -> None:
# given
metric = verify_httpclient_docs.metric_names()[0]
original = verify_httpclient_docs.read_docs
verify_httpclient_docs.read_docs = lambda: original().replace(metric, "")
output = io.StringIO()
try:
# when
with redirect_stdout(output):
rc = verify_httpclient_docs.main()
finally:
verify_httpclient_docs.read_docs = original
# when
rc, output = run_main()
# then
self.assertEqual(rc, 1)
self.assertIn(f"metric '{metric}'", output.getvalue())
self.assertIn(f"metric '{metric}'", output)
def test_a_new_field_whose_leaf_is_documented_in_another_section_fails_naming_its_path(self) -> None:
# given: `enabled` is documented, but under redirect and proxy, not under tls
self.use_reference(REFERENCE)
self.use_manifest("clients[N].redirect.enabled", "clients[N].proxy.enabled", "clients[N].tls.enabled")
# when
rc, output = run_main()
# then
self.assertEqual(rc, 1)
self.assertIn("configuration property 'clients[N].tls.enabled'", output)
self.assertNotIn("'clients[N].redirect.enabled'", output)
self.assertNotIn("'clients[N].proxy.enabled'", output)
def test_a_new_field_documented_under_its_section_is_not_reported(self) -> None:
# given
row = "| `profile-id` | — | |\n"
self.assertIn(row, REFERENCE)
self.use_reference(REFERENCE.replace(row, row + "| `enabled` | `true` | |\n"))
self.use_manifest("clients[N].redirect.enabled", "clients[N].proxy.enabled", "clients[N].tls.enabled")
# when
_, output = run_main()
# then
self.assertNotIn("configuration property '", output)
def test_a_field_named_only_outside_a_property_table_fails(self) -> None:
# given: the removed-key table and the circuit-breaker table name these, no property table does
self.use_reference(REFERENCE)
fields = (
"clients[N].timeout.request-write-idle",
"clients[N].timeout.proxy-connect",
"clients[N].circuit-breaker.total-call",
)
self.use_manifest(*fields)
# when
rc, output = run_main()
# then
self.assertEqual(rc, 1)
for field in fields:
self.assertIn(f"configuration property '{field}'", output)
def test_a_list_field_is_matched_by_its_name_without_the_index(self) -> None:
# given
self.use_reference(REFERENCE)
self.use_manifest("clients[N].allowed-hosts[M]")
# when
_, output = run_main()
# then
self.assertNotIn("configuration property '", output)
def test_the_reference_is_read_by_block_and_group_from_property_tables_only(self) -> None:
# given
reference = "\n".join(
[
"# 설정",
"## 주 스위치",
"| 속성 | 타입 |",
"|---|---|",
"| `app.httpclient.enabled` | boolean |",
"## `app.httpclient.clients[N]`",
"| 속성 | 타입 | 비고 |",
"|---|---|---|",
"| `name` | string | `app.httpclient.in-another-cell` |",
"```yaml",
"| 속성 | x |",
"|---|---|",
"| `fenced` | x |",
"```",
"### `pool`",
"| 속성 | 기본값 |",
"|---|---|",
"| `max-idle-time` | `30s` |",
"| `pool.max-life-time` | `5m` |",
"",
"| 끝낸 것 | 이유 |",
"|---|---|",
"| `explained` | not a property table |",
"### `redirect`, `request`",
"| 속성 | 기본값 |",
"|---|---|",
"| `redirect.enabled` | `false` |",
"| `timeout.dns` | not a group this heading names |",
"| `bare` | ambiguous under two groups |",
"### 지운 설정",
"| 지운 key | 이유 |",
"|---|---|",
"| `app.httpclient.clients[N].timeout.request-write-idle` | removed |",
"## 시작 위반 코드",
"| 속성 | x |",
"|---|---|",
"| `top-level` | x |",
"## `app.httpclient.dynamic-targets[N]`",
"| 속성 | 기본값 |",
"|---|---|",
"| `name` | — |",
]
)
# when
documented = verify_httpclient_docs.documented_properties(reference)
# then
self.assertEqual(
documented,
{
"enabled",
"clients[N].name",
"clients[N].pool.max-idle-time",
"clients[N].pool.max-life-time",
"clients[N].redirect.enabled",
"top-level",
"dynamic-targets[N].name",
},
)
def test_a_manifest_with_no_field_fails_instead_of_checking_nothing(self) -> None:
# given
self.use_manifest()
# when
rc, output = run_main()
# then
self.assertEqual(rc, 1)
self.assertIn("no configuration property", output)
def test_a_transport_constant_with_a_digit_is_checked(self) -> None:
# given
transport_type = self.workdir / "TransportType.java"
transport_type.write_text(
"package x;\n\npublic enum TransportType {\n APACHE,\n QUIC2\n}\n", encoding="utf-8"
)
verify_httpclient_docs.TRANSPORT_TYPE = transport_type
# when
rc, output = run_main()
# then
self.assertEqual(rc, 1)
self.assertIn("transport 'QUIC2'", output)
if __name__ == "__main__":
+112 -18
View File
@@ -7,7 +7,10 @@ The design (§33 "Documentation") requires the support matrix, configuration ref
guide and runbook to match the code. Review cannot hold that line by itself, so
this verifier extracts the names that are part of the public contract -- stable exceptions, metric
names, configuration properties, startup violation codes, and transports -- and fails when one
exists in code but nowhere in the documentation.
exists in code but nowhere in the documentation. A configuration property must appear where a reader
would look it up: in a table of the configuration reference, under the section of its block and
group (see `documented_properties`). It also fails when a kind yields no name at all, because an
extractor that stopped matching its source would otherwise pass by checking nothing.
It deliberately checks one direction only. A name documented but not yet implemented is a plan; a
name implemented but undocumented is a surprise for whoever is on call.
@@ -23,6 +26,11 @@ REPO_ROOT = Path(__file__).resolve().parent.parent
PLATFORM = REPO_ROOT / "src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient"
DOCS_DIR = REPO_ROOT / "docs/httpclient"
ENV_FIELD_MANIFEST = REPO_ROOT / "docs/httpclient/env-fields.yaml"
CONFIGURATION_REFERENCE = DOCS_DIR / "configuration-reference.md"
TRANSPORT_TYPE = PLATFORM / "profile/TransportType.java"
PROPERTY_PREFIX = "app.httpclient."
PROPERTY_TABLE_HEADER = "속성"
CODE_SPAN = re.compile(r"`([^`]+)`")
REQUIRED_DOCS = [
"support-matrix.md",
@@ -43,6 +51,82 @@ def read_docs() -> str:
)
def read_configuration_reference() -> str:
return CONFIGURATION_REFERENCE.read_text(encoding="utf-8")
def documented_properties(reference: str) -> set[str]:
"""Field paths the configuration reference lists, spelled as the manifest spells them.
Only property tables count -- those whose header starts with `속성` -- and only the first cell
of their rows, read against the headings above the table. The removed-key table (`지운 key`) and
explanatory tables (`끝낸 것`) name settings without documenting a field.
- A `#` or `##` heading naming `app.httpclient.<block>` opens that block (`clients[N]`,
`dynamic-targets[N]`); any other one returns to the top level.
- A `###` heading names the group its rows belong to. Under `### `pool`` the bare leaf
`max-idle-time` means `clients[N].pool.max-idle-time`. Under a heading naming several groups
(`### `redirect`, `request`, `response``) a row spells `group.leaf`; a dotted name whose first
segment the heading does not name is ignored, and so is any name under a `###` heading that
names no group.
- Rows directly under the block heading are its own fields. A name spelled
`app.httpclient.<path>` is that path in any property table.
Matching only the last segment anywhere in the documentation let `clients[N].tls.enabled` pass
on the strength of `redirect.enabled`; six last segments are already shared, so any new field
with one of those names went undocumented without a failure.
"""
documented: set[str] = set()
block = ""
groups: list[str] | None = None
in_fence = False
header: str | None = None # first header cell of the table being read, None outside a table
for line in reference.splitlines():
if not line.startswith("|"):
header = None
if line.startswith("```"):
in_fence = not in_fence
continue
if in_fence:
continue
heading = re.match(r"(#+)\s", line)
if heading:
names = CODE_SPAN.findall(line)
if len(heading.group(1)) <= 2:
block = next(
(name[len(PROPERTY_PREFIX) :] for name in names if name.startswith(PROPERTY_PREFIX)),
"",
)
groups = None
else:
groups = names
continue
if not line.startswith("|"):
continue
first_cell = line.split("|")[1]
if header is None:
header = first_cell.strip()
continue
if header != PROPERTY_TABLE_HEADER:
continue
for name in CODE_SPAN.findall(first_cell):
if name.startswith(PROPERTY_PREFIX):
documented.add(name[len(PROPERTY_PREFIX) :])
continue
if groups is None:
path = name
elif "." in name:
if name.split(".")[0] not in groups:
continue
path = name
elif len(groups) == 1:
path = f"{groups[0]}.{name}"
else:
continue
documented.add(f"{block}.{path}" if block else path)
return documented
def stable_exceptions() -> list[str]:
error_dir = PLATFORM / "api/error"
return sorted(
@@ -72,7 +156,7 @@ def violation_codes() -> list[str]:
def configuration_properties() -> list[str]:
"""Every leaf property under `app.httpclient`, nested and dynamic blocks included.
"""Every leaf property under `app.httpclient` as its full path, nested and dynamic blocks included.
Read from the environment-field manifest rather than from the record source. The manifest is
derived from `HttpClientPlatformSettings` and held to it in both directions by
@@ -87,16 +171,15 @@ def configuration_properties() -> list[str]:
if not stripped.startswith("- field:"):
continue
path = stripped[len("- field:") :].strip()
leaf = path.split(".")[-1]
# `clients[N]` and `allowed-hosts[M]` are documented by name, not by position.
names.add(re.sub(r"\[[NM]\]$", "", leaf))
# A list such as `allowed-hosts[M]` is documented by name, not by position.
names.add(re.sub(r"\[[NM]\]$", "", path))
return sorted(names)
def transports() -> list[str]:
source = (PLATFORM / "profile/TransportType.java").read_text(encoding="utf-8")
source = TRANSPORT_TYPE.read_text(encoding="utf-8")
body = source[source.index("public enum TransportType") :]
return sorted(set(re.findall(r"^\s{2}([A-Z][A-Z_]*),?$", body, flags=re.MULTILINE)))
return sorted(set(re.findall(r"^\s{2}([A-Z][A-Z0-9_]*),?$", body, flags=re.MULTILINE)))
def main() -> int:
@@ -106,19 +189,30 @@ def main() -> int:
return 1
documentation = read_docs()
reference = documented_properties(read_configuration_reference())
failures: list[str] = []
checks = {
"stable exception": stable_exceptions(),
"metric": metric_names(),
"startup violation code": violation_codes(),
"configuration property": configuration_properties(),
"transport": transports(),
# kind -> (names from the code, where they must appear, how to say where). A string is searched
# for the name; the configuration reference is a set of exact field paths.
checks: dict[str, tuple[list[str], str | set[str], str]] = {
"stable exception": (stable_exceptions(), documentation, ""),
"metric": (metric_names(), documentation, ""),
"startup violation code": (violation_codes(), documentation, ""),
"configuration property": (
configuration_properties(),
reference,
f" in a {CONFIGURATION_REFERENCE.name} table under its section",
),
"transport": (transports(), documentation, ""),
}
for kind, names in checks.items():
for kind, (names, documented, where) in checks.items():
if not names:
failures.append(
f"no {kind} found in the code: its extractor matched nothing, so none would be checked"
)
for name in names:
if name not in documentation:
failures.append(f"{kind} '{name}' exists in code but is not documented")
if name not in documented:
failures.append(f"{kind} '{name}' exists in code but is not documented{where}")
if failures:
print(f"FAIL httpclient documentation drift ({len(failures)} finding(s)):")
@@ -126,9 +220,9 @@ def main() -> int:
print(" - " + failure)
return 1
total = sum(len(names) for names in checks.values())
total = sum(len(names) for names, _, _ in checks.values())
print(f"PASS httpclient documentation covers {total} code-derived name(s):")
for kind, names in checks.items():
for kind, (names, _, _) in checks.items():
print(f" {kind}: {len(names)}")
return 0