우리집 비서 만들기 프로젝트 #7 - 서버편: 허브와 모듈의 약속

"""감사 로그. 한 줄에 JSON 하나(JSONL).

비밀값과 메일 본문은 남기지 않는다. 누가(사람, 기기), 언제, 무엇을, 결과가 어땠는지만 남긴다.
"""
import json
import logging
import threading
import time
from pathlib import Path

logger = logging.getLogger("secretary.audit")
_lock = threading.Lock()


class AuditLog:
    """감사 로그 기록기. 파일 끝에 한 줄씩 덧붙이기만 하고, 고치거나 지우지 않는다."""

    def __init__(self, path: Path):
        """로그 파일 경로를 기억하고, 폴더가 없으면 만든다."""
        self.path = path
        path.parent.mkdir(parents=True, exist_ok=True)

    def write(self, event: str, *, user: str | None = None, device: str | None = None, ip: str | None = None,
              **fields) -> None:
        """사건 하나를 JSON 한 줄로 기록한다. 서버 로그(docker logs)에도 같은 줄을 남긴다.

        event : 무슨 일인지. 예) "auth.fail", "approval.approve"
        user, device, ip : 누가, 어떤 기기로, 어디서
        **fields : 그 밖의 정보. 예) reason="bad_signature". 비밀값과 메일 본문은 넣지 않는다.
        """
        record = {"ts": int(time.time()), "event": event, "user": user, "device": device, "ip": ip, **fields}
        line = json.dumps(record, ensure_ascii=False, default=str)
        with _lock:
            with self.path.open("a", encoding="utf-8") as f:
                f.write(line + "\n")
        logger.info(line)

1
def write(event, *, user=None, **fields):
2
    print(event, user, fields)
3

4

5
write("approval.create", user="dad", approval="nCCzRFogNQvd", rule="same_user")
6

7
info = {"approval": "nCCzRFogNQvd", "action": "mail.send"}
8
write("approval.approve", user="mom", **info)
9

10
print({**info, "rule": "admin"})

{
  "name": "mail",
  "title": "메일",
  "actions": {
    "send": {
      "title": "메일 보내기",
      "approval": true,
      "roles": null,
      "params": { "type": "object", "required": ["to", "subject", "body"] }
    }
  }
}

{
  "params": { "to": ["grandma@family.example"], "subject": "퇴근", "body": "지금 출발해요" },
  "caller": { "user_id": "dad", "name": "아빠", "role": "admin", "email": "dad@example.com" }
}

1
"""모듈 카탈로그. 허브가 아는 모듈 목록과, 모듈을 부르는 HTTP 클라이언트.
2

3
허브는 모듈의 코드를 import 하지 않는다. 설정에 적힌 주소로 manifest(소개서)를 받아 오고,
4
명령이 오면 그 주소로 HTTP 요청을 보낼 뿐이다. 약속(계약)은 docs/module-contract.md 참고.
5
"""
6
import logging
7
import re
8
import time
9

10
import httpx
11
from pydantic import BaseModel, Field, ValidationError, field_validator
12

13
logger = logging.getLogger("secretary.catalog")
14

15
MANIFEST_TTL_SECONDS = 60
16
# 액션 이름은 URL 경로와 scope에 들어가므로 영문 소문자, 숫자, _, - 만
17
ACTION_RE = re.compile(r"[a-z0-9][a-z0-9_-]{0,31}")
18

19

20
class ModuleError(Exception):
21
    """모듈을 부르다 실패했을 때. status는 클라이언트에게 돌려줄 HTTP 상태 코드."""
22

23
    def __init__(self, status: int, message: str):
24
        super().__init__(message)
25
        self.status = status
26
        self.message = message
27

28

29
class ActionSpec(BaseModel):
30
    """manifest 안의 액션 하나. 필요한 scope는 따로 적지 않고 "<모듈>:<액션>"으로 정해진다."""
31

32
    title: str = Field(max_length=60)
33
    approval: bool = False
34
    roles: list[str] | None = None
35
    params: dict | None = None
36

37

38
class Manifest(BaseModel):
39
    """모듈 소개서. GET /manifest 응답을 이 모양으로 검사한다. 모양이 틀린 모듈은 쓰지 않는다."""
40

41
    name: str
42
    title: str = Field(max_length=60)
43
    actions: dict[str, ActionSpec]
44

45
    @field_validator("actions")
46
    @classmethod
47
    def _action_names(cls, actions: dict) -> dict:
48
        """액션 이름 규칙(ACTION_RE)에 맞지 않는 액션이 하나라도 있으면 manifest 전체를 거부한다."""
49
        bad = [a for a in actions if not ACTION_RE.fullmatch(a)]
50
        if bad:
51
            raise ValueError(f"bad action names: {bad}")
52
        return actions
53

54

55
class ModuleCatalog:
56
    """설정에 등록된 모듈들의 manifest를 기억하고, 모듈에 요청을 보낸다."""
57

58
    def __init__(self, endpoints: dict[str, tuple[str, str]], timeout: float = 10.0, transport=None):
59
        """endpoints: 모듈 이름 → (주소, 토큰). transport는 테스트에서 가짜 모듈을 붙일 때만 넣는다."""
60
        self.endpoints = endpoints
61
        self._http = httpx.AsyncClient(timeout=timeout, transport=transport)
62
        self._cache: dict[str, tuple[float, Manifest]] = {}
63

64
    async def close(self) -> None:
65
        """HTTP 연결을 닫는다. 서버가 꺼질 때 부른다."""
