pr / done (pull_request) Canceled after 0s
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를 본다.
232 lines
9.4 KiB
Python
Executable File
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())
|