Huny's Dev Blog
huny.dev

Cloudflare Inbound TCP & 양방향 gRPC 아키텍처 해부: Spectrum·Workers connect()·Durable Objects getTcpPort()와 allowHalfOpen·TLS 종단 경계 점검하기

2026년 11월 19일 Public Beta로 공개된 Cloudflare Workers 인바운드 TCP 및 Containers 양방향 gRPC 파이프라인의 내부 구조와 실무 운영 경계를 분석한다. Spectrum Worker-origin 인그레스, Worker connect(socket)와 Durable Object getTcpPort(50051) 기반 4단 소켓 파이핑, allowHalfOpen: true 누락 시 발생하는 TCP Half-Close 응답 유실, secureTransport: "off" 패스스루와 Container 내부 TLS(h2)·Secrets Store 종단 책임, Pro/Business 존의 1앱·1포트 쿼터 제약, 로컬 wrangler.jsonc connect 설정 및 Python 사전 검증 스크립트를 정리한다.

Hun Jang
Hun Jang Nov 21, 2026

Cloudflare Inbound TCP 및 양방향 gRPC 파이프라인의 계층별 바이트 스트림 흐름을 표현한 추상 표지 아트워크

기존 Cloudflare Workers는 HTTP fetch() 요청을 처리하거나 cloudflare:sockets를 통해 외부로 나가는 아웃바운드 TCP 소켓만 열 수 있었다. 이 때문에 원시 TCP 프로토콜이나 풀 듀플렉스(Full-Duplex) 양방향 gRPC(HTTP/2 스트리밍) 서비스를 Cloudflare 엣지에 직접 올리려면 별도 외부 게이트웨이나 HTTP/gRPC-Web 변환 프록시를 두어야 했다. Cloudflare는 2026년 11월 19일 이 제약을 깨고 Workers 인바운드 TCP 연결 및 Containers 양방향(Bidirectional) gRPC 지원을 Public Beta로 공개했다.

핵심 아키텍처 판단 기준을 먼저 요약하면, 이 기능은 Spectrum(L4 인그레스) → Worker connect(socket) → Durable Object getTcpPort() → Cloudflare Container(10.0.0.1:<port>)로 이어지는 4단 소켓 파이핑을 통해 원시 TCP 및 양방향 gRPC를 처리한다. 이때 Worker와 Durable Object는 TLS를 복호화하거나 gRPC 프레임을 파싱하지 않고 암호화된 바이트 스트림을 양방향 pipeTo()로 그대로 통과시키며, 실제 TLS 종단(Secrets Store 인증서)과 HTTP/2(h2) 처리 책임은 최하단 Container에 있다. 실무에서는 양쪽 소켓 홉 모두에 allowHalfOpen: true를 지정하지 않아 TCP Half-Close 시 최종 gRPC 응답이 잘리는 문제, secureTransport: "off" 대신 이중 TLS를 켜서 핸드셰이크가 실패하는 문제, 그리고 Pro/Business 존의 존당 1앱·1포트 쿼터 제한을 반드시 사전에 점검해야 한다. 이 글은 2026년 11월 21일 기준 Cloudflare Changelog(2026-11-19), Bidirectional gRPC with Workers and Containers 가이드, Durable Object Container API 문서를 교차 검증해 정리했으며, 실제 유료 Spectrum·Containers 존에 트래픽을 인가하는 대신 공식 명세의 요금제 쿼터·소켓 옵션(allowHalfOpen·secureTransport)·TCP Half-Close 및 로컬 wrangler 설정 경계를 모델링한 로컬 Python 사전 검증 스크립트를 기준으로 설명한다.

1. 4단 인라인 소켓 파이프라인: Spectrum → Worker → Durable Object → Container

인바운드 TCP 기반 양방향 gRPC 파이프라인에서는 각 계층의 역할이 명확히 분리된다. 먼저 Cloudflare Spectrum이 공용 TCP 연결을 수신해 Worker-origin 애플리케이션으로 넘기면, Worker 엔트리포인트의 connect(socket, env) 핸들러가 소켓을 받아 Durable Object 인스턴스로 전달한다.

이어 Durable Object는 자체 connect(socket) 핸들러에서 컨테이너가 기동·준비된 뒤 this.ctx.container.getTcpPort(50051).connect("10.0.0.1:50051", ...)를 호출해 컨테이너 내부 루프백 포트(50051)와 양방향 파이프를 연결한다.

Cloudflare Inbound TCP 및 양방향 gRPC 4단 파이프라인, 암호화 바이트 패스스루 구간과 allowHalfOpen·TLS 종단·요금제 경계 도식

최하단 Cloudflare Container에서는 Go, Python, Node.js(@grpc/grpc-js) 등 기존 언어로 작성된 표준 gRPC 서버를 수정 없이 그대로 실행할 수 있다. 예를 들어 양방향 스트리밍 서비스(rpc Chat(stream ByteChunk) returns (stream ByteChunk))를 등록하고 Secrets Store에서 주입한 TLS 인증서와 개인키로 TLS를 종단하면, HTTP/2(h2) 프레임과 양방향 메시지 교환이 컨테이너 내부에서 완결된다.

2. 실무에서 놓치기 쉬운 5가지 아키텍처·운영 경계와 방식 비교표

2.1 핵심 운영 함정 5가지

  • 1) allowHalfOpen: true 누락 시 TCP Half-Close 조기 단절: gRPC와 스트리밍 TCP에서는 클라이언트가 요청 데이터를 모두 보낸 뒤 쓰기 방향(FIN)을 먼저 닫고 서버의 마지막 응답과 gRPC 트레일러(status)를 기다리는 half-close 패턴이 일반적이다. Worker→DO와 DO→Container 양쪽 홉 중 한 곳이라도 allowHalfOpen: true가 빠지면 클라이언트 FIN 수신 즉시 반대 방향 읽기 스트림까지 닫혀 최종 응답 프레임이 유실된다.
  • 2) TLS 종단 책임과 secureTransport: "off" 패스스루 경계: 이 아키텍처에서 Spectrum(tls: "off" 패스스루)·Worker·Durable Object는 클라이언트가 시작한 TLS 암호화 바이트 스트림을 복호화하지 않고 그대로 전달한다. 따라서 내부 connect() 호출에 secureTransport: "off"를 유지하고 Container가 Secrets Store의 인증서/개인키로 TLS와 ALPN h2를 종단해야 한다. 내부 홉에 secureTransport: "on"을 중복 지정하면 이중 TLS 래핑으로 핸드셰이크가 실패한다.
  • 3) 존 요금제별 Spectrum Worker-origin 쿼터 제한: 공식 릴리스 노트 기준 Worker-origin Spectrum 애플리케이션은 Pro·Business 존과 Spectrum Enterprise가 활성화된 Enterprise 존에서 사용할 수 있다. 다만 Spectrum Enterprise가 없는 Pro·Business 존은 존당 Worker-origin 애플리케이션 1개와 단일 TCP 포트 1개만 지원하므로 마이크로서비스마다 포트를 여러 개 여는 설계는 Enterprise(Spectrum Enterprise) 이상에서만 가능하다.
  • 4) 로컬 개발(wrangler dev)과 프로덕션 *.workers.dev 경계 차이: 로컬에서는 wrangler.jsonc에 "connect": [{"protocol": "tcp", "port": 8788}]를 선언해 localhost:8788로 원시 TCP/gRPC 트래픽을 테스트할 수 있다. 그러나 프로덕션에서는 *.workers.dev HTTP 엔드포인트나 HTTP CONNECT로 공용 인터넷의 인바운드 TCP를 직접 받을 수 없으며, 반드시 커스텀 도메인 존의 Spectrum Worker-origin 설정이 필요하다.
  • 5) 컨테이너 기동·Readiness 미대기 및 Workers 리소스 제약: Worker가 바이트를 파싱하지 않아도 소켓 파이핑 자체는 Workers 런타임의 메모리·CPU·서브리퀘스트 한도 내에서 동작한다. 또한 Durable Object가 컨테이너 기동 및 readiness check 완료 전에 getTcpPort(50051).connect()를 호출하면 연결이 거부될 수 있으므로 컨테이너 상태 확인 절차를 반드시 선행해야 한다.
비교 항목
기존 Workers HTTP +
gRPC-Web 프록시
Workers fetch() +
Outbound TCP (cloudflare:sockets)
Spectrum + Worker + DO +
Container (Inbound TCP/gRPC)
외부 VM / Kubernetes
L4 로드밸런서 구성
인바운드 원시 TCP 수신
불가 (HTTP L7 요청만 수용)
불가 (아웃바운드 TCP만 지원)
가능 (Spectrum → connect())
가능 (별도 인프라 상시 운영)
양방향 풀 듀플렉스 gRPC
제한적 (클라이언트 스트리밍 제약)
클라이언트 인바운드 수용 불가
네이티브 지원 (HTTP/2 패스스루)
네이티브 지원
TLS 종단 위치
Cloudflare L7 엣지
아웃바운드 대상 서버
Container 내부 (Secrets Store)
Ingress Controller / Envoy
요금제·포트 제약
Free 플랜부터 사용 가능
Workers 유료/무료 제약 내 사용
Pro/Bus 1앱·1포트 / Ent 다중
클라우드 LB 비용 및 존 관리
실무 권장 용도
브라우저 단방향 RPC 호출
Worker에서 외부 DB/Redis 연결
실시간 음성·스트리밍 gRPC·커스텀 TCP
대규모 멀티포트·고정 클러스터 워크로드

3. 로컬 Wrangler 설정 확인과 Python 사전 검증 스크립트

3.1 로컬 wrangler.jsonc 인바운드 TCP 리스너 설정

프로덕션 Spectrum 연동 전 로컬 wrangler dev 환경에서 connect(socket) 핸들러와 바이트 스트림 파이핑을 재현하려면 설정 파일에 로컬 TCP 리스너를 선언한다.

3.2 Python 표준 라이브러리 기반 쿼터·소켓 옵션·Half-Close·TLS 경계 사전 검증기

배포 전 ① 존 요금제별 Spectrum Worker-origin 앱/포트 쿼터, ② Worker→DO 및 DO→Container 양쪽 홉의 allowHalfOpen·secureTransport·socket.opened·Promise.allSettled 정리·10.0.0.1:<port> 루프백·Secrets Store TLS/ALPN h2·컨테이너 readiness 여부, ③ wrangler.jsonc 로컬 connect 설정 및 *.workers.dev 오용 여부, ④ TCP Half-Close 시뮬레이션까지 일괄 점검하는 로컬 Python 스크립트(verify_cf_inbound_tcp_grpc.py)다.

로컬 Python 3 실행 결과, Pro 존 단일 포트 정상 구성의 무오류 통과(0건), Pro 존 다중 앱·다중 포트 쿼터 초과 2건 탐지, Enterprise + Spectrum 활성화 시 다중 구성 허용 확인, allowHalfOpen 누락·이중 TLS·127.0.0.1 오기재·TLS 종단/ALPN h2 누락·컨테이너 readiness 미확인·*.workers.dev 오용 등 14건의 배포 오설정 일괄 탐지, 그리고 Half-Close 시뮬레이션에서 allowHalfOpen=True일 때만 ['greeting', 'final_response_and_trailers']가 온전하게 수신되고 False일 때는 ['greeting']만 전달된 채 절단되는 동작(ALL CHECKS PASSED)을 모두 확인했다.

4. 실무 도입 및 운영 점검 체크리스트

존 요금제 및 Spectrum Worker-origin 포트 쿼터 확인: 대상 존이 Pro/Business인지 Enterprise(Spectrum Enterprise 포함)인지 확인하고, Pro/Business 존이라면 단일 Worker-origin 앱과 단일 TCP 포트 1개 한도 내에 수용되도록 서비스 진입점을 통합한다.

양방향 홉 allowHalfOpen: true 및 finally 소켓 정리 강제: Worker→DO container.connect()와 DO→Container getTcpPort().connect() 양쪽 모두에 allowHalfOpen: true를 설정하고, await socket.opened 확인과 Promise.allSettled 소켓 종료 처리를 빠뜨리지 않는다.

TLS 종단 책임 및 Secrets Store 인증서 바인딩 점검: Spectrum·Worker·DO 구간은 암호화 바이트 패스스루(secureTransport: "off")로 유지하고, Container 내부 gRPC 서버가 Secrets Store에서 주입한 TLS 인증서/개인키와 HTTP/2(h2) ALPN을 정상 협상하는지 검증한다.

컨테이너 기동·Readiness 확인 후 getTcpPort() 연결: Durable Object가 컨테이너가 준비되기 전에 10.0.0.1:<port>로 소켓을 열지 않도록 readiness 체크와 재시도 경계를 두고, Workers 런타임 CPU·메모리 제한을 모니터링한다.

로컬 wrangler.jsonc 테스트와 프로덕션 라우팅 분리: 로컬 개발은 connect: [{"protocol": "tcp", "port": 8788}]로 소켓 흐름을 선제 검증하되, 프로덕션에서는 *.workers.dev가 아닌 커스텀 도메인의 Spectrum 애플리케이션을 통해서만 인바운드 TCP를 수신한다.

5. 참고 자료 및 공식 출처 (2026-11-21 확인)

확인 기준일: November 21, 2026

추천 글