cmd-stream: Go를 위한 고성능 분산 Command Pattern (DCP)

Go Reference

GoReportCard

codecov

OpenSSF Best Practices

OpenSSF Scorecard

Follow on X

cmd-stream은 Go를 위한 분산 Command Pattern (DCP)을 구현하는 네트워킹 프레임워크입니다.
TCP/TLS를 통한 저지연 통신에 최적화되어 있으며, 요청을 일급(first-class) Command 객체로 처리함으로써 전통적인 RPC의 유연하고 디커플링된 대안을 제공합니다.

아키텍처는 간단합니다. 클라이언트가 서버로 Command를 전송하면, Invoker가 이를 실행하고 Receiver가 실제 서버 측 기능을 제공합니다.

Command Pattern이 네트워크 통신에 어떻게 적용되는지 더 알고 싶으신가요? 이 일련의 게시물을 확인해 보세요.

왜 cmd-stream인가?

이는 비동기 요청을 장기간 유지되는 연결(long-lived connections) 위에서 다중화(multiplexing)하여 네트워크 오버헤드를 최소화함으로써 고성능과 자원 효율성을 제공합니다. 이는 인프라 비용 절감에 도움을 주고 더 효과적으로 확장할 수 있게 합니다.

개요 (Overview)

TCP, TLS 또는 상호 TLS(mutual TLS) 위에서 작동합니다.
명령(Commands) 전송과 결과(Results) 수신 모두에 단 하나의 연결만 사용하는 비동기 클라이언트를 갖추고 있습니다.
서버 스트리밍을 지원하여, 즉 한 명령이 여러 개의 결과를 다시 보낼 수 있습니다.
재연결(reconnect) 및 연결 유지(keepalive) 기능을 제공합니다.
Circuit Breaker 패턴을 지원합니다.
OpenTelemetry 통합이 가능합니다.
다양한 직렬화 형식(serialization formats)과 함께 작동할 수 있습니다.
모듈식 디자인을 따릅니다.

벤치마크 (Benchmarks)

QPS Benchmark

자세한 성능 비교는 go-client-server-benchmarks를 참조하십시오.

스트레스 테스트 (Stress Testing)

이 프레임워크는 12시간 연속 스트레스 테스트를 성공적으로 통과하여 극한의 조건에서도 안정성을 보장합니다.

테스트 방법론 및 결과에 대한 더 자세한 내용은 stress-test-go를 참조하십시오.

설치 (Installation)

프레임워크를 얻으려면 다음을 사용하십시오:

go get github.com/cmd-stream/cmd-stream-go

사용 방법 (How To)

시작하기는 쉽습니다:

Command Pattern을 구현합니다.
다음 코덱 중 하나를 사용합니다:
- codec-json-go - 간단하고 사용하기 쉬운 JSON 코덱 (프로토타이핑에 이상적).
- codec-protobuf-go - Protobuf 기반 코덱 (코드 생성이 필요함).
- codec-mus-stream-go - 고성능 MUS 코덱 (코드 생성이 필요함).

팁: 간단함을 위해 JSON으로 시작하고, 최대 성능을 위해 나중에 MUS로 전환하십시오.

간략한 살펴보기 (Quick Look)

명령(Commands)이 어떻게 정의되고 네트워크를 통해 전송 및 실행될 수 있는지 보여주는 최소한의 엔드투엔드 예제입니다:

// Calc는 산술 논리를 처리합니다.
type Calc struct{}

...

전체 구현은 calc_json 예제를 참고하세요.

추가 자료 (Additional Resources)

네트워크 프로토콜 지원 (Network Protocols Support)

Go의 표준 net 패키지를 기반으로, cmd-stream은 TCP, TLS 및 상호 TLS(client 인증용)와 같은 연결 지향 프로토콜을 지원합니다.

고성능 통신 채널 (High-performance Communication Channel)

서비스 간 성능을 극대화하려면:

N개의 병렬 클라이언트를 사용하세요. 일반적으로 더 많은 연결은 포화점(saturation point)에 도달할 때까지 처리량(throughput)을 개선합니다.
필요할 때 개방하기보다는 모든 연결을 미리 설정해 두세요 (Pre-establish).
재연결로 인한 오버헤드를 피하기 위해 연결을 활성 상태로 유지하세요 (Keep connections alive).

이러한 방법들은 Group을 통해 구현되어 서비스 간의 처리량과 지연 시간(latency)을 크게 향상시킬 수 있습니다.

cmd-stream과 RPC

이미 RPC를 사용하고 계신가요? cmd-stream을 더 빠른 전송 계층(transport layer)으로 사용할 수 있습니다. RPC 예제를 확인해 보세요.

아키텍처 (Architecture)

cmd-stream은 명확한 관심사 분리(clear separation of concerns)를 보장하는 동시에 최대 성능을 유지하도록 계층형 아키텍처로 구축되었습니다:

core: 핵심 클라이언트 및 서버 정의.
delegate: 모든 통신 관련 작업 및 연결 초기화.
handler: 서버 측 Command 처리.
transport: 네트워크를 통한 Command 및 결과 전송.
sender: 고수준(High-level) 송신자 구현.
testkit: 통합 테스트용 데이터 및 기반 구조.

cmd-stream은 어느 부분을 쉽게 교체할 수 있도록 설계되었습니다.

기여 및 보안 (Contributing & Security)

모든 종류의 기여를 환영합니다! 참여 방법에 대한 자세한 내용은 CONTRIBUTING.md를 참고해 주세요.

보안 취약점을 발견하셨다면, 비공개로 신고하는 방법에 대한 지침은 Security Policy를 참고해 주세요.

버그, 피드백 또는 기능 요청이 있으시면 이슈를 열어주세요!

버전 호환성

호환 가능한 모듈 버전에 대한 전체 목록은 VERSIONS.md를 확인해 주세요.

cmd-stream: Go용 고성능 분산 Command Pattern (DCP)

요약

핵심 포인트