document-haness/docs/keycloak-session-store/final/.techviz/a3-commit-to-disk-gap/spec.json

{
  "version": "1.1",
  "id": "a3-commit-to-disk-gap",
  "title": "200 과 디스크 사이의 빈 구간",
  "question": "로그인이 성공했는데 세션이 없을 수 있는 이유는 무엇인가",
  "type": "architecture",
  "direction": "TB",
  "audience": [
    "RPO 를 따져야 하는 운영 엔지니어"
  ],
  "summary": "Keycloak 이 트랜잭션마다 synchronous_commit 을 끄기 때문에 COMMIT 이 WAL 디스크 기록을 기다리지 않는다. 그 사이에 죽으면 그만큼 사라진다.",
  "alt": "클라이언트가 200 을 받은 뒤에도 WAL 이 아직 디스크에 닿지 않은 구간이 남아 있는 구성.",
  "long_description": "Keycloak 은 트랜잭션마다 SET LOCAL synchronous_commit TO OFF 를 건다. PostgreSQL 은 COMMIT 을 WAL 디스크 기록을 기다리지 않고 즉시 반환하고, 클라이언트는 200 과 토큰을 받는다. 실측된 wal_writer_delay 는 200ms 이며 그 사이에 프로세스가 죽으면 그만큼이 사라진다. 153건 중 4건이 그렇게 유실됐다. 버그가 아니라 의도된 설계이고 그 대가를 숫자로 확인한 것이다.",
  "source_context": {
    "document": "docs/keycloak-session-store/final/document.md",
    "document_sha256": "1d44cba1905544d92f1d26ae36a8deb64a3db3914d6b488fd30d6ae7f8cfbabe",
    "anchor": {
      "kind": "heading",
      "value": "A-2 · A-3 — DB 가 멈출 때와 죽을 때",
      "line": 201
    }
  },
  "composition": {
    "profile": "component-flow",
    "diagram_only": true,
    "reference_ids": [
      "payment-event-flow"
    ],
    "rationale": "응답이 돌아가는 시점과 데이터가 디스크에 닿는 시점이 다르다는 것이 지배적 질문이다. 경로의 시간 차이이므로 component-flow 를 골랐다."
  },
  "groups": [],
  "nodes": [
    {
      "id": "client",
      "label": "클라이언트",
      "kind": "actor",
      "role": "source",
      "emphasis": "primary",
      "description": "200 과 토큰을 받는다.",
      "details": [
        "성공 응답 153건"
      ],
      "evidence": [
        {
          "start_line": 207,
          "end_line": 213
        }
      ],
      "assumption": false
    },
    {
      "id": "keycloak",
      "label": "Keycloak",
      "kind": "service",
      "role": "control",
      "emphasis": "normal",
      "description": "트랜잭션마다 synchronous_commit 을 끈다.",
      "details": [
        "SET LOCAL synchronous_commit TO OFF"
      ],
      "evidence": [
        {
          "start_line": 211,
          "end_line": 215
        }
      ],
      "assumption": false
    },
    {
      "id": "pg",
      "label": "PostgreSQL",
      "kind": "datastore",
      "role": "control",
      "emphasis": "warning",
      "description": "COMMIT 을 즉시 반환한다. WAL 은 아직 메모리에 있다.",
      "details": [
        "wal_writer_delay 200ms"
      ],
      "evidence": [
        {
          "start_line": 211,
          "end_line": 215
        }
      ],
      "assumption": false
    },
    {
      "id": "disk",
      "label": "디스크의 WAL",
      "kind": "datastore",
      "role": "target",
      "emphasis": "primary",
      "description": "여기 닿아야 살아남는다.",
      "details": [
        "DB 존재 149건"
      ],
      "evidence": [
        {
          "start_line": 207,
          "end_line": 215
        }
      ],
      "assumption": false
    }
  ],
  "edges": [
    {
      "id": "c-k",
      "from": "client",
      "to": "keycloak",
      "label": "로그인 요청",
      "kind": "request",
      "evidence": [
        {
          "start_line": 207,
          "end_line": 211
        }
      ],
      "assumption": false
    },
    {
      "id": "k-pg",
      "from": "keycloak",
      "to": "pg",
      "label": "세션 INSERT · COMMIT",
      "kind": "write",
      "evidence": [
        {
          "start_line": 211,
          "end_line": 215
        }
      ],
      "assumption": false
    },
    {
      "id": "pg-disk",
      "from": "pg",
      "to": "disk",
      "label": "지연된 WAL 기록",
      "kind": "write",
      "evidence": [
        {
          "start_line": 211,
          "end_line": 215
        }
      ],
      "assumption": false
    }
  ],
  "legend": [],
  "metadata": {
    "rationale": "성공 응답과 영속화를 두 사건으로 분리했다. RPO 가 0 이 아닌 이유가 그 사이에 있다."
  }
}