WebSocket 서버 없이 Go 백엔드로 실시간 기능 만들기
· Hibira
공식 pusher-http-go로 Go에서 실시간 이벤트를 발행하고, 비공개·presence 채널을 인가하고, 웹훅을 검증합니다. 브라우저는 Hibira에 연결합니다.

Go는 WebSocket 서버를 만들기 좋은 언어라서, 많은 팀이 먼저 직접 만들어 보려고 합니다. hub를 두고, 연결마다 goroutine을 띄우고, 이벤트가 들어오면 브로드캐스트하는 식이죠. 서버가 한 대일 때는 잘 돌아갑니다. 하지만 두 대 이상으로 늘리고, presence(누가 온라인인지)를 만들고, 재연결과 배포 중 연결 이동까지 다루게 되면 WebSocket은 기능 하나가 아니라 운영해야 하는 시스템이 됩니다.
다른 방법은 Go 백엔드는 "무엇을 보낼지"만 정하고, 수만 개의 연결을 유지하는 일은 호스팅 서비스에 맡기는 것입니다. Hibira는 Pusher Channels 프로토콜을 사용하므로 Pusher 공식 Go 라이브러리 pusher-http-go를 그대로 쓰고, 브라우저에서는 pusher-js를 쓰면 됩니다. 이 글에서는 클라이언트 만들기, 이벤트 발행, 비공개 및 presence 채널 인가, 프런트엔드 연결, 웹훅 수신의 다섯 가지를 차례로 다룹니다.
1단계: 설치하고 클라이언트 만들기
go get github.com/pusher/pusher-http-go/v5시작할 때 클라이언트를 하나 만들고 App ID, key, secret은 환경 변수에서 읽습니다(앱을 만들면 볼 수 있습니다). 그다음 이벤트를 발행하는 핸들러나 서비스에 넘겨 줍니다.
import pusher "github.com/pusher/pusher-http-go/v5"
func newRealtime() *pusher.Client {
return &pusher.Client{
AppID: os.Getenv("HIBIRA_APP_ID"),
Key: os.Getenv("HIBIRA_APP_KEY"),
Secret: os.Getenv("HIBIRA_APP_SECRET"),
Host: "ws.hibira.io",
Secure: true,
// 라이브러리가 첫 요청 때 만들게 두지 말고 시작할 때 설정해 둡니다
HTTPClient: &http.Client{Timeout: 3 * time.Second},
}
}HTTPClient 줄에는 이유가 있습니다. 이것을 설정하지 않으면 pusher-http-go는 첫 요청 때 타임아웃 5초짜리 http.Client를 만들어 클라이언트에 다시 써 넣습니다. 여러 goroutine이 동시에 처음 발행하면 이는 데이터 경쟁이 되고, go test -race가 잡아냅니다. 시작할 때 직접 설정하고, 이참에 서비스에 맞는 타임아웃으로 바꿔 두세요.
2단계: 이벤트 발행하기
발행은 HTTP 호출 한 번입니다. 주문 발송을 예로 들어 보겠습니다.
func shipOrder(rt *pusher.Client, w http.ResponseWriter, r *http.Request) {
order := Order{ID: 1024, Status: "shipped"}
// … 먼저 주문 상태를 데이터베이스에 씁니다 …
socketID := r.Header.Get("X-Socket-ID") // 프런트엔드가 보낸 값, 비어 있을 수 있음
if err := rt.TriggerExclusive("private-user-42", "order-updated", order, socketID); err != nil {
log.Printf("realtime: %v", err) // 발행에 실패해도 주문 자체는 그대로 둡니다
}
json.NewEncoder(w).Encode(order)
}실무 팁:
- 먼저 데이터베이스에 쓰고, 그다음 발행합니다. 실시간 이벤트는 알림이지 데이터의 원본이 아닙니다. 다시 연결된 클라이언트는 놓쳤을지 모르는 이벤트에 기대지 말고 API에서 다시 읽어야 합니다.
- 보낸 사람은 제외합니다. 프런트엔드의 socket ID를
TriggerExclusive에 넘기면 변경을 일으킨 탭은 자기 업데이트를 다시 받지 않습니다. 모두에게 보낼 때는 그냥Trigger면 충분합니다. - 한 번에 여러 개를 보냅니다. 한 요청에서 여러 채널을 업데이트할 때는
TriggerMulti(같은 이벤트를 여러 채널로)나TriggerBatch(서로 다른 이벤트)로 왕복 횟수를 줄입니다. - 요청을 붙잡아 두지 않습니다. 발행이 지연에 민감한 경로에 있다면 백그라운드 goroutine이나 작업 큐에 맡기되, 오류 처리와 종료 시 남은 작업 마무리는 챙기세요.
보안 참고: X-Socket-ID는 이벤트가 요청한 탭으로 되돌아가는 것을 막기 위한 선택적 값일 뿐, 사용자 신원을 증명하지 않습니다. 채널 권한은 서버가 검증한 세션 또는 JWT로 확인하고, 폼 형식과 요청 크기를 검증해 데이터가 조용히 잘리지 않도록 하세요.
3단계: 비공개 및 presence 채널 인가
private-나 presence-로 시작하는 채널은 구독 전에 클라이언트가 내 서버에 서명을 요청합니다. 이 엔드포인트는 Go 서비스가 제공하므로 "누가 어떤 채널을 볼 수 있는지"는 전적으로 내 코드가 정합니다.
func pusherAuth(rt *pusher.Client) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
user, ok := currentUser(r) // 직접 구현한 세션 또는 JWT 확인
if !ok {
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
}
body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 4096))
if err != nil {
http.Error(w, "bad request", http.StatusBadRequest)
return
}
form, err := url.ParseQuery(string(body))
if err != nil {
http.Error(w, "bad request", http.StatusBadRequest)
return
}
channel := form.Get("channel_name")
if (!strings.HasPrefix(channel, "private-") && !strings.HasPrefix(channel, "presence-")) || !user.CanJoin(channel) {
http.Error(w, "forbidden", http.StatusForbidden)
return
}
var resp []byte
if strings.HasPrefix(channel, "presence-") {
resp, err = rt.AuthorizePresenceChannel(body, pusher.MemberData{
UserID: user.ID,
UserInfo: map[string]string{"name": user.Name},
})
} else {
resp, err = rt.AuthorizePrivateChannel(body)
}
if err != nil {
http.Error(w, "forbidden", http.StatusForbidden)
return
}
w.Header().Set("Content-Type", "application/json")
w.Write(resp)
}
}라이브러리는 서명만 할 뿐 권한은 확인하지 않으므로 CanJoin 단계는 꼭 직접 작성해야 합니다. 흔한 실수는 "로그인했는지"만 확인하는 것인데, 그러면 로그인한 사용자라면 누구나 private-user-42를 구독할 수 있습니다. presence 채널의 UserInfo는 채널의 모든 멤버에게 전달되니 공개해도 되는 정보만 넣으세요.
Go 1.22부터 쓸 수 있는 http.ServeMux 패턴으로 세 엔드포인트를 연결합니다.
rt := newRealtime()
mux := http.NewServeMux()
mux.HandleFunc("POST /orders/{id}/ship", func(w http.ResponseWriter, r *http.Request) { shipOrder(rt, w, r) })
mux.HandleFunc("POST /pusher/auth", pusherAuth(rt))
mux.HandleFunc("POST /pusher/webhook", pusherWebhook(rt))
log.Fatal(http.ListenAndServe(":8080", mux))4단계: 프런트엔드 연결하기
브라우저에서는 pusher-js의 호스트를 Hibira로, 인가 엔드포인트를 Go 서비스로 지정합니다.
import Pusher from 'pusher-js';
const pusher = new Pusher('your-app-key', {
cluster: 'hkg',
wsHost: 'ws.hibira.io',
wsPort: 443,
wssPort: 443,
forceTLS: true,
enabledTransports: ['ws', 'wss'],
channelAuthorization: { endpoint: '/pusher/auth', transport: 'ajax' },
});
pusher.subscribe('private-user-42').bind('order-updated', (order) => {
renderOrder(order);
});
// 자체 API를 호출할 때 socket ID를 보내 서버가 이 탭을 제외하게 합니다
await fetch('/orders/1024/ship', {
method: 'POST',
headers: { 'X-Socket-ID': pusher.connection.socket_id },
});인가 요청에는 브라우저의 쿠키가 함께 가므로, 프런트엔드와 Go 서비스가 같은 도메인에 있다면 기존 세션을 그대로 쓸 수 있습니다. JWT를 쓴다면 channelAuthorization.headers에 Authorization 헤더를 추가합니다. 모바일 앱도 마찬가지로, PusherSwift와 pusher-java-client 모두 호스트와 인가 엔드포인트를 설정할 수 있습니다.
5단계: 웹훅 받기
채널에 첫 구독자가 생길 때, presence 채널에 누가 들어오거나 나갈 때를 알고 싶다면 앱 페이지에서 웹훅 URL을 설정합니다. X-Pusher-Key 헤더와 HMAC 서명 검증은 pusher-http-go가 해 줍니다.
func pusherWebhook(rt *pusher.Client) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))
if err != nil {
http.Error(w, "bad request", http.StatusBadRequest)
return
}
hook, err := rt.Webhook(r.Header, body) // X-Pusher-Key와 서명을 검증합니다
if err != nil {
http.Error(w, "invalid signature", http.StatusUnauthorized)
return
}
for _, e := range hook.Events {
switch e.Name {
case "member_added":
markOnline(e.UserID)
case "member_removed":
markOffline(e.UserID)
}
}
w.WriteHeader(http.StatusOK)
}
}웹훅은 짧은 시간 동안의 이벤트를 모아 한 번의 요청으로 보냅니다. 엔드포인트가 2xx로 응답하지 않으면 Hibira는 최대 5분 동안 재시도하므로 처리는 멱등이어야 합니다. 같은 member_added를 두 번 받아도 결과가 같아야 합니다. 처리가 오래 걸린다면 먼저 200을 응답하고 백그라운드 작업에 넘기세요.
출시 전 점검
- 발행하는 코드를
go test -race로 실행해 봤다. - 비공개 채널 인가에서 "로그인했는지"만이 아니라 "이 사용자가 이 채널을 볼 수 있는지"를 확인한다.
- App secret은 환경 변수나 시크릿 관리 서비스에만 두고, 버전 관리나 프런트엔드 코드에는 넣지 않았다.
- 앱 페이지의 디버그 콘솔에서 발행한 이벤트, 구독, 웹훅이 보이는지 확인했다.
Go 기본 설정은 Go 연동 가이드에도 있으며, 앱 페이지에서 열면 호스트가 자동으로 채워집니다. 푸시 알림이 필요하다면 푸시 알림 가이드에 Go 예제가 있습니다. 전체 시나리오는 주문 추적과 협업과 접속 상태를 참고하세요. Claude Code 같은 AI 도우미로 코드를 작성한다면 Hibira MCP 서버를 통해 Go 연동 가이드를 가져와 프로젝트를 바로 수정하게 할 수도 있습니다.