"""상태 파일 (계획 2026-09-27 L6 §2.7 · D-L6-12). `///hook/.json`, 스키마 `STATUS_SCHEMA`(`solar-eval-hook/v1`), 원자적 쓰기(같은 디렉토리의 임시 파일 → fsync → `os.replace`). 키: `schema · run_id · project · case · command · started_at · finished_at · strict · legs{: {status, code, …detail}} · ok`(`ok` = 실패 다리 0). batch run 은 run 마다 번들 다리 결과로 먼저 쓰고, `hook.finish_batch` 가 끝 다리 결과로 `update_legs` 를 부른다. hub 대상이 아닌 run 은 상태 파일이 없다. 값은 코드·건수·id·시각만 — 다리의 `hint`(되살리기 문구)는 콘솔 몫이라 싣지 않고, 고객 텍스트·URL·예외 원문도 없다. 마지막 방어로 직렬화한 문서에 hub·레거시 DB URL 값이 들어 있으면 쓰지 않고 `ValueError`(값은 문구에 싣지 않는다, D-L6-4). 환경 변수 값만으로는 설정 파일 `hub.database_url` 값을 모르므로 호출자가 `secrets=`(`optin.config_secrets`)로 넘긴다 — 그 값도 같은 규칙으로 거부·가린다(계획 2026-09-28 L10 §2.6 "비밀" · 검토 F1-4). 쓰기 실패는 hook 이 콘솔 경고로 강등한다(D-L6-2) — 이 모듈은 예외를 그대로 낸다. """ from __future__ import annotations import json import os import re import tempfile from collections.abc import Mapping, Sequence from pathlib import Path from typing import Any from solar_eval.hub_hook.optin import ENV_HUB_DATABASE_URL from solar_eval.hub_hook.types import ( HOOK_DIRNAME, STATUS_FAILED, STATUS_SCHEMA, Command, HookResult, LegResult, Target, ) #: 문서에 값이 새면 안 되는 환경 변수(자격증명을 담은 URL). # 옛 이름(EVALHUB_DATABASE_URL)은 더 이상 읽지 않지만, 개명 전 셸에 남아 있을 수 있어 값이 새지 않게 계속 가린다. SECRET_ENV_NAMES = (ENV_HUB_DATABASE_URL, "EXPERIMENT_HUB_DATABASE_URL", "EVALHUB_DATABASE_URL") #: 이보다 짧은 값은 우연히 겹칠 수 있어 검사하지 않는다(URL 은 이보다 길다). MIN_SECRET_LENGTH = 8 #: 파일 이름이 되는 run_id — 경로 구분자·제어 문자·`.`/`..` 금지. _UNSAFE_RUN_ID = re.compile(r"[/\\\x00-\x1f\x7f]") #: 임시 파일 이름은 run_id 에 기대지 않는다 — `.json` 이 이름 한도(255바이트) 안이어도 `..json.XXXX.tmp` #: 는 넘칠 수 있다(리뷰 지적 1 — 237~250바이트 run_id 에서 ENAMETOOLONG). _TMP_PREFIX = ".hook-" _TMP_SUFFIX = ".tmp" #: URL 의 `사용자:비밀번호@` — 비밀번호 자리만 가린다. _URL_PASSWORD = re.compile(r"(?P[A-Za-z][A-Za-z0-9+.-]*://[^\s:/@]*:)[^\s@]*@") _REDACTED = "***" #: 설정 출처 비밀의 이름표 — 거부 문구·가림 자리에 값 대신 싣는다. CONFIG_SECRET_LABEL = "hub.database_url" def status_path(target: Target, run_id: str) -> Path: """`///hook/.json`. run_id 가 파일 이름으로 안전하지 않으면 `ValueError`.""" from poc_bundle.home import hub_reports_dir _check_run_id(run_id) return hub_reports_dir() / target.account / target.case / HOOK_DIRNAME / f"{run_id}.json" def _check_run_id(run_id: str) -> None: if not isinstance(run_id, str) or run_id in ("", ".", "..") or _UNSAFE_RUN_ID.search(run_id): raise ValueError("hook status: run_id is not a safe file name") def leg_document(leg: LegResult) -> dict[str, Any]: """다리 하나 → `{status, code, …detail}`. detail 이 `status`·`code` 를 덮지 못한다. hint 는 싣지 않는다.""" return {**dict(leg.detail), "status": leg.status, "code": leg.code} def _ok(legs: Mapping[str, Mapping[str, Any]]) -> bool: return all(leg.get("status") != STATUS_FAILED for leg in legs.values()) def status_document( target: Target, result: HookResult, command: Command, *, strict: bool ) -> dict[str, Any]: """상태 파일 문서(순수).""" legs = {name: leg_document(leg) for name, leg in result.legs.items()} return { "schema": STATUS_SCHEMA, "run_id": result.run_id, "project": target.project, "case": target.case_ref, "command": command, "started_at": result.started_at, "finished_at": result.finished_at, "strict": bool(strict), "legs": legs, "ok": _ok(legs), } def write_status( target: Target, result: HookResult, command: Command, *, strict: bool, secrets: Sequence[str] = (), ) -> Path: """run 하나의 훅 결과를 원자적으로 쓰고 경로를 돌려준다(같은 run 은 덮어쓴다). `secrets` = 설정 출처 비밀(거부 목록).""" path = status_path(target, result.run_id) _atomic_write(path, status_document(target, result, command, strict=strict), secrets) return path def update_legs( target: Target, run_id: str, legs: Mapping[str, LegResult], *, secrets: Sequence[str] = (), ) -> None: """이미 있는 상태 파일의 다리 몇 개를 원자적으로 바꿔 쓰고 `ok` 를 다시 센다(batch 끝 hub 다리, D-L6-12). 파일이 없으면 `FileNotFoundError`, 스키마나 run_id 가 다르면 `ValueError` — 호출자(hook)가 경고로 강등한다. """ path = status_path(target, run_id) doc = json.loads(path.read_text("utf-8")) if ( not isinstance(doc, dict) or doc.get("schema") != STATUS_SCHEMA or doc.get("run_id") != run_id ): raise ValueError(f"hook status: {path.name} is not a {STATUS_SCHEMA} file for this run") current = doc.get("legs") merged = dict(current) if isinstance(current, dict) else {} merged.update({name: leg_document(leg) for name, leg in legs.items()}) _atomic_write(path, {**doc, "legs": merged, "ok": _ok(merged)}, secrets) def _atomic_write(path: Path, doc: Mapping[str, Any], secrets: Sequence[str] = ()) -> None: """직렬화·비밀 검사 → 같은 디렉토리 임시 파일 → fsync → `os.replace`. 실패하면 임시 파일을 지우고 다시 낸다.""" text = json.dumps(doc, ensure_ascii=False, indent=2) + "\n" _refuse_secrets(text, secrets) path.parent.mkdir(parents=True, exist_ok=True) fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=_TMP_PREFIX, suffix=_TMP_SUFFIX) tmp = Path(tmp_name) try: with os.fdopen(fd, "w", encoding="utf-8") as fh: fh.write(text) fh.flush() os.fsync(fh.fileno()) os.replace(tmp, path) except BaseException: tmp.unlink(missing_ok=True) raise def _secret_values(extra: Sequence[str] = ()) -> list[tuple[str, str]]: """(이름표, 값) — 환경 변수 값 + 설정 출처 값(`extra`, 이름표 `hub.database_url`). 검사할 만큼 긴 값만.""" pairs = [(name, os.environ.get(name, "").strip()) for name in SECRET_ENV_NAMES] pairs += [(CONFIG_SECRET_LABEL, value.strip()) for value in extra if isinstance(value, str)] return [(name, value) for name, value in pairs if len(value) >= MIN_SECRET_LENGTH] def _refuse_secrets(text: str, extra: Sequence[str] = ()) -> None: for name, value in _secret_values(extra): if value in text: raise ValueError(f"hook status: refusing to store the value of {name}") def _mask_url_password(text: str) -> str: return _URL_PASSWORD.sub(lambda m: f"{m.group('head')}{_REDACTED}@", text) def _whole_value_replacement(name: str, value: str) -> str: """알려진 비밀 값 하나를 무엇으로 바꿀까. 비밀이 비밀번호 자리뿐이면(쿼리·조각 없음) 비밀번호만 가린 URL — 호스트·DB 이름이 진단에 남는다. 그 밖(쿼리 문자열 비밀번호 등 — 어디가 비밀인지 모른다)은 통째로 `<이름표>`.""" masked = _mask_url_password(value) only_password = masked != value and "?" not in value and "#" not in value return masked if only_password else f"<{name}>" def redact_secrets(text: str, extra: Sequence[str] = ()) -> str: """콘솔에 옮기는 외부 출력(hub CLI stderr)에서 비밀을 가린다(리뷰 지적 6). **알려진 값을 먼저**(리뷰 L10 지적 4): `SECRET_ENV_NAMES` 값이나 설정 출처 값(`extra`)이 통째로 있으면 `_whole_value_replacement` 로 바꾸고, hub CLI `redactUrl` 이 비밀번호만 가린 모양(`u:***@…?sslpassword=…`)으로 있어도 같은 이름표로 바꾼다. 그 **뒤에** 남은 모르는 URL 의 비밀번호 자리를 `***` 로(`redactUrl` 과 같은 모양 — 호스트·DB 이름은 진단에 남는다). 순서가 거꾸로면 비밀번호를 가린 순간 값이 통째로 맞지 않아 쿼리 비밀이 샌다. 상태 파일은 이 함수를 쓰지 않는다 — 거기에는 외부 출력을 아예 싣지 않는다(`_refuse_secrets` 가 마지막 방어). """ for name, value in _secret_values(extra): replacement = _whole_value_replacement(name, value) text = text.replace(value, replacement) masked = _mask_url_password(value) if masked not in (value, replacement): text = text.replace(masked, replacement) return _mask_url_password(text)