분산 시스템 on 엔지니어 생존기록

분산 시스템 설계(1) - Paxos 심화(분산 Key-Value 스토어)

Sun, 22 Mar 2026 10:34:52 +0900

Paxos 알고리즘 관련 세번째 글입니다. 그러니까… 지난 글에서는 아주 간단하게 리더를 선출하는 예제를 만들어 봤었지만, 그게 뭐랄까 좀 예제를 위한 예제 같은 느낌이 들었습니다. Multi-Paxos를 제대로 구현하지도 못했고 말이죠. 그래서 Claude와 함께 고민을 하던 중에 Redis 같은 분산 Key-Value 스토어(이하 dkv)를 만들어 보는 게 어떨까 싶었습니다. 그래서 관련해서 튜토리얼을 생성해내고, 직접 쳐보기도 하면서 Claude Code와 예제를 완성하고 코드를 모두 한 줄씩 읽어가면서 동작을 이해하려 노력해봤습니다.

그 과정의 결과물을 여기 에 올려두었습니다.

간략한 소개

해당 리포지토리에 방문하시면 훨씬 더 상세한 README가 기다리고 있긴 합니다. 해당 내용은 초반에 틀을 제가 손으로 직접 잡고 나머지 부분을 Claude Code와 함께 완성 및 보강했습니다. 여기서는 어떻게 dkv가 동작하는지를 좀 설명드려보고자 합니다.

Paxos Prepare-Accept를 통한 리더 선출

우선 3개의 노드를 실행하는 과정을 볼까요? 일단 첫 번째 노드부터 실행합니다.

❯ go run ./cmd/dkv -id=1
2026/03/17 14:16:53 gRPC listening on 127.0.0.1:9001
time=2026-03-17T14:16:53.495+09:00 level=INFO msg="wal: 재생 완료" node=1 lastApplied=1 totalRecords=42 acceptorStates=41 committedEntries=1
time=2026-03-17T14:16:53.495+09:00 level=INFO msg="paxos: 시작" node=1 peers="[1 2 3]" electionTimeout=500ms heartbeatInterval=100ms
time=2026-03-17T14:16:53.495+09:00 level=INFO msg="http: HTTP 서버 시작" node=1 addr=127.0.0.1:8001
Node 1 started — HTTP: 127.0.0.1:8001, gRPC: 127.0.0.1:9001
time=2026-03-17T14:16:54.253+09:00 level=INFO msg="election: 타이머 발동, 선거 시작" node=1 elapsed=2562047h47m16.854775807s threshold=500ms
time=2026-03-17T14:16:54.253+09:00 level=INFO msg="election: 🟢 prepare 시작" node=1 ballot=N1.1 prevNumber=0
time=2026-03-17T14:16:54.256+09:00 level=INFO msg="election: prepare 전송 실패" node=1 peer=2 ballot=N1.1 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9002: connect: connection refused\""
time=2026-03-17T14:16:54.256+09:00 level=INFO msg="election: prepare 전송 실패" node=1 peer=3 ballot=N1.1 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9003: connect: connection refused\""
time=2026-03-17T14:16:54.257+09:00 level=INFO msg="election: prepare 거부됨" node=1 peer=1 ballot=N1.1 promisedBallot=N30.1
time=2026-03-17T14:16:54.257+09:00 level=INFO msg="election: prepare 결과" node=1 promises=0 majority=2 ballot=N1.1 result=실패
time=2026-03-17T14:16:54.257+09:00 level=INFO msg="election: ballot fast-forward" node=1 from=1 to=30
time=2026-03-17T14:16:54.257+09:00 level=INFO msg="election: 실패" node=1 err="🔴election failed: 0/2 promises"
time=2026-03-17T14:16:54.988+09:00 level=INFO msg="election: 타이머 발동, 선거 시작" node=1 elapsed=2562047h47m16.854775807s threshold=500ms
time=2026-03-17T14:16:54.988+09:00 level=INFO msg="election: 🟢 prepare 시작" node=1 ballot=N31.1 prevNumber=30
time=2026-03-17T14:16:54.988+09:00 level=INFO msg="election: prepare 전송 실패" node=1 peer=2 ballot=N31.1 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9002: connect: connection refused\""
time=2026-03-17T14:16:54.988+09:00 level=INFO msg="election: prepare 전송 실패" node=1 peer=3 ballot=N31.1 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9003: connect: connection refused\""
time=2026-03-17T14:16:54.994+09:00 level=INFO msg="election: prepare 약속 받음" node=1 peer=1 ballot=N31.1
time=2026-03-17T14:16:54.994+09:00 level=INFO msg="election: prepare 결과" node=1 promises=1 majority=2 ballot=N31.1 result=실패
time=2026-03-17T14:16:54.994+09:00 level=INFO msg="election: 실패" node=1 err="🔴election failed: 1/2 promises"
...

뭔가 로그가 복잡해 보이지만, 리더 선출을 위한 선거(Prepare)를 진행하고 있습니다. 🟢과 🔴를 주목해서 보시면 선거가 시작됐지만 아직 자신 밖에 없으므로 선거는 실패하고 있습니다. 자 이제 2번 노드 투입합니다!

❯ go run ./cmd/dkv -id=2
2026/03/17 14:17:01 gRPC listening on 127.0.0.1:9002
time=2026-03-17T14:17:01.908+09:00 level=INFO msg="wal: 재생 완료" node=2 lastApplied=1 totalRecords=20 acceptorStates=19 committedEntries=1
time=2026-03-17T14:17:01.908+09:00 level=INFO msg="paxos: 시작" node=2 peers="[1 2 3]" electionTimeout=500ms heartbeatInterval=100ms
time=2026-03-17T14:17:01.908+09:00 level=INFO msg="http: HTTP 서버 시작" node=2 addr=127.0.0.1:8002
Node 2 started — HTTP: 127.0.0.1:8002, gRPC: 127.0.0.1:9002
time=2026-03-17T14:17:02.429+09:00 level=INFO msg="election: 타이머 발동, 선거 시작" node=2 elapsed=2562047h47m16.854775807s threshold=500ms
time=2026-03-17T14:17:02.429+09:00 level=INFO msg="election: 🟢 prepare 시작" node=2 ballot=N1.2 prevNumber=0
time=2026-03-17T14:17:02.431+09:00 level=INFO msg="election: prepare 전송 실패" node=2 peer=3 ballot=N1.2 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9003: connect: connection refused\""
time=2026-03-17T14:17:02.431+09:00 level=INFO msg="election: prepare 거부됨" node=2 peer=1 ballot=N1.2 promisedBallot=N42.1
time=2026-03-17T14:17:02.432+09:00 level=INFO msg="election: prepare 거부됨" node=2 peer=2 ballot=N1.2 promisedBallot=N25.1
time=2026-03-17T14:17:02.432+09:00 level=INFO msg="election: prepare 결과" node=2 promises=0 majority=2 ballot=N1.2 result=실패
time=2026-03-17T14:17:02.432+09:00 level=INFO msg="election: ballot fast-forward" node=2 from=1 to=42
time=2026-03-17T14:17:02.432+09:00 level=INFO msg="election: 실패" node=2 err="🔴election failed: 0/2 promises"
time=2026-03-17T14:17:02.991+09:00 level=INFO msg="election: 타이머 발동, 선거 시작" node=2 elapsed=2562047h47m16.854775807s threshold=500ms
time=2026-03-17T14:17:02.991+09:00 level=INFO msg="election: 🟢 prepare 시작" node=2 ballot=N43.2 prevNumber=42
time=2026-03-17T14:17:02.991+09:00 level=INFO msg="election: prepare 전송 실패" node=2 peer=3 ballot=N43.2 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9003: connect: connection refused\""
time=2026-03-17T14:17:02.996+09:00 level=INFO msg="election: prepare 약속 받음" node=2 peer=2 ballot=N43.2
time=2026-03-17T14:17:03.000+09:00 level=INFO msg="election: prepare 약속 받음" node=2 peer=1 ballot=N43.2
time=2026-03-17T14:17:03.000+09:00 level=INFO msg="election: prepare 결과" node=2 promises=2 majority=2 ballot=N43.2 result=성공
time=2026-03-17T14:17:03.000+09:00 level=INFO msg="election: 미커밋 엔트리 재제안" node=2 slot=1 ballot=N43.2 key=hahaha
time=2026-03-17T14:17:03.008+09:00 level=INFO msg="election: 🎉 리더 당선" node=2 ballot=N43.2 committedUpTo=1

마지막 줄을 보시면 2번 노드는 시작되자 마자 과반수의 지지를 받아 리더가 됩니다! 이때 1번 노드의 상황을 볼까요?

...
time=2026-03-17T14:17:02.997+09:00 level=INFO msg="election: 🟢 prepare 시작" node=1 ballot=N43.1 prevNumber=42
time=2026-03-17T14:17:02.997+09:00 level=INFO msg="election: prepare 전송 실패" node=1 peer=3 ballot=N43.1 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9003: connect: connection refused\""
time=2026-03-17T14:17:02.997+09:00 level=INFO msg="election: prepare 전송 실패" node=1 peer=2 ballot=N43.1 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9002: connect: connection refused\""
time=2026-03-17T14:17:03.000+09:00 level=INFO msg="election: prepare 거부됨" node=1 peer=1 ballot=N43.1 promisedBallot=N43.2
time=2026-03-17T14:17:03.000+09:00 level=INFO msg="election: prepare 결과" node=1 promises=0 majority=2 ballot=N43.1 result=실패
time=2026-03-17T14:17:03.000+09:00 level=INFO msg="election: 실패" node=1 err="🔴election failed: 0/2 promises"
time=2026-03-17T14:17:03.110+09:00 level=INFO msg="heartbeat: 새 리더 감지" node=1 leader=2 ballot=N43.2 prevLeader=0
...

자신이 리더가 되고자 하는 요청(Prepare)는 한 표도 받지 못했고, 2번 노드가 2표를 모두 약속받은 뒤 Accept까지 진행해버렸기 때문에 2번 노드가 새로운 리더임을 인정하게 됩니다.

이제 3번 노드가 또 합류합니다!

❯ go run ./cmd/dkv -id=3
2026/03/17 14:17:11 gRPC listening on 127.0.0.1:9003
time=2026-03-17T14:17:11.717+09:00 level=INFO msg="wal: 재생 완료" node=3 lastApplied=1 totalRecords=31 acceptorStates=30 committedEntries=1
time=2026-03-17T14:17:11.717+09:00 level=INFO msg="paxos: 시작" node=3 peers="[1 2 3]" electionTimeout=500ms heartbeatInterval=100ms
time=2026-03-17T14:17:11.717+09:00 level=INFO msg="http: HTTP 서버 시작" node=3 addr=127.0.0.1:8003
Node 3 started — HTTP: 127.0.0.1:8003, gRPC: 127.0.0.1:9003
time=2026-03-17T14:17:12.468+09:00 level=INFO msg="election: 타이머 발동, 선거 시작" node=3 elapsed=2562047h47m16.854775807s threshold=500ms
time=2026-03-17T14:17:12.469+09:00 level=INFO msg="election: 🟢 prepare 시작" node=3 ballot=N1.3 prevNumber=0
time=2026-03-17T14:17:12.471+09:00 level=INFO msg="election: prepare 거부됨" node=3 peer=2 ballot=N1.3 promisedBallot=N43.2
time=2026-03-17T14:17:12.471+09:00 level=INFO msg="election: prepare 거부됨" node=3 peer=3 ballot=N1.3 promisedBallot=N34.3
time=2026-03-17T14:17:12.471+09:00 level=INFO msg="election: prepare 거부됨" node=3 peer=1 ballot=N1.3 promisedBallot=N43.2
time=2026-03-17T14:17:12.471+09:00 level=INFO msg="election: prepare 결과" node=3 promises=0 majority=2 ballot=N1.3 result=실패
time=2026-03-17T14:17:12.471+09:00 level=INFO msg="election: ballot fast-forward" node=3 from=1 to=43
time=2026-03-17T14:17:12.471+09:00 level=INFO msg="election: 실패" node=3 err="🔴election failed: 0/2 promises"
time=2026-03-17T14:17:13.092+09:00 level=INFO msg="election: 타이머 발동, 선거 시작" node=3 elapsed=2562047h47m16.854775807s threshold=500ms
...
time=2026-03-17T14:17:16.468+09:00 level=INFO msg="election: 🟢 prepare 시작" node=3 ballot=N49.3 prevNumber=48
time=2026-03-17T14:17:16.469+09:00 level=INFO msg="election: prepare 거부됨" node=3 peer=2 ballot=N49.3 promisedBallot=N43.2
time=2026-03-17T14:17:16.469+09:00 level=INFO msg="election: prepare 거부됨" node=3 peer=1 ballot=N49.3 promisedBallot=N43.2
time=2026-03-17T14:17:16.472+09:00 level=INFO msg="election: prepare 약속 받음" node=3 peer=3 ballot=N49.3
time=2026-03-17T14:17:16.472+09:00 level=INFO msg="election: prepare 결과" node=3 promises=1 majority=2 ballot=N49.3 result=실패
time=2026-03-17T14:17:16.472+09:00 level=INFO msg="election: 실패" node=3 err="🔴election failed: 1/2 promises"
time=2026-03-17T14:17:17.109+09:00 level=INFO msg="heartbeat: 새 리더 감지" node=3 leader=2 ballot=N43.2 prevLeader=0

처음에는 자신을 리더로 제안(Propose)하지만, 결국 2번 노드가 리더임을 인정하게 됩니다.

Paxos Accept를 통한 key-value 전파

3번 노드에 키를 gundam으로 하고 값을 건담이말을건담으로 넣어볼까요?

❯ curl -L -X PUT http://127.0.0.1:8003/kv/gundam -d "건담이말을건담"
OK (index=2)

참고로 -L 플래그는 요청이 리다이렉트 될 수 있도록 해줍니다. 현재 dkv는 리더가 아닌 노드에게 쓰기 요청을 하면 해당 요청을 리더에게 리다이렉트 하도록 구현되었거든요! 자 그럼 1번 노드에서 키를 조회해볼까요?

❯ curl http://127.0.0.1:8001/kv/gundam
건담이말을건담

3번 노드가 쓰기 요청을 리더인 2번 노드에게 전달하고, 리더는 다른 노드들에 Accept 요청을 전송해서 쓰기 요청이 다른 노드에 전파되도록 합니다. 그래서 1번 노드에서도 키로 값을 조회해올 수 있는 거죠.

리더 선출 과정에서 이미 Prepare를 거쳤기 때문에 바로 Accept단계로 넘어갑니다!

정리

이걸 구현하고 이해해보려고 노력하면서 왜 Paxos가 더 이상 쓰이지 않는지 이해했습니다. 이게 좀 많이 복잡하네요. 솔직히 아직도 좀 헷갈립니다. 다음 부터는 dkv를 만드는 과정에서 제가 새롭게 배운 내용들을 따로 한 번 정리해보려고 합니다. 그러고 나서 Raft를 추가로 구현해볼 생각입니다.

분산 시스템 설계(1) - Paxos 알고리즘(GO)

Sun, 22 Feb 2026 08:03:55 +0900

지난 글에서는 Paxos 알고리즘에 대해서 정리를 했고, 리더 선출 예시를 살펴보면서 구체적인 알고리즘 동작과정을 살펴봤습니다. 해당 예시는 node.js로 작성을 했었죠. 이번에는 그 예시의 Go 버전을 확인해볼까 합니다. 이유는… 별게 없고 그냥 제가 최근에 Go를 좀 보기 시작 했기 때문입니다! 하하하하하….

구조와 동작은 지난 글의 내용과 똑같습니다. 다만, Go는 접근 방식이 다르다 보니 구체적인 구현에서는 좀 차이를 보이는데요. 그런 특징적인 부분들을 정리해보고자 합니다. 미래의 저를 위해서 말이죠!

코드 실행 방법

go는 원래 컴파일을 통해 실행 파일을 생성하지만, 다음 명령을 통해 바로 실행 해볼 수 있으며, 실행 과정은 이전의 node.js 버전과 동일합니다!

> go run . cluster

go run 명령도 컴파일을 합니다! 컴파일을 통해 임시 바이너리를 생성해서 실행을 하지만, 눈에 보이지 않을 뿐입니다. 개발 중에 계속 컴파일 -> 실행은 너무 귀찮죠 하하하하…

프로그램 진입점 구현

프로그램이 시작되는 main.go는 다음과 같습니다.

package main

import (
 "fmt"
 "os"
)

func main() {
 if len(os.Args) < 2 {
 fmt.Println("사용법:")
 fmt.Println(" go run . cluster -- 클러스터 모드 (3개 노드 실행)")
 os.Exit(1)
 }

 switch os.Args[1] {
 case "node":
 runNode() // 클러스터 관리 cli가 각 노드를 실행할 때 사용
 case "cluster":
 runCluster() // 클러스터 관리 cli를 실행
 default:
 fmt.Printf("알 수 없는 명령어: %s\n", os.Args[1])
 os.Exit(1)
 }
}

프로그램에 설정된 인자에 따라서 서로 다른 모드로 실행합니다.

cluster: 클러스터 관리 cli를 실행
node: 서버 노드를 실행

앞서 실행 방법에서 봤듯이 우리는 “cluster” 모드로 클러스터 관리 cli를 실행합니다. 그리고 클러스터 관리 cli가 “node” 모드로 3개의 서버 노드를 실행하게 되죠. main.go와 이후에 살펴볼 cluster.go, node.go 가 모두 같은 main 패키지에 포함되어 있기 때문에 다른 파일의 함수를 자유롭게 가져다 쓸 수 있습니다.

클러스터 관리자 cli 구현

cluster.go의 전체 소스코드는 다음과 같습니다.

package main

import (
 "bufio"
 "encoding/json"
 "fmt"
 "net/http"
 "os"
 "os/exec"
 "os/signal"
 "strconv"
 "strings"
 "sync"
 "syscall"
 "time"
)

type nodeConfig struct {
 id int
 port int
}

// 각 노드 아이디와 포트 번호 정의
var nodes = []nodeConfig{
 {id: 1, port: 3001},
 {id: 2, port: 3002},
 {id: 3, port: 3003},
}

// 가독성을 위해 각 노드의 아이디별 출력 색상 정의
var colors = map[int]string{
 1: "\033[36m", // 파란색 (cyan)
 2: "\033[33m", // 노란색
 3: "\033[35m", // 핑크색 (magenta)
}

const colorReset = "\033[0m"

// 노드 프로세스 관리를 위한 맵 정의
var (
 // 키 타입이 int이고, 값 타입이 *exec.Cmd인 맵
 processes = make(map[int]*exec.Cmd)
 // 맵에 대한 동시성 접근을 위한 뮤텍스(lock)
 processesMu sync.Mutex
)

