ChServerM, 축을 골라 조립하는 서버

핵심 개념

서버 하나 = 슬롯마다 부품 하나

아래가 이 프레임워크의 전부다. 각 슬롯에서 부품을 하나씩 고르면 그게 서버가 된다. 부품을 바꾸는 비용은 대개 .UseXxx() 한 줄이다.

가장 먼저 정할 것

커넥션에 “상태”가 있는가?

이 한 가지가 나머지 선택의 절반을 결정한다. 둘 중 어느 쪽인지 먼저 고른다 — 두 프로필 모두 같은 핸들러 코드로 돌아간다.

💡 중간 형태(일부 메시지만 순서 보장)도 같은 부품으로 조립된다. 한쪽만 도는 추상화는 추상화가 아니라는 게 이 프레임워크의 합격 기준이다.

첫 실행 · 5분 경로

샘플 실행 → 직접 조립 → 축 갈아끼우기

순서대로 따라가면 된다. 1번은 저장소 클론이 필요하고, 2번부터는 nuget 패키지만으로 조립한다.

최소 예제 · 서버 + 클라이언트

받은 걸 그대로 돌려주는 에코 서버

서버와 클라이언트가 같은 프레이밍·디스패치를 쓴다 — 그게 이 프레임워크의 대칭이다. 조립도의 슬롯이 실제 코드에서 어떻게 채워지는지, 주석(// …)이 왜 그렇게 쓰는지 알려준다.

// 프레이밍: 최대 페이로드는 기본값에 기대지 말고 워크로드에 맞게 명시한다.
const int MaxPayload = 64 * 1024;
FramingOptions framing = new() { MaxPayloadLength = MaxPayload };
FixedHeaderFrameEncoder encoder = new(framing);

// 실행 모델: 같은 커넥션은 순차, 다른 커넥션끼리는 병렬.
await using PartitionedExecutionModel executionModel = new();

await using ChServerMServer server = new ServerBuilder()
    .UseTransport(new TcpServerTransport(endPoint, tcpOptions))  // 전송
    .UseFraming(new FixedHeaderFrameDecoder(framing), encoder)      // 프레이밍
    .UseExecutionModel(executionModel)                            // 순서 보장
    .ConfigureDispatcher(d => d
        // 메시지 ID 1: 받은 페이로드를 그대로 돌려보낸다. (ID 0 은 예약 센티넬)
        .MapRaw(new MessageId(1), async context =>
        {
            await FrameWriter.WriteFrameAsync(
                context.Connection.Output, encoder,
                context.Envelope.MessageId, context.Payload,
                FrameFlags.None, context.Envelope.Sequence, context.CancellationToken);
            return DispatchStatus.Handled;
        }))
    .Build();

await server.StartAsync();  // 와이어 형식: [고정 헤더][페이로드]

// 클라이언트도 서버와 같은 프레이밍·인코더를 쓴다.
FramingOptions framing = new() { MaxPayloadLength = 64 * 1024 };
FixedHeaderFrameEncoder encoder = new(framing);

// 응답을 받아 둘 곳 — 핸들러가 여기에 결과를 넣는다.
TaskCompletionSource<byte[]> echoed = new(TaskCreationOptions.RunContinuationsAsynchronously);

await using ChServerMClient client = new ClientBuilder()
    .UseTransport(new TcpClientTransport(tcpOptions))         // 서버와 같은 버퍼 임계값
    .UseFraming(new FixedHeaderFrameDecoder(framing), encoder)
    .ConfigureDispatcher(d => d
        .MapRaw(new MessageId(1), context =>
        {
            // Payload 는 핸들러가 반환하면 무효 — await 너머로 들고 가려면 복사한다.
            echoed.TrySetResult(context.Payload.ToArray());
            return new ValueTask<DispatchStatus>(DispatchStatus.Handled);
        }))
    .Build();

// 접속 → 메시지 1개 전송 → 에코 수신.
ClientSession session = await client.ConnectAsync(new IPEndPoint(IPAddress.Loopback, 5000));

await FrameWriter.WriteFrameAsync(
    session.Connection.Output, encoder, new MessageId(1),
    "안녕, ChServerM"u8, FrameFlags.None, sequence: 0, session.Connection.ConnectionClosed);

Console.WriteLine($"에코: {Encoding.UTF8.GetString(await echoed.Task)}");  // → 에코: 안녕, ChServerM

await session.Connection.DisposeAsync();

에코: 안녕, ChServerM 이 찍히면 왕복이 완성된 것이다. 서버·클라이언트가 같은 MessageId(1) · 같은 프레이밍으로 짝을 이룬다. 전체 using 목록과 설명은 docs/GETTING-STARTED.md 에 있다.

무엇을 언제 꽂는가

축별 선택 가이드

처음이라면 기본 표시를 고르면 된다. 바꿀 이유가 생겼을 때 아래 “고르는 경우”를 본다.

3단계 · 다음

축 갈아끼우기 — 대부분 한 줄

위 최소 서버에서 바꿀 수 있는 것들이 곧 프레임워크의 표면이다.

막히면

초보자가 자주 만나는 벽

대부분 런타임 교착 대신 시작 시점에 실패하도록 설계돼 있다 — 에러가 곧 안내다.