diff --git a/docs/httpclient/configuration-reference.md b/docs/httpclient/configuration-reference.md index 340573a2..f9c77b28 100644 --- a/docs/httpclient/configuration-reference.md +++ b/docs/httpclient/configuration-reference.md @@ -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는 환경 변수 이름의 한 조각이 diff --git a/docs/upgrade/2026-11-httpclient-docs-check.md b/docs/upgrade/2026-11-httpclient-docs-check.md new file mode 100644 index 00000000..544ec7ef --- /dev/null +++ b/docs/upgrade/2026-11-httpclient-docs-check.md @@ -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은 그대로다. +- 검사는 한 방향이다. 문서에 있지만 코드에 없는 이름은 실패가 아니다. diff --git a/scripts/tests/test_verify_httpclient_docs.py b/scripts/tests/test_verify_httpclient_docs.py index 58ae01b3..961b2347 100644 --- a/scripts/tests/test_verify_httpclient_docs.py +++ b/scripts/tests/test_verify_httpclient_docs.py @@ -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__": diff --git a/scripts/verify-httpclient-docs.py b/scripts/verify-httpclient-docs.py index 10644295..f0846b69 100755 --- a/scripts/verify-httpclient-docs.py +++ b/scripts/verify-httpclient-docs.py @@ -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.` 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.` 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