// 노드 프로세스 시작 처리 함수
func startNode(nc nodeConfig) {
 // 현재 노드가 통신해야 할 다른 노드의 URL 목록 생성
 var peers []string
 for _, n := range nodes {
 if n.id != nc.id {
 peers = append(peers, fmt.Sprintf("http://localhost:%d", n.port))
 }
 }

 color := colors[nc.id]
 fmt.Printf("%s노드 %d 시작...%s\n", color, nc.id, colorReset)

 // 노드 프로세스 생성
 args := []string{"run", ".", "node", strconv.Itoa(nc.id), strconv.Itoa(nc.port)}
 args = append(args, peers...)

 cmd := exec.Command("go", args...)

 stdout, err := cmd.StdoutPipe()
 if err != nil {
 fmt.Printf("노드 %d stdout pipe 실패: %v\n", nc.id, err)
 return
 }
 stderr, err := cmd.StderrPipe()
 if err != nil {
 fmt.Printf("노드 %d stderr pipe 실패: %v\n", nc.id, err)
 return
 }

 if err := cmd.Start(); err != nil {
 fmt.Printf("노드 %d 시작 실패: %v\n", nc.id, err)
 return
 }

 // 여러 goroutine에서 동시에 접근할 수 있으므로, 동시성 접근을 위해 뮤텍스를 사용
 processesMu.Lock()
 processes[nc.id] = cmd
 processesMu.Unlock()

 // goroutine: 노드 프로세스의 출력에 색상을 적용하여 출력
 go func() {
 scanner := bufio.NewScanner(stdout)
 for scanner.Scan() {
 fmt.Printf("%s%s%s\n", color, scanner.Text(), colorReset)
 }
 }()

 // goroutine: 노드 프로세스의 에러 출력에 색상을 적용하여 출력
 go func() {
 scanner := bufio.NewScanner(stderr)
 for scanner.Scan() {
 fmt.Printf("%s[노드 %d 에러] %s%s\n", color, nc.id, scanner.Text(), colorReset)
 }
 }()

 // goroutine: 노드 프로세스가 종료될 때 처리
 go func() {
 err := cmd.Wait()
 exitCode := -1
 if cmd.ProcessState != nil {
 exitCode = cmd.ProcessState.ExitCode()
 }
 fmt.Printf("%s[노드 %d] 프로세스 종료 (code: %d, err: %v)%s\n",
 color, nc.id, exitCode, err, colorReset)

 processesMu.Lock()
 delete(processes, nc.id)
 processesMu.Unlock()
 }()
}

// 노드 프로세스 종료 처리 함수
func killNode(id int) {
 processesMu.Lock()
 // 맵에서 노드 프로세스 조회
 cmd, exists := processes[id]
 processesMu.Unlock()

 // 노드 프로세스가 존재하면 종료
 if exists && cmd.Process != nil {
 if err := cmd.Process.Signal(syscall.SIGTERM); err != nil {
 fmt.Printf("[클러스터] 노드 %d 시그널 전송 실패: %v\n", id, err)
 }
 color := colors[id]
 fmt.Printf("\n%s[클러스터] 노드 %d 종료%s\n\n", color, id, colorReset)
 } else {
 fmt.Printf("\n[클러스터] 노드 %d 실행 중이 아님\n\n", id)
 }
}

// 클러스터 상태 출력 함수
func printStatus() {
 fmt.Println("\n=== 클러스터 상태 ===")

 // 타임아웃이 1초인 http.Client 생성
 client := &http.Client{Timeout: 1 * time.Second}

 for _, node := range nodes {
 // 즉시 실행되는 익명 함수. 함수 종료시 defer 처리된 리소스 해제
 func() {
 url := fmt.Sprintf("http://localhost:%d/status", node.port)
 resp, err := client.Get(url)
 color := colors[node.id]

 if err != nil {
 fmt.Printf("%s 노드 %d: 다운%s\n", color, node.id, colorReset)
 return
 }
 // err 발생시 resp는 nil. 따라서 err 체크 후 defer 처리가 일반적인 방법.
 defer resp.Body.Close()

 var data StatusResponse
 // resp.Body를 JSON -> StatusResponse 타입으로 변환; 그리고 err 발생시 처리
 if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
 fmt.Printf("%s 노드 %d: (응답 파싱 실패)%s\n", color, node.id, colorReset)
 return
 }

 leaderMark := " "
 if data.IsLeader {
 leaderMark = "👑"
 }

 leaderStr := "none"
 if data.CurrentLeaderID != nil {
 leaderStr = strconv.Itoa(*data.CurrentLeaderID)
 }
 promisedStr := "none"
 if data.PromisedProposal != nil {
 promisedStr = strconv.Itoa(*data.PromisedProposal)
 }
 acceptedStr := "none"
 if data.AcceptedProposal != nil {
 acceptedStr = strconv.Itoa(*data.AcceptedProposal)
 }

 // 노드 상태 출력
 fmt.Printf("%s%s 노드 %d: leader=%s, term=%d, isLeader=%v, promised=%s, accepted=%s%s\n",
 color, leaderMark, node.id, leaderStr, data.CurrentTerm, data.IsLeader,
 promisedStr, acceptedStr, colorReset)
 }()
 }
 fmt.Println()
}

func isValidNodeID(id int) bool {
 for _, n := range nodes {
 if n.id == id {
 return true
 }
 }
 return false
}

func findNode(id int) *nodeConfig {
 for _, n := range nodes {
 if n.id == id {
 return &n
 }
 }
 return nil
}

// === 대화형 CLI 구현 ===

func runCluster() {
 // 모든 노드 시작
 fmt.Print("\n🚀 Starting Paxos Leader Election Cluster...\n\n")

 for _, node := range nodes {
 startNode(node)
 }

 // 모든 노드가 시작될 때까지 대기 후 명령어 출력
 time.AfterFunc(1*time.Second, func() {
 fmt.Println()
 fmt.Println(strings.Repeat("=", 60))
 fmt.Println("📋 사용 가능한 명령어:")
 fmt.Println(" kill <id> - 노드 종료 (특정 노드에 장애가 발생하여 종료되는 걸 시뮬레이션)")
 fmt.Println(" start <id> - 종료된 노드 재시작")
 fmt.Println(" status - 클러스터 상태 출력")
 fmt.Println(" exit - 모든 노드 종료 및 종료")
 fmt.Println(strings.Repeat("=", 60))
 fmt.Println()
 })

 // goroutine 끼리 메세지를 주고받기 위한 채널 생성, 버퍼 크기를 1로 설정하여 수신자가 메세지를 받을 때까지 대기할 수 있도록 함
 sigChan := make(chan os.Signal, 1)
 // Ctrl+C 발생시 해당 시그널을 채널로 전달
 signal.Notify(sigChan, os.Interrupt)

 go func() {
 // 채널에서 메세지(Ctrl+C)를 받을 때까지 대기
 <-sigChan
 fmt.Print("\n\n🛑 모든 노드 종료...\n\n")
 // 모든 노드 프로세스에 SIGTERM 시그널 전송
 processesMu.Lock()
 for _, cmd := range processes {
 if cmd.Process != nil {
 cmd.Process.Signal(syscall.SIGTERM)
 }
 }
 processesMu.Unlock()
 time.Sleep(500 * time.Millisecond)
 os.Exit(0)
 }()

 // 대화형 CLI 명령어 처리
 scanner := bufio.NewScanner(os.Stdin)
 // Stdin이 종료될 때까지 한 줄씩 읽어서 처리
 for scanner.Scan() {
 line := strings.TrimSpace(scanner.Text())
 if line == "" {
 continue
 }

 parts := strings.SplitN(line, " ", 2)
 cmd := parts[0]
 arg := ""
 if len(parts) > 1 {
 arg = parts[1]
 }

 // 명령어 처리
 switch cmd {
 case "kill":
 id, err := strconv.Atoi(arg)
 if err != nil || !isValidNodeID(id) {
 fmt.Printf("잘못된 노드 ID: %s\n", arg)
 continue
 }
 killNode(id)

 case "start":
 id, err := strconv.Atoi(arg)
 if err != nil || !isValidNodeID(id) {
 fmt.Printf("잘못된 노드 ID: %s\n", arg)
 continue
 }
 processesMu.Lock()
 _, running := processes[id]
 processesMu.Unlock()
 if running {
 fmt.Printf("\n노드 %d 이미 실행 중\n\n", id)
 } else {
 nc := findNode(id)
 if nc != nil {
 startNode(*nc)
 }
 }

 case "status":
 printStatus()

 case "exit":
 fmt.Print("\n🛑 모든 노드 종료...\n\n")
 processesMu.Lock()
 for _, cmd := range processes {
 if cmd.Process != nil {
 cmd.Process.Signal(syscall.SIGTERM)
 }
 }
 processesMu.Unlock()
 time.Sleep(500 * time.Millisecond)
 os.Exit(0)

 case "help":
 fmt.Println("\n📋 사용 가능한 명령어:")
 fmt.Println(" kill <id> - 노드 종료")
 fmt.Println(" start <id> - 종료된 노드 재시작")
 fmt.Println(" status - 클러스터 상태 출력")
 fmt.Println(" exit - 모든 노드 종료 및 종료")

 default:
 fmt.Printf("알 수 없는 명령어: %s. 'help' 명령어를 사용하세요.\n\n", cmd)
 }
 }
}

map 타입

두 군데에서 map을 사용하고 있는데 타입 정의 생김새가 좀 다릅니다.

// 키 타입이 int이고, 값 타입이 string인 맵
var colors = map[int]string{
 1: "\033[36m", // 파란색 (cyan)
 2: "\033[33m", // 노란색
 3: "\033[35m", // 핑크색 (magenta)
}
...
// 키 타입이 int이고, 값 타입이 *exec.Cmd인 맵
processes = make(map[int]*exec.Cmd)

우선 배열의 인덱스 처럼 둘러싸인 타입이 키의 타입이고, 그 뒤에 붙은 타입이 값의 타입이다 하는 건 몇 번 보다보면 알 수 있습니다. 그런데 colors는 그냥 map을 생성했고, processes는 make 함수를 호출해서 생성하고 있네요?

우선 colors는 map 리터럴(literal) 방식으로 map을 생성하고 있습니다. map안에 어떤 값이 들어갈지 명시해주면서 생성하고 있죠. 그래서 이 때는 Go가 map의 생성을 암묵적으로(implicitly) 처리해줍니다. 그런데 processes는 빈 map을 생성하고 있습니다. 그래서 암묵적으로 map을 생성할 수 없고, 따라서 make 함수를 호출해서 Go가 런타임 초기화를 실행하도록 해줘야 합니다.

map은 javascript의 map, C#의 Dictionary와 같은 key-value 매핑을 저장하는 자료 구조이고 동작방식도 동일합니다. 다만, Go에서는 map을 생성하기 위해서 make 함수를 사용해야 합니다. map외에도 make 함수를 사용하는 경우는 슬라이스와 채널이 있는데요, 이 타입들은 내부적으로 해시테이블, 동적 배열, 큐 등의 자료구조를 사용하기 때문에 Go가 런타임 초기화를 실행해야 합니다. 그래서 make를 실행해야 한다고 하네요! struct나 배열, int등의 다른 기본 타입들은 make없이도 각 타입의 기본 값(zero value)으로도 충분합니다.

또 한가지 Go의 특징은 map에서 값을 찾을 때도 볼 수 있습니다.

// 맵에서 노드 프로세스 조회
cmd, exists := processes[id]

map에서 값을 조회할 때, 리턴 받을 변수를 2개 지정해주면 2번째 변수에는 map에 특정 키에 해당하는 값이 있는지 여부를 같이 리턴해주는데요, 예를 들어 타입스크립트에서는 다음과 같이 해야 합니다.

const cmd = processes.get(id);
const exists = processes.has(id);

typescript 버전과 비교하면 가독성은 떨어지는 느낌입니다. 하지만 간결하죠? 간결함을 우선하는 Go의 철학이 느껴지네요!

동시성 처리 및 lock 걸기

스레드와 고루틴 비교

각 언어와 런타임은 여러 작업을 동시에 처리하기 위해 스레드(thread)를 활용합니다. 스레드는 간단하게 말하면, 코드 실행 묶음이라고 볼 수 있는데요, CPU의 각 코어는 한 번에 하나의 스레드만 처리할 수 있습니다. 예를 들어 1번 코어가 처리 중인 스레드가 네트워크를 통해 응답이 아주 오래걸리는 요청을 처리 중이라면 어떻게 될까요? 1번 코어가 그 스레드를 계속 처리하게 둔다면 우리는 코어 1개를 낭비하는 셈이죠. OS는 이런 비효율을 참지 못합니다. 오래 걸리는 스레드는 응답이 올 때 까지 잠깐 대기 시키고 다른 스레드를 처리하게 하는 등 멀티 스레드 작업을 진행하게 하죠. 언어와 런타임은 이런 OS의 스레드 관리를 기반으로 해서 자체적인 동시성 처리 모델을 제시합니다.

다만, 이 멀티 스레드라는 게 공짜가 아닙니다. 코어가 처리해야 되는 스레드를 변경할 때는 문맥 교환(context-switching)이 발생합니다. 스레드1->스레드2로 문맥 교환되는 과정을 간략하게 살펴보면요,

커널 모드 진입*: CPU는 필요한 권한을 얻기 위해 유저 모드에서 커널 모드로 진입
스레드1의 상태 저장: CPU 레지스터, 프로그램 카운터, 스택 포인터 등 스레드1의 모든 상태를 스레드1의 메모리 블록에 기록(TCB, Thread Control Block)
스케쥴러 상태 갱신: OS가 스레드1을 대기 상태로 설정하고 스레드2를 대기 큐에서 선택
TLB/cache 초기화*: 스레드1과 스레드2가 서로 다른 프로세스의 스레드라면, TLB(translation lookaside buffer)를 초기화
스레드2의 상태 불러오기: 스레드2의 TCB에서 모든 상태를 불러오기
유저 모드로 복귀*: CPU가 유저 모드로 돌아와서 스레드2의 이전 상태로 부터 계속 실행

저도 정확하게 다 아는 건 아니지만, 어쨌든 이런 복잡한 작업을 매번 진행해야 하고 특히 * 가 붙은 부분들이 비교적 많은 시간이 걸리는 작업이라고 합니다. 게다가 또 하나의 문제점도 있습니다. 저 유명한 StackOverflow 에러를 다들 아시겠지만, OS의 스레드는 대략 1-8MB 정도의 스택 메모리를 가지는데, 스레드 내부에서 발생하는 각 로컬 변수와 함수 호출 등을 기록하기 위해서 사용하죠. 그래서 어마어마하게 큰 로컬 변수나 어마어마하게 복잡한 제귀 호출을 하다보면 띵하고 StackOverflow가 발생합니다. 그런데 Go는 이걸 조금 다르게 접근한다고 하네요.

Go는 이런 동시성 처리의 문제를 고루틴(Goroutine)으로 접근합니다. 고루틴은 OS레벨의 스레드가 아니라 각 스레드에서 스위칭해서 실행할 수 있도록 하는 일종의 경량 스레드라고 할 수 있을 거 같네요. 그리고 OS레벨의 스레드가 아니라는 건, 앞서 살펴본 문맥 교환이 발생하지 않도록 하면서도 수많은 동시성 작업을 처리할 수 있다는 말이 됩니다. 게다가 한 가지 더 장점이 있는데요, 고루틴은 스택 메모리를 유연하게 사용합니다. 매우 작게 시작해서(2-4KB) 필요에 따라 늘리고 줄일 수 있게 설계되었습니다.

그러니까 OS 레벨의 스레드를 사용하는 경우,

graph TD
subgraph OS["OS 커널 (스케줄러)"]
direction LR
OSS["OS 스케줄러<br/>모든 스레드를 직접 관리<br/>⚠️ 비싼 문맥 교환"]
end
subgraph CPU["하드웨어 (4코어)"]
C1["코어 1"]
C2["코어 2"]
C3["코어 3"]
C4["코어 4"]
end
subgraph Threads["OS 스레드 (각 1-8 MB 고정 스택)"]
T1["스레드 1<br/>📦 1 MB 스택"]
T2["스레드 2<br/>📦 1 MB 스택"]
T3["스레드 3<br/>📦 1 MB 스택"]
T4["스레드 4<br/>📦 1 MB 스택"]
T5["스레드 5<br/>📦 1 MB 스택"]
T6["스레드 6<br/>📦 1 MB 스택"]
T7["스레드 7<br/>📦 1 MB 스택"]
T8["스레드 8<br/>📦 1 MB 스택"]
end
T1 & T2 & T3 & T4 & T5 & T6 & T7 & T8 -->|"OS 문맥 교환<br/>🐌 ~1-10 μs<br/>커널 모드 전환 + 레지스터 저장<br/>+ 캐시 플러시"| OSS
OSS --> C1 & C2 & C3 & C4
style OS fill:#8b0000,color:#fff
style CPU fill:#1a3a5c,color:#fff
style Threads fill:#2e2e1a,color:#fff

스레드의 문맥 교환 비용도 막대 하지만, 스레드의 개수 * 스택 메모리 를 계산해보면, 메모리 사용량 역시 부담이 되죠.

하지만 고루틴을 사용하는 경우,

graph TD
subgraph CPU["하드웨어 (4코어)"]
C1["코어 1"]
C2["코어 2"]
C3["코어 3"]
C4["코어 4"]
end
subgraph OSThreads["OS 스레드 (코어에 고정)"]
M1["OS 스레드 1<br/>(M)"]
M2["OS 스레드 2<br/>(M)"]
M3["OS 스레드 3<br/>(M)"]
M4["OS 스레드 4<br/>(M)"]
end
C1 --- M1
C2 --- M2
C3 --- M3
C4 --- M4
subgraph GoRuntime["Go 런타임 스케줄러 (유저 공간)"]
GS["Go 스케줄러<br/>⚡ 저비용 고루틴 전환<br/>스택 포인터만 교체"]
end
M1 & M2 & M3 & M4 --> GS
subgraph Goroutines["고루틴 (초기 스택 2-4 KB, 필요시 자동 확장)"]
G1["G1 🪶"]
G2["G2 🪶"]
G3["G3 🪶"]
G4["G4 🪶"]
G5["G5 🪶"]
G6["G6 🪶"]
G7["G7 🪶"]
G8["G8 🪶"]
G9["G9 🪶"]
G10["G10 🪶"]
G11["G11 🪶"]
G12["G12 🪶"]
GN["... 100K+ 🪶"]
end
GS --> G1 & G2 & G3 & G4 & G5 & G6 & G7 & G8 & G9 & G10 & G11 & G12 & GN
style CPU fill:#1a3a5c,color:#fff
style OSThreads fill:#2e1a2e,color:#fff
style GoRuntime fill:#2d5a27,color:#fff
style Goroutines fill:#1a2e1a,color:#fff

각 고루틴은 CPU의 커널 전환 같은 문맥 교환 없이 사용할 수 있으므로 스레드 전환에 비해 50-100배 정도 빠르고 메모리 사용량도 현저히 적습니다.

위 다이어그램에서는 간단하게 설명하기 위해서 마치 Go가 코어와 OS 스레드를 1:1 매핑 시키는 것 처럼 묘사했지만, 사실은 그렇지 않습니다. Go는 GMP(Goroutine-Machine-Processor) 스케쥴러를 사용하는데요, 이 스케쥴러는 OS 스레드(M)를 코어에 1:1 매핑하지는 않습니다. 실제로는 GOMAXPROCS 설정에 따라 논리적 프로세서(P)를 생성하고, 각 P는 OS 스레드(M)에 붙어서 고루틴(G)을 실행합니다. 그러니까 코어와 OS 스레드(M)가 1:N이 될 수도 있는거죠. 또한 특정 P의 대기열이 비면, 다른 P의 대기 중인 고루틴(G)을 빼앗아 올 수도 있습니다!

Java의 Project Loom(JDK 21)에서 지원하는 Virtual Thread가 이 고루틴을 구현한 것입니다!

동시성 처리 작업에 lock 걸기

자 지금까지 미래의 저를 위해서 스레드와 고루틴을 비교해서 적어봤는데요, 어떤 방법을 사용하든 동시성을 다루다 보면 상태 값을 어떻게 공유해야 할지 문제가 생깁니다. 스레드나 고루틴은 생성 순서가 처리 순서를 보장하지 못하기 때문에 예상하지 못한 결과가 나올 수 있죠. 그래서 먼저 접근 한 쪽이 처리 우선권을 가지도록 lock을 걸 필요가 있습니다.

// 노드 프로세스 관리를 위한 맵 정의
var (
 // 키 타입이 int이고, 값 타입이 *exec.Cmd인 맵
 processes = make(map[int]*exec.Cmd)
 // 맵에 대한 동시성 접근을 위한 뮤텍스(lock)
 processesMu sync.Mutex
)
...
// 여러 goroutine에서 동시에 접근할 수 있으므로, 동시성 접근을 위해 뮤텍스를 사용
processesMu.Lock()
processes[nc.id] = cmd
processesMu.Unlock()

