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를 본다.
268 lines
9.0 KiB
Python
268 lines
9.0 KiB
Python
"""scripts/verify-httpclient-docs.py의 시험. 코드의 이름이 문서에서 빠지면 실패하는지 본다.
|
|
|
|
python3 -m unittest discover -s scripts/tests
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import importlib.util
|
|
import io
|
|
import sys
|
|
import tempfile
|
|
import unittest
|
|
from contextlib import redirect_stdout
|
|
from pathlib import Path
|
|
|
|
SCRIPTS = Path(__file__).resolve().parent.parent
|
|
_spec = importlib.util.spec_from_file_location("verify_httpclient_docs", SCRIPTS / "verify-httpclient-docs.py")
|
|
verify_httpclient_docs = importlib.util.module_from_spec(_spec)
|
|
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, "")
|
|
|
|
# when
|
|
rc, output = run_main()
|
|
|
|
# then
|
|
self.assertEqual(rc, 1)
|
|
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__":
|
|
unittest.main()
|