[fix](protocol): improve Protobuf decoding with precise payload reading and clarification

- Refactored `Decode` to use `io.ReadFull` for accurate length-prefix and payload reading.
- Simplified logic to avoid mismatched length issues and clarified comments for maintainability.

.github/workflows/docker-publish.yml

@@ -56,4 +56,6 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-to: type=gha,mode=max
+          build-args: |
+            VERSION=${{ github.sha }}

Dockerfile.server

@@ -18,6 +18,8 @@ FROM golang:1.25-alpine AS builder
 # 기본값을 지정해두면 로컬 docker build 시에도 별도 인자 없이 빌드 가능합니다.
 ARG TARGETOS=linux
 ARG TARGETARCH=amd64
+# Git 태그/커밋 정보를 main.version 에 주입하기 위한 VERSION 인자 (기본 dev)
+ARG VERSION=dev
 
 WORKDIR /src
 
@@ -32,7 +34,8 @@ RUN go mod download
 COPY . .
 
 # 서버 바이너리 빌드 (멀티 아키텍처: TARGETOS/TARGETARCH 기반)
-RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /out/hop-gate-server ./cmd/server
+# -ldflags 를 통해 main.version 에 VERSION 값을 주입합니다.
+RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -ldflags "-X main.version=${VERSION}" -o /out/hop-gate-server ./cmd/server
 
 # ---------- Runtime stage ----------
 FROM alpine:3.20

Makefile

@@ -18,7 +18,9 @@ BIN_DIR := ./bin
 SERVER_BIN := $(BIN_DIR)/hop-gate-server
 CLIENT_BIN := $(BIN_DIR)/hop-gate-client
 
-VERSION ?= $(shell git describe --tags --dirty --always 2>/dev/null || echo dev)
+# VERSION 은 현재 커밋의 7글자 SHA 를 사용합니다 (예: 1a2b3c4).
+# git 정보가 없으면 dev 로 fallback 합니다.
+VERSION ?= $(shell git rev-parse --short=7 HEAD 2>/dev/null || echo dev)
 
 # .env 파일 로드
 include .env

cmd/client/main.go

@@ -15,6 +15,10 @@ import (
 	"github.com/dalbodeule/hop-gate/internal/proxy"
 )
 
+// version 은 빌드 시 -ldflags "-X main.version=xxxxxxx" 로 덮어쓰이는 필드입니다.
+// 기본값 "dev" 는 로컬 개발용입니다.
+var version = "dev"
+
 func getEnvOrPanic(logger logging.Logger, key string) string {
 	value, exists := os.LookupEnv(key)
 	if !exists || strings.TrimSpace(value) == "" {
@@ -124,6 +128,7 @@ func main() {
 
 	logger.Info("hop-gate client starting", logging.Fields{
 		"stack":                 "prometheus-loki-grafana",
+		"version":               version,
 		"server_addr":           finalCfg.ServerAddr,
 		"domain":                finalCfg.Domain,
 		"local_target":          finalCfg.LocalTarget,

cmd/server/main.go

@@ -29,6 +29,10 @@ import (
 	"github.com/dalbodeule/hop-gate/internal/store"
 )
 
+// version 은 빌드 시 -ldflags "-X main.version=xxxxxxx" 로 덮어쓰이는 필드입니다.
+// 기본값 "dev" 는 로컬 개발용입니다.
+var version = "dev"
+
 type dtlsSessionWrapper struct {
 	sess         dtls.Session
 	mu           sync.Mutex
@@ -815,6 +819,7 @@ func main() {
 
 	logger.Info("hop-gate server starting", logging.Fields{
 		"stack":        "prometheus-loki-grafana",
+		"version":      version,
 		"http_listen":  cfg.HTTPListen,
 		"https_listen": cfg.HTTPSListen,
 		"dtls_listen":  cfg.DTLSListen,

github.com/dalbodeule/hop-gate/internal/protocol/pb/hopgate_stream.pb.go

@@ -0,0 +1,799 @@
+// Code generated by protoc-gen-go. DO NOT EDIT.
+// versions:
+// 	protoc-gen-go v1.36.10
+// 	protoc        v6.33.1
+// source: internal/protocol/hopgate_stream.proto
+
+package protocolpb
+
+import (
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
+	reflect "reflect"
+	sync "sync"
+	unsafe "unsafe"
+)
+
+const (
+	// Verify that this generated code is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(20 - protoimpl.MinVersion)
+	// Verify that runtime/protoimpl is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
+)
+
+// HeaderValues 는 HTTP 헤더의 다중 값 표현을 위한 래퍼입니다.
+// HeaderValues wraps multiple header values for a single HTTP header key.
+type HeaderValues struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Values        []string               `protobuf:"bytes,1,rep,name=values,proto3" json:"values,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *HeaderValues) Reset() {
+	*x = HeaderValues{}
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[0]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *HeaderValues) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*HeaderValues) ProtoMessage() {}
+
+func (x *HeaderValues) ProtoReflect() protoreflect.Message {
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[0]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use HeaderValues.ProtoReflect.Descriptor instead.
+func (*HeaderValues) Descriptor() ([]byte, []int) {
+	return file_internal_protocol_hopgate_stream_proto_rawDescGZIP(), []int{0}
+}
+
+func (x *HeaderValues) GetValues() []string {
+	if x != nil {
+		return x.Values
+	}
+	return nil
+}
+
+// Request 는 DTLS 터널 위에서 교환되는 HTTP 요청을 표현합니다.
+// This mirrors internal/protocol.Request.
+type Request struct {
+	state       protoimpl.MessageState `protogen:"open.v1"`
+	RequestId   string                 `protobuf:"bytes,1,opt,name=request_id,json=requestId,proto3" json:"request_id,omitempty"`
+	ClientId    string                 `protobuf:"bytes,2,opt,name=client_id,json=clientId,proto3" json:"client_id,omitempty"`          // optional client identifier
+	ServiceName string                 `protobuf:"bytes,3,opt,name=service_name,json=serviceName,proto3" json:"service_name,omitempty"` // logical service name on the client side
+	Method      string                 `protobuf:"bytes,4,opt,name=method,proto3" json:"method,omitempty"`
+	Url         string                 `protobuf:"bytes,5,opt,name=url,proto3" json:"url,omitempty"`
+	// HTTP header: map of key -> multiple values.
+	Header map[string]*HeaderValues `protobuf:"bytes,6,rep,name=header,proto3" json:"header,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"`
+	// Raw HTTP body bytes.
+	Body          []byte `protobuf:"bytes,7,opt,name=body,proto3" json:"body,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *Request) Reset() {
+	*x = Request{}
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[1]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *Request) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*Request) ProtoMessage() {}
+
+func (x *Request) ProtoReflect() protoreflect.Message {
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[1]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use Request.ProtoReflect.Descriptor instead.
+func (*Request) Descriptor() ([]byte, []int) {
+	return file_internal_protocol_hopgate_stream_proto_rawDescGZIP(), []int{1}
+}
+
+func (x *Request) GetRequestId() string {
+	if x != nil {
+		return x.RequestId
+	}
+	return ""
+}
+
+func (x *Request) GetClientId() string {
+	if x != nil {
+		return x.ClientId
+	}
+	return ""
+}
+
+func (x *Request) GetServiceName() string {
+	if x != nil {
+		return x.ServiceName
+	}
+	return ""
+}
+
+func (x *Request) GetMethod() string {
+	if x != nil {
+		return x.Method
+	}
+	return ""
+}
+
+func (x *Request) GetUrl() string {
+	if x != nil {
+		return x.Url
+	}
+	return ""
+}
+
+func (x *Request) GetHeader() map[string]*HeaderValues {
+	if x != nil {
+		return x.Header
+	}
+	return nil
+}
+
+func (x *Request) GetBody() []byte {
+	if x != nil {
+		return x.Body
+	}
+	return nil
+}
+
+// Response 는 DTLS 터널 위에서 교환되는 HTTP 응답을 표현합니다.
+// This mirrors internal/protocol.Response.
+type Response struct {
+	state     protoimpl.MessageState `protogen:"open.v1"`
+	RequestId string                 `protobuf:"bytes,1,opt,name=request_id,json=requestId,proto3" json:"request_id,omitempty"`
+	Status    int32                  `protobuf:"varint,2,opt,name=status,proto3" json:"status,omitempty"`
+	// HTTP header.
+	Header map[string]*HeaderValues `protobuf:"bytes,3,rep,name=header,proto3" json:"header,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"`
+	// Raw HTTP body bytes.
+	Body []byte `protobuf:"bytes,4,opt,name=body,proto3" json:"body,omitempty"`
+	// Optional error description when tunneling fails.
+	Error         string `protobuf:"bytes,5,opt,name=error,proto3" json:"error,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *Response) Reset() {
+	*x = Response{}
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[2]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *Response) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*Response) ProtoMessage() {}
+
+func (x *Response) ProtoReflect() protoreflect.Message {
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[2]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use Response.ProtoReflect.Descriptor instead.
+func (*Response) Descriptor() ([]byte, []int) {
+	return file_internal_protocol_hopgate_stream_proto_rawDescGZIP(), []int{2}
+}
+
+func (x *Response) GetRequestId() string {
+	if x != nil {
+		return x.RequestId
+	}
+	return ""
+}
+
+func (x *Response) GetStatus() int32 {
+	if x != nil {
+		return x.Status
+	}
+	return 0
+}
+
+func (x *Response) GetHeader() map[string]*HeaderValues {
+	if x != nil {
+		return x.Header
+	}
+	return nil
+}
+
+func (x *Response) GetBody() []byte {
+	if x != nil {
+		return x.Body
+	}
+	return nil
+}
+
+func (x *Response) GetError() string {
+	if x != nil {
+		return x.Error
+	}
+	return ""
+}
+
+// StreamOpen 은 새로운 스트림(HTTP 요청/응답, WebSocket 등)을 여는 메시지입니다.
+// This represents opening a new stream (HTTP request/response, WebSocket, etc.).
+type StreamOpen struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	Id    string                 `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"` // StreamID (text form)
+	// Which logical service / local target to use on the client side.
+	ServiceName string `protobuf:"bytes,2,opt,name=service_name,json=serviceName,proto3" json:"service_name,omitempty"`
+	TargetAddr  string `protobuf:"bytes,3,opt,name=target_addr,json=targetAddr,proto3" json:"target_addr,omitempty"` // e.g. "127.0.0.1:8080"
+	// Initial HTTP-like headers (including Upgrade, etc.).
+	Header        map[string]*HeaderValues `protobuf:"bytes,4,rep,name=header,proto3" json:"header,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *StreamOpen) Reset() {
+	*x = StreamOpen{}
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[3]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *StreamOpen) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*StreamOpen) ProtoMessage() {}
+
+func (x *StreamOpen) ProtoReflect() protoreflect.Message {
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[3]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use StreamOpen.ProtoReflect.Descriptor instead.
+func (*StreamOpen) Descriptor() ([]byte, []int) {
+	return file_internal_protocol_hopgate_stream_proto_rawDescGZIP(), []int{3}
+}
+
+func (x *StreamOpen) GetId() string {
+	if x != nil {
+		return x.Id
+	}
+	return ""
+}
+
+func (x *StreamOpen) GetServiceName() string {
+	if x != nil {
+		return x.ServiceName
+	}
+	return ""
+}
+
+func (x *StreamOpen) GetTargetAddr() string {
+	if x != nil {
+		return x.TargetAddr
+	}
+	return ""
+}
+
+func (x *StreamOpen) GetHeader() map[string]*HeaderValues {
+	if x != nil {
+		return x.Header
+	}
+	return nil
+}
+
+// StreamData 는 이미 열린 스트림에 대한 단방향 데이터 프레임입니다.
+// This is a unidirectional data frame on an already-open stream.
+type StreamData struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Id            string                 `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`    // StreamID
+	Seq           uint64                 `protobuf:"varint,2,opt,name=seq,proto3" json:"seq,omitempty"` // per-stream sequence number starting from 0
+	Data          []byte                 `protobuf:"bytes,3,opt,name=data,proto3" json:"data,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *StreamData) Reset() {
+	*x = StreamData{}
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[4]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *StreamData) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*StreamData) ProtoMessage() {}
+
+func (x *StreamData) ProtoReflect() protoreflect.Message {
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[4]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use StreamData.ProtoReflect.Descriptor instead.
+func (*StreamData) Descriptor() ([]byte, []int) {
+	return file_internal_protocol_hopgate_stream_proto_rawDescGZIP(), []int{4}
+}
+
+func (x *StreamData) GetId() string {
+	if x != nil {
+		return x.Id
+	}
+	return ""
+}
+
+func (x *StreamData) GetSeq() uint64 {
+	if x != nil {
+		return x.Seq
+	}
+	return 0
+}
+
+func (x *StreamData) GetData() []byte {
+	if x != nil {
+		return x.Data
+	}
+	return nil
+}
+
+// StreamAck 는 StreamData 에 대한 ACK/NACK 및 선택적 재전송 힌트를 전달합니다.
+// This conveys ACK/NACK and optional retransmission hints for StreamData.
+type StreamAck struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	Id    string                 `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
+	// Last contiguously received sequence number (starting from 0).
+	AckSeq uint64 `protobuf:"varint,2,opt,name=ack_seq,json=ackSeq,proto3" json:"ack_seq,omitempty"`
+	// Additional missing sequence numbers beyond ack_seq (optional).
+	LostSeqs []uint64 `protobuf:"varint,3,rep,packed,name=lost_seqs,json=lostSeqs,proto3" json:"lost_seqs,omitempty"`
+	// Optional receive window size hint.
+	WindowSize    uint32 `protobuf:"varint,4,opt,name=window_size,json=windowSize,proto3" json:"window_size,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *StreamAck) Reset() {
+	*x = StreamAck{}
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[5]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *StreamAck) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*StreamAck) ProtoMessage() {}
+
+func (x *StreamAck) ProtoReflect() protoreflect.Message {
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[5]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use StreamAck.ProtoReflect.Descriptor instead.
+func (*StreamAck) Descriptor() ([]byte, []int) {
+	return file_internal_protocol_hopgate_stream_proto_rawDescGZIP(), []int{5}
+}
+
+func (x *StreamAck) GetId() string {
+	if x != nil {
+		return x.Id
+	}
+	return ""
+}
+
+func (x *StreamAck) GetAckSeq() uint64 {
+	if x != nil {
+		return x.AckSeq
+	}
+	return 0
+}
+
+func (x *StreamAck) GetLostSeqs() []uint64 {
+	if x != nil {
+		return x.LostSeqs
+	}
+	return nil
+}
+
+func (x *StreamAck) GetWindowSize() uint32 {
+	if x != nil {
+		return x.WindowSize
+	}
+	return 0
+}
+
+// StreamClose 는 스트림 종료(정상/에러)를 알립니다.
+// This indicates normal or error termination of a stream.
+type StreamClose struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Id            string                 `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
+	Error         string                 `protobuf:"bytes,2,opt,name=error,proto3" json:"error,omitempty"` // empty means normal close
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *StreamClose) Reset() {
+	*x = StreamClose{}
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[6]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *StreamClose) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*StreamClose) ProtoMessage() {}
+
+func (x *StreamClose) ProtoReflect() protoreflect.Message {
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[6]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use StreamClose.ProtoReflect.Descriptor instead.
+func (*StreamClose) Descriptor() ([]byte, []int) {
+	return file_internal_protocol_hopgate_stream_proto_rawDescGZIP(), []int{6}
+}
+
+func (x *StreamClose) GetId() string {
+	if x != nil {
+		return x.Id
+	}
+	return ""
+}
+
+func (x *StreamClose) GetError() string {
+	if x != nil {
+		return x.Error
+	}
+	return ""
+}
+
+// Envelope 는 DTLS 세션 위에서 교환되는 상위 레벨 메시지 컨테이너입니다.
+// 하나의 Envelope 에는 HTTP 요청/응답 또는 스트림 관련 메시지 중 하나만 포함됩니다.
+// Envelope is the top-level container exchanged over the DTLS session.
+// Exactly one payload (http_request/http_response/stream_*) is set per message.
+type Envelope struct {
+	state protoimpl.MessageState `protogen:"open.v1"`
+	// Types that are valid to be assigned to Payload:
+	//
+	//	*Envelope_HttpRequest
+	//	*Envelope_HttpResponse
+	//	*Envelope_StreamOpen
+	//	*Envelope_StreamData
+	//	*Envelope_StreamClose
+	//	*Envelope_StreamAck
+	Payload       isEnvelope_Payload `protobuf_oneof:"payload"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *Envelope) Reset() {
+	*x = Envelope{}
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[7]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *Envelope) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*Envelope) ProtoMessage() {}
+
+func (x *Envelope) ProtoReflect() protoreflect.Message {
+	mi := &file_internal_protocol_hopgate_stream_proto_msgTypes[7]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use Envelope.ProtoReflect.Descriptor instead.
+func (*Envelope) Descriptor() ([]byte, []int) {
+	return file_internal_protocol_hopgate_stream_proto_rawDescGZIP(), []int{7}
+}
+
+func (x *Envelope) GetPayload() isEnvelope_Payload {
+	if x != nil {
+		return x.Payload
+	}
+	return nil
+}
+
+func (x *Envelope) GetHttpRequest() *Request {
+	if x != nil {
+		if x, ok := x.Payload.(*Envelope_HttpRequest); ok {
+			return x.HttpRequest
+		}
+	}
+	return nil
+}
+
+func (x *Envelope) GetHttpResponse() *Response {
+	if x != nil {
+		if x, ok := x.Payload.(*Envelope_HttpResponse); ok {
+			return x.HttpResponse
+		}
+	}
+	return nil
+}
+
+func (x *Envelope) GetStreamOpen() *StreamOpen {
+	if x != nil {
+		if x, ok := x.Payload.(*Envelope_StreamOpen); ok {
+			return x.StreamOpen
+		}
+	}
+	return nil
+}
+
+func (x *Envelope) GetStreamData() *StreamData {
+	if x != nil {
+		if x, ok := x.Payload.(*Envelope_StreamData); ok {
+			return x.StreamData
+		}
+	}
+	return nil
+}
+
+func (x *Envelope) GetStreamClose() *StreamClose {
+	if x != nil {
+		if x, ok := x.Payload.(*Envelope_StreamClose); ok {
+			return x.StreamClose
+		}
+	}
+	return nil
+}
+
+func (x *Envelope) GetStreamAck() *StreamAck {
+	if x != nil {
+		if x, ok := x.Payload.(*Envelope_StreamAck); ok {
+			return x.StreamAck
+		}
+	}
+	return nil
+}
+
+type isEnvelope_Payload interface {
+	isEnvelope_Payload()
+}
+
+type Envelope_HttpRequest struct {
+	HttpRequest *Request `protobuf:"bytes,1,opt,name=http_request,json=httpRequest,proto3,oneof"`
+}
+
+type Envelope_HttpResponse struct {
+	HttpResponse *Response `protobuf:"bytes,2,opt,name=http_response,json=httpResponse,proto3,oneof"`
+}
+
+type Envelope_StreamOpen struct {
+	StreamOpen *StreamOpen `protobuf:"bytes,3,opt,name=stream_open,json=streamOpen,proto3,oneof"`
+}
+
+type Envelope_StreamData struct {
+	StreamData *StreamData `protobuf:"bytes,4,opt,name=stream_data,json=streamData,proto3,oneof"`
+}
+
+type Envelope_StreamClose struct {
+	StreamClose *StreamClose `protobuf:"bytes,5,opt,name=stream_close,json=streamClose,proto3,oneof"`
+}
+
+type Envelope_StreamAck struct {
+	StreamAck *StreamAck `protobuf:"bytes,6,opt,name=stream_ack,json=streamAck,proto3,oneof"`
+}
+
+func (*Envelope_HttpRequest) isEnvelope_Payload() {}
+
+func (*Envelope_HttpResponse) isEnvelope_Payload() {}
+
+func (*Envelope_StreamOpen) isEnvelope_Payload() {}
+
+func (*Envelope_StreamData) isEnvelope_Payload() {}
+
+func (*Envelope_StreamClose) isEnvelope_Payload() {}
+
+func (*Envelope_StreamAck) isEnvelope_Payload() {}
+
+var File_internal_protocol_hopgate_stream_proto protoreflect.FileDescriptor
+
+const file_internal_protocol_hopgate_stream_proto_rawDesc = "" +
+	"\n" +
+	"&internal/protocol/hopgate_stream.proto\x12\x13hopgate.protocol.v1\"&\n" +
+	"\fHeaderValues\x12\x16\n" +
+	"\x06values\x18\x01 \x03(\tR\x06values\"\xc6\x02\n" +
+	"\aRequest\x12\x1d\n" +
+	"\n" +
+	"request_id\x18\x01 \x01(\tR\trequestId\x12\x1b\n" +
+	"\tclient_id\x18\x02 \x01(\tR\bclientId\x12!\n" +
+	"\fservice_name\x18\x03 \x01(\tR\vserviceName\x12\x16\n" +
+	"\x06method\x18\x04 \x01(\tR\x06method\x12\x10\n" +
+	"\x03url\x18\x05 \x01(\tR\x03url\x12@\n" +
+	"\x06header\x18\x06 \x03(\v2(.hopgate.protocol.v1.Request.HeaderEntryR\x06header\x12\x12\n" +
+	"\x04body\x18\a \x01(\fR\x04body\x1a\\\n" +
+	"\vHeaderEntry\x12\x10\n" +
+	"\x03key\x18\x01 \x01(\tR\x03key\x127\n" +
+	"\x05value\x18\x02 \x01(\v2!.hopgate.protocol.v1.HeaderValuesR\x05value:\x028\x01\"\x8c\x02\n" +
+	"\bResponse\x12\x1d\n" +
+	"\n" +
+	"request_id\x18\x01 \x01(\tR\trequestId\x12\x16\n" +
+	"\x06status\x18\x02 \x01(\x05R\x06status\x12A\n" +
+	"\x06header\x18\x03 \x03(\v2).hopgate.protocol.v1.Response.HeaderEntryR\x06header\x12\x12\n" +
+	"\x04body\x18\x04 \x01(\fR\x04body\x12\x14\n" +
+	"\x05error\x18\x05 \x01(\tR\x05error\x1a\\\n" +
+	"\vHeaderEntry\x12\x10\n" +
+	"\x03key\x18\x01 \x01(\tR\x03key\x127\n" +
+	"\x05value\x18\x02 \x01(\v2!.hopgate.protocol.v1.HeaderValuesR\x05value:\x028\x01\"\x83\x02\n" +
+	"\n" +
+	"StreamOpen\x12\x0e\n" +
+	"\x02id\x18\x01 \x01(\tR\x02id\x12!\n" +
+	"\fservice_name\x18\x02 \x01(\tR\vserviceName\x12\x1f\n" +
+	"\vtarget_addr\x18\x03 \x01(\tR\n" +
+	"targetAddr\x12C\n" +
+	"\x06header\x18\x04 \x03(\v2+.hopgate.protocol.v1.StreamOpen.HeaderEntryR\x06header\x1a\\\n" +
+	"\vHeaderEntry\x12\x10\n" +
+	"\x03key\x18\x01 \x01(\tR\x03key\x127\n" +
+	"\x05value\x18\x02 \x01(\v2!.hopgate.protocol.v1.HeaderValuesR\x05value:\x028\x01\"B\n" +
+	"\n" +
+	"StreamData\x12\x0e\n" +
+	"\x02id\x18\x01 \x01(\tR\x02id\x12\x10\n" +
+	"\x03seq\x18\x02 \x01(\x04R\x03seq\x12\x12\n" +
+	"\x04data\x18\x03 \x01(\fR\x04data\"r\n" +
+	"\tStreamAck\x12\x0e\n" +
+	"\x02id\x18\x01 \x01(\tR\x02id\x12\x17\n" +
+	"\aack_seq\x18\x02 \x01(\x04R\x06ackSeq\x12\x1b\n" +
+	"\tlost_seqs\x18\x03 \x03(\x04R\blostSeqs\x12\x1f\n" +
+	"\vwindow_size\x18\x04 \x01(\rR\n" +
+	"windowSize\"3\n" +
+	"\vStreamClose\x12\x0e\n" +
+	"\x02id\x18\x01 \x01(\tR\x02id\x12\x14\n" +
+	"\x05error\x18\x02 \x01(\tR\x05error\"\xae\x03\n" +
+	"\bEnvelope\x12A\n" +
+	"\fhttp_request\x18\x01 \x01(\v2\x1c.hopgate.protocol.v1.RequestH\x00R\vhttpRequest\x12D\n" +
+	"\rhttp_response\x18\x02 \x01(\v2\x1d.hopgate.protocol.v1.ResponseH\x00R\fhttpResponse\x12B\n" +
+	"\vstream_open\x18\x03 \x01(\v2\x1f.hopgate.protocol.v1.StreamOpenH\x00R\n" +
+	"streamOpen\x12B\n" +
+	"\vstream_data\x18\x04 \x01(\v2\x1f.hopgate.protocol.v1.StreamDataH\x00R\n" +
+	"streamData\x12E\n" +
+	"\fstream_close\x18\x05 \x01(\v2 .hopgate.protocol.v1.StreamCloseH\x00R\vstreamClose\x12?\n" +
+	"\n" +
+	"stream_ack\x18\x06 \x01(\v2\x1e.hopgate.protocol.v1.StreamAckH\x00R\tstreamAckB\t\n" +
+	"\apayloadB@Z>github.com/dalbodeule/hop-gate/internal/protocol/pb;protocolpbb\x06proto3"
+
+var (
+	file_internal_protocol_hopgate_stream_proto_rawDescOnce sync.Once
+	file_internal_protocol_hopgate_stream_proto_rawDescData []byte
+)
+
+func file_internal_protocol_hopgate_stream_proto_rawDescGZIP() []byte {
+	file_internal_protocol_hopgate_stream_proto_rawDescOnce.Do(func() {
+		file_internal_protocol_hopgate_stream_proto_rawDescData = protoimpl.X.CompressGZIP(unsafe.Slice(unsafe.StringData(file_internal_protocol_hopgate_stream_proto_rawDesc), len(file_internal_protocol_hopgate_stream_proto_rawDesc)))
+	})
+	return file_internal_protocol_hopgate_stream_proto_rawDescData
+}
+
+var file_internal_protocol_hopgate_stream_proto_msgTypes = make([]protoimpl.MessageInfo, 11)
+var file_internal_protocol_hopgate_stream_proto_goTypes = []any{
+	(*HeaderValues)(nil), // 0: hopgate.protocol.v1.HeaderValues
+	(*Request)(nil),      // 1: hopgate.protocol.v1.Request
+	(*Response)(nil),     // 2: hopgate.protocol.v1.Response
+	(*StreamOpen)(nil),   // 3: hopgate.protocol.v1.StreamOpen
+	(*StreamData)(nil),   // 4: hopgate.protocol.v1.StreamData
+	(*StreamAck)(nil),    // 5: hopgate.protocol.v1.StreamAck
+	(*StreamClose)(nil),  // 6: hopgate.protocol.v1.StreamClose
+	(*Envelope)(nil),     // 7: hopgate.protocol.v1.Envelope
+	nil,                  // 8: hopgate.protocol.v1.Request.HeaderEntry
+	nil,                  // 9: hopgate.protocol.v1.Response.HeaderEntry
+	nil,                  // 10: hopgate.protocol.v1.StreamOpen.HeaderEntry
+}
+var file_internal_protocol_hopgate_stream_proto_depIdxs = []int32{
+	8,  // 0: hopgate.protocol.v1.Request.header:type_name -> hopgate.protocol.v1.Request.HeaderEntry
+	9,  // 1: hopgate.protocol.v1.Response.header:type_name -> hopgate.protocol.v1.Response.HeaderEntry
+	10, // 2: hopgate.protocol.v1.StreamOpen.header:type_name -> hopgate.protocol.v1.StreamOpen.HeaderEntry
+	1,  // 3: hopgate.protocol.v1.Envelope.http_request:type_name -> hopgate.protocol.v1.Request
+	2,  // 4: hopgate.protocol.v1.Envelope.http_response:type_name -> hopgate.protocol.v1.Response
+	3,  // 5: hopgate.protocol.v1.Envelope.stream_open:type_name -> hopgate.protocol.v1.StreamOpen
+	4,  // 6: hopgate.protocol.v1.Envelope.stream_data:type_name -> hopgate.protocol.v1.StreamData
+	6,  // 7: hopgate.protocol.v1.Envelope.stream_close:type_name -> hopgate.protocol.v1.StreamClose
+	5,  // 8: hopgate.protocol.v1.Envelope.stream_ack:type_name -> hopgate.protocol.v1.StreamAck
+	0,  // 9: hopgate.protocol.v1.Request.HeaderEntry.value:type_name -> hopgate.protocol.v1.HeaderValues
+	0,  // 10: hopgate.protocol.v1.Response.HeaderEntry.value:type_name -> hopgate.protocol.v1.HeaderValues
+	0,  // 11: hopgate.protocol.v1.StreamOpen.HeaderEntry.value:type_name -> hopgate.protocol.v1.HeaderValues
+	12, // [12:12] is the sub-list for method output_type
+	12, // [12:12] is the sub-list for method input_type
+	12, // [12:12] is the sub-list for extension type_name
+	12, // [12:12] is the sub-list for extension extendee
+	0,  // [0:12] is the sub-list for field type_name
+}
+
+func init() { file_internal_protocol_hopgate_stream_proto_init() }
+func file_internal_protocol_hopgate_stream_proto_init() {
+	if File_internal_protocol_hopgate_stream_proto != nil {
+		return
+	}
+	file_internal_protocol_hopgate_stream_proto_msgTypes[7].OneofWrappers = []any{
+		(*Envelope_HttpRequest)(nil),
+		(*Envelope_HttpResponse)(nil),
+		(*Envelope_StreamOpen)(nil),
+		(*Envelope_StreamData)(nil),
+		(*Envelope_StreamClose)(nil),
+		(*Envelope_StreamAck)(nil),
+	}
+	type x struct{}
+	out := protoimpl.TypeBuilder{
+		File: protoimpl.DescBuilder{
+			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
+			RawDescriptor: unsafe.Slice(unsafe.StringData(file_internal_protocol_hopgate_stream_proto_rawDesc), len(file_internal_protocol_hopgate_stream_proto_rawDesc)),
+			NumEnums:      0,
+			NumMessages:   11,
+			NumExtensions: 0,
+			NumServices:   0,
+		},
+		GoTypes:           file_internal_protocol_hopgate_stream_proto_goTypes,
+		DependencyIndexes: file_internal_protocol_hopgate_stream_proto_depIdxs,
+		MessageInfos:      file_internal_protocol_hopgate_stream_proto_msgTypes,
+	}.Build()
+	File_internal_protocol_hopgate_stream_proto = out.File
+	file_internal_protocol_hopgate_stream_proto_goTypes = nil
+	file_internal_protocol_hopgate_stream_proto_depIdxs = nil
+}

go.mod

@@ -10,6 +10,7 @@ require (
 	github.com/pion/dtls/v3 v3.0.7
 	github.com/prometheus/client_golang v1.19.0
 	golang.org/x/net v0.47.0
+	google.golang.org/protobuf v1.36.10
 )
 
 require (
@@ -40,5 +41,4 @@ require (
 	golang.org/x/sys v0.38.0 // indirect
 	golang.org/x/text v0.31.0 // indirect
 	golang.org/x/tools v0.38.0 // indirect
-	google.golang.org/protobuf v1.36.10 // indirect
 )

go.sum

@@ -32,8 +32,6 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/hashicorp/hcl/v2 v2.18.1 h1:6nxnOJFku1EuSawSD81fuviYUV8DxFr3fp2dUi3ZYSo=
 github.com/hashicorp/hcl/v2 v2.18.1/go.mod h1:ThLC89FV4p9MPW804KVbe/cEXoQ8NZEh+JtMeeGErHE=
-github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
-github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=

internal/protocol/codec.go

@@ -46,12 +46,15 @@ func (jsonCodec) Decode(r io.Reader, env *Envelope) error {
 	return dec.Decode(env)
 }
 
-// protobufCodec 은 Protobuf + length-prefix framing 기반 WireCodec 구현입니다.
+// protobufCodec 은 Protobuf  length-prefix framing 기반 WireCodec 구현입니다.
-// 한 Envelope 당 [4바이트 big-endian 길이] + [protobuf bytes] 형태로 인코딩합니다.
+// 한 Envelope 당 [4바이트 big-endian 길이]  [protobuf bytes] 형태로 인코딩합니다.
 type protobufCodec struct{}
 
 // Encode 는 Envelope 를 Protobuf Envelope 로 변환한 뒤, length-prefix 프레이밍으로 기록합니다.
+// DTLS는 UDP 기반이므로, length prefix와 protobuf 데이터를 단일 버퍼로 합쳐 하나의 Write로 전송합니다.
 // Encode encodes an Envelope as a length-prefixed protobuf message.
+// For DTLS (UDP-based), we combine the length prefix and protobuf data into a single buffer
+// and send it with a single Write call to preserve message boundaries.
 func (protobufCodec) Encode(w io.Writer, env *Envelope) error {
 	pbEnv, err := toProtoEnvelope(env)
 	if err != nil {
@@ -83,44 +86,50 @@ func (protobufCodec) Encode(w io.Writer, env *Envelope) error {
 		return fmt.Errorf("protobuf codec: empty marshaled envelope")
 	}
 
-	var lenBuf [4]byte
 	if len(data) > int(^uint32(0)) {
 		return fmt.Errorf("protobuf codec: envelope too large: %d bytes", len(data))
 	}
-	binary.BigEndian.PutUint32(lenBuf[:], uint32(len(data)))
 
-	if _, err := w.Write(lenBuf[:]); err != nil {
+	// DTLS 환경에서는 length prefix와 protobuf 데이터를 단일 버퍼로 합쳐서 하나의 Write로 전송
-		return fmt.Errorf("protobuf codec: write length prefix: %w", err)
+	// For DTLS, combine length prefix and protobuf data into a single buffer
-	}
+	frame := make([]byte, 4+len(data))
-	if _, err := w.Write(data); err != nil {
+	binary.BigEndian.PutUint32(frame[:4], uint32(len(data)))
-		return fmt.Errorf("protobuf codec: write payload: %w", err)
+	copy(frame[4:], data)
+
+	if _, err := w.Write(frame); err != nil {
+		return fmt.Errorf("protobuf codec: write frame: %w", err)
 	}
 	return nil
 }
 
 // Decode 는 length-prefix 프레임에서 Protobuf Envelope 를 읽어들여
 // 내부 Envelope 구조체로 변환합니다.
+// DTLS는 UDP 기반이므로, 한 번의 Read로 전체 데이터그램을 읽습니다.
 // Decode reads a length-prefixed protobuf Envelope and converts it into the internal Envelope.
+// For DTLS (UDP-based), we read the entire datagram in a single Read call.
 func (protobufCodec) Decode(r io.Reader, env *Envelope) error {
-	var lenBuf [4]byte
+	// 1) 길이 prefix 4바이트를 정확히 읽는다.
-	if _, err := io.ReadFull(r, lenBuf[:]); err != nil {
+	header := make([]byte, 4)
+	if _, err := io.ReadFull(r, header); err != nil {
 		return fmt.Errorf("protobuf codec: read length prefix: %w", err)
 	}
-	n := binary.BigEndian.Uint32(lenBuf[:])
+
-	if n == 0 {
+	length := binary.BigEndian.Uint32(header)
+	if length == 0 {
 		return fmt.Errorf("protobuf codec: zero-length envelope")
 	}
-	if n > maxProtoEnvelopeBytes {
+	if length > maxProtoEnvelopeBytes {
-		return fmt.Errorf("protobuf codec: envelope too large: %d bytes (max %d)", n, maxProtoEnvelopeBytes)
+		return fmt.Errorf("protobuf codec: envelope too large: %d bytes (max %d)", length, maxProtoEnvelopeBytes)
 	}
 
-	buf := make([]byte, int(n))
+	// 2) payload 를 length 바이트만큼 정확히 읽는다.
-	if _, err := io.ReadFull(r, buf); err != nil {
+	payload := make([]byte, int(length))
+	if _, err := io.ReadFull(r, payload); err != nil {
 		return fmt.Errorf("protobuf codec: read payload: %w", err)
 	}
 
 	var pbEnv protocolpb.Envelope
-	if err := proto.Unmarshal(buf, &pbEnv); err != nil {
+	if err := proto.Unmarshal(payload, &pbEnv); err != nil {
 		return fmt.Errorf("protobuf codec: unmarshal envelope: %w", err)
 	}
 
@@ -128,7 +137,8 @@ func (protobufCodec) Decode(r io.Reader, env *Envelope) error {
 }
 
 // DefaultCodec 은 현재 런타임에서 사용하는 기본 WireCodec 입니다.
-// 이제 Protobuf 기반 codec 을 기본으로 사용합니다.
+// 현재는 Protobuf  length-prefix 기반 codec 을 기본으로 사용합니다.
+// 서버와 클라이언트가 모두 이 버전을 사용해야 wire-format 이 일치합니다.
 var DefaultCodec WireCodec = protobufCodec{}
 
 // toProtoEnvelope 는 내부 Envelope 구조체를 Protobuf Envelope 로 변환합니다.

internal/protocol/codec_test.go

@@ -0,0 +1,221 @@
+package protocol
+
+import (
+	"bytes"
+	"io"
+	"testing"
+)
+
+// mockDatagramConn simulates a datagram-based connection (like DTLS over UDP)
+// where each Write sends a separate message and each Read receives a complete message.
+// This mock verifies the FIXED behavior where the codec properly handles message boundaries.
+type mockDatagramConn struct {
+	messages [][]byte
+	readIdx  int
+}
+
+func newMockDatagramConn() *mockDatagramConn {
+	return &mockDatagramConn{
+		messages: make([][]byte, 0),
+	}
+}
+
+func (m *mockDatagramConn) Write(p []byte) (n int, err error) {
+	// Simulate datagram behavior: each Write is a separate message
+	msg := make([]byte, len(p))
+	copy(msg, p)
+	m.messages = append(m.messages, msg)
+	return len(p), nil
+}
+
+func (m *mockDatagramConn) Read(p []byte) (n int, err error) {
+	// Simulate datagram behavior: each Read returns a complete message
+	if m.readIdx >= len(m.messages) {
+		return 0, io.EOF
+	}
+	msg := m.messages[m.readIdx]
+	m.readIdx++
+	if len(p) < len(msg) {
+		return 0, io.ErrShortBuffer
+	}
+	copy(p, msg)
+	return len(msg), nil
+}
+
+// TestProtobufCodecDatagramBehavior tests that the protobuf codec works correctly
+// with datagram-based transports (like DTLS over UDP) where message boundaries are preserved.
+func TestProtobufCodecDatagramBehavior(t *testing.T) {
+	codec := protobufCodec{}
+	conn := newMockDatagramConn()
+
+	// Create a test envelope
+	testEnv := &Envelope{
+		Type: MessageTypeHTTP,
+		HTTPRequest: &Request{
+			RequestID:   "test-req-123",
+			ClientID:    "client-1",
+			ServiceName: "test-service",
+			Method:      "GET",
+			URL:         "/test/path",
+			Header: map[string][]string{
+				"User-Agent": {"test-client"},
+			},
+			Body: []byte("test body content"),
+		},
+	}
+
+	// Encode the envelope
+	if err := codec.Encode(conn, testEnv); err != nil {
+		t.Fatalf("Failed to encode envelope: %v", err)
+	}
+
+	// Verify that exactly one message was written (length prefix + data in single Write)
+	if len(conn.messages) != 1 {
+		t.Fatalf("Expected 1 message to be written, got %d", len(conn.messages))
+	}
+
+	// Verify the message structure: [4-byte length][protobuf data]
+	msg := conn.messages[0]
+	if len(msg) < 4 {
+		t.Fatalf("Message too short: %d bytes", len(msg))
+	}
+
+	// Decode the envelope
+	var decodedEnv Envelope
+	if err := codec.Decode(conn, &decodedEnv); err != nil {
+		t.Fatalf("Failed to decode envelope: %v", err)
+	}
+
+	// Verify the decoded envelope matches the original
+	if decodedEnv.Type != testEnv.Type {
+		t.Errorf("Type mismatch: got %v, want %v", decodedEnv.Type, testEnv.Type)
+	}
+	if decodedEnv.HTTPRequest == nil {
+		t.Fatal("HTTPRequest is nil after decode")
+	}
+	if decodedEnv.HTTPRequest.RequestID != testEnv.HTTPRequest.RequestID {
+		t.Errorf("RequestID mismatch: got %v, want %v", decodedEnv.HTTPRequest.RequestID, testEnv.HTTPRequest.RequestID)
+	}
+	if decodedEnv.HTTPRequest.Method != testEnv.HTTPRequest.Method {
+		t.Errorf("Method mismatch: got %v, want %v", decodedEnv.HTTPRequest.Method, testEnv.HTTPRequest.Method)
+	}
+	if decodedEnv.HTTPRequest.URL != testEnv.HTTPRequest.URL {
+		t.Errorf("URL mismatch: got %v, want %v", decodedEnv.HTTPRequest.URL, testEnv.HTTPRequest.URL)
+	}
+	if !bytes.Equal(decodedEnv.HTTPRequest.Body, testEnv.HTTPRequest.Body) {
+		t.Errorf("Body mismatch: got %v, want %v", decodedEnv.HTTPRequest.Body, testEnv.HTTPRequest.Body)
+	}
+}
+
+// TestProtobufCodecStreamData tests encoding/decoding of StreamData messages
+func TestProtobufCodecStreamData(t *testing.T) {
+	codec := protobufCodec{}
+	conn := newMockDatagramConn()
+
+	// Create a StreamData envelope
+	testEnv := &Envelope{
+		Type: MessageTypeStreamData,
+		StreamData: &StreamData{
+			ID:   StreamID("stream-123"),
+			Seq:  42,
+			Data: []byte("stream data payload"),
+		},
+	}
+
+	// Encode
+	if err := codec.Encode(conn, testEnv); err != nil {
+		t.Fatalf("Failed to encode StreamData: %v", err)
+	}
+
+	// Verify single message
+	if len(conn.messages) != 1 {
+		t.Fatalf("Expected 1 message, got %d", len(conn.messages))
+	}
+
+	// Decode
+	var decodedEnv Envelope
+	if err := codec.Decode(conn, &decodedEnv); err != nil {
+		t.Fatalf("Failed to decode StreamData: %v", err)
+	}
+
+	// Verify
+	if decodedEnv.Type != MessageTypeStreamData {
+		t.Errorf("Type mismatch: got %v, want %v", decodedEnv.Type, MessageTypeStreamData)
+	}
+	if decodedEnv.StreamData == nil {
+		t.Fatal("StreamData is nil")
+	}
+	if decodedEnv.StreamData.ID != testEnv.StreamData.ID {
+		t.Errorf("StreamID mismatch: got %v, want %v", decodedEnv.StreamData.ID, testEnv.StreamData.ID)
+	}
+	if decodedEnv.StreamData.Seq != testEnv.StreamData.Seq {
+		t.Errorf("Seq mismatch: got %v, want %v", decodedEnv.StreamData.Seq, testEnv.StreamData.Seq)
+	}
+	if !bytes.Equal(decodedEnv.StreamData.Data, testEnv.StreamData.Data) {
+		t.Errorf("Data mismatch: got %v, want %v", decodedEnv.StreamData.Data, testEnv.StreamData.Data)
+	}
+}
+
+// TestProtobufCodecMultipleMessages tests encoding/decoding multiple messages
+func TestProtobufCodecMultipleMessages(t *testing.T) {
+	codec := protobufCodec{}
+	conn := newMockDatagramConn()
+
+	// Create multiple test envelopes
+	envelopes := []*Envelope{
+		{
+			Type: MessageTypeStreamOpen,
+			StreamOpen: &StreamOpen{
+				ID:         StreamID("stream-1"),
+				Service:    "test-service",
+				TargetAddr: "127.0.0.1:8080",
+			},
+		},
+		{
+			Type: MessageTypeStreamData,
+			StreamData: &StreamData{
+				ID:   StreamID("stream-1"),
+				Seq:  1,
+				Data: []byte("first chunk"),
+			},
+		},
+		{
+			Type: MessageTypeStreamData,
+			StreamData: &StreamData{
+				ID:   StreamID("stream-1"),
+				Seq:  2,
+				Data: []byte("second chunk"),
+			},
+		},
+		{
+			Type: MessageTypeStreamClose,
+			StreamClose: &StreamClose{
+				ID:    StreamID("stream-1"),
+				Error: "",
+			},
+		},
+	}
+
+	// Encode all messages
+	for i, env := range envelopes {
+		if err := codec.Encode(conn, env); err != nil {
+			t.Fatalf("Failed to encode message %d: %v", i, err)
+		}
+	}
+
+	// Verify that each encode produced exactly one message
+	if len(conn.messages) != len(envelopes) {
+		t.Fatalf("Expected %d messages, got %d", len(envelopes), len(conn.messages))
+	}
+
+	// Decode and verify all messages
+	for i := 0; i < len(envelopes); i++ {
+		var decoded Envelope
+		if err := codec.Decode(conn, &decoded); err != nil {
+			t.Fatalf("Failed to decode message %d: %v", i, err)
+		}
+		if decoded.Type != envelopes[i].Type {
+			t.Errorf("Message %d type mismatch: got %v, want %v", i, decoded.Type, envelopes[i].Type)
+		}
+	}
+}

tools/build_server_image.sh

@@ -0,0 +1,57 @@
+#!/bin/sh
+
+# POSIX sh 버전의 hop-gate 서버 이미지 빌드 스크립트.
+# VERSION 은 현재 git 커밋의 7글자 SHA 를 사용합니다.
+
+set -eu
+
+# 스크립트 위치 기준 리포 루트 계산
+SCRIPT_DIR=$(cd "$(dirname "$0")" >/dev/null 2>&1 && pwd)
+REPO_ROOT="${SCRIPT_DIR}/.."
+cd "${REPO_ROOT}"
+
+# 현재 커밋 7글자 SHA, git 정보가 없으면 dev
+VERSION=$(git rev-parse --short=7 HEAD 2>/dev/null || echo dev)
+
+# 기본 이미지 이름 (첫 번째 인자로 override 가능)
+# 예:
+#   ./tools/build_server_image.sh
+#   ./tools/build_server_image.sh my/image/name
+IMAGE_NAME=${1:-ghcr.io/dalbodeule/hop-gate}
+
+echo "Building hop-gate server image"
+echo "  context : ${REPO_ROOT}"
+echo "  image   : ${IMAGE_NAME}:${VERSION}"
+echo "  version : ${VERSION}"
+
+# docker buildx 사용 가능 여부 확인
+if command -v docker >/dev/null 2>&1 && docker buildx version >/dev/null 2>&1; then
+  BUILD_CMD="docker buildx build"
+else
+  BUILD_CMD="docker build"
+fi
+
+# 선택적 환경 변수:
+#   PLATFORM=linux/amd64,linux/arm64   # buildx 용
+#   PUSH=1                             # buildx --push
+
+PLATFORM_ARGS=""
+if [ "${PLATFORM-}" != "" ]; then
+  PLATFORM_ARGS="--platform ${PLATFORM}"
+fi
+
+PUSH_ARGS=""
+if [ "${PUSH-}" != "" ]; then
+  PUSH_ARGS="--push"
+fi
+
+# 실제 빌드 실행
+# shellcheck disable=SC2086
+${BUILD_CMD} \
+  ${PLATFORM_ARGS} \
+  -f Dockerfile.server \
+  --build-arg VERSION="${VERSION}" \
+  -t "${IMAGE_NAME}:${VERSION}" \
+  -t "${IMAGE_NAME}:latest" \
+  ${PUSH_ARGS} \
+  .