66
        await self._http.aclose()
67

68
    def _headers(self, name: str) -> dict:
69
        """그 모듈의 내부 토큰을 붙인 헤더. 모듈은 이 토큰이 맞을 때만 요청을 받는다."""
70
        return {"Authorization": f"Bearer {self.endpoints[name][1]}"}
71

72
    async def manifest(self, name: str) -> Manifest:
73
        """모듈의 manifest를 돌려준다. 1분 동안은 기억해 둔 것을 쓰고, 지나면 다시 받아 온다.
74

75
        모듈이 꺼져 있으면 503. 다시 받아 오다 실패해도 전에 받아 둔 manifest가 있으면 그걸 쓴다.
76
        """
77
        if name not in self.endpoints:
78
            raise ModuleError(404, "없는 모듈입니다.")
79
        cached = self._cache.get(name)
80
        if cached and time.monotonic() - cached[0] < MANIFEST_TTL_SECONDS:
81
            return cached[1]
82
        url = self.endpoints[name][0]
83
        try:
84
            res = await self._http.get(f"{url}/manifest", headers=self._headers(name))
85
            res.raise_for_status()
86
            manifest = Manifest.model_validate(res.json())
87
            if manifest.name != name:
88
                raise ValueError(f"manifest name mismatch: {manifest.name}")
89
        except (httpx.HTTPError, ValidationError, ValueError) as e:
90
            logger.warning("module %s manifest failed: %s", name, e)
91
            if cached:
92
                return cached[1]
93
            raise ModuleError(503, "모듈에 연결할 수 없습니다.") from e
94
        self._cache[name] = (time.monotonic(), manifest)
95
        return manifest
96

97
    async def action(self, name: str, action: str) -> ActionSpec:
98
        """모듈의 액션 하나를 찾는다. 없으면 404."""
99
        spec = (await self.manifest(name)).actions.get(action)
100
        if spec is None:
101
            raise ModuleError(404, "없는 액션입니다.")
102
        return spec
103

104
    async def _post(self, name: str, path: str, params: dict, caller: dict) -> dict:
105
        """모듈에 POST를 보내고 JSON 응답을 돌려준다.
106

107
        모듈이 422를 주면 그 메시지를 그대로 사용자에게 보여 준다(입력이 틀린 것이므로).
108
        그 밖의 실패(연결 안 됨, 500, 401)는 자세한 내용을 서버 로그에만 남기고 502로 바꾼다.
109
        """
110
        url = self.endpoints[name][0]
111
        try:
112
            res = await self._http.post(f"{url}{path}", json={"params": params, "caller": caller},
113
                                        headers=self._headers(name))
114
        except httpx.HTTPError as e:
115
            logger.warning("module %s %s failed: %s", name, path, e)
116
            raise ModuleError(502, "모듈에 연결할 수 없습니다.") from e
117
        if res.status_code == 422:
118
            try:
119
                message = str(res.json().get("message", ""))[:200]
120
            except ValueError:
121
                message = ""
122
            raise ModuleError(422, message or "요청 내용이 올바르지 않습니다.")
123
        if res.status_code != 200:
124
            logger.warning("module %s %s returned %s", name, path, res.status_code)
125
            raise ModuleError(502, "모듈 실행에 실패했습니다.")
126
        return res.json()
127

128
    async def validate(self, name: str, action: str, params: dict, caller: dict) -> str:
129
        """실행 전에 입력을 검사받고, 승인 화면에 보여 줄 한 줄 요약을 받아 온다."""
130
        data = await self._post(name, f"/actions/{action}/validate", params, caller)
131
        return str(data.get("summary", f"{name}.{action}"))[:200]
132

133
    async def execute(self, name: str, action: str, params: dict, caller: dict) -> str:
134
        """모듈에 실제 실행을 맡기고 결과 문구를 돌려준다."""
135
        data = await self._post(name, f"/actions/{action}", params, caller)
136
        return str(data.get("result", "완료"))[:200]
137

138

139
def caller_context(user) -> dict:
140
    """모듈에 넘길 "누가 시켰는지" 정보. 기기 키나 Secret 같은 인증 정보는 절대 넘기지 않는다."""
141
    return {"user_id": user.id, "name": user.name, "role": user.role, "email": user.email}

1
import re
2

3
from pydantic import BaseModel, Field, ValidationError, field_validator
4

5
ACTION_RE = re.compile(r"[a-z0-9][a-z0-9_-]{0,31}")
6

7

8
class ActionSpec(BaseModel):
9
    title: str = Field(max_length=60)
10
    approval: bool = False
11

12

13
class Manifest(BaseModel):
14
    name: str
15
    actions: dict[str, ActionSpec]
16

17
    @field_validator("actions")
18
    @classmethod
19
    def _action_names(cls, actions: dict) -> dict:
20
        bad = [a for a in actions if not ACTION_RE.fullmatch(a)]
21
        if bad:
22
            raise ValueError(f"bad action names: {bad}")
23
        return actions
24

25

26
def check(data: dict) -> None:
27
    try:
28
        m = Manifest.model_validate(data)
29
        print("통과:", m.actions["send"].title, m.actions["send"].approval)
30
    except ValidationError as e:
31
        for err in e.errors():
32
            print("거부:", err["loc"], err["msg"])
33

34

35
check({"name": "mail", "actions": {"send": {"title": "메일 보내기", "approval": True}}})
36
check({"name": "mail", "actions": {"send": {"approval": "글쎄"}}})
37
check({"name": "mail", "actions": {"../admin": {"title": "관리"}}})