document-haness/docs/keycloak-session-store/final/.techviz/d4a-hook-effect/spec.json

{
  "version": "1.1",
  "id": "d4a-hook-effect",
  "title": "훅 하나가 만드는 차이",
  "question": "갱신을 서빙으로 잇는 자리는 무엇인가",
  "type": "architecture",
  "direction": "TB",
  "audience": [
    "인증서 자동 갱신을 운영하는 엔지니어"
  ],
  "summary": "deploy 훅이 없으면 사람이 reload 할 때까지 옛 인증서를 서빙한다. 훅 하나로 그 구간이 1~2초가 된다.",
  "alt": "certbot 이 갱신에 성공한 뒤 deploy 훅이 nginx 를 reload 하는 경로와, 그 훅이 없어 사람이 개입해야 하는 경로가 갈리는 구성.",
  "long_description": "훅이 없을 때 새 인증서가 디스크에 기록된 08:20:27 과 실제로 서빙된 08:58:52 사이가 2305초였고, 그것도 사람이 nginx -s reload 를 쳤기 때문이다. deploy 훅을 넣자 발급에서 서빙까지 1~2초가 됐다. 판정은 문구가 아니라 워커 PID 로 한다. certbot 이 Hook 'deploy-hook' ran with error output 이라고 찍지만 실패가 아니며 nginx 의 types_hash 경고가 stderr 로 나갔을 뿐이다. 로그에서 error 를 grep 하는 감시는 성공한 훅을 실패로 오독한다.",
  "source_context": {
    "document": "docs/keycloak-session-store/final/document.md",
    "document_sha256": "1d44cba1905544d92f1d26ae36a8deb64a3db3914d6b488fd30d6ae7f8cfbabe",
    "anchor": {
      "kind": "heading",
      "value": "D-4 · D-4a — 인증서, 그리고 이 실험대 최대의 발견",
      "line": 509
    }
  },
  "composition": {
    "profile": "component-flow",
    "diagram_only": true,
    "reference_ids": [
      "payment-event-flow"
    ],
    "rationale": "갱신과 서빙을 잇는 자리가 있는가 없는가가 지배적 질문이다. 경로의 유무이므로 component-flow 를 골랐다."
  },
  "groups": [],
  "nodes": [
    {
      "id": "renew",
      "label": "certbot 갱신 성공",
      "kind": "process",
      "role": "source",
      "emphasis": "primary",
      "description": "archive 에 쓰고 live 링크를 옮긴다.",
      "details": [],
      "evidence": [
        {
          "start_line": 560,
          "end_line": 570
        }
      ],
      "assumption": false
    },
    {
      "id": "hook",
      "label": "deploy 훅",
      "kind": "process",
      "role": "control",
      "emphasis": "primary",
      "description": "갱신이 실제로 일어났을 때만 실행된다.",
      "details": [
        "nginx -t && nginx -s reload"
      ],
      "evidence": [
        {
          "start_line": 560,
          "end_line": 575
        }
      ],
      "assumption": false
    },
    {
      "id": "worker",
      "label": "nginx 워커 교체",
      "kind": "process",
      "role": "control",
      "emphasis": "primary",
      "description": "마스터는 유지되고 워커만 새로 뜬다.",
      "details": [
        "28829 → 37252"
      ],
      "evidence": [
        {
          "start_line": 571,
          "end_line": 580
        }
      ],
      "assumption": false
    },
    {
      "id": "serving",
      "label": "새 인증서 서빙",
      "kind": "service",
      "role": "target",
      "emphasis": "primary",
      "description": "훅이 없으면 사람이 칠 때까지 옛 것이다.",
      "details": [
        "훅 없음 2305초 · 훅 있음 1~2초"
      ],
      "evidence": [
        {
          "start_line": 560,
          "end_line": 580
        }
      ],
      "assumption": false
    }
  ],
  "edges": [
    {
      "id": "r-h",
      "from": "renew",
      "to": "hook",
      "label": "갱신 성공 시 호출",
      "kind": "request",
      "evidence": [
        {
          "start_line": 560,
          "end_line": 575
        }
      ],
      "assumption": false
    },
    {
      "id": "h-w",
      "from": "hook",
      "to": "worker",
      "label": "reload 신호",
      "kind": "request",
      "evidence": [
        {
          "start_line": 560,
          "end_line": 580
        }
      ],
      "assumption": false
    },
    {
      "id": "w-s",
      "from": "worker",
      "to": "serving",
      "label": "새 워커가 새 인증서를 읽는다",
      "kind": "request",
      "evidence": [
        {
          "start_line": 571,
          "end_line": 580
        }
      ],
      "assumption": false
    }
  ],
  "legend": [],
  "metadata": {
    "rationale": "훅의 유무를 한 축에 놓고, 판정 신호를 워커 PID 로 명시했다. 로그 문구로 판정하면 틀린다."
  }
}