Mutex를 통해 lock을 획득한 고루틴만 값을 변경할 수 있도록 하고 있습니다. lock은 필요한 작업을 마치면 반드시 해제 해야 하고, lock을 거는 시간은 최소화 해야 합니다. 따라서 다음과 같은 두 가지 패턴역시 이후 살펴볼 node.go 파일에서 등장합니다.

func (node *PaxosNode) runElection() {
 node.mu.Lock()
 ...
 allNodes := make([]string, len(node.allNodes))
 /**
 * lock은 최대한 짧게 유지하는게 중요하므로 필요한 작업 이후에 해제해야 함.
 * 따라서 이후 작업에 사용할 node.allNodes를 로컬 변수에 복사하여 사용.
 */
 copy(allNodes, node.allNodes)
 majority := node.majority
 nodeID := node.nodeID
 // lock 해제
 node.mu.Unlock()

 // 함수 종료시 리더 선출 상태를 초기화하기 위해 defer 처리
 defer func() {
 node.mu.Lock()
 node.electionInProgress = false
 node.mu.Unlock()
 }()
 ...
}

lock이 필요한 최소한의 작업을 진행하고 그 값을 로컬 변수에 복사. 그리고 lock을 해제하고, 이후의 작업에서는 복사한 로컬 변수로 현재 상태에 대한 작업 진행
함수 종료시 실행되어야 하는 작업을 defer로 감싸고 lock을 통해 상태 값을 변경

채널

채널은 고루틴끼리 서로 메세지를 주고 받을 수 있는 메세지 큐 같은 자료구조입니다. 이 코드에서는 다음과 같이 사용되고 있습니다.

func runCluster() {
 ...
 // goroutine 끼리 메세지를 주고받기 위한 채널 생성, 버퍼 크기를 1로 설정하여 수신자가 메세지를 받을 때까지 대기할 수 있도록 함
 sigChan := make(chan os.Signal, 1)
 // Ctrl+C 발생시 해당 시그널을 채널로 전달
 signal.Notify(sigChan, os.Interrupt)

 go func() {
 // 채널에서 메세지(Ctrl+C)를 받을 때까지 대기
 <-sigChan
 fmt.Print("\n\n🛑 모든 노드 종료...\n\n")
 // 모든 노드 프로세스에 SIGTERM 시그널 전송
 processesMu.Lock()
 for _, cmd := range processes {
 if cmd.Process != nil {
 cmd.Process.Signal(syscall.SIGTERM)
 }
 }
 processesMu.Unlock()
 time.Sleep(500 * time.Millisecond)
 os.Exit(0)
 }()
 ...
}

runCluster를 실행하는 메인 고루틴에서 프로그램 종료 시그널을 수신하면, 해당 시그널을 채널을 통해 고루틴에게 전송합니다. 그리고 시그널을 받은(<-sigChan) 고루틴은 각 프로세스에 종료 시그널을 전송해서 모든 노드가 종료될 수 있도록 합니다.

여기서 주목할 점은 채널을 생성할 때 버퍼 크기를 1로 설정해준 부분입니다. 만약 버퍼 크기가 없다면, 채널을 통해 전송한 메세지는 그 즉시 수신되어야 하며 수신자가 없다면 메세지를 전송한 고루틴은 수신자가 나타날 때 까지 계속 대기 하게됩니다. 그리고 만약 모든 고루틴이 메세지를 수신할 수 없는 상황이 된다면 deadlock이 발생하여 종료됩니다. 이후 node.go 파일에서 좀 더 다양한 채널의 사용 예시가 등장합니다!

즉시 실행 익명 함수(IIFE)로 defer 보장

printStatus 함수를 보면, 클러스터의 상태를 조회하기 위해 각 노드에 상태 조회 api 요청을 전송합니다. 그리고 api 응답을 닫기(close) 위해 defer를 사용하는데요, 이 작업이 항상 실행되도록 보장하기 위해 즉시 실행되는 익명 함수(IIFE, Immediately Invoked Function Express)를 사용하고 있습니다.

// 클러스터 상태 출력 함수
func printStatus() {
 fmt.Println("\n=== 클러스터 상태 ===")

 // 타임아웃이 1초인 http.Client 생성
 client := &http.Client{Timeout: 1 * time.Second}

 for _, node := range nodes {
 // 즉시 실행되는 익명 함수. 함수 종료시 defer 처리된 리소스 해제
 func() {
 url := fmt.Sprintf("http://localhost:%d/status", node.port)
 resp, err := client.Get(url)
 color := colors[node.id]

 if err != nil {
 fmt.Printf("%s 노드 %d: 다운%s\n", color, node.id, colorReset)
 return
 }
 // err 발생시 resp는 nil. 따라서 err 체크 후 defer 처리가 일반적인 방법.
 defer resp.Body.Close()

 var data StatusResponse
 // resp.Body를 JSON -> StatusResponse 타입으로 변환; 그리고 err 발생시 처리
 if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
 fmt.Printf("%s 노드 %d: (응답 파싱 실패)%s\n", color, node.id, colorReset)
 return
 }
 ...
 }()
 }
}

각 API 요청을 IIFE로 감싸면서 해당 함수가 끝날 때 defer된 defer resp.Body.Close() 가 실행될 수 있도록 하고 있습니다.

웹 서버 노드 구현

이제 웹 서버 노드의 구현을 확인해보겠습니다. 우선 node.go의 전체 코드는 다음과 같습니다.

package main

import (
 "bytes"
 "context"
 "encoding/json"
 "fmt"
 "math/rand/v2"
 "net/http"
 "os"
 "os/signal"
 "strconv"
 "strings"
 "sync"
 "syscall"
 "time"
)

// === 타입 정의 ===

type PrepareRequest struct {
 ProposalNumber int `json:"proposalNumber"`
}

type PrepareResponse struct {
 Promise bool `json:"promise"`
 AcceptedProposal *int `json:"acceptedProposal"`
 AcceptedValue *int `json:"acceptedValue"`
}

type AcceptRequest struct {
 ProposalNumber int `json:"proposalNumber"`
 Value int `json:"value"`
}

type AcceptResponse struct {
 Accepted bool `json:"accepted"`
}

type HeartbeatMessage struct {
 LeaderID int `json:"leaderId"`
 Term int `json:"term"`
}

type StatusResponse struct {
 NodeID int `json:"nodeId"`
 CurrentLeaderID *int `json:"currentLeaderId"`
 CurrentTerm int `json:"currentTerm"`
 PromisedProposal *int `json:"promisedProposal"`
 AcceptedProposal *int `json:"acceptedProposal"`
 AcceptedValue *int `json:"acceptedValue"`
 IsLeader bool `json:"isLeader"`
}

// === Paxos 노드 구조체 ===

// PaxosNode는 Paxos 노드의 모든 상태를 관리합니다.
type PaxosNode struct {
 mu sync.Mutex

 // 컨텍스트 (graceful shutdown 용도)
 ctx context.Context
 cancel context.CancelFunc

 // 설정
 nodeID int // 노드 아이디
 port int // 노드 포트
 peers []string // 통신해야 할 다른 노드의 URL 목록
 allNodes []string // 자신을 포함한 모든 노드의 URL 목록
 majority int // 다수 필요 개수 (전체 노드 수 / 2 + 1)

 // === Paxos Acceptor 상태 변수들 ===
 promisedProposal *int // 약속한 제안 번호 (nil = 아직 약속 없음)
 acceptedProposal *int // 수락된 제안 번호 (nil = 아직 수락 없음)
 acceptedValue *int // 수락된 값(리더의 노드 아이디) (nil = 아직 수락 없음)

 // === Leader 상태와 Heartbeat ===
 currentLeaderID *int // 현재 리더 아이디 (nil = 리더 없음)
 currentTerm int // 현재 턴
 electionRound int // 선거 라운드

 // === 타이머 ===
 heartbeatStop chan struct{} // 리더의 하트비트 전송 중지 시그널
 electionTimer *time.Timer // 하트비트 타임아웃 감시 타이머 (3~5초, 리더는 선출 후 중지)
 nextElectionTimer *time.Timer // 다음 선거 시작 타이머
 electionInProgress bool // 선거 진행 중 플래그 (동시 선거 방지)

 // HTTP 클라이언트
 httpClient *http.Client
}

// newPaxosNode는 새로운 Paxos 노드를 생성합니다.
// cli 매개변수로 전달받은 노드 아이디, 포트, 통신해야 할 다른 노드의 URL 목록 등의 값을 변수에 저장
func newPaxosNode(ctx context.Context, nodeID, port int, peers []string) *PaxosNode {
 ctx, cancel := context.WithCancel(ctx)
 selfURL := fmt.Sprintf("http://localhost:%d", port)
 allNodes := append([]string{selfURL}, peers...)
 majority := len(allNodes)/2 + 1

 return &PaxosNode{
 ctx: ctx,
 cancel: cancel,
 nodeID: nodeID,
 port: port,
 peers: peers,
 allNodes: allNodes,
 majority: majority,
 httpClient: &http.Client{Timeout: 1 * time.Second},
 }
}

// intPtr는 int를 *int로 변환하는 헬퍼 함수입니다.
func intPtr(v int) *int {
 return &v
}

// ceilDiv는 올림 나눗셈을 수행합니다.
func ceilDiv(a, b int) int {
 return (a + b - 1) / b
}

// === Paxos Proposer 로직 ===

// runElection은 리더 선출 시작
func (node *PaxosNode) runElection() {
 node.mu.Lock()
 // 이미 리더 선출 중인 경우
 if node.electionInProgress {
 node.mu.Unlock()
 // 리더 선출 중단
 return
 }
 node.electionInProgress = true

 // 제안 번호가 이미 있는 것보다 큰지 확인
 if node.promisedProposal != nil {
 /**
 * 이전에 약속된 제안 번호가 있는 경우, 라운드 조정(다른 노드가 이미 제안한 제안 번호보다 높은 제안 번호를 사용하도록 함)
 *
 * ex: max(0, ceilDiv(6, 3)) = max(0, 2) = 2
 */
 node.electionRound = max(node.electionRound, ceilDiv(*node.promisedProposal, len(node.allNodes)))
 }
 node.electionRound++

 /**
 * 제안 번호 = 노드 아이디 + (라운드 * 노드 개수) -> 각 라운드 마다 노드의 제안 번호의 고유성을 보장하기 위함
 *
 * 예를 들어, 노드 1, 2, 3이 있고, 라운드가 1인 경우,
 * 노드 1, 라운드 1: 1 + (1 * 3) = 4
 * 노드 2, 라운드 1: 2 + (1 * 3) = 5
 * 노드 3, 라운드 1: 3 + (1 * 3) = 6
 * 노드 1, 라운드 2: 1 + (2 * 3) = 7
 * 노드 2, 라운드 2: 2 + (2 * 3) = 8
 * 노드 3, 라운드 2: 3 + (2 * 3) = 9
 * ...
 */
 proposalNumber := node.nodeID + (node.electionRound * len(node.allNodes))
 allNodes := make([]string, len(node.allNodes))
 /**
 * lock은 최대한 짧게 유지하는게 중요하므로 필요한 작업 이후에 해제해야 함.
 * 따라서 이후 작업에 사용할 node.allNodes를 로컬 변수에 복사하여 사용.
 */
 copy(allNodes, node.allNodes)
 majority := node.majority
 nodeID := node.nodeID
 // lock 해제
 node.mu.Unlock()

 // 함수 종료시 리더 선출 상태를 초기화하기 위해 defer 처리
 defer func() {
 node.mu.Lock()
 node.electionInProgress = false
 node.mu.Unlock()
 }()

 fmt.Printf("\n[노드 %d] 🗳️ 리더 선출 시작 / 제안 번호 #%d\n", nodeID, proposalNumber)

 // === Phase 1: PREPARE 요청 전송 ===
 fmt.Printf("[노드 %d] Phase 1: 모든 노드에 PREPARE 요청 전송...\n", nodeID)

 type prepareResult struct {
 resp *PrepareResponse
 err error
 }
 results := make([]prepareResult, len(allNodes))
 var wg sync.WaitGroup

 // 자신을 포함한 모든 노드에 PREPARE 요청 전송
 for i, nodeURL := range allNodes {
 wg.Add(1)
 go func(idx int, url string) {
 defer wg.Done()
 resp, err := node.sendPrepare(url, proposalNumber)
 results[idx] = prepareResult{resp: resp, err: err}
 }(i, nodeURL)
 }
 wg.Wait()

 // PREPARE 요청 결과 처리 - 약속을 받은 것들만 추출
 var promises []PrepareResponse
 for _, r := range results {
 if r.err == nil && r.resp != nil && r.resp.Promise {
 promises = append(promises, *r.resp)
 }
 }

 fmt.Printf("[노드 %d] Phase 1: 약속을 받은 노드 %d/%d 개 (필요 %d 개)\n",
 nodeID, len(promises), len(allNodes), majority)

 if len(promises) < majority {
 fmt.Printf("[노드 %d] ❌ Phase 1 실패: 약속을 받은 노드가 다수 필요 개수보다 적습니다. 리더 선출을 중단하고 다음 선거 시작.\n", nodeID)
 node.scheduleNextElection()
 return
 }

 // 수락된 값 중 가장 높은 값을 채택, 없으면 자신을 제안
 proposedValue := nodeID
 highestAcceptedProposal := -1

 for _, p := range promises {
 // 수락된 값 중 가장 높은 값을 채택
 if p.AcceptedProposal != nil && *p.AcceptedProposal > highestAcceptedProposal {
 highestAcceptedProposal = *p.AcceptedProposal
 proposedValue = *p.AcceptedValue
 }
 }

 if highestAcceptedProposal > -1 {
 fmt.Printf("[노드 %d] Phase 1: 이전에 수락된 값 (노드 %d) 채택 / 제안 번호 #%d\n",
 nodeID, proposedValue, highestAcceptedProposal)
 } else {
 fmt.Printf("[노드 %d] Phase 1: 이전에 수락된 값이 없으므로 자신을 제안 (노드 %d)\n", nodeID, proposedValue)
 }

 // === Phase 2: Accept ===
 fmt.Printf("[노드 %d] Phase 2: 모든 노드에 ACCEPT (값: 노드 %d) 요청 전송...\n", nodeID, proposedValue)

 type acceptResult struct {
 resp *AcceptResponse
 err error
 }
 // ACCEPT 요청 결과를 저장할 슬라이스 생성
 acceptResults := make([]acceptResult, len(allNodes))
 // 모든 작업이 완료될 때까지 대기할 WaitGroup 생성
 wg = sync.WaitGroup{}

 // 자신을 포함한 모든 노드에 ACCEPT 요청 전송, 병렬 처리
 for i, nodeURL := range allNodes {
 // 대기 그룹에 작업 1개 추가
 wg.Add(1)
 // goroutine: ACCEPT 요청 전송
 go func(idx int, url string) {
 // 작업 완료시 대기 그룹에서 작업 1개 제거
 defer wg.Done()
 resp, err := node.sendAccept(url, proposalNumber, proposedValue)
 acceptResults[idx] = acceptResult{resp: resp, err: err}
 }(i, nodeURL)
 }
 // 모든 작업이 완료될 때까지 대기
 wg.Wait()

 // ACCEPT 요청 결과 처리 - 수락된 것들 카운트
 accepts := 0
 for _, r := range acceptResults {
 if r.err == nil && r.resp != nil && r.resp.Accepted {
 accepts++
 }
 }

 fmt.Printf("[노드 %d] Phase 2: 수락된 노드 %d/%d 개 (필요 %d 개)\n",
 nodeID, accepts, len(allNodes), majority)

 if accepts >= majority {
 fmt.Printf("[노드 %d] ✅ 리더 선출 성공! 노드 %d 가 리더가 되었습니다. (제안 번호 %d)\n",
 nodeID, proposedValue, proposalNumber)

 if proposedValue == nodeID {
 fmt.Printf("[노드 %d] 👑 나는 리더!\n", nodeID)
 // 리더는 자신의 선출 타임아웃을 중지 (팔로워만 타임아웃을 감시)
 node.mu.Lock()
 if node.electionTimer != nil {
 node.electionTimer.Stop()
 }
 node.mu.Unlock()
 node.startHeartbeat(proposalNumber)
 }
 } else {
 fmt.Printf("[노드 %d] ❌ Phase 2 실패: 수락된 노드가 다수 필요 개수보다 적습니다. 리더 선출을 중단하고 다음 선거 시작.\n", nodeID)
 node.scheduleNextElection()
 }
}

func (node *PaxosNode) sendPrepare(url string, proposalNumber int) (*PrepareResponse, error) {
 body, err := json.Marshal(PrepareRequest{ProposalNumber: proposalNumber})
 if err != nil {
 return nil, fmt.Errorf("marshal prepare request: %w", err)
 }

 req, err := http.NewRequestWithContext(node.ctx, "POST", url+"/paxos/prepare", bytes.NewReader(body))
 if err != nil {
 return nil, fmt.Errorf("create prepare request: %w", err)
 }
 req.Header.Set("Content-Type", "application/json")

 resp, err := node.httpClient.Do(req)
 if err != nil {
 return nil, fmt.Errorf("send prepare to %s: %w", url, err)
 }
 defer resp.Body.Close()

 if resp.StatusCode != http.StatusOK {
 return nil, fmt.Errorf("prepare request to %s returned status %d", url, resp.StatusCode)
 }

 var result PrepareResponse
 if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
 return nil, fmt.Errorf("decode prepare response from %s: %w", url, err)
 }

 return &result, nil
}

func (node *PaxosNode) sendAccept(url string, proposalNumber, value int) (*AcceptResponse, error) {
 body, err := json.Marshal(AcceptRequest{ProposalNumber: proposalNumber, Value: value})
 if err != nil {
 return nil, fmt.Errorf("marshal accept request: %w", err)
 }

 req, err := http.NewRequestWithContext(node.ctx, "POST", url+"/paxos/accept", bytes.NewReader(body))
 if err != nil {
 return nil, fmt.Errorf("create accept request: %w", err)
 }
 req.Header.Set("Content-Type", "application/json")

 resp, err := node.httpClient.Do(req)
 if err != nil {
 return nil, fmt.Errorf("send accept to %s: %w", url, err)
 }
 defer resp.Body.Close()

 if resp.StatusCode != http.StatusOK {
 return nil, fmt.Errorf("accept request to %s returned status %d", url, resp.StatusCode)
 }

 var result AcceptResponse
 if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
 return nil, fmt.Errorf("decode accept response from %s: %w", url, err)
 }

 return &result, nil
}

func (node *PaxosNode) sendHeartbeat(url string, leaderID, term int) error {
 body, err := json.Marshal(HeartbeatMessage{LeaderID: leaderID, Term: term})
 if err != nil {
 return fmt.Errorf("marshal heartbeat: %w", err)
 }

 req, err := http.NewRequestWithContext(node.ctx, "POST", url+"/leader/heartbeat", bytes.NewReader(body))
 if err != nil {
 return fmt.Errorf("create heartbeat request: %w", err)
 }
 req.Header.Set("Content-Type", "application/json")

 resp, err := node.httpClient.Do(req)
 if err != nil {
 return fmt.Errorf("send heartbeat to %s: %w", url, err)
 }
 defer resp.Body.Close()

 return nil
}

// 리더가 자신을 생존을 알리는 하트비트 전송을 시작하는 함수 (리더만 실행)
func (node *PaxosNode) startHeartbeat(term int) {
 node.mu.Lock()
 // 기존 하트비트 중지 (TOCTOU 경합 방지를 위해 인라인 처리)
 if node.heartbeatStop != nil {
 // 기존 하트비트 채널 종료
 close(node.heartbeatStop)
 }
 // 데이터는 없이 신호만 수신할 채널 생성
 stopCh := make(chan struct{})
 node.heartbeatStop = stopCh
 node.mu.Unlock()

 // goroutine: 각 채널의 메세지 수신 및 처리
 go func() {
 // 1초 간격 타이머 채널 생성
 ticker := time.NewTicker(1 * time.Second)
 // goroutine 종료시 타이머 종료
 defer ticker.Stop()

 for { // 종료될 때까지 무한 반복하는 이벤트 루프
 // 각 채널에서 수신되는 신호를 대기하며, 수신된 신호에 따라 동작 결정(select)
 select {
 case <-stopCh: // 하트비트 중지 신호
 return
 case <-node.ctx.Done(): // context 취소 신호
 return
 case <-ticker.C: // 1초 간격 타이머 채널 신호
 fmt.Printf("[노드 %d] 💓 하트비트 전송 (턴 %d)\n", node.nodeID, term)

 node.mu.Lock()
 // 이후 작업에 사용할 node.peers를 로컬 변수에 복사하여 사용
 peers := make([]string, len(node.peers))
 copy(peers, node.peers)
 // lock 해제
 node.mu.Unlock()

 // 자신(리더)를 제외한 나머지 노드에 하트비트 전송
 for _, peerURL := range peers {
 // goroutine: 하트비트 전송
 go func(url string) {
 _ = node.sendHeartbeat(url, node.nodeID, term)
 }(peerURL)
 }
 }
 }
 }()
}

// 하트비트 중지 처리 함수
func (node *PaxosNode) stopHeartbeat() {
 node.mu.Lock()
 if node.heartbeatStop != nil {
 close(node.heartbeatStop)
 node.heartbeatStop = nil
 }
 node.mu.Unlock()
}

// 모든 타이머와 하트비트를 정리하고 context를 취소하는 함수
func (node *PaxosNode) shutdown() {
 node.mu.Lock()
 if node.electionTimer != nil {
 node.electionTimer.Stop()
 }
 if node.nextElectionTimer != nil {
 node.nextElectionTimer.Stop()
 }
 node.mu.Unlock()
 node.stopHeartbeat()
 node.cancel()
}

// 리더 선출 타임아웃 리셋 처리 함수
//
// 타임아웃 이후, 리더가 없으면 리더 선출 시작
func (node *PaxosNode) resetElectionTimeout() {
 node.mu.Lock()
 defer node.mu.Unlock()

 if node.electionTimer != nil {
 // 기존 리더 선출 타이머 중지
 node.electionTimer.Stop()
 }

 // 리더 선출 타임아웃 랜덤 적용 (3-5초)
 timeout := 3*time.Second + time.Duration(rand.Float64()*2000)*time.Millisecond

 // goroutine: 리더 선출 타임아웃 타이머 설정
 node.electionTimer = time.AfterFunc(timeout, func() {
 fmt.Printf("[노드 %d] ⏰ 하트비트 타임아웃 - 리더 없음 감지, 리더 선출 시작...\n", node.nodeID)

 node.mu.Lock()
 node.currentLeaderID = nil
 // 현재 리더로 선출된 노드가 서비스 다운되는 경우에 해당 노드는 리더 선출에서 제외되어야 함
 // 따라서 수락된 상태를 리셋하여 진행하며, 각 리더 선출은 사실상 새로운 Paxos 인스턴스가 되도록 함
 node.acceptedProposal = nil
 node.acceptedValue = nil
 node.mu.Unlock()

 node.runElection()
 })
}

// 다음 리더 선출 예약 처리 함수
func (node *PaxosNode) scheduleNextElection() {
 node.mu.Lock()
 defer node.mu.Unlock()

 if node.nextElectionTimer != nil {
 // 기존 다음 리더 선출 타이머 중지
 node.nextElectionTimer.Stop()
 }

 // 다음 선거 시작 전 랜덤 딜레이 적용
 delay := 2*time.Second + time.Duration(rand.Float64()*3000)*time.Millisecond

 // goroutine: 다음 리더 선출 타이머 설정
 node.nextElectionTimer = time.AfterFunc(delay, func() {
 node.mu.Lock()
 hasLeader := node.currentLeaderID != nil
 node.mu.Unlock()

 // 현재 리더가 없으면 다음 선거 시작
 if !hasLeader {
 node.runElection()
 }
 })
}

// === HTTP 핸들러들 ===

// Paxos Phase 1: Prepare 요청 처리 함수
func (node *PaxosNode) handlePrepare(w http.ResponseWriter, r *http.Request) {
 // 요청 본문을 JSON -> PrepareRequest 타입으로 변환; 그리고 err 발생시 처리
 var req PrepareRequest
 if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 http.Error(w, "bad request", http.StatusBadRequest)
 return
 }

 node.mu.Lock()
 fmt.Printf("[노드 %d] PREPARE 요청 수신 / 제안 번호 #%d\n", node.nodeID, req.ProposalNumber)

 // 함수 내부에서만 쓰이므로 포인터(*) 없이 사용
 var resp PrepareResponse

 if node.promisedProposal == nil || req.ProposalNumber > *node.promisedProposal {
 node.promisedProposal = intPtr(req.ProposalNumber)
 // 수락된 상태를 리셋하여 진행하며, 각 리더 선출은 사실상 새로운 Paxos 인스턴스가 되도록 함(죽은 리더 재선출 방지)
 node.acceptedProposal = nil
 node.acceptedValue = nil

 fmt.Printf("[노드 %d] → 제안 번호 #%d 약속\n", node.nodeID, req.ProposalNumber)
 resp = PrepareResponse{Promise: true, AcceptedProposal: nil, AcceptedValue: nil}
 } else {
 fmt.Printf("[노드 %d] → 이미 약속한 제안 번호 #%d 거절\n", node.nodeID, *node.promisedProposal)
 resp = PrepareResponse{Promise: false, AcceptedProposal: nil, AcceptedValue: nil}
 }
 node.mu.Unlock()

 w.Header().Set("Content-Type", "application/json")
 if err := json.NewEncoder(w).Encode(resp); err != nil {
 fmt.Printf("[노드 %d] 응답 쓰기 실패: %v\n", node.nodeID, err)
 }
}

// Paxos Phase 2: ACCEPT 요청 처리 함수
func (node *PaxosNode) handleAccept(w http.ResponseWriter, r *http.Request) {
 var req AcceptRequest
 if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 http.Error(w, "bad request", http.StatusBadRequest)
 return
 }

 node.mu.Lock()
 fmt.Printf("[노드 %d] ACCEPT 요청 수신 / 제안 번호 #%d, 값: 노드 %d\n",
 node.nodeID, req.ProposalNumber, req.Value)

 var resp AcceptResponse

 // 약속된 제안 번호가 없거나, 현재 제안 번호가 약속된 제안 번호보다 크거나 같으면 수락
 if node.promisedProposal == nil || req.ProposalNumber >= *node.promisedProposal {
 // 약속된 제안 번호 갱신
 node.promisedProposal = intPtr(req.ProposalNumber)
 // 수락된 제안 번호 갱신
 node.acceptedProposal = intPtr(req.ProposalNumber)
 // 수락된 값 갱신(리더의 노드 아이디)
 node.acceptedValue = intPtr(req.Value)
 // 현재 리더 아이디 갱신
 node.currentLeaderID = intPtr(req.Value)
 // 현재 턴 갱신
 node.currentTerm = req.ProposalNumber

 fmt.Printf("[노드 %d] → 수락! 새로운 리더: 노드 %d (제안 번호 %d)\n",
 node.nodeID, req.Value, req.ProposalNumber)

 // 리더가 아니라면 하트비트 중지
 shouldStopHeartbeat := req.Value != node.nodeID
 node.mu.Unlock()

 if shouldStopHeartbeat {
 node.stopHeartbeat()
 }

 // 리더 선출 타임아웃 리셋
 node.resetElectionTimeout()

 resp = AcceptResponse{Accepted: true}
 } else {
 fmt.Printf("[노드 %d] → 이미 약속한 제안 번호 #%d 거절\n",
 node.nodeID, *node.promisedProposal)
 node.mu.Unlock()
 resp = AcceptResponse{Accepted: false}
 }

 w.Header().Set("Content-Type", "application/json")
 if err := json.NewEncoder(w).Encode(resp); err != nil {
 fmt.Printf("[노드 %d] 응답 쓰기 실패: %v\n", node.nodeID, err)
 }
}

// 리더가 전송하는 하트비트 수신 처리 함수
func (node *PaxosNode) handleHeartbeat(w http.ResponseWriter, r *http.Request) {
 var msg HeartbeatMessage
 if err := json.NewDecoder(r.Body).Decode(&msg); err != nil {
 http.Error(w, "bad request", http.StatusBadRequest)
 return
 }

 node.mu.Lock()
 // 새로운 턴이 시작되었다면,
 shouldReset := msg.Term >= node.currentTerm
 if shouldReset {
 // 새로운 리더가 등장했다면,
 if node.currentLeaderID == nil || *node.currentLeaderID != msg.LeaderID {
 fmt.Printf("[노드 %d] 💓 새로운 리더로부터 하트비트 수신 / 리더: 노드 %d (턴 %d)\n",
 node.nodeID, msg.LeaderID, msg.Term)
 }

 // 현재 리더 아이디 갱신
 node.currentLeaderID = intPtr(msg.LeaderID)
 // 현재 턴 갱신
 node.currentTerm = msg.Term
 }
 node.mu.Unlock()

 /**
 * 리더 선출 타임아웃 리셋(타임아웃 이후, 리더가 없으면 리더 선출 시작)
 *
 * 리더의 하트비트가 안정적으로 수신된다면, 리더 선출의 타임아웃은 계속 리셋된다. -> 현재 상태 유지.
 * 현재 턴 이상의 하트비트만 타임아웃 리셋 (오래된 리더의 하트비트는 무시)
 */
 if shouldReset {
 node.resetElectionTimeout()
 }

 w.Header().Set("Content-Type", "application/json")
 if err := json.NewEncoder(w).Encode(map[string]bool{"ok": true}); err != nil {
 fmt.Printf("[노드 %d] 응답 쓰기 실패: %v\n", node.nodeID, err)
 }
}

// 상태 조회 엔드포인트 처리 함수
func (node *PaxosNode) handleStatus(w http.ResponseWriter, r *http.Request) {
 node.mu.Lock()
 isLeader := node.currentLeaderID != nil && *node.currentLeaderID == node.nodeID
 resp := StatusResponse{
 NodeID: node.nodeID,
 CurrentLeaderID: node.currentLeaderID,
 CurrentTerm: node.currentTerm,
 PromisedProposal: node.promisedProposal,
 AcceptedProposal: node.acceptedProposal,
 AcceptedValue: node.acceptedValue,
 IsLeader: isLeader,
 }
 node.mu.Unlock()

 w.Header().Set("Content-Type", "application/json")
 if err := json.NewEncoder(w).Encode(resp); err != nil {
 fmt.Printf("[노드 %d] 응답 쓰기 실패: %v\n", node.nodeID, err)
 }
}

// === 메인 함수 ===

func runNode() {
 if len(os.Args) < 4 {
 fmt.Println("Usage: go run . node <id> <port> <peers...>")
 os.Exit(1)
 }

 nodeID, err := strconv.Atoi(os.Args[2])
 if err != nil {
 fmt.Fprintf(os.Stderr, "invalid node ID %q: %v\n", os.Args[2], err)
 os.Exit(1)
 }

 port, err := strconv.Atoi(os.Args[3])
 if err != nil {
 fmt.Fprintf(os.Stderr, "invalid port %q: %v\n", os.Args[3], err)
 os.Exit(1)
 }

 peers := os.Args[4:]

 ctx := context.Background()
 node := newPaxosNode(ctx, nodeID, port, peers)

 fmt.Printf("[노드 %d] 시작 with 통신해야 할 다른 노드의 URL 목록: %s\n",
 nodeID, strings.Join(peers, ", "))
 fmt.Printf("[노드 %d] 다수 필요: %d 중 %d 이상\n",
 nodeID, len(node.allNodes), node.majority)

 mux := http.NewServeMux()
 mux.HandleFunc("POST /paxos/prepare", node.handlePrepare)
 mux.HandleFunc("POST /paxos/accept", node.handleAccept)
 mux.HandleFunc("POST /leader/heartbeat", node.handleHeartbeat)
 mux.HandleFunc("GET /status", node.handleStatus)

 server := &http.Server{
 Addr: fmt.Sprintf(":%d", port),
 Handler: mux,
 }

 go func() {
 fmt.Printf("[노드 %d] 🚀 포트 %d에서 수신 중...\n", nodeID, port)
 if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
 fmt.Printf("[노드 %d] 서버 에러: %v\n", nodeID, err)
 os.Exit(1)
 }
 }()

 // 리더 선출 예약(랜덤 딜레이 적용)
 delay := 1*time.Second + time.Duration(rand.Float64()*2000)*time.Millisecond
 fmt.Printf("[노드 %d] 리더 조회 전 %dms 대기...\n", nodeID, delay.Milliseconds())

 // 랜덤 딜레이 이후, 리더가 없으면 리더 선출 시작
 time.AfterFunc(delay, func() {
 node.mu.Lock()
 hasLeader := node.currentLeaderID != nil
 node.mu.Unlock()

 if !hasLeader {
 fmt.Printf("[노드 %d] 리더 없음, 리더 선출 시작...\n", nodeID)
 node.runElection()
 }
 })

 // 리더 선출 타임아웃 리셋(타임아웃 이후, 리더가 없으면 리더 선출 시작)
 node.resetElectionTimeout()

 sigChan := make(chan os.Signal, 1)
 signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
 <-sigChan

 fmt.Printf("[노드 %d] 종료 중...\n", nodeID)
 node.shutdown()

 shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 2*time.Second)
 defer shutdownCancel()
 _ = server.Shutdown(shutdownCtx)
}

포인터를 이용한 nullable 필드(*int)

이제와서 뒷북이긴 하지만, Go는 포인터를 사용합니다! 하하하하… 그런데 정말 다행인 건 C, C++ 처럼 직접 메모리를 관리하거나 포인터 연산을 걱정할 필요는 없습니다. Go에서 포인터는 그저 모든 게 값인 세상에서 어떤 값을 참조로 사용할지 선택권을 주는 수단입니다. 포인터에 대한 자세한 설명은 다음으로 미루고, 일단 여기서는 nullable 필드를 눈 여겨 보도록 할까요?

type PaxosNode struct {
 ...
 // 설정
 nodeID int // 노드 아이디
 port int // 노드 포트
 peers []string // 통신해야 할 다른 노드의 URL 목록
 allNodes []string // 자신을 포함한 모든 노드의 URL 목록
 majority int // 다수 필요 개수 (전체 노드 수 / 2 + 1)

 // === Paxos Acceptor 상태 변수들 ===
 promisedProposal *int // 약속한 제안 번호 (nil = 아직 약속 없음)
 acceptedProposal *int // 수락된 제안 번호 (nil = 아직 수락 없음)
 acceptedValue *int // 수락된 값(리더의 노드 아이디) (nil = 아직 수락 없음)
 ...
}

똑같은 int 변수 지만 어떤 변수는 int로, 어떤 변수는 *int로 선언되었습니다. Go에서는 변수를 선언할 때 값을 선언하지 않으면 해당 변수 타입의 기본 값으로 초기화를 진행합니다. int의 경우 0이고, *int의 경우는 nil 이죠. 즉, 반드시 값이 존재하지만 초기값이 0인 변수와 값이 존재하지 않을 수도 있는 변수 를 선언하는 거죠.

모든 고루틴이 종료될 때까지 기다리는 WaitGroup

자신을 포함해서 모든 노드에 prepare를 전송하는 코드를 살펴보죠.

// === Phase 1: PREPARE 요청 전송 ===
fmt.Printf("[노드 %d] Phase 1: 모든 노드에 PREPARE 요청 전송...\n", nodeID)

type prepareResult struct {
 resp *PrepareResponse
 err error
}
results := make([]prepareResult, len(allNodes))
var wg sync.WaitGroup

// 자신을 포함한 모든 노드에 PREPARE 요청 전송 ----> 모든 요청을 병렬로 처리
for i, nodeURL := range allNodes {
 wg.Add(1) // 고루틴 시작전 ----> WaitGroup 1 증가
 go func(idx int, url string) {
 defer wg.Done() // 고루틴 종료시 작업 완료 ----> WaitGroup 1 감소
 resp, err := node.sendPrepare(url, proposalNumber)
 results[idx] = prepareResult{resp: resp, err: err}
 }(i, nodeURL)
}
wg.Wait() // 모든 작업이 완료될 때 까지 대기

각 고루틴을 실행하기 전에 Add로 작업 수를 증가시키고, 병렬로 실행되는 고루틴이 종료될 때(defer) Done으로 작업 완료 처리합니다. 그리고 Wait으로 모든 작업이 완료될 때까지 대기하게 되죠. node.js의 Promise.allSettled 와 닮았네요!

채널 select -> 채널을 위한 switch

리더가 자신의 생존을 다른 노드에게 알리는 startHeartbeat 함수를 보면, 여러 채널에서 수신되는 메세지에 따라 다른 동작을 수행하도록 하고 있습니다.

// 리더가 자신을 생존을 알리는 하트비트 전송을 시작하는 함수 (리더만 실행)
func (node *PaxosNode) startHeartbeat(term int) {
 node.mu.Lock()
 // 기존 하트비트 중지 (TOCTOU 경합 방지를 위해 인라인 처리)
 if node.heartbeatStop != nil {
 // 기존 하트비트 채널 종료
 close(node.heartbeatStop)
 }
 // 데이터는 없이 신호만 수신할 채널 생성
 stopCh := make(chan struct{})
 node.heartbeatStop = stopCh
 node.mu.Unlock()

 // goroutine: 각 채널의 메세지 수신 및 처리
 go func() {
 // 1초 간격 타이머 채널 생성
 ticker := time.NewTicker(1 * time.Second)
 // goroutine 종료시 타이머 종료
 defer ticker.Stop()

 for { // 종료될 때까지 무한 반복하는 이벤트 루프
 // 각 채널에서 수신되는 신호를 대기하며, 수신된 신호에 따라 동작 결정(select)
 select {
 case <-stopCh: // 하트비트 중지 신호
 return
 case <-node.ctx.Done(): // context 취소 신호
 return
 case <-ticker.C: // 1초 간격 타이머 채널 신호
 fmt.Printf("[노드 %d] 💓 하트비트 전송 (턴 %d)\n", node.nodeID, term)

 node.mu.Lock()
 // 이후 작업에 사용할 node.peers를 로컬 변수에 복사하여 사용
 peers := make([]string, len(node.peers))
 copy(peers, node.peers)
 // lock 해제
 node.mu.Unlock()

 // 자신(리더)를 제외한 나머지 노드에 하트비트 전송
 for _, peerURL := range peers {
 // goroutine: 하트비트 전송
 go func(url string) {
 _ = node.sendHeartbeat(url, node.nodeID, term)
 }(peerURL)
 }
 }
 }
 }()
}

// 하트비트 중지 처리 함수
func (node *PaxosNode) stopHeartbeat() {
 node.mu.Lock()
 if node.heartbeatStop != nil {
 close(node.heartbeatStop)
 node.heartbeatStop = nil
 }
 node.mu.Unlock()
}

고루틴 내부를 살펴보면 다음과 같이 동작하고 있습니다.

1초 간격의 타이머를 설정하고
무한 반복하는 이벤트 루프 시작
stopCh에 메세지가 들어오면, 이벤트 루프 중지하고 고루틴 종료
context 취소 메세지가 들어오면, 이벤트 루프 중지하고 고루틴 종료
1초 간격 타이머 메세지가 들어오면, 나머지 노드에 하트비트 전송

그리고 그 아래 stopHeartbeat를 보면 고루틴에서 수신하는 stopCh를 close 함수로 닫아버리는데요, 이렇게 하면 모든 수신자에게 중지 신호가 전달됩니다.

context.Context 로 우아한 종료(graceful shutdown)

새로운 노드를 실행하는 runNode, newPaxosNode 함수를 살펴보면, context와 해당 context를 중지시킬 수 있는 cancelFunc를 생성하여 이후 처리 과정에서 계속 사용하도록 전달하고 있습니다.

func newPaxosNode(ctx context.Context, nodeID, port int, peers []string) *PaxosNode {
 ctx, cancel := context.WithCancel(ctx) // context를 중지 시킬 수 있는 cancelFunc 생성
 selfURL := fmt.Sprintf("http://localhost:%d", port)
 allNodes := append([]string{selfURL}, peers...)
 majority := len(allNodes)/2 + 1

 return &PaxosNode{
 ctx: ctx,
 cancel: cancel, // 노드에 cancelFunc 전달
 nodeID: nodeID,
 port: port,
 peers: peers,
 allNodes: allNodes,
 majority: majority,
 httpClient: &http.Client{Timeout: 1 * time.Second},
 }
}

...

func runNode() {
 ...
 ctx := context.Background()
 node := newPaxosNode(ctx, nodeID, port, peers)
 ...
}

// 모든 타이머와 하트비트를 정리하고 context를 취소하는 함수
func (node *PaxosNode) shutdown() {
 ...
 node.cancel() // 노드 중지시 cancelFunc를 실행하여 모든 작업 중지
}

그리고 shutdown 함수를 보면, 노드의 cancelFunc를 실행하여 해당 context와 관련된 모든 작업(http 요청, 타이머, 고루틴 등)을 중지하도록 하고 있습니다.

참고자료

Tucker의 Go 언어 프로그래밍, 공봉식, 골든래빗
요즘 개발자를 위한 시스템 설계 수업. 디렌드라 신하, 테자스 초프라 저. 길벗
CLAUDE

분산 시스템 설계(1) - Paxos 알고리즘

Sat, 14 Feb 2026 10:05:42 +0900

분산 시스템이란?

오래전 시스템은 메인 프레임으로 대표되는 중앙 시스템으로 구성되었습니다. 메인 프레임에 터미널로 연결해서 각자의 작업을 진행했었죠.

(IBM의 701 메인프레임 컴퓨터와 콘솔, 출처: IBM)

그런데 메인 프레임은 엄청난 덩치 뿐만 아니라 취약한 문제가 있었습니다. 메인 프레임이 고장나면 모든 사용자들이 장애의 영향을 받았던 거죠. 그래서 장애를 좀 더 유연하게 견딜 수 있는, 그리고 메인 프레임의 물리적인 한계를 넘어서 처리 용량을 확장할 수 있는 분산 시스템이 등장하기 시작합니다. 제가 기억하는 아주 유명했던 분산 시스템으로 SETI@home(Search for Extra-Terrestrial at home)이 있습니다.

(출처: https://setiathome.berkeley.edu/sah_graphics.php)

1997년에 UC 버클리에서 시작된 프로젝트로 푸에르토 리코에 위치한 아레시보 전파 망원경의 데이터를 통해 외계 생명체의 신호를 탐색하고자 했습니다. 전파 데이터가 너무 방대했기 때문에 이를 처리하기 위해 많은 컴퓨터가 필요했었는데요, 인터넷 연결이 가능한 PC를 가지고 있는 사람 누구나 프로젝트에 참여할 수 있도록 했습니다. 전세계 226개국에서 500만명 이상의 사람들이 자원해서 참여했고, 2020년 데이터 수집이 중단되었다고 합니다.

이렇게 컴퓨팅 파워의 한계와 장애 극복을 위한 분산 컴퓨팅은 계속 발전해왔고 DCOM, CORBA 등의 벤더 종속적인 기술이 등장했습니다. 그리고 SOAP 웹서비스 등의 벤더 독립적인 기술이 등장해 세상을 바꾸나 싶었지만, 찻잔 속의 태풍으로 끝이 났죠. 그리고 SOA 등의 현학적인 용어가 난무하는 시대를 지나 지금 우리는 클라우드가 보편적인 시대를 살고 있습니다. 이제는 분산 시스템이라는 말을 잘 쓰지 않긴합니다. 그게 기본이니까요.

하지만 기본이라는 말은 반대로 하면 원리를 모르는 사람들이 많다는 말도 되겠죠. 물론…. 저도 그 중에 하나입니다. 하하하하….

CAP, PACELC

분산 시스템의 유명한 이론적 정리는 CAP, PACELC가 있습니다. 우선 CAP을 볼까요?

CAP

graph TD
CAP["CAP Theorem<br/>(Brewer's Theorem, 2000)"]
CAP --> C["Consistency<br/>모든 노드가 같은 데이터를 봄"]
CAP --> A["Availability<br/>모든 요청이 응답을 받음"]
CAP --> P["Partition Tolerance<br/>네트워크 분할에도 동작"]
C ~~~ A ~~~ P
subgraph CP["CP Systems"]
CP1["MongoDB"] ~~~ CP2["HBase"] ~~~ CP3["Redis Cluster"]
end
subgraph AP["AP Systems"]
AP1["Cassandra"] ~~~ AP2["DynamoDB"] ~~~ AP3["CouchDB"]
end
subgraph CA["CA Systems (이론적)"]
CA1["Traditional RDBMS<br/>(single node)"]
end
C --> CP
P --> CP
A --> AP
P --> AP
C --> CA
A --> CA
style C fill:#ff9999,stroke:#333
style A fill:#99cc99,stroke:#333
style P fill:#9999ff,stroke:#333
style CP fill:#ffcccc,stroke:#333
style AP fill:#ccffcc,stroke:#333
style CA fill:#ccccff,stroke:#333
style CAP fill:#ffffcc,stroke:#333

Consistency, Availability, Partition Tolerance 이 세가지 요소 중에서 2가지를 선택해야 한다는 게 CAP 이론입니다. 하지만 이 이론에는 함정이 있는데요, 세상에 장애가 발생하지 않은 완벽한 네트워크는 없으므로 반드시 Partition Tolerance는 챙겨야 하기 때문에 CP 또는 AP 둘 중의 하나로 강제된다는 거죠. 그리고 요즘 대세인 결과적 일관성(Eventual Consistency)의 경우 AP에 해당하기는 하지만 일관성(C)을 포기한 건 아니므로 엄밀히 말하면 CAP의 이분법적 분류로는 정확히 설명하기 어렵다는 문제가 있습니다.

PACELC

그래서 대안적으로 제시된 게 PACELC 입니다.

graph TD
PACELC["PACELC Theorem<br/>(Daniel Abadi, 2012)"]
PACELC --> Q{"네트워크 Partition<br/>발생?"}
Q -->|"Yes (P)"| PAC{"Partition 상황"}
Q -->|"No (E)"| ELC{"정상 상황 (Else)"}
PAC -->|"Choose"| PA["Availability<br/>가용성 우선"]
PAC -->|"Choose"| PC["Consistency<br/>일관성 우선"]
ELC -->|"Choose"| EL["Latency<br/>낮은 지연 우선"]
ELC -->|"Choose"| EC["Consistency<br/>일관성 우선"]
subgraph PA_EC["PA/EC Systems"]
direction LR
S1["DynamoDB"] ~~~ S2["Cassandra"] ~~~ S3["CouchDB"]
end
subgraph PA_EL["PA/EL Systems"]
direction LR
S4["Cassandra (tunable)"] ~~~ S5["Riak"]
end
subgraph PC_EC["PC/EC Systems"]
direction LR
S6["MongoDB"] ~~~ S7["HBase"] ~~~ S8["BigTable"]
end
subgraph PC_EL["PC/EL Systems"]
direction LR
S9["PNUTS (Yahoo)"]
end
PA --> PA_EC
PA --> PA_EL
PC --> PC_EC
PC --> PC_EL
EC --> PA_EC
EC --> PC_EC
EL --> PA_EL
EL --> PC_EL
style PACELC fill:#ffffcc,stroke:#333
style Q fill:#fff0e0,stroke:#333
style PAC fill:#ffdddd,stroke:#333
style ELC fill:#ddddff,stroke:#333
style PA fill:#ff9999,stroke:#333
style PC fill:#99ccff,stroke:#333
style EL fill:#99ff99,stroke:#333
style EC fill:#cc99ff,stroke:#333
style PA_EC fill:#ffe0f0,stroke:#333
style PA_EL fill:#e0ffe0,stroke:#333
style PC_EC fill:#e0e0ff,stroke:#333
style PC_EL fill:#fff0e0,stroke:#333

선택지는 다음과 같습니다.

네트워크 장애시(P) -> 가용성(A)이냐 일관성(C)이냐.
정상 상황(E)에서 -> 일관성(C)이냐 낮은 지연(L)이냐.

예를 들면 이번에 알아볼 Paxos 알고리즘은 PC/EC 에 해당합니다.

네트워크 장애시(P) -> 다수의 노드는 동작하지만, 소수의 노드는 동작을 멈춘다. 따라서 일관성(C)을 가용성(A)보다 우선한다.
정상 상황(E)에서 -> 다수의 노드 간에 합의 과정을 거치는데 이 과정에서 보다 많은 지연시간이 발생한다. 따라서 일관성(C)을 낮은 지연(L)보다 우선한다.

Paxos 알고리즘

앞선 정리에서 볼 수 있듯이 Paxos 알고리즘은 합의를 통한 일관성을 가장 중요한 가치로 생각하며, 분산 시스템에서 모든 서버가 같은 상태와 결정을 공유하고 유지할 수 있는 방법을 제안합니다.

Paxos 알고리즘의 핵심 구성 요소는 다음과 같습니다.

제안자(Proposer): 제안자는 합의해야 할 값을 제안하고, 시스템의 다른 노드에 제안값을 전파합니다.
수용자(Acceptor): 제안자에게서 제안을 받고, 제안값의 수용 여부를 다른 노드에 알립니다.
학습자(Learner): 합의된 값을 수용하는 노드.

그럼 이 노드들이 어떻게 서로 합의를 진행하는지 알아볼까요?

sequenceDiagram
participant P as 제안자<br/>(Proposer)
participant A1 as 수용자 1<br/>(Acceptor)
participant A2 as 수용자 2<br/>(Acceptor)
participant A3 as 수용자 3<br/>(Acceptor)
participant L as 학습자<br/>(Learner)
Note over P, L: 📌 1단계: 준비 (Prepare)
rect rgb(220, 240, 255)
P->>A1: Prepare(N)
P->>A2: Prepare(N)
P->>A3: Prepare(N)
A1-->>P: Promise(N)
A2-->>P: Promise(N)
A3-->>P: Promise(N)
Note over P: 과반수 약속 확인 ✅
end
Note over P, L: 📌 2단계: 수락 + 학습 (Accept + Learn)
rect rgb(220, 255, 220)
P->>A1: Accept(N, 값)
P->>A2: Accept(N, 값)
P->>A3: Accept(N, 값)
par 제안자에게 수락 응답
A1-->>P: Accepted ✅
A2-->>P: Accepted ✅
A3-->>P: Accepted ✅
and 학습자에게 동시 전달
A1->>L: Accepted(N, 값)
A2->>L: Accepted(N, 값)
A3->>L: Accepted(N, 값)
end
Note over P: 과반수 수락 → 값 선택 확정 🎉
Note over L: 과반수 수락 확인 → 합의된 값 학습 완료 ✅
end

여기서 중요한 점은 1단계에서는 제안 번호(N)을 제시하고, 2단계에서 제안 번호(N)와 함께 제안 값을 전달한다는 점입니다. 하나씩 알아볼까요?

여기서는 논리적인 구분을 위해서 제안자, 수용자, 학습자를 나눠놓았지만 사실 Paxos에 참여하는 각 노드가 3개의 역할을 모두 수행하는 경우도 있습니다. 이 글의 후반부에서 관련된 예시를 다룰 예정입니다!

1단계: 준비(Prepare)

1단계에서는 제안자가 수용자들에게 자신의 제안번호(N)를 제시하며, 자신의 제안번호(N)에 대해서 ‘수락할 것을 약속해달라(promise)‘고 요청합니다.

수용자들은 제시 받은 제안번호(N)과 이전에 이미 약속한 제안번호(B)에 대해 다음과 같이 반응합니다.

이미 약속한 제안번호(B)가 존재하는가?
존재하지 않는다면, 현재의 제안번호(N)에 대해 수용할 것을 약속한다.
존재한다면, 이미 약속한 제안번호(B)과 현재의 제안번호(N)을 비교한다.
- 이미 약속한 제안번호가 더 크다면(B > N), 현재의 제안번호(N)을 거절한다.
- 현재의 제안번호(N)이 이미 약속한 제안번호(B)보다 더 크다면, 이전 약속(B)을 파기하고 현재의 제안번호(N)에 대해 수용할 것을 약속한다.

flowchart TD
START([수용자가 제안 수신<br/>Prepare N]) --> CHECK{이미 약속한<br/>제안 번호 B가<br/>존재하는가?}
CHECK -->|존재하지 않음| ACCEPT_NEW[✅ 현재 제안 번호 N에 대해<br/>수용할 것을 약속<br/>Promise N]
CHECK -->|존재함| COMPARE{현재 제안 번호 N과<br/>이미 약속한 제안 번호 B<br/>비교}
COMPARE -->|B > N<br/>이미 약속한 번호가 더 큼| REJECT[❌ 현재 제안 거절<br/>Reject N]
COMPARE -->|N > B<br/>현재 제안 번호가 더 큼| ACCEPT_HIGHER[✅ 이전 약속 B 파기<br/>현재 제안 번호 N에 대해<br/>수용할 것을 약속<br/>Promise N]
ACCEPT_NEW --> WAIT([수용 요청 대기<br/>Accept N, 값])
ACCEPT_HIGHER --> WAIT
style START fill:#4A90D9,stroke:#333,color:#fff
style CHECK fill:#F5A623,stroke:#333,color:#fff
style COMPARE fill:#F5A623,stroke:#333,color:#fff
style ACCEPT_NEW fill:#7ED321,stroke:#333,color:#fff
style REJECT fill:#D0021B,stroke:#333,color:#fff
style ACCEPT_HIGHER fill:#7ED321,stroke:#333,color:#fff
style WAIT fill:#9B9B9B,stroke:#333,color:#fff

어떤 값이든 수용할 것을 약속한 노드들은 이제 수용 요청 대시 상태로 진입합니다.

2단계: 수용(Accept)

이제 제안자는 각 수용자에게 자신있게 자신의 제안 번호(N)와 함께 값을 전달합니다. 이제 수용자들은 자신이 수용할 것을 약속한 제안 번호(B)와 비교하며 다음과 같이 반응합니다.

수용할 것을 약속한 제안 번호(B)가 존재하는지 확인
B가 존재하지 않는다면, 제안 번호(N)의 값을 수용(Prepare 없이 Accept가 진행되는 경우는 생각하기 어렵긴 하지만!)
B가 존재한다면, 제안 번호(N)과 비교
- N < B 이면, 이미 약속한 제안 번호(B)가 더 크기 때문에 N을 거절
- N = B 이면, 현재 제안 번호(N)가 수용할 것을 약속한 제안 번호이므로 값을 수용하고, 제안자 및 학습자에게 수용되었음을 통지
- N > B 이면, 현재 제안 번호(N)가 이미 약속한 제안 번호(B)보다 크므로 이전 약속을 파기하고 N을 수용할 것을 약속

flowchart TD
START([수용자가 수락 요청 수신<br/>Accept N, 값]) --> CHECK{현재 약속한<br/>제안번호 B가<br/>존재하는가?}
CHECK -->|존재하지 않음| ACCEPT[✅ 수락<br/>Accepted N, 값]
CHECK -->|존재함| COMPARE{현재 수락 요청의<br/>제안번호 N과<br/>약속한 제안번호 B<br/>비교}
COMPARE -->|B > N<br/>약속한 번호가 더 큼| REJECT[❌ 거절<br/>더 높은 번호에 이미 약속함]
COMPARE -->|N = B<br/>약속한 번호와 동일| ACCEPT2[✅ 수락<br/>Accepted N, 값]
COMPARE -->|N > B<br/>수락 요청 번호가 더 큼| ACCEPT3[✅ 수락<br/>Accepted N, 값]
ACCEPT --> NOTIFY([제안자 + 학습자에게<br/>Accepted 전달])
ACCEPT2 --> NOTIFY
ACCEPT3 --> NOTIFY
REJECT --> WAIT([제안자에게 거절 응답])
style START fill:#4A90D9,stroke:#333,color:#fff
style CHECK fill:#F5A623,stroke:#333,color:#fff
style COMPARE fill:#F5A623,stroke:#333,color:#fff
style ACCEPT fill:#7ED321,stroke:#333,color:#fff
style ACCEPT2 fill:#7ED321,stroke:#333,color:#fff
style ACCEPT3 fill:#7ED321,stroke:#333,color:#fff
style REJECT fill:#D0021B,stroke:#333,color:#fff
style NOTIFY fill:#9B9B9B,stroke:#333,color:#fff
style WAIT fill:#9B9B9B,stroke:#333,color:#fff

위 다이어그램에서 볼 수 있듯이 Prepare 단계에서 과반수의 약속을 받았더라도 Accept 단계에서 거절될 수도 있습니다. 더 높은 제안 번호의 Prepare가 중간에 끼어들 수도 있기 때문이죠.

좀 더 쓸모있는 예시를 들어보자: 분산 시스템의 리더 노드 선출

자, 알고리즘은 뭐 이런 식으로 진행됩니다. 그런데 제가 이 내용을 처음 봤을 때는 솔직히 뭐 어쩌라고? 싶었습니다. 이게 도대체 뭔 소린지, 그리고 어디다가 써먹을 수 있다는 건지 영 감이 안잡혔죠. 그래서 이리저리 머리를 굴려보다가 그럴듯한 예시를 하나 생각해냈습니다.

우리가 쓰는 디비든 쿠버네티스 같은 인프라 운영 시스템이든 각종 실패를 견디기 위해서 노드를 분산해둡니다. 쿠버네티스의 경우 클러스터 운영을 위한 마스터 노드(또는 컨트롤 플레인)와 서비스를 돌리기 위한 워커 노드가 있죠. 특히 마스터 노드의 경우 전체 시스템 관리 및 워커 노드를 제어하는 등의 핵심 역할을 맡고 있습니다. 이런 마스터 노드가 죽으면 곤란하기 때문에 여러 마스터 노드를 실행해서 특정 노드에 장애가 생겨도 서비스 운영에 문제가 없도록 하고 있죠.

그런데 이 글을 시작하면서 분산 시스템에서는 합의가 중요하다고 했었습니다. 여러대의 마스터 노드가 있을 때 각자 서로 다른 결정을 하면 안되겠죠. 그래서 리더 노드를 선출하고 다른 노드들은 리더가 결정한 내용을 따르도록 하고 있습니다. 지금 부터 살펴볼 예제는 바로 그 리더를 선출하는 과정을 Paxos 알고리즘으로 구현해 볼 겁니다!

시스템 개요

간결한 구현을 위해서 시작점이 되는 cli 앱이 3개의 웹 서버 클러스터를 실행하고, 3개의 웹 서버가 서로 통신하면서 Paxos 알고리즘을 통해 리더를 선출하게 됩니다. 그리고 필요에 따라서 각 서버를 죽이거나 재실행해서 다양한 경우를 실험해 볼 수 있도록 할 겁니다.

원래 이런 시스템은 멀티 Paxos로 구현해야 합니다. Paxos는 원래 합의를 한 번 하면 그걸로 끝이기 때문에 여러번의 합의를 하려면 계속 새로운 Paxos 인스턴스를 생성해야 합니다. 그런데 그렇게 하면 너무 복잡하니까, 단일 Paxos로 구현해서 매 라운드 마다 상태 값을 초기화 하고 다시 설정하는 형태로 구현해서 멀티 Paxos를 흉내내는 형태로 구현할 겁니다.

node.js와 typescript를 이용해서 2개의 파일로 구현할 겁니다.

runCluster.ts: 3개의 웹 서버를 실행하고 관리하는 클러스터 관리자 cli 구현
node.ts: 각 웹서버를 express로 구현

그리고 시스템 아키텍처는 다음과 같습니다.

graph TD
USER["사용자 터미널"] --> CLI["runCluster.ts<br/>(클러스터 관리자 + 대화형 CLI)<br/>━━━━━━━━━━━━━━━━<br/>- child_process.spawn으로 3개 노드 생성<br/>- 각 노드 stdout에 색상 적용 출력<br/>- readline으로 대화형 CLI 제공"]
CLI -->|"spawn: npx tsx node.ts 1 3001 ..."| N1["node.ts (노드 1)<br/>:3001"]
CLI -->|"spawn: npx tsx node.ts 2 3002 ..."| N2["node.ts (노드 2)<br/>:3002"]
CLI -->|"spawn: npx tsx node.ts 3 3003 ..."| N3["node.ts (노드 3)<br/>:3003"]
N1 <-->|"HTTP POST"| N2
N2 <-->|"HTTP POST"| N3
N1 <-->|"HTTP POST"| N3
style CLI fill:#f9f,stroke:#333,stroke-width:2px
style N1 fill:#36c,stroke:#333,color:#fff
style N2 fill:#c93,stroke:#333,color:#fff
style N3 fill:#c3c,stroke:#333,color:#fff

runCluster.ts가 3개의 웹서버 노드 프로세스를 생성하고, 각 노드는 Express 서버를 실행하여 HTTP로 통신합니다.

클러스터 관리자 cli 구현

클러스터 관리자 cli는 각 웹서버 노드 프로세스를 실행하고, 특정 노드 프로세스를 죽이거나 다시 시작하거나 할 수 있습니다.

graph LR
CLI["대화형 CLI<br/>(readline)"] --> KILL["kill &lt;id&gt;"]
CLI --> START["start &lt;id&gt;"]
CLI --> STATUS["status"]
CLI --> EXIT["exit"]
KILL --> K_ACTION["child.kill('SIGTERM')<br/>→ 노드 프로세스 종료"]
START --> S_ACTION["startNode(nodeConfig)<br/>→ 새 child_process.spawn<br/>→ 노드 재시작"]
STATUS --> ST_ACTION["fetch GET /status<br/>→ 각 노드 상태 조회<br/>→ 콘솔 출력"]
EXIT --> E_ACTION["processes.forEach(p => p.kill('SIGTERM'))<br/>→ 모든 노드 종료<br/>→ process.exit(0)"]
style CLI fill:#f9f,stroke:#333
style K_ACTION fill:#fcc,stroke:#333
style S_ACTION fill:#cfc,stroke:#333
style ST_ACTION fill:#ccf,stroke:#333
style E_ACTION fill:#ffc,stroke:#333

runCluster.ts의 전체 코드는 다음과 같습니다.

import { spawn, ChildProcess } from 'child_process';
import * as readline from 'readline';
import { fileURLToPath } from 'url';
import { dirname } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

type NodeConfig = {
 id: number;
 port: number;
};

// 각 노드 아이디와 포트 번호 정의
const NODES: NodeConfig[] = [
 { id: 1, port: 3001 },
 { id: 2, port: 3002 },
 { id: 3, port: 3003 }
];

// 노드 프로세스 관리를 위한 맵 정의
const processes = new Map<number, ChildProcess>();

// 가독성을 위해 각 노드의 아이디별 출력 색상 정의
const colors = {
 1: '\x1b[36m', // 파란색
 2: '\x1b[33m', // 노란색
 3: '\x1b[35m', // 핑크색
 reset: '\x1b[0m', // 기본 색상
};

/**
 * 노드 프로세스를 시작하는 함수
 * @param nodeConfig - 노드 아이디와 포트 번호 정의
 */
function startNode(nodeConfig: NodeConfig) {
 // 현재 노드가 통신해야 할 다른 노드의 URL 목록 생성
 const peers: string[] = NODES
 .filter((n: NodeConfig) => n.id !== nodeConfig.id)
 .map((n: NodeConfig) => `http://localhost:${n.port}`);

 console.log(`${colors[nodeConfig.id as keyof typeof colors]}노드 ${nodeConfig.id} 시작...${colors.reset}`);

 // 노드 프로세스 생성
 const child = spawn(
 'npx',
 ['tsx', 'node.ts', String(nodeConfig.id), String(nodeConfig.port), ...peers],
 {
 cwd: __dirname,
 stdio: ['ignore', 'pipe', 'pipe'],
 }
 );

 // 노드 프로세스의 출력에 색상을 적용 하여 출력
 child.stdout?.on('data', (data: Buffer) => {
 const color = colors[nodeConfig.id as keyof typeof colors] || colors.reset;
 process.stdout.write(`${color}${data.toString()}${colors.reset}`);
 });

 // 노드 프로세스의 에러 출력에 색상을 적용 하여 출력
 child.stderr?.on('data', (data: Buffer) => {
 const color = colors[nodeConfig.id as keyof typeof colors] || colors.reset;
 process.stderr.write(`${color}[노드 ${nodeConfig.id} 오류] ${data.toString()}${colors.reset}`);
 });

 // 노드 프로세스가 종료될 때 처리
 child.on('exit', (code, signal) => {
 console.log(`${colors[nodeConfig.id as keyof typeof colors]}[노드 ${nodeConfig.id}] 프로세스 종료 (code: ${code}, signal: ${signal})${colors.reset}`);
 processes.delete(nodeConfig.id);
 });

 // 노드 프로세스를 관리하는 맵에 추가
 processes.set(nodeConfig.id, child);
}

/**
 * 노드 프로세스 종료
 * @param id - 종료할 노드의 아이디
 */
function killNode(id: number) {
 const child = processes.get(id);

 // 노드 프로세스가 존재하면 종료
 if (child) {
 child.kill('SIGTERM');
 console.log(`\n${colors[id as keyof typeof colors]}[클러스터] 노드 ${id} 종료${colors.reset}\n`);
 } else {
 console.log(`\n[클러스터] 노드 ${id} 실행 중이 아님\n`);
 }
}

/**
 * 클러스터 상태 출력
 */
async function printStatus() {
 console.log('\n=== 클러스터 상태 ===');

 for (const node of NODES) {
 try {
 const res = await fetch(`http://localhost:${node.port}/status`, {
 signal: AbortSignal.timeout(1000),
 });
 const data = await res.json();
 const color = colors[node.id as keyof typeof colors] || colors.reset;
 const leaderMark = data.isLeader ? '👑' : ' ';

 // 노드 상태 출력
 console.log(
 `${color}${leaderMark} 노드 ${node.id}: 리더=${data.currentLeaderId ?? '없음'}, ` +
 `턴=${data.currentTerm}, 리더=${data.isLeader}, ` +
 `약속한 제안 번호=${data.promisedProposal ?? '없음'}, 수락한 제안 번호=${data.acceptedProposal ?? '없음'}${colors.reset}`
 );
 } catch {
 const color = colors[node.id as keyof typeof colors] || colors.reset;
 console.log(`${color} 노드 ${node.id}: ❌ 다운${colors.reset}`);
 }
 }

 console.log('');
}

/**
 * 대화형 CLI 구현
 */

const rl = readline.createInterface({
 input: process.stdin,
 output: process.stdout,
});

// 모든 노드 시작
console.log('\n🚀 Starting Paxos Leader Election Cluster...\n');
for (const node of NODES) {
 startNode(node);
}

// 모든 노드가 시작될 때까지 대기 후 명령어 출력
setTimeout(() => {
 console.log('\n' + '='.repeat(60));
 console.log('📋 사용 가능한 명령어:');
 console.log(' kill <id> - 노드 종료 (특정 노드에 장애가 발생하여 종료되는 걸 시뮬레이션)');
 console.log(' start <id> - 종료된 노드 재시작');
 console.log(' status - 클러스터 상태 출력');
 console.log(' exit - 모든 노드 종료 및 종료');
 console.log('='.repeat(60) + '\n');
}, 1000);

// 대화형 CLI 명령어 처리
rl.on('line', async (line: string) => {
 const [cmd, arg] = line.trim().split(' ');

 // 명령어 처리
 switch (cmd) {
 case 'kill':
 const killId = parseInt(arg);
 if (NODES.find((n) => n.id === killId)) {
 killNode(killId);
 } else {
 console.log(`잘못된 노드 ID: ${arg}\n`);
 }
 break;

 case 'start':
 const startId = parseInt(arg);
 const node = NODES.find((n) => n.id === startId);
 if (node) {
 if (processes.has(startId)) {
 console.log(`\n노드 ${startId}: 이미 실행 중\n`);
 } else {
 startNode(node);
 }
 } else {
 console.log(`잘못된 노드 ID: ${arg}\n`);
 }
 break;

 case 'status':
 await printStatus();
 break;

 case 'exit':
 console.log('\n🛑 모든 노드 종료...\n');
 processes.forEach((p) => p.kill('SIGTERM'));
 setTimeout(() => process.exit(0), 500);
 break;

 case 'help':
 console.log('\n📋 사용 가능한 명령어:');
 console.log(' kill <id> - 노드 종료');
 console.log(' start <id> - 종료된 노드 재시작');
 console.log(' status - 클러스터 상태 출력');
 console.log(' exit - 모든 노드 종료 및 종료\n');
 break;

 default:
 if (line.trim()) {
 console.log(`알 수 없는 명령어: ${cmd}. 'help' 명령어를 사용하여 사용 가능한 명령어를 확인하세요.\n`);
 }
 }
});

// Ctrl+C 처리
process.on('SIGINT', () => {
 console.log('\n\n🛑 모든 노드 종료...\n');
 processes.forEach((p) => p.kill('SIGTERM'));
 setTimeout(() => process.exit(0), 500);
});

웹 서버 노드 구현

웹 서버 노드는 paxos 알고리즘을 위한 변수들과 각종 타이머, API 라우트 등을 포함하고 있습니다.

graph TD
subgraph CONFIG["설정 (Configuration)"]
C1["nodeId: number<br>자신의 노드ID"] ~~~ C2["port: number"] ~~~ C3["peers: string[]<br>자신을 제외한 클러스터의 노드"] ~~~ C4["allNodes: string[]<br>자신을 포함한 클러스터의 모든 노드"] ~~~ C5["majority: number<br>다수 노드의 수"]
end
subgraph PAXOS["Paxos Acceptor 상태"]
P1["promisedProposal: number | null<br>수락을 약속한 제안번호"] ~~~ P2["acceptedProposal: number | null<br>수락한 제안번호"] ~~~ P3["acceptedValue: number | null<br>수락한 값(리더의 노드ID)"]
end
subgraph LEADER["Leader 상태"]
L1["currentLeaderId: number | null"] ~~~ L2["currentTurn: number"] ~~~ L3["electionRound: number"]
end
subgraph TIMERS["타이머"]
T1["heartbeatTimer: NodeJS.Timeout | null<br/>(setInterval 1초 주기, 리더가 자신이 살아있음을 전송)"] ~~~ T2["electionTimer: NodeJS.Timeout | null<br/>(setTimeout 3~5초, 리더는 중지)"]
end
subgraph ROUTES["Express Routes"]
R1["POST /paxos/prepare"] ~~~ R2["POST /paxos/accept"] ~~~ R3["POST /leader/heartbeat"] ~~~ R4["GET /status"]
end
subgraph LOGIC["핵심 로직 함수"]
F1["runElection()"] ~~~ F2["startHeartbeat()"] ~~~ F3["stopHeartbeat()"] ~~~ F4["resetElectionTimeout()"] ~~~ F5["scheduleNextElection()"]
end
CONFIG --> PAXOS --> LEADER --> TIMERS --> ROUTES --> LOGIC
style CONFIG fill:#e0f0ff,stroke:#333
style PAXOS fill:#ffe0f0,stroke:#333
style LEADER fill:#f0ffe0,stroke:#333
style TIMERS fill:#fff0e0,stroke:#333
style ROUTES fill:#f0e0ff,stroke:#333
style LOGIC fill:#e0fff0,stroke:#333

각 API는 paxos 알고리즘의 Prepare, Accept 단계를 위한 /paxos/prepare, /paxos/accept와 리더의 생존 신호를 수신할 /leader/heartbeat를 구현합니다.

graph LR
N["노드 (Proposer/Acceptor)"]
N -->|"POST /paxos/prepare<br/>{proposalNumber: N}"| PREP["Phase 1: PREPARE"]
PREP -->|"{promise: boolean,<br/>acceptedProposal: number | null,<br/>acceptedValue: number | null}"| N
N -->|"POST /paxos/accept<br/>{proposalNumber: N, value: V}"| ACC["Phase 2: ACCEPT"]
ACC -->|"{accepted: boolean}"| N
N -->|"POST /leader/heartbeat<br/>{leaderId: L, term: T}"| HB["하트비트 수신"]
HB -->|"{ok: true}"| N
N -->|"GET /status"| ST["상태 조회"]
ST -->|"{nodeId, currentLeaderId,<br/>currentTerm, promisedProposal,<br/>acceptedProposal, acceptedValue,<br/>isLeader}"| N
style PREP fill:#ffcccc,stroke:#333
style ACC fill:#ccffcc,stroke:#333
style HB fill:#ccccff,stroke:#333
style ST fill:#ffffcc,stroke:#333

엔드포인트 요약:

엔드포인트	메서드	요청	응답	용도
`/paxos/prepare`	POST	`{ proposalNumber }`	`{ promise, acceptedProposal, acceptedValue }`	Paxos Phase 1 - 약속 요청
`/paxos/accept`	POST	`{ proposalNumber, value }`	`{ accepted }`	Paxos Phase 2 - 수락 요청
`/leader/heartbeat`	POST	`{ leaderId, term }`	`{ ok }`	리더 생존 신호 전송
`/status`	GET	-	전체 상태 객체	노드 상태 조회 (디버깅용)

node.ts의 전체 코드는 다음과 같습니다.

import express from 'express';

// === 타입 정의 ===

type NodeConfig = {
 id: number;
 port: number;
 peers: string[];
};

type PrepareRequest = {
 proposalNumber: number;
};

type PrepareResponse = {
 promise: boolean;
 acceptedProposal: number | null;
 acceptedValue: number | null;
};

type AcceptRequest = {
 proposalNumber: number;
 value: number;
};

type AcceptResponse = {
 accepted: boolean;
};

type HeartbeatMessage = {
 leaderId: number;
 term: number;
};

// cli 매개변수로 전달받은 노드 아이디, 포트, 통신해야 할 다른 노드의 URL 목록 등의 값을 변수에 저장
const nodeId = parseInt(process.argv[2]);
const port = parseInt(process.argv[3]);
const peers = process.argv.slice(4);
const allNodes = [`http://localhost:${port}`, ...peers];
const majority = Math.floor(allNodes.length / 2) + 1;

console.log(`[노드 ${nodeId}] 시작 with 통신해야 할 다른 노드의 URL 목록: ${peers.join(', ')}`);
console.log(`[노드 ${nodeId}] 다수 필요: ${allNodes.length} 중 ${majority} 이상`);

// === Paxos Acceptor 상태 변수들 ===

let promisedProposal: number | null = null;
let acceptedProposal: number | null = null;
// 수락된 값(리더의 노드 아이디)
let acceptedValue: number | null = null;

// === Leader 상태와 Heartbeat ===

let currentLeaderId: number | null = null;
let currentTerm: number = 0;
// 리더의 하트비트 전송 타이머
let heartbeatTimer: NodeJS.Timeout | null = null;
// 리더 부재시 선출을 진행하기 위한 타이머
let electionTimer: NodeJS.Timeout | null = null;
let electionRound = 0;

// === Paxos Proposer 로직 ===

/**
 * 리더 선출 시작
 * @returns 리더 선출 성공 여부, 실패시 null 반환
 */
async function runElection(): Promise<boolean | null> {
 // 제안 번호가 이미 있는 것보다 큰지 확인
 if (promisedProposal !== null) {
 /**
 * 이전에 약속된 제안 번호가 있는 경우, 라운드 조정(다른 노드가 이미 제안한 제안 번호보다 높은 제안 번호를 사용하도록 함)
 *
 * ex: Math.max(0, Math.ceil(6 / 3)) = Math.max(0, 2) = 2
 */
 electionRound = Math.max(electionRound, Math.ceil(promisedProposal / allNodes.length));
 }
 electionRound++;

 /**
 * 제안 번호 = 노드 아이디 + (라운드 * 노드 개수) -> 각 라운드 마다 노드의 제안 번호의 고유성을 보장하기 위함
 *
 * 예를 들어, 노드 1, 2, 3이 있고, 라운드가 1인 경우,
 * 노드 1, 라운드 1: 1 + (1 * 3) = 4
 * 노드 2, 라운드 1: 2 + (1 * 3) = 5
 * 노드 3, 라운드 1: 3 + (1 * 3) = 6
 * 노드 1, 라운드 2: 1 + (2 * 3) = 7
 * 노드 2, 라운드 2: 2 + (2 * 3) = 8
 * 노드 3, 라운드 2: 3 + (2 * 3) = 9
 * ...
 */
 const proposalNumber = nodeId + (electionRound * allNodes.length);

 console.log(`\n[노드 ${nodeId}] 🗳️ 리더 선출 시작 / 제안 번호 #${proposalNumber}`);

 // Phase 1: PREPARE 요청 전송
 console.log(`[노드 ${nodeId}] Phase 1: 모든 노드에 PREPARE 요청 전송...`);

 const preparePromises = allNodes.map(async (nodeUrl) => {
 // 자신을 포함한 모든 노드에 PREPARE 요청 전송
 try {
 // PREPARE 요청 전송
 const response = await fetch(`${nodeUrl}/paxos/prepare`, {
 method: 'POST',
 headers: { 'Content-Type': 'application/json' },
 body: JSON.stringify({ proposalNumber } as PrepareRequest),
 signal: AbortSignal.timeout(1000),
 });

 // PREPARE 요청 실패 시 null 반환
 if (!response.ok) return null;
 return await response.json() as PrepareResponse;
 } catch (error) {
 // PREPARE 요청 실패 시 null 반환
 return null;
 }
 });

 // PREPARE 요청 결과 처리
 const prepareResults = await Promise.allSettled(preparePromises);
 // PREPARE 요청 결과 중 성공한 것들 중 약속을 받은 것들만 추출
 const promises = prepareResults
 .filter((r): r is PromiseFulfilledResult<PrepareResponse> =>
 r.status === 'fulfilled' && r.value !== null && !!r.value.promise
 )
 .map((r) => r.value);

 console.log(`[노드 ${nodeId}] Phase 1: 약속을 받은 노드 ${promises.length}/${allNodes.length} 개 (필요 ${majority} 개)`);

 if (promises.length < majority) {
 console.log(`[노드 ${nodeId}] ❌ Phase 1 실패: 약속을 받은 노드가 다수 필요 개수보다 적습니다. 리더 선출을 중단하고 다음 선거 시작.`);
 scheduleNextElection();
 return false;
 }

 // 수락된 값 중 가장 높은 값을 채택, 없으면 자신을 제안
 let proposedValue = nodeId;
 let highestAcceptedProposal = -1;

 for (const p of promises) {
 // 수락된 값 중 가장 높은 값을 채택
 if (p.acceptedProposal !== null && p.acceptedProposal > highestAcceptedProposal) {
 highestAcceptedProposal = p.acceptedProposal;
 proposedValue = p.acceptedValue!;
 }
 }

 if (highestAcceptedProposal > -1) {
 console.log(`[노드 ${nodeId}] Phase 1: 이전에 수락된 값 (노드 ${proposedValue}) 채택 / 제안 번호 #${highestAcceptedProposal}`);
 } else {
 console.log(`[노드 ${nodeId}] Phase 1: 이전에 수락된 값이 없으므로 자신을 제안 (노드 ${proposedValue})`);
 }

 // Phase 2: Accept
 console.log(`[노드 ${nodeId}] Phase 2: 모든 노드에 ACCEPT (값: 노드 ${proposedValue}) 요청 전송...`);

 const acceptPromises = allNodes.map(async (nodeUrl) => {
 // 자신을 포함한 모든 노드에 ACCEPT 요청 전송
 try {
 // ACCEPT 요청 전송
 const response = await fetch(`${nodeUrl}/paxos/accept`, {
 method: 'POST',
 headers: { 'Content-Type': 'application/json' },
 body: JSON.stringify({ proposalNumber, value: proposedValue } as AcceptRequest),
 signal: AbortSignal.timeout(1000),
 });

 // ACCEPT 요청 실패 시 null 반환
 if (!response.ok) return null;
 return await response.json() as AcceptResponse;
 } catch (error) {
 // ACCEPT 요청 실패 시 null 반환
 return null;
 }
 });

 // ACCEPT 요청 결과 처리
 const acceptResults = await Promise.allSettled(acceptPromises);
 // ACCEPT 요청 결과 중 성공한 것들 중 수락된 것들만 추출
 const accepts = acceptResults
 .filter((r) => r.status === 'fulfilled' && r.value !== null && r.value.accepted)
 .length;

 console.log(`[노드 ${nodeId}] Phase 2: 수락된 노드 ${accepts}/${allNodes.length} 개 (필요 ${majority} 개)`);

 if (accepts >= majority) {
 console.log(`[노드 ${nodeId}] ✅ 리더 선출 성공! 노드 ${proposedValue} 가 리더가 되었습니다. (제안 번호 ${proposalNumber})`);

 if (proposedValue === nodeId) {
 console.log(`[노드 ${nodeId}] 👑 나는 리더!`);
 // 리더는 자신의 선출 타임아웃을 중지 (팔로워만 타임아웃을 감시해야 함)
 if (electionTimer) {
 clearTimeout(electionTimer);
 electionTimer = null;
 }
 startHeartbeat(proposalNumber);
 }

 return true;
 } else {
 console.log(`[노드 ${nodeId}] ❌ Phase 2 실패: 수락된 노드가 다수 필요 개수보다 적습니다. 리더 선출을 중단하고 다음 선거 시작.`);
 scheduleNextElection();
 return false;
 }
}

/**
 * 다음 리더 선출 예약
 */
function scheduleNextElection() {
 // 다음 선거 시작 전 랜덤 딜레이 적용
 const delay = 2000 + Math.random() * 3000;
 setTimeout(() => {
 // 현재 리더가 없으면 다음 선거 시작
 if (currentLeaderId === null) {
 runElection();
 }
 }, delay);
}

/**
 * 하트비트 시작
 * @param term 현재 턴
 */
function startHeartbeat(term: number) {
 // 하트비트 중지
 stopHeartbeat();

 heartbeatTimer = setInterval(() => {
 console.log(`[노드 ${nodeId}] 💓 하트비트 전송 (턴 ${term})`);

 // 자신(리더)를 제외한 나머지 노드에 하트비트 전송
 peers.forEach(async (peerUrl) => {
 try {
 await fetch(`${peerUrl}/leader/heartbeat`, {
 method: 'POST',
 headers: { 'Content-Type': 'application/json' },
 body: JSON.stringify({ leaderId: nodeId, term } as HeartbeatMessage),
 signal: AbortSignal.timeout(1000),
 });
 } catch (error) {
 // 노드 다운 시 무시
 }
 });
 }, 1000);
}

/**
 * 하트비트 중지
 */
function stopHeartbeat() {
 if (heartbeatTimer) {
 clearInterval(heartbeatTimer);
 heartbeatTimer = null;
 }
}

/**
 * 리더 선출 타임아웃 리셋
 *
 * 타임아웃 이후, 리더가 없으면 리더 선출 시작
 */
function resetElectionTimeout() {
 if (electionTimer) {
 clearTimeout(electionTimer);
 }

 // 리더 선출 타임아웃 랜덤 적용 (3-5초)
 const timeout = 3000 + Math.random() * 2000;

 electionTimer = setTimeout(() => {
 console.log(`[노드 ${nodeId}] ⏰ 하트비트 타임아웃 - 리더 없음 감지, 리더 선출 시작...`);
 currentLeaderId = null;
 // 현재 리더로 선출된 노드가 서비스 다운되는 경우에 해당 노드는 리더 선출에서 제외되어야 함
 // 따라서 수락된 상태를 리셋하여 진행하며, 각 리더 선출은 사실상 새로운 Paxos 인스턴스가 되도록 함
 acceptedProposal = null;
 acceptedValue = null;
 runElection();
 }, timeout);
}

// === Express Routes ===

const app = express();
app.use(express.json());

// Paxos Phase 1: Prepare
app.post('/paxos/prepare', (req, res) => {
 const { proposalNumber } = req.body as PrepareRequest;

 console.log(`[노드 ${nodeId}] PREPARE 요청 수신 / 제안 번호 #${proposalNumber}`);

 if (promisedProposal === null || proposalNumber > promisedProposal) {
 promisedProposal = proposalNumber;
 // 수락된 상태를 리셋하여 진행하며, 각 리더 선출은 사실상 새로운 Paxos 인스턴스가 되도록 함(죽은 리더 재선출 방지)
 acceptedProposal = null;
 acceptedValue = null;
 console.log(`[노드 ${nodeId}] → 제안 번호 #${proposalNumber} 약속`);

 res.json({
 promise: true,
 acceptedProposal: null,
 acceptedValue: null,
 } as PrepareResponse);
 } else {
 console.log(`[노드 ${nodeId}] → 이미 약속한 제안 번호 #${promisedProposal} 거절`);
 res.json({
 promise: false,
 acceptedProposal: null,
 acceptedValue: null,
 } as PrepareResponse);
 }
});

// Paxos Phase 2: ACCEPT 요청 처리
app.post('/paxos/accept', (req, res) => {
 const { proposalNumber, value } = req.body as AcceptRequest;

 console.log(`[노드 ${nodeId}] ACCEPT 요청 수신 / 제안 번호 #${proposalNumber}, 값: 노드 ${value}`);

 // 약속된 제안 번호가 없거나, 현재 제안 번호가 약속된 제안 번호보다 크거나 같으면 수락
 if (promisedProposal === null || proposalNumber >= promisedProposal) {
 // 약속된 제안 번호 갱신
 promisedProposal = proposalNumber;
 // 수락된 제안 번호 갱신
 acceptedProposal = proposalNumber;
 // 수락된 값 갱신(리더의 노드 아이디)
 acceptedValue = value;
 // 현재 리더 아이디 갱신
 currentLeaderId = value;
 // 현재 턴 갱신
 currentTerm = proposalNumber;

 console.log(`[노드 ${nodeId}] → 수락! 새로운 리더: 노드 ${value} (제안 번호 ${proposalNumber})`);

 // 리더가 아니라면 하트비트 중지
 if (value !== nodeId) {
 stopHeartbeat();
 }

 // 리더 선출 타임아웃 리셋
 resetElectionTimeout();

 res.json({ accepted: true } as AcceptResponse);
 } else {
 console.log(`[노드 ${nodeId}] → 이미 약속한 제안 번호 #${promisedProposal} 거절`);
 res.json({ accepted: false } as AcceptResponse);
 }
});

// 리더가 전송하는 하트비트 수신
app.post('/leader/heartbeat', (req, res) => {
 const { leaderId, term } = req.body as HeartbeatMessage;

 // 새로운 턴이 시작되었다면,
 if (term >= currentTerm) {
 // 새로운 리더가 등장했다면,
 if (leaderId !== currentLeaderId) {
 console.log(`[노드 ${nodeId}] 💓 새로운 리더로부터 하트비트 수신 / 리더: 노드 ${leaderId} (턴 ${term})`);
 }

 // 현재 리더 아이디 갱신
 currentLeaderId = leaderId;
 // 현재 턴 갱신
 currentTerm = term;

 /**
 * 리더 선출 타임아웃 리셋(타임아웃 이후, 리더가 없으면 리더 선출 시작)
 *
 * 리더의 하트비트가 안정적으로 수신된다면, 리더 선출의 타임아웃은 계속 리셋된다. -> 현재 상태 유지.
 */
 resetElectionTimeout();
 }

 res.json({ ok: true });
});

// 상태 조회 엔드포인트
app.get('/status', (req, res) => {
 res.json({
 nodeId,
 currentLeaderId,
 currentTerm,
 promisedProposal,
 acceptedProposal,
 acceptedValue,
 isLeader: currentLeaderId === nodeId,
 });
});

// === 메인 함수 ===

app.listen(port, () => {
 console.log(`[노드 ${nodeId}] 🚀 포트 ${port}에서 수신 중...`);

 // 리더 선출 예약(랜덤 딜레이 적용)
 const delay = 1000 + Math.random() * 2000;
 console.log(`[노드 ${nodeId}] 리더 조회 전 ${Math.round(delay)}ms 대기...`);

 // 랜덤 딜레이 이후, 리더가 없으면 리더 선출 시작
 setTimeout(() => {
 if (currentLeaderId === null) {
 console.log(`[노드 ${nodeId}] 리더 없음, 리더 선출 시작...`);
 runElection();
 }
 }, delay);

 // 리더 선출 타임아웃 리셋(타임아웃 이후, 리더가 없으면 리더 선출 시작)
 resetElectionTimeout();
});

이제 돌려보자!

이제 모든 준비가 끝났습니다. npm start 명령으로 예제를 실행해볼까요?

❯ npm start

> paxos-leader-election@1.0.0 start
> npx tsx runCluster.ts


🚀 Starting Paxos Leader Election Cluster...

노드 1 시작...
노드 2 시작...
노드 3 시작...
[노드 1] 시작 with 통신해야 할 다른 노드의 URL 목록: http://localhost:3002, http://localhost:3003
[노드 2] 시작 with 통신해야 할 다른 노드의 URL 목록: http://localhost:3001, http://localhost:3003
[노드 2] 다수 필요: 3 중 2 이상
[노드 3] 시작 with 통신해야 할 다른 노드의 URL 목록: http://localhost:3001, http://localhost:3002
[노드 3] 다수 필요: 3 중 2 이상
[노드 1] 다수 필요: 3 중 2 이상
[노드 2] 🚀 포트 3002에서 수신 중...
[노드 2] 리더 조회 전 2639ms 대기...
[노드 3] 🚀 포트 3003에서 수신 중...
[노드 3] 리더 조회 전 2096ms 대기...
[노드 1] 🚀 포트 3001에서 수신 중...
[노드 1] 리더 조회 전 1722ms 대기...

============================================================
📋 사용 가능한 명령어:
 kill <id> - 노드 종료 (특정 노드에 장애가 발생하여 종료되는 걸 시뮬레이션)
 start <id> - 종료된 노드 재시작
 status - 클러스터 상태 출력
 exit - 모든 노드 종료 및 종료
============================================================

[노드 1] 리더 없음, 리더 선출 시작...

[노드 1] 🗳️ 리더 선출 시작 / 제안 번호 #4
[노드 1] Phase 1: 모든 노드에 PREPARE 요청 전송...
[노드 1] PREPARE 요청 수신 / 제안 번호 #4
[노드 1] → 제안 번호 #4 약속
[노드 3] PREPARE 요청 수신 / 제안 번호 #4
[노드 3] → 제안 번호 #4 약속
[노드 2] PREPARE 요청 수신 / 제안 번호 #4
[노드 2] → 제안 번호 #4 약속
[노드 1] Phase 1: 약속을 받은 노드 3/3 개 (필요 2 개)
[노드 1] Phase 1: 이전에 수락된 값이 없으므로 자신을 제안 (노드 1)
[노드 1] Phase 2: 모든 노드에 ACCEPT (값: 노드 1) 요청 전송...
[노드 1] ACCEPT 요청 수신 / 제안 번호 #4, 값: 노드 1
[노드 1] → 수락! 새로운 리더: 노드 1 (제안 번호 4)
[노드 3] ACCEPT 요청 수신 / 제안 번호 #4, 값: 노드 1
[노드 3] → 수락! 새로운 리더: 노드 1 (제안 번호 4)
[노드 2] ACCEPT 요청 수신 / 제안 번호 #4, 값: 노드 1
[노드 2] → 수락! 새로운 리더: 노드 1 (제안 번호 4)
[노드 1] Phase 2: 수락된 노드 3/3 개 (필요 2 개)
[노드 1] ✅ 리더 선출 성공! 노드 1 가 리더가 되었습니다. (제안 번호 4)
[노드 1] 👑 나는 리더!
[노드 1] 💓 하트비트 전송 (턴 4)
[노드 1] 💓 하트비트 전송 (턴 4)
[노드 1] 💓 하트비트 전송 (턴 4)
[노드 1] 💓 하트비트 전송 (턴 4)
[노드 1] 💓 하트비트 전송 (턴 4)
ki[노드 1] 💓 하트비트 전송 (턴 4)
ll[노드 1] 💓 하트비트 전송 (턴 4)
 1[노드 1] 💓 하트비트 전송 (턴 4)


[클러스터] 노드 1 종료

[노드 1] 프로세스 종료 (code: 143, signal: null)
[노드 3] ⏰ 하트비트 타임아웃 - 리더 없음 감지, 리더 선출 시작...

[노드 3] 🗳️ 리더 선출 시작 / 제안 번호 #12
[노드 3] Phase 1: 모든 노드에 PREPARE 요청 전송...
[노드 2] PREPARE 요청 수신 / 제안 번호 #12
[노드 2] → 제안 번호 #12 약속
[노드 3] PREPARE 요청 수신 / 제안 번호 #12
[노드 3] → 제안 번호 #12 약속
[노드 3] Phase 1: 약속을 받은 노드 2/3 개 (필요 2 개)
[노드 3] Phase 1: 이전에 수락된 값이 없으므로 자신을 제안 (노드 3)
[노드 3] Phase 2: 모든 노드에 ACCEPT (값: 노드 3) 요청 전송...
[노드 3] ACCEPT 요청 수신 / 제안 번호 #12, 값: 노드 3
[노드 3] → 수락! 새로운 리더: 노드 3 (제안 번호 12)
[노드 2] ACCEPT 요청 수신 / 제안 번호 #12, 값: 노드 3
[노드 2] → 수락! 새로운 리더: 노드 3 (제안 번호 12)
[노드 3] Phase 2: 수락된 노드 2/3 개 (필요 2 개)
[노드 3] ✅ 리더 선출 성공! 노드 3 가 리더가 되었습니다. (제안 번호 12)
[노드 3] 👑 나는 리더!
[노드 3] 💓 하트비트 전송 (턴 12)
[노드 3] 💓 하트비트 전송 (턴 12)
st[노드 3] 💓 하트비트 전송 (턴 12)
art 1
노드 1 시작...
[노드 3] 💓 하트비트 전송 (턴 12)
[노드 1] 시작 with 통신해야 할 다른 노드의 URL 목록: http://localhost:3002, http://localhost:3003
[노드 1] 다수 필요: 3 중 2 이상
[노드 1] 🚀 포트 3001에서 수신 중...
[노드 1] 리더 조회 전 1960ms 대기...
[노드 3] 💓 하트비트 전송 (턴 12)
[노드 1] 💓 새로운 리더로부터 하트비트 수신 / 리더: 노드 3 (턴 12)
[노드 3] 💓 하트비트 전송 (턴 12)
[노드 3] 💓 하트비트 전송 (턴 12)
[노드 3] 💓 하트비트 전송 (턴 12)
k[노드 3] 💓 하트비트 전송 (턴 12)
ill 3[노드 3] 💓 하트비트 전송 (턴 12)


[클러스터] 노드 3 종료

[노드 3] 프로세스 종료 (code: 143, signal: null)
[노드 1] ⏰ 하트비트 타임아웃 - 리더 없음 감지, 리더 선출 시작...

[노드 1] 🗳️ 리더 선출 시작 / 제안 번호 #4
[노드 1] Phase 1: 모든 노드에 PREPARE 요청 전송...
[노드 2] PREPARE 요청 수신 / 제안 번호 #4
[노드 2] → 이미 약속한 제안 번호 #12 거절
[노드 1] PREPARE 요청 수신 / 제안 번호 #4
[노드 1] → 제안 번호 #4 약속
[노드 1] Phase 1: 약속을 받은 노드 1/3 개 (필요 2 개)
[노드 1] ❌ Phase 1 실패: 약속을 받은 노드가 다수 필요 개수보다 적습니다. 리더 선출을 중단하고 다음 선거 시작.
[노드 2] ⏰ 하트비트 타임아웃 - 리더 없음 감지, 리더 선출 시작...

[노드 2] 🗳️ 리더 선출 시작 / 제안 번호 #17
[노드 2] Phase 1: 모든 노드에 PREPARE 요청 전송...
[노드 1] PREPARE 요청 수신 / 제안 번호 #17
[노드 1] → 제안 번호 #17 약속
[노드 2] PREPARE 요청 수신 / 제안 번호 #17
[노드 2] → 제안 번호 #17 약속
[노드 2] Phase 1: 약속을 받은 노드 2/3 개 (필요 2 개)
[노드 2] Phase 1: 이전에 수락된 값이 없으므로 자신을 제안 (노드 2)
[노드 2] Phase 2: 모든 노드에 ACCEPT (값: 노드 2) 요청 전송...
[노드 2] ACCEPT 요청 수신 / 제안 번호 #17, 값: 노드 2
[노드 2] → 수락! 새로운 리더: 노드 2 (제안 번호 17)
[노드 1] ACCEPT 요청 수신 / 제안 번호 #17, 값: 노드 2
[노드 1] → 수락! 새로운 리더: 노드 2 (제안 번호 17)
[노드 2] Phase 2: 수락된 노드 2/3 개 (필요 2 개)
[노드 2] ✅ 리더 선출 성공! 노드 2 가 리더가 되었습니다. (제안 번호 17)
[노드 2] 👑 나는 리더!
[노드 2] 💓 하트비트 전송 (턴 17)
[노드 2] 💓 하트비트 전송 (턴 17)
[노드 2] 💓 하트비트 전송 (턴 17)
[노드 2] 💓 하트비트 전송 (턴 17)
[노드 2] 💓 하트비트 전송 (턴 17)
^C

🛑 모든 노드 종료...

클러스터가 실행된 뒤, 1번 노드가 리더로 선출이 되었습니다. 그리고 게속해서 1번 노드가 자신이 살아있음을 다른 노드에서 전송하죠. 이 동안에는 다른 노드들이 리더가 살아있기 때문에 리더 선출을 시도하지 않습니다.

그리고 중간에 kill 1을 입력해서 1번 노드를 제거했습니다. 그러자 리더의 생존 신고(하트비트)가 더 이상 도착하지 않게되고, 이를 감지한 다른 노드들이 리더 선출을 시작합니다. 그리고 노드 3번이 리더가 됩니다.

다시 start 1을 입력해서 1번 노드를 시작하면, 1번 노드는 현재 3번 노드가 리더라는 걸 파악하고 따르기로 합니다. 그리고 다시 3번 노드를 제거하면, 리더 선출이 시작되고 이번엔 2번 노드가 리더가 됩니다.

이 과정을 다이어그램으로 도식화 해보면 다음과 같습니다.

flowchart TD
START["runElection() 호출"] --> CALC["제안 번호 계산<br/>proposalNumber = nodeId + (electionRound * 3)"]
CALC --> PHASE1["Phase 1: PREPARE<br/>모든 노드에 PREPARE 전송"]
PHASE1 --> PROMISE_CHECK{"과반수 약속<br/>받았는가?"}
PROMISE_CHECK -->|"No (promises < majority)"| FAIL1["scheduleNextElection()<br/>2~5초 후 재시도"]
PROMISE_CHECK -->|"Yes (promises >= majority)"| VALUE_CHECK["이전에 수락된 값 확인<br/>없으면 자신을 제안"]
VALUE_CHECK --> PHASE2["Phase 2: ACCEPT<br/>모든 노드에 ACCEPT 전송<br/>(제안 번호, 제안 값)"]
PHASE2 --> ACCEPT_CHECK{"과반수 수락<br/>받았는가?"}
ACCEPT_CHECK -->|"No (accepts < majority)"| FAIL2["scheduleNextElection()<br/>2~5초 후 재시도"]
ACCEPT_CHECK -->|"Yes (accepts >= majority)"| LEADER_CHECK{"proposedValue<br/>=== nodeId?"}
LEADER_CHECK -->|"Yes (나를 제안)"| LEADER["리더 확정! 👑<br/>electionTimer 중지<br/>startHeartbeat()"]
LEADER_CHECK -->|"No (다른 노드 제안)"| FOLLOWER["팔로워로 전환<br/>resetElectionTimeout()"]
LEADER --> END1["하트비트 전송 시작<br/>(1초 주기)"]
FOLLOWER --> END2["하트비트 수신 대기<br/>(3~5초 타임아웃)"]
FAIL1 --> WAIT1["랜덤 딜레이 대기"]
FAIL2 --> WAIT2["랜덤 딜레이 대기"]
WAIT1 --> CHECK1{"currentLeaderId<br/>=== null?"}
WAIT2 --> CHECK2{"currentLeaderId<br/>=== null?"}
CHECK1 -->|Yes| START
CHECK1 -->|No| END3["이미 리더 존재<br/>재시도 안 함"]
CHECK2 -->|Yes| START
CHECK2 -->|No| END3
style START fill:#e0f0ff,stroke:#333
style PHASE1 fill:#ffcccc,stroke:#333
style PHASE2 fill:#ccffcc,stroke:#333
style LEADER fill:#ffd700,stroke:#333,stroke-width:3px
style FOLLOWER fill:#ccccff,stroke:#333
style FAIL1 fill:#ffccaa,stroke:#333
style FAIL2 fill:#ffccaa,stroke:#333

혹시 더 상세한 설명을 원하는 분들 위해서(음.. 미래의 저를 위해서…!) 더 자세한 알고리즘의 흐름을 이 글 마지막의 Appendix에 추가해두었습니다.

Appendix - 더 상세한 설명

미래의 저를 위해서 더 상세한 설명을 남겨두겠습니다!

구체적 시나리오: 노드 3이 리더로 선출

초기 상태

노드	promisedProposal	acceptedProposal	acceptedValue	currentLeaderId
1	null	null	null	null
2	null	null	null	null
3	null	null	null	null

노드 3이 가장 먼저 랜덤 딜레이가 만료되어 선출을 시작한다고 가정합니다.

Phase 1: PREPARE 시퀀스

sequenceDiagram
participant P as 노드 3 (Proposer)
participant A1 as 노드 1 (Acceptor)
participant A2 as 노드 2 (Acceptor)
participant A3 as 노드 3 (Acceptor)
Note over P: electionRound++ → 1<br/>proposalNumber = 3+(1*3) = 6
P->>A1: PREPARE(#6)
P->>A2: PREPARE(#6)
P->>A3: PREPARE(#6)
Note over A1: promisedProposal=null<br/>6 > null → 약속!<br/>promisedProposal=6<br/>accepted 리셋 (죽은 리더 방지)
Note over A2: promisedProposal=null<br/>6 > null → 약속!<br/>promisedProposal=6<br/>accepted 리셋
Note over A3: promisedProposal=null<br/>6 > null → 약속!<br/>promisedProposal=6<br/>accepted 리셋
A1-->>P: {promise:true, accepted:null}
A2-->>P: {promise:true, accepted:null}
A3-->>P: {promise:true, accepted:null}
Note over P: 약속 3/3 (필요 2) ✅<br/>이전 수락 값 없음<br/>→ 자신(노드 3) 제안

핵심 포인트:

promisedProposal === null || proposalNumber > promisedProposal 조건 충족 시 약속
PREPARE 처리 시 acceptedProposal과 acceptedValue를 null로 리셋 (node.ts:295-296)
- 이유: 리더 선출에서는 각 선거가 새로운 Paxos 인스턴스처럼 동작
- 죽은 리더가 재선출되는 것을 방지
응답에 이전 수락 값 포함 (표준 Paxos 메커니즘)

Phase 1 이후 상태

노드	promisedProposal	acceptedProposal	acceptedValue	currentLeaderId
1	6	null (리셋)	null (리셋)	null
2	6	null (리셋)	null (리셋)	null
3	6	null (리셋)	null (리셋)	null

Phase 2: ACCEPT 시퀀스

sequenceDiagram
participant P as 노드 3 (Proposer)
participant A1 as 노드 1 (Acceptor)
participant A2 as 노드 2 (Acceptor)
participant A3 as 노드 3 (Acceptor)
P->>A1: ACCEPT(#6, value:3)
P->>A2: ACCEPT(#6, value:3)
P->>A3: ACCEPT(#6, value:3)
Note over A1: 6 >= promisedProposal(6) → 수락!<br/>acceptedProposal=6<br/>acceptedValue=3<br/>currentLeaderId=3<br/>currentTerm=6<br/>resetElectionTimeout()
Note over A2: 6 >= 6 → 수락!<br/>currentLeaderId=3<br/>currentTerm=6<br/>resetElectionTimeout()
Note over A3: 6 >= 6 → 수락!<br/>currentLeaderId=3<br/>currentTerm=6
A1-->>P: {accepted:true}
A2-->>P: {accepted:true}
A3-->>P: {accepted:true}
Note over P: 수락 3/3 (필요 2) ✅<br/>리더 선출 성공!<br/>proposedValue(3) === nodeId(3)<br/>→ "나는 리더!" 👑<br/>→ electionTimer 중지<br/>→ startHeartbeat(6)

핵심 포인트:

promisedProposal === null || proposalNumber >= promisedProposal 조건 충족 시 수락
모든 Acceptor가 상태 업데이트:
- acceptedProposal, acceptedValue 설정
- currentLeaderId, currentTerm 갱신
- 리더가 아닌 노드는 stopHeartbeat() 호출
- resetElectionTimeout() 호출 → 3~5초 타이머 리셋
노드 3은 proposedValue === nodeId 확인 후:
- electionTimer 중지 (node.ts:192-194) ← 중요! 리더는 타이머 불필요
- startHeartbeat(6) 호출

Phase 2 이후 최종 상태

노드	promisedProposal	acceptedProposal	acceptedValue	currentLeaderId	currentTerm	heartbeatTimer	electionTimer	역할
1	6	6	3	3	6	null	활성 (3~5초)	팔로워
2	6	6	3	3	6	null	활성 (3~5초)	팔로워
3	6	6	3	3	6	활성 (1초)	null (중지)	리더 👑

선출 후 하트비트 흐름

sequenceDiagram
participant L as 노드 3 (리더)
participant F1 as 노드 1 (팔로워)
participant F2 as 노드 2 (팔로워)
loop 매 1초 (setInterval 1000ms)
L->>F1: POST /leader/heartbeat {leaderId:3, term:6}
L->>F2: POST /leader/heartbeat {leaderId:3, term:6}
Note over F1: term(6) >= currentTerm(6)<br/>resetElectionTimeout()<br/>타임아웃 리셋: 3~5초
Note over F2: term(6) >= currentTerm(6)<br/>resetElectionTimeout()<br/>타임아웃 리셋: 3~5초
F1-->>L: {ok:true}
F2-->>L: {ok:true}
end
Note over L,F2: 하트비트(1초) << 타임아웃(3~5초)<br/>→ 정상 상태에서는 타임아웃이 절대 만료되지 않음

하트비트 전송 코드 (node.ts:225-245):

function startHeartbeat(term: number) {
 stopHeartbeat(); // 기존 타이머 제거

 heartbeatTimer = setInterval(() => {
 console.log(`[노드 ${nodeId}] 💓 하트비트 전송 (턴 ${term})`);

 // ★ 자신(리더)를 제외한 peers에만 전송
 peers.forEach(async (peerUrl) => {
 try {
 await fetch(`${peerUrl}/leader/heartbeat`, {
 method: 'POST',
 headers: { 'Content-Type': 'application/json' },
 body: JSON.stringify({ leaderId: nodeId, term }),
 signal: AbortSignal.timeout(1000),
 });
 } catch (error) {
 // 노드 다운 시 무시
 }
 });
 }, 1000);
}

하트비트 수신 핸들러 (node.ts:352-375):

app.post('/leader/heartbeat', (req, res) => {
 const { leaderId, term } = req.body;

 if (term >= currentTerm) {
 if (leaderId !== currentLeaderId) {
 console.log(`[노드 ${nodeId}] 💓 새로운 리더로부터 하트비트 수신`);
 }
 currentLeaderId = leaderId;
 currentTerm = term;
 resetElectionTimeout(); // ★ 핵심! 타임아웃 리셋
 }

 res.json({ ok: true });
});

타이밍 관계:

하트비트 전송: 1초 (setInterval(1000))
선출 타임아웃: 3~5초 (3000 + Math.random() * 2000)
하트비트 주기 « 타임아웃 범위 → 정상 상태에서는 타임아웃 절대 만료 안 됨

리더 장애 감지와 재선출

시나리오: kill 3 → 노드 2가 새 리더로 선출

sequenceDiagram
participant CLI as 클러스터 CLI
participant N3 as 노드 3 (리더)
participant N1 as 노드 1 (팔로워)
participant N2 as 노드 2 (팔로워)
CLI->>N3: kill 3 (SIGTERM)
Note over N3: 프로세스 종료<br/>하트비트 중단
destroy N3
Note over N1: 하트비트 안 옴...
Note over N2: 하트비트 안 옴...
Note over N2: 3.5초 후 타임아웃 만료!<br/>currentLeaderId = null<br/>accepted 상태 리셋<br/>→ runElection()
Note over N2: promisedProposal = 6<br/>electionRound = max(0, ceil(6/3)) = 2<br/>electionRound++ = 3<br/>proposalNumber = 2+(3*3) = 11
N2->>N1: PREPARE(#11)
N2->>N2: PREPARE(#11) (자신)
N2--xN3: PREPARE(#11) (타임아웃)
Note over N1: 11 > 6 → 약속!<br/>promisedProposal=11<br/>accepted 리셋
N1-->>N2: {promise:true}
Note over N2: 자신도 약속
Note over N2: 약속 2/3 (필요 2) ✅
N2->>N1: ACCEPT(#11, value:2)
N2->>N2: ACCEPT(#11, value:2) (자신)
N2--xN3: ACCEPT(#11, value:2) (타임아웃)
Note over N1: 11 >= 11 → 수락!<br/>currentLeaderId=2<br/>currentTerm=11<br/>resetElectionTimeout()
N1-->>N2: {accepted:true}
Note over N2: 자신도 수락
Note over N2: 수락 2/3 (필요 2) ✅<br/>새 리더 확정! 👑<br/>electionTimer 중지<br/>startHeartbeat(11)
loop 매 1초
N2->>N1: heartbeat {leaderId:2, term:11}
Note over N1: resetElectionTimeout()
end

electionRound 조정 로직 (node.ts:70-71):

if (promisedProposal !== null) {
 electionRound = Math.max(electionRound, Math.ceil(promisedProposal / allNodes.length));
}
electionRound++;

예시:

promisedProposal = 6, allNodes.length = 3
electionRound = max(0, ceil(6/3)) = max(0, 2) = 2
electionRound++ = 3
proposalNumber = 2 + (3*3) = 11

과반수 요구:

3개 노드 중 1개 다운 → 2개 응답 (= 과반수) → 선출 가능!
Paxos의 장애 허용 능력: N개 노드에서 (N-1)/2개 장애 허용

재선출 후 상태

노드	promisedProposal	acceptedProposal	acceptedValue	currentLeaderId	currentTerm	heartbeatTimer	electionTimer	역할
1	11	11	2	2	11	null	활성 (3~5초)	팔로워
2	11	11	2	2	11	활성 (1초)	null (중지)	리더 👑
3	-	-	-	-	-	-	-	DOWN

노드 재시작과 팔로워 합류

시나리오: start 3 → 노드 3이 팔로워로 자연스럽게 합류

sequenceDiagram
participant CLI as 클러스터 CLI
participant N2 as 노드 2 (리더)
participant N3 as 노드 3 (재시작)
CLI->>N3: start 3 (새 프로세스 spawn)
Note over N3: 모든 상태 초기화<br/>currentLeaderId=null<br/>currentTerm=0<br/>Express 서버 시작 (:3003)<br/>랜덤 딜레이: 1.8초 대기
N2->>N3: heartbeat {leaderId:2, term:11}
Note over N3: term(11) >= currentTerm(0)<br/>새 리더 감지!<br/>currentLeaderId=2<br/>currentTerm=11<br/>resetElectionTimeout()
N3-->>N2: {ok:true}
Note over N3: 딜레이 만료 (1.8초)<br/>currentLeaderId=2 (null 아님)<br/>→ runElection() 호출 안 함! ✅
N2->>N3: heartbeat {leaderId:2, term:11}
Note over N3: resetElectionTimeout()<br/>안정적으로 팔로워 동작

재시작 초기화 흐름 (node.ts:393-409):

app.listen(port, () => {
 console.log(`[노드 ${nodeId}] 🚀 포트 ${port}에서 수신 중...`);

 // 1~3초 랜덤 딜레이
 const delay = 1000 + Math.random() * 2000;
 console.log(`[노드 ${nodeId}] 리더 조회 전 ${Math.round(delay)}ms 대기...`);

 // 딜레이 후 리더가 없으면 선출 시작
 setTimeout(() => {
 if (currentLeaderId === null) { // ★ 핵심 조건
 console.log(`[노드 ${nodeId}] 리더 없음, 리더 선출 시작...`);
 runElection();
 }
 }, delay);

 resetElectionTimeout();
});

핵심 메커니즘:

노드 3이 재시작하면 모든 상태 변수가 초기값 (currentLeaderId = null)
랜덤 딜레이 (1~3초) 동안 대기
이 시간 동안 리더(노드 2)의 하트비트(1초 주기)가 도착
하트비트 수신 시 currentLeaderId = 2로 설정
딜레이 만료 시 currentLeaderId !== null → 선출 시작 안 함!
자연스럽게 팔로워로 합류

재시작 후 안정 상태

노드	promisedProposal	acceptedProposal	acceptedValue	currentLeaderId	currentTerm	electionTimer	역할
1	11	11	2	2	11	활성	팔로워
2	11	11	2	2	11	null (중지)	리더 👑
3	null	null	null	2 (학습)	11 (학습)	활성	팔로워 (새로 합류)

주목: 노드 3은 Paxos 상태가 null이지만 하트비트만으로 리더 정보를 학습합니다. 메모리 기반 구현이므로 재시작 시 상태 복구 없음.

타이밍 관계 요약

타이머	시간	구현	용도
하트비트 전송 주기	1초	`setInterval(1000)`	리더가 팔로워에게 생존 신호 전송
하트비트 타임아웃 (선출 트리거)	3~5초	`3000 + Math.random() * 2000`	팔로워가 리더 장애 감지
초기 선출 딜레이	1~3초	`1000 + Math.random() * 2000`	클러스터 시작 시 동시 선출 방지
선거 실패 후 재시도 딜레이	2~5초	`2000 + Math.random() * 3000`	Phase 실패 후 재시도 간격
HTTP 요청 타임아웃	1초	`AbortSignal.timeout(1000)`	네트워크 요청 타임아웃

타이밍 설계 원칙:

하트비트 주기 « 타임아웃 → 정상 상태에서 타임아웃 절대 만료 안 됨
모든 딜레이/타임아웃에 랜덤 범위 → 선출 충돌 방지 (livelock 방지)
HTTP 타임아웃 « 하트비트 주기 → 빠른 장애 감지

전체 흐름 한눈에 보기

flowchart TD
START["클러스터 시작<br/>runCluster.ts 실행"] --> SPAWN["3개 노드 프로세스 spawn<br/>(child_process.spawn)"]
SPAWN --> NODE1["노드 1: Express 서버 시작<br/>랜덤 딜레이 (1.5초)"]
SPAWN --> NODE2["노드 2: Express 서버 시작<br/>랜덤 딜레이 (2.1초)"]
SPAWN --> NODE3["노드 3: Express 서버 시작<br/>랜덤 딜레이 (1.2초)"]
NODE1 --> TIMEOUT1["resetElectionTimeout()<br/>타임아웃: 4.1초"]
NODE2 --> TIMEOUT2["resetElectionTimeout()<br/>타임아웃: 3.5초"]
NODE3 --> TIMEOUT3["resetElectionTimeout()<br/>타임아웃: 4.2초"]
NODE3 --> FIRST["딜레이 만료 (1.2초)<br/>가장 먼저!"]
FIRST --> ELECTION1["runElection()<br/>제안 번호 #6"]
ELECTION1 --> P1["Phase 1: PREPARE(#6)<br/>→ 3개 약속"]
P1 --> P2["Phase 2: ACCEPT(#6, val:3)<br/>→ 3개 수락"]
P2 --> LEADER1["노드 3 리더 확정 👑<br/>electionTimer 중지<br/>startHeartbeat(6)"]
LEADER1 --> HB_LOOP["하트비트 루프<br/>(1초마다)"]
HB_LOOP --> HB1["노드 1 수신<br/>resetElectionTimeout()"]
HB_LOOP --> HB2["노드 2 수신<br/>resetElectionTimeout()"]
HB1 --> STABLE["안정 상태<br/>리더: 노드 3, 턴: 6"]
HB2 --> STABLE
STABLE --> KILL["사용자: kill 3<br/>리더 프로세스 종료"]
KILL --> STOP_HB["하트비트 중단"]
STOP_HB --> DETECT1["노드 1: 하트비트 안 옴<br/>타임아웃 대기 (4.1초)"]
STOP_HB --> DETECT2["노드 2: 하트비트 안 옴<br/>타임아웃 대기 (3.5초)"]
DETECT2 --> REELECTION["노드 2 타임아웃 만료 (3.5초)<br/>accepted 상태 리셋<br/>runElection()"]
REELECTION --> RE_P1["Phase 1: PREPARE(#11)<br/>→ 2개 약속 (노드 3 DOWN)"]
RE_P1 --> RE_P2["Phase 2: ACCEPT(#11, val:2)<br/>→ 2개 수락"]
RE_P2 --> LEADER2["노드 2 리더 확정 👑<br/>startHeartbeat(11)"]
LEADER2 --> HB_LOOP2["하트비트 루프<br/>(1초마다)"]
HB_LOOP2 --> STABLE2["안정 상태<br/>리더: 노드 2, 턴: 11"]
STABLE2 --> RESTART["사용자: start 3<br/>새 프로세스 spawn"]
RESTART --> NODE3_NEW["노드 3 재시작<br/>모든 상태 초기화<br/>랜덤 딜레이 (1.8초)"]
NODE3_NEW --> HB_RECEIVE["하트비트 수신<br/>currentLeaderId=2<br/>currentTerm=11"]
HB_RECEIVE --> DELAY_EXPIRE["딜레이 만료 (1.8초)<br/>currentLeaderId !== null<br/>→ 선출 안 함"]
DELAY_EXPIRE --> FOLLOWER["노드 3 팔로워로 합류<br/>안정적으로 동작"]
FOLLOWER --> FINAL["최종 클러스터 상태<br/>리더: 노드 2<br/>팔로워: 노드 1, 3"]
style START fill:#e0f0ff,stroke:#333
style LEADER1 fill:#ffd700,stroke:#333,stroke-width:3px
style LEADER2 fill:#ffd700,stroke:#333,stroke-width:3px
style KILL fill:#ffcccc,stroke:#333
style REELECTION fill:#ffddaa,stroke:#333
style FOLLOWER fill:#ccffcc,stroke:#333
style FINAL fill:#ccccff,stroke:#333,stroke-width:2px

참고자료

요즘 개발자를 위한 시스템 설계 수업. 디렌드라 신하, 테자스 초프라 저. 길벗
https://www.ibm.com/history/700
https://setiathome.berkeley.edu/sah_graphics.php
CLAUDE
Perpexity