From f889b6d073463ffa8f77cb234ea6267aabe98bf2 Mon Sep 17 00:00:00 2001 From: exijn Date: Tue, 10 Nov 2026 20:46:50 +0900 Subject: [PATCH] =?UTF-8?q?feat(ops):=20=EC=9B=90=ED=81=B4=EB=A6=AD=20?= =?UTF-8?q?=ED=96=89=EC=82=AC=20=EC=8B=9C=EC=9E=91=20=EC=8A=A4=ED=81=AC?= =?UTF-8?q?=EB=A6=BD=ED=8A=B8=EC=99=80=20Restart=3Dno=20drop-in=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - scripts/event_start.py: 상태 확인 → reset-failed/start → Restart=no drop-in → 로봇 늦은 기동 대기 → 승인 만료 검사 → 대기 실행 정리 확인 → 켜기 → 한 줄 결과. 기본 dry-run, --execute 필요. - deploy/systemd/poppy-agent.service.d/10-event-no-restart.conf, docs/event-start.md - fake runner/스냅샷 테스트 15개 Closes #100 Co-Authored-By: Claude Opus 5.5 --- .../10-event-no-restart.conf | 5 + docs/event-start.md | 42 +++ scripts/event_start.py | 307 ++++++++++++++++++ tests/test_event_start.py | 219 +++++++++++++ 4 files changed, 573 insertions(+) create mode 100644 deploy/systemd/poppy-agent.service.d/10-event-no-restart.conf create mode 100644 docs/event-start.md create mode 100644 scripts/event_start.py create mode 100644 tests/test_event_start.py diff --git a/deploy/systemd/poppy-agent.service.d/10-event-no-restart.conf b/deploy/systemd/poppy-agent.service.d/10-event-no-restart.conf new file mode 100644 index 0000000..104d169 --- /dev/null +++ b/deploy/systemd/poppy-agent.service.d/10-event-no-restart.conf @@ -0,0 +1,5 @@ +# 행사 운영용 drop-in (#100). /etc/systemd/system/poppy-agent.service.d/ 에 설치되어 재부팅 뒤에도 유지된다. +# 비정상 종료 뒤 자동 재시작으로 실제 동작이 다시 켜지지 않게 한다. 재시작은 운영자가 +# scripts/event_start.py 로 상태를 확인하며 한다. +[Service] +Restart=no diff --git a/docs/event-start.md b/docs/event-start.md new file mode 100644 index 0000000..42c9940 --- /dev/null +++ b/docs/event-start.md @@ -0,0 +1,42 @@ +# 원클릭 행사 시작 (`scripts/event_start.py`, #100) + +운영 노트북에서 운영자가 TTY 로 실행한다. AI 에이전트는 dry-run 과 fake 테스트만 수행한다. + +## 순서 + +1. `systemctl show poppy-agent` 로 상태 확인 → `failed` 면 `reset-failed` + `start`, `inactive` 면 `start`, + `active` 면 그대로. 그 밖의 상태는 FAIL(수동 확인). +2. `deploy/systemd/poppy-agent.service.d/10-event-no-restart.conf`(`Restart=no`)가 + `/etc/systemd/system/poppy-agent.service.d/` 에 없거나 다르면 설치 후 `daemon-reload`. 디스크의 drop-in + 이라 재부팅 뒤에도 유지된다. 비정상 종료 뒤 자동 재시작으로 실제 동작이 다시 켜지지 않게 한다. +3. 로봇 늦은 기동 대기: `/run/poppy-agent/status.json` 의 `lifecycleState=READY` 와 `telemetry.fresh=true` + 를 `--poll-seconds`(기본 5 s) 간격으로 `--wait-seconds`(기본 180 s)까지 재시도. +4. 승인 만료 검사: `TRIAL_EXPIRED`, `EXPIRES_AT` 설정 오류, 남은 시간 30분 이하면 FAIL. 만료 시각을 + 바꾸거나 우회하지 않는다(교사 승인 갱신 후 켜기 스크립트가 새 만료 시각을 쓴다). +5. 오래된 대기 실행 정리 확인: Server 쪽 정리(Poppy-Server#132) 후 운영자가 `--queue-cleared` 를 줘야 + 다음 단계로 간다. +6. 켜기: `--switch-command '<켜기 스크립트> on'` 을 실행하고 `physicalExecution.state=READY` 까지 대기. + 지정하지 않으면 `MANUAL` 로 끝난다. + +마지막 줄은 한 줄 결과다: `OK: ...`, `DRY-RUN OK: ...`, `MANUAL: ...`, `FAIL: <원인과 조치>`. +FAIL 이면 exit code 1. + +## 사용 + +```bash +# 기본은 dry-run: 아무 명령도 실행하지 않고 출력만 한다 +python3 scripts/event_start.py --queue-cleared --switch-command '<켜기 스크립트> on' + +# 실제 실행(운영자) +python3 scripts/event_start.py --execute --queue-cleared --switch-command '<켜기 스크립트> on' +``` + +dry-run 은 `--simulate-state failed|inactive|active`, `--simulate-drop-in` 으로 가정 상태를 바꿀 수 있고, +`--status-path` 로 fixture 스냅샷을 줄 수 있다. + +## 한계 + +- EnvironmentFile 은 읽지 않는다. physical off 상태에서는 만료 시각이 스냅샷에 없으므로 승인 검사는 + 켜기 스크립트와 켜기 후 READY 확인에 맡긴다. +- 대기 실행 정리는 Server API 계약이 정해지지 않아(Poppy-Server#132) 운영자 확인 플래그로 대신한다. +- `Restart=no` 이므로 Agent 가 죽으면 이 스크립트를 다시 실행해 상태를 확인하며 시작한다. diff --git a/scripts/event_start.py b/scripts/event_start.py new file mode 100644 index 0000000..e88fbbb --- /dev/null +++ b/scripts/event_start.py @@ -0,0 +1,307 @@ +"""One-command event start for the operator laptop (#100). + +Order: service state -> reset-failed/start (physical execution stays as configured) +-> persistent ``Restart=no`` drop-in -> wait for a late Robot (fresh telemetry) +-> approval expiry check -> stale pending Execution check -> switch on -> READY. +The last line printed is a one-line summary for the operator. + +Safety: +- The default is a dry run: every command is printed and nothing is executed. + ``--execute`` is required to touch systemd or run the switch command. +- The approval expiry is only checked, never extended or bypassed. An expired or + soon-expiring approval stops the script before the switch. +- Physical execution is switched on only after the operator confirms the stale + pending Executions are cleared (``--queue-cleared``; Poppy-Server#132). +- This script sends no Robot command and does not read the EnvironmentFile; it + reads only the secret-free status snapshot (``POPPY_RUNTIME_STATUS_PATH``). +""" + +from __future__ import annotations + +import argparse +import json +import shlex +import subprocess +import sys +import time +from collections.abc import Callable, Sequence +from dataclasses import dataclass, field +from datetime import UTC, datetime, timedelta +from pathlib import Path + +UNIT = "poppy-agent" +STATUS_PATH = Path("/run/poppy-agent/status.json") +DROP_IN_NAME = "10-event-no-restart.conf" +DROP_IN_SOURCE = ( + Path(__file__).resolve().parents[1] / "deploy" / "systemd" / "poppy-agent.service.d" +) +DROP_IN_DIR = Path("/etc/systemd/system/poppy-agent.service.d") +MIN_APPROVAL_REMAINING = timedelta(minutes=30) + + +class StepFailed(RuntimeError): + """A step that must stop the start sequence; the message is the summary.""" + + +@dataclass(frozen=True, slots=True) +class CommandResult: + returncode: int + stdout: str = "" + + +Runner = Callable[[Sequence[str]], CommandResult] + + +@dataclass +class Report: + steps: list[tuple[str, str]] = field(default_factory=list) + + def add(self, step: str, outcome: str) -> None: + self.steps.append((step, outcome)) + print(f"[{step}] {outcome}", flush=True) + + +def subprocess_runner(command: Sequence[str]) -> CommandResult: + completed = subprocess.run( # noqa: S603 - fixed argument lists only + list(command), capture_output=True, text=True, check=False, timeout=60 + ) + return CommandResult(completed.returncode, completed.stdout) + + +class DryRunRunner: + """Print commands instead of running them; answers come from a simulated state.""" + + def __init__(self, simulated_active_state: str, drop_in_present: bool) -> None: + self.active_state = simulated_active_state + self.drop_in_present = drop_in_present + self.commands: list[list[str]] = [] + + def __call__(self, command: Sequence[str]) -> CommandResult: + self.commands.append(list(command)) + print(f" (dry-run) {shlex.join(command)}", flush=True) + if list(command[:2]) == ["systemctl", "show"]: + return CommandResult(0, f"ActiveState={self.active_state}\n") + if list(command[:1]) == ["cmp"]: + return CommandResult(0 if self.drop_in_present else 1) + if list(command[:3]) in ( + ["sudo", "systemctl", "start"], + ["sudo", "systemctl", "restart"], + ): + self.active_state = "active" + return CommandResult(0) + + +def parse_properties(text: str) -> dict[str, str]: + properties: dict[str, str] = {} + for line in text.splitlines(): + key, sep, value = line.partition("=") + if sep: + properties[key.strip()] = value.strip() + return properties + + +def read_status(path: Path) -> dict[str, object] | None: + try: + loaded = json.loads(path.read_text(encoding="utf-8")) + except (OSError, ValueError): + return None + return loaded if isinstance(loaded, dict) else None + + +def _physical(status: dict[str, object]) -> dict[str, object]: + physical = status.get("physicalExecution") + return physical if isinstance(physical, dict) else {} + + +def telemetry_fresh(status: dict[str, object]) -> bool: + telemetry = status.get("telemetry") + return isinstance(telemetry, dict) and telemetry.get("fresh") is True + + +def approval_expires_at(status: dict[str, object]) -> datetime | None: + trial = _physical(status).get("trial") + if not isinstance(trial, dict): + return None + raw = trial.get("expiresAt") + if not isinstance(raw, str): + return None + try: + parsed = datetime.fromisoformat(raw) + except ValueError: + return None + return parsed if parsed.tzinfo is not None else None + + +def check_approval(status: dict[str, object], now: datetime, minimum: timedelta) -> str: + """Return a description of the approval window or raise ``StepFailed``.""" + physical = _physical(status) + reasons = physical.get("reasons") + issues = physical.get("configIssues") + if isinstance(reasons, list) and "TRIAL_EXPIRED" in reasons: + raise StepFailed( + "승인 만료(TRIAL_EXPIRED): 교사 승인 갱신 후 켜기 스크립트로 새 만료 시각 설정" + ) + if isinstance(issues, list) and any("EXPIRES_AT" in str(issue) for issue in issues): + raise StepFailed( + "승인 만료 시각 설정 오류: 교사 승인 갱신 후 켜기 스크립트로 새 만료 시각 설정" + ) + expires = approval_expires_at(status) + if expires is None: + # Physical execution is still off, so the window is checked by the switch. + return "만료 시각 미표시(physical off) — 켜기 단계에서 확인" + remaining = expires - now + if remaining <= minimum: + minutes = max(0, int(remaining.total_seconds() // 60)) + raise StepFailed(f"승인 만료 임박(남은 {minutes}분): 교사 승인 갱신 필요") + return f"승인 유효(남은 {int(remaining.total_seconds() // 60)}분)" + + +@dataclass +class EventStart: + runner: Runner + status_path: Path + execute: bool + queue_cleared: bool + switch_command: list[str] | None + wait_seconds: float + poll_seconds: float + now: Callable[[], datetime] = lambda: datetime.now(UTC) + sleep: Callable[[float], None] = time.sleep + monotonic: Callable[[], float] = time.monotonic + status_reader: Callable[[Path], dict[str, object] | None] = read_status + report: Report = field(default_factory=Report) + + def run(self) -> str: + try: + self._service() + self._drop_in() + status = self._wait_for( + "로봇 텔레메트리", + lambda s: s.get("lifecycleState") == "READY" and telemetry_fresh(s), + "로봇 미기동 또는 텔레메트리 없음: 로봇 전원·유선 연결 확인 후 다시 실행", + ) + self.report.add("승인", check_approval(status, self.now(), MIN_APPROVAL_REMAINING)) + self._queue() + self._switch_on() + except StepFailed as exc: + return f"FAIL: {exc}" + if self.switch_command is None: + return "MANUAL: 서비스·로봇 준비 완료, 켜기 명령을 직접 실행 (--switch-command 미지정)" + if not self.execute: + return "DRY-RUN OK: 실제 실행은 --execute" + return "OK: 실제 동작 READY" + + def _service(self) -> None: + shown = self.runner(["systemctl", "show", UNIT, "-p", "ActiveState,Result,NRestarts"]) + state = parse_properties(shown.stdout).get("ActiveState", "unknown") + if state == "failed": + self._mutate(["sudo", "systemctl", "reset-failed", UNIT]) + self._mutate(["sudo", "systemctl", "start", UNIT]) + self.report.add("서비스", "failed → reset-failed → start") + elif state in {"inactive", "unknown"}: + self._mutate(["sudo", "systemctl", "start", UNIT]) + self.report.add("서비스", f"{state} → start") + elif state in {"active", "activating", "reloading"}: + self.report.add("서비스", f"{state} (변경 없음)") + else: + raise StepFailed(f"서비스 상태 {state}: 수동 확인 필요") + + def _drop_in(self) -> None: + source = DROP_IN_SOURCE / DROP_IN_NAME + target = DROP_IN_DIR / DROP_IN_NAME + same = self.runner(["cmp", "-s", str(source), str(target)]) + if same.returncode == 0: + self.report.add("Restart=no", "설치됨") + return + self._mutate(["sudo", "install", "-D", "-m", "644", str(source), str(target)]) + self._mutate(["sudo", "systemctl", "daemon-reload"]) + self.report.add("Restart=no", "drop-in 설치 → daemon-reload (재부팅 후 유지)") + + def _queue(self) -> None: + if not self.queue_cleared: + raise StepFailed( + "대기 실행 정리 미확인: Server 에서 오래된 대기 실행 정리 후 " + "--queue-cleared 로 재실행" + ) + self.report.add("대기 실행", "운영자 정리 확인") + + def _switch_on(self) -> None: + if self.switch_command is None: + self.report.add("켜기", "건너뜀(수동)") + return + result = self._mutate(self.switch_command) + if result.returncode != 0: + raise StepFailed(f"켜기 명령 실패(exit {result.returncode})") + if not self.execute: + self.report.add("켜기", "dry-run") + return + self._wait_for( + "READY", + lambda s: _physical(s).get("state") == "READY", + "켜기 후 READY 아님: status.json 의 physicalExecution.reasons 확인", + ) + self.report.add("켜기", "READY") + + def _mutate(self, command: Sequence[str]) -> CommandResult: + return self.runner(command) + + def _wait_for( + self, + name: str, + ready: Callable[[dict[str, object]], bool], + failure: str, + ) -> dict[str, object]: + deadline = self.monotonic() + self.wait_seconds + attempts = 0 + while True: + attempts += 1 + status = self.status_reader(self.status_path) + if status is not None and ready(status): + self.report.add(name, f"확인({attempts}회)") + return status + if self.monotonic() >= deadline: + raise StepFailed(failure) + self.sleep(self.poll_seconds) + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument("--execute", action="store_true", help="actually run commands") + parser.add_argument("--status-path", type=Path, default=STATUS_PATH) + parser.add_argument("--queue-cleared", action="store_true") + parser.add_argument("--switch-command", help="operator switch-on command, e.g. ' on'") + parser.add_argument("--wait-seconds", type=float, default=180.0) + parser.add_argument("--poll-seconds", type=float, default=5.0) + parser.add_argument( + "--simulate-state", + default="failed", + choices=["failed", "inactive", "active"], + help="dry-run only: assumed service ActiveState", + ) + parser.add_argument("--simulate-drop-in", action="store_true", help="dry-run only") + return parser + + +def main(argv: Sequence[str] | None = None) -> int: + args = build_parser().parse_args(argv) + runner: Runner = ( + subprocess_runner + if args.execute + else DryRunRunner(args.simulate_state, args.simulate_drop_in) + ) + starter = EventStart( + runner=runner, + status_path=args.status_path, + execute=args.execute, + queue_cleared=args.queue_cleared, + switch_command=shlex.split(args.switch_command) if args.switch_command else None, + wait_seconds=args.wait_seconds, + poll_seconds=args.poll_seconds, + ) + summary = starter.run() + print(summary, flush=True) + return 1 if summary.startswith("FAIL") else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/test_event_start.py b/tests/test_event_start.py new file mode 100644 index 0000000..b4c68f9 --- /dev/null +++ b/tests/test_event_start.py @@ -0,0 +1,219 @@ +"""scripts/event_start.py with fake runners and status snapshots only (#100).""" + +from __future__ import annotations + +import importlib.util +import sys +from collections.abc import Sequence +from datetime import UTC, datetime, timedelta +from pathlib import Path + +import pytest + +ROOT = Path(__file__).resolve().parents[1] +SPEC = importlib.util.spec_from_file_location("event_start", ROOT / "scripts" / "event_start.py") +assert SPEC is not None and SPEC.loader is not None +event_start = importlib.util.module_from_spec(SPEC) +sys.modules["event_start"] = event_start +SPEC.loader.exec_module(event_start) + +NOW = datetime(2026, 11, 12, 9, 0, tzinfo=UTC) +SWITCH = ["/operator/switch.sh", "on"] + + +def snapshot( + *, + fresh: bool = True, + lifecycle: str = "READY", + physical_state: str = "NOT_READY", + expires: datetime | None = NOW + timedelta(hours=2), + reasons: list[str] | None = None, + issues: list[str] | None = None, +) -> dict[str, object]: + trial = {} if expires is None else {"expiresAt": expires.isoformat()} + return { + "lifecycleState": lifecycle, + "telemetry": {"fresh": fresh, "batteryPercent": 80, "receivedAt": NOW.isoformat()}, + "physicalExecution": { + "state": physical_state, + "reasons": reasons or [], + "configIssues": issues or [], + "trial": trial, + }, + } + + +class FakeRunner: + def __init__(self, active_state: str = "failed", drop_in: bool = True) -> None: + self.active_state = active_state + self.drop_in = drop_in + self.commands: list[list[str]] = [] + self.switch_exit = 0 + self.on_switch: list[dict[str, object]] | None = None + + def __call__(self, command: Sequence[str]) -> event_start.CommandResult: + self.commands.append(list(command)) + if command[:2] == ["systemctl", "show"]: + return event_start.CommandResult(0, f"ActiveState={self.active_state}\nResult=x\n") + if command[0] == "cmp": + return event_start.CommandResult(0 if self.drop_in else 1) + if list(command) == SWITCH: + return event_start.CommandResult(self.switch_exit) + return event_start.CommandResult(0) + + +class Clock: + def __init__(self) -> None: + self.t = 0.0 + + def monotonic(self) -> float: + return self.t + + def sleep(self, seconds: float) -> None: + self.t += seconds + + +def starter( + runner: FakeRunner, + statuses: list[dict[str, object] | None], + *, + execute: bool = True, + queue_cleared: bool = True, + switch: list[str] | None = SWITCH, +) -> event_start.EventStart: + clock = Clock() + queue = list(statuses) + + def reader(_path: Path) -> dict[str, object] | None: + return queue.pop(0) if len(queue) > 1 else queue[0] + + return event_start.EventStart( + runner=runner, + status_path=Path("/nonexistent/status.json"), + execute=execute, + queue_cleared=queue_cleared, + switch_command=switch, + wait_seconds=30, + poll_seconds=5, + now=lambda: NOW, + sleep=clock.sleep, + monotonic=clock.monotonic, + status_reader=reader, + ) + + +def test_failed_service_is_reset_started_and_switched_on_in_order() -> None: + runner = FakeRunner("failed") + summary = starter(runner, [snapshot(), snapshot(physical_state="READY")]).run() + + assert summary == "OK: 실제 동작 READY" + mutating = [c for c in runner.commands if c[0] != "systemctl" and c[0] != "cmp"] + assert mutating == [ + ["sudo", "systemctl", "reset-failed", "poppy-agent"], + ["sudo", "systemctl", "start", "poppy-agent"], + SWITCH, + ] + + +def test_active_service_is_left_alone() -> None: + runner = FakeRunner("active") + starter(runner, [snapshot(), snapshot(physical_state="READY")]).run() + assert not any(c[:2] == ["sudo", "systemctl"] for c in runner.commands) + + +def test_missing_drop_in_is_installed_and_reloaded() -> None: + runner = FakeRunner("active", drop_in=False) + starter(runner, [snapshot(), snapshot(physical_state="READY")]).run() + install = [c for c in runner.commands if c[:2] == ["sudo", "install"]] + assert install and install[0][-1].endswith("poppy-agent.service.d/10-event-no-restart.conf") + assert ["sudo", "systemctl", "daemon-reload"] in runner.commands + + +def test_late_robot_is_waited_for_then_proceeds() -> None: + runner = FakeRunner("active") + stale = snapshot(fresh=False) + summary = starter( + runner, [None, stale, stale, snapshot(), snapshot(physical_state="READY")] + ).run() + assert summary.startswith("OK") + + +def test_robot_that_never_appears_fails_before_switch() -> None: + runner = FakeRunner("active") + summary = starter(runner, [snapshot(fresh=False)]).run() + assert summary.startswith("FAIL: 로봇 미기동") + assert SWITCH not in runner.commands + + +@pytest.mark.parametrize( + "status", + [ + snapshot(reasons=["TRIAL_EXPIRED"]), + snapshot(issues=["POPPY_PHYSICAL_TRIAL_EXPIRES_AT is not in the future"]), + snapshot(expires=NOW + timedelta(minutes=10)), + snapshot(expires=NOW - timedelta(minutes=1)), + ], +) +def test_expired_or_expiring_approval_stops_before_switch(status: dict[str, object]) -> None: + runner = FakeRunner("active") + summary = starter(runner, [status]).run() + assert summary.startswith("FAIL: 승인") + assert SWITCH not in runner.commands + + +def test_unconfirmed_queue_blocks_the_switch() -> None: + runner = FakeRunner("active") + summary = starter(runner, [snapshot()], queue_cleared=False).run() + assert summary.startswith("FAIL: 대기 실행 정리 미확인") + assert SWITCH not in runner.commands + + +def test_switch_failure_and_not_ready_are_reported() -> None: + runner = FakeRunner("active") + runner.switch_exit = 2 + assert starter(runner, [snapshot()]).run() == "FAIL: 켜기 명령 실패(exit 2)" + + runner = FakeRunner("active") + summary = starter(runner, [snapshot()]).run() + assert summary.startswith("FAIL: 켜기 후 READY 아님") + + +def test_without_switch_command_the_switch_is_manual() -> None: + runner = FakeRunner("active") + summary = starter(runner, [snapshot()], switch=None).run() + assert summary.startswith("MANUAL") + + +def test_unexpected_service_state_needs_a_human() -> None: + runner = FakeRunner("deactivating") + assert starter(runner, [snapshot()]).run() == "FAIL: 서비스 상태 deactivating: 수동 확인 필요" + + +def test_default_cli_is_a_dry_run_that_executes_nothing( + tmp_path: Path, capsys, monkeypatch +) -> None: + def forbidden(*_args: object, **_kwargs: object) -> None: + raise AssertionError("dry-run must not run subprocesses") + + monkeypatch.setattr(event_start.subprocess, "run", forbidden) + monkeypatch.setattr(event_start.time, "sleep", lambda _s: None) + status = tmp_path / "status.json" + future = datetime.now(UTC) + timedelta(hours=2) + import json + + status.write_text(json.dumps(snapshot(expires=future)), encoding="utf-8") + code = event_start.main( + ["--status-path", str(status), "--queue-cleared", "--switch-command", "/op/switch.sh on"] + ) + out = capsys.readouterr().out + assert code == 0 + assert "(dry-run) sudo systemctl reset-failed poppy-agent" in out + assert "(dry-run) /op/switch.sh on" in out + assert out.strip().splitlines()[-1] == "DRY-RUN OK: 실제 실행은 --execute" + + +def test_drop_in_sets_restart_no() -> None: + text = (ROOT / "deploy/systemd/poppy-agent.service.d/10-event-no-restart.conf").read_text( + encoding="utf-8" + ) + assert "[Service]" in text and "Restart=no" in text