Files
clean-architecture-backend-…/scripts/verify-httpclient-docs.py
DongHyeonka ea25f624b2
pr / done (pull_request) Canceled after 0s
fix(scripts)!: httpclient 문서 검사가 설정 필드를 절과 표 위치로 대조한다
verify-httpclient-docs.py는 manifest 필드를 마지막 마디로 줄이고
(clients[N].tls.enabled → enabled) 아홉 문서를 이은 글에서 부분 문자열로
찾는다. 마지막 마디가 겹치는 이름이 여섯 종(enabled 셋, name, type,
protocols, allowed-hosts, allowed-ports)이라 그 이름의 새 필드는 문서 없이
통과한다. 「지운 설정」 표에만 적힌 key도 통과한다. 다섯 종류 추출 어느
것도 0개를 실패로 보지 않고, transport 정규식은 숫자를 빼서 HTTP3 꼴
상수를 뽑지 못한다.

설정 필드는 configuration-reference.md의 속성 표(머리 첫 칸 「속성」)를
제목과 첫 칸으로 읽어(documented_properties) 전체 경로로 대조한다. ##
제목의 app.httpclient.<block>이 블록, ### 제목의 코드 표기가 묶음이다.
지운 key 표·설명 표와 코드 블록 안 표는 세지 않는다. manifest 필드는 끝
[N]·[M]만 뗀다. 종류마다 0개면 실패하고, transport 정규식에 숫자를
넣었다. 이 대조로 처음 드러난 최상위 rotation-drain-timeout 행을 설정
참조에 더했다. 버린 안: 마지막 두 마디 대조. 표가 절 아래 leaf만 적어서
51개 필드의 두 마디가 문서에 같이 나오지 않아, 문서 표 형식부터 바꿔야
했다.

위험: 설정 필드는 이제 configuration-reference.md 속성 표에 있어야 한다.
다른 여덟 문서에만 있으면 실패다. 나머지 네 종류는 전처럼 부분 문자열로
찾는다. 실제 트리 대조는 여전히 release job에서만 돈다. 시험은 고정
설정 참조와 manifest를 써서 실제 트리에 필드를 더해도 빨개지지 않는다.

검증: 새 시험을 main 판 검사기에 얹어 FAIL 4·ERROR 1(새 필드·속성 표
밖 key·빈 manifest·숫자 transport가 rc=0으로 통과, 파서 시험은 함수
없음). 고친 뒤 python3 -m unittest discover -s scripts/tests OK(313),
python3 scripts/verify-httpclient-docs.py rc=0(설정 필드 74, 문서 쪽
남는 경로 0), 검사기 변이 15개 중 14개를 시험이 잡고 1개는 등가,
check-docs.py·check-work-docs.py rc=0.

Refs: REV-BE-0013
BREAKING CHANGE: app.httpclient 필드를 더한 파생 서비스는 그 필드를
  configuration-reference.md의 자기 절 속성 표에 적어야 release 문서
  검사를 통과한다. docs/upgrade/2026-11-httpclient-docs-check.md를 본다.
2026-11-22 03:11:04 +09:00

232 lines
9.4 KiB
Python
Executable File

#!/usr/bin/env python3
"""Fail when the HTTP Client Platform's code and documentation have drifted.
Called by: the release workflow (`.gitea/workflows/release.yml`, job `httpclient-documentation`).
The design (§33 "Documentation") requires the support matrix, configuration reference, security
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. 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.
"""
from __future__ import annotations
import re
import sys
from pathlib import Path
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",
"configuration-reference.md",
"retry-and-ambiguity.md",
"security.md",
"streaming.md",
"operations.md",
"release-checklist.md",
"performance-baseline.md",
"repository-adaptation.md",
]
def read_docs() -> str:
return "\n".join(
(DOCS_DIR / name).read_text(encoding="utf-8") for name in REQUIRED_DOCS
)
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(
path.stem
for path in error_dir.glob("Http*Exception.java")
if path.stem != "HttpClientException"
)
def metric_names() -> list[str]:
source = (PLATFORM / "observation/HttpClientObservationNames.java").read_text(encoding="utf-8")
return sorted(set(re.findall(r'"(http\.client\.[a-z_.]+)"', source)))
def violation_codes() -> list[str]:
codes: set[str] = set()
for source_file in [
PLATFORM / "profile/ClientProfileValidator.java",
PLATFORM / "security/TlsPolicyValidator.java",
# The startup validator moved from app-bootstrap into the leaf; the old path made this
# script fail on a missing file before it checked anything.
PLATFORM / "autoconfigure/HttpClientStartupValidator.java",
]:
source = source_file.read_text(encoding="utf-8")
codes.update(re.findall(r'"([A-Z][A-Z0-9_]{4,})"', source))
return sorted(codes)
def configuration_properties() -> list[str]:
"""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
`HttpClientPlatformEnvManifestTest`, so it cannot drift from the code; parsing the
record here a second time, with a regex, could only agree with it by luck. The previous version
of this function did exactly that and saw eighteen top-level names, which is why a nested pool,
timeout or TLS setting could be added and documented nowhere.
"""
names: set[str] = set()
for line in ENV_FIELD_MANIFEST.read_text(encoding="utf-8").splitlines():
stripped = line.strip()
if not stripped.startswith("- field:"):
continue
path = stripped[len("- field:") :].strip()
# 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 = 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-Z0-9_]*),?$", body, flags=re.MULTILINE)))
def main() -> int:
missing_docs = [name for name in REQUIRED_DOCS if not (DOCS_DIR / name).is_file()]
if missing_docs:
print("FAIL missing documentation file(s): " + ", ".join(missing_docs))
return 1
documentation = read_docs()
reference = documented_properties(read_configuration_reference())
failures: list[str] = []
# 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, 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 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)):")
for failure in failures:
print(" - " + failure)
return 1
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():
print(f" {kind}: {len(names)}")
return 0
if __name__ == "__main__":
sys.exit(main())