Phase 2: Slice 1 — Ping (handshake + Ping/Reply)

[TomiCheng]

Goal

First slice of real client connectivity: connect to a Geode server, complete the handshake, send a Ping, receive a Reply. Walking-skeleton end-to-end.

Done when

• A TcpConnection class wraps TcpClient + NetworkStream and exposes a SendFrameAsync / ReceiveFrameAsync pair built on Phase 1's frame codec.
• Handshake follows the ad-hoc byte sequence in cppcache/src/TcrConnection.cpp::sendHandshakeForServer. Re-implement byte-by-byte from the C++ source — do not paraphrase.
• PingAsync() sends a Ping (5) frame and awaits a Reply (6) frame.
• Integration test (Testcontainers) connects to the Geode container started by GeodeFixture and gets a real Reply.

Tasks

• src/Geode.Client/Transport/TcpConnection.cs
• src/Geode.Client/Transport/Handshake.cs
• src/Geode.Client/Transport/ClientProxyMembershipID.cs (host / PID / UUID / durable id)
• src/Geode.Client/Operations/PingOperation.cs
• tests/Geode.Client.Tests/Transport/HandshakeBytesTests.cs (golden bytes)
• tests/Geode.Client.IntegrationTests/PingTests.cs

References

• cppcache/src/TcrConnection.cpp — sendHandshakeForServer, readHandshakeAck
• cppcache/src/HandShake.cpp / .hpp
• CLAUDE.md → "Handshake（最容易踩雷的一段）"

Out of scope

• Connection pool (Phase 6) — single connection only.
• Locator discovery (Phase 7) — server endpoint must be configured directly.
• TLS (Phase 8).
• Authentication (Phase 9) — anonymous only.

Branch

feat/phase-2-ping

Note

This is the protocol-correctness gauntlet. Expect to iterate. Capture bytes with Wireshark on the loopback interface if the server rejects the handshake — the diff between what we send and what the Java client sends is usually one byte off in ClientProxyMembershipID.

[TomiCheng]

Closing — delivered in #8 (merged ecb46dc).

Done-when checklist

• TcpConnection wrapping TcpClient + Stream, frame-codec
  pair → Geode.Client.Protocol.TcrConnection (ConnectAsync,
  SendAsync(ReadOnlyMemory<byte>), ReceiveAsync(),
  SendRequestAsync(TcrMessage), IAsyncDisposable).
• Handshake — implemented as TcrConnection.HandshakeAsync
  with all 14 wire steps. Authoritative reference shifted from
  cppcache to the Java server (ClientSideHandshakeImpl.write +
  ServerSideHandshakeImpl); cppcache had stale comments
  (e.g. AcceptanceCode wrong by 21, REPLY_OK 58 vs 59) that would
  have been miscompiled if we had paraphrased it.
• ClientProxyMembershipID — ClientProxyMembershipIdBuilder,
  process-scoped uniqueTag ("Native_" + 10 alnum + PID,
  cryptographic RNG), DNS / IP / PID from BCL.
• PingAsync() — extension method in
  Geode.Client.Protocol.Operations.PingExtensions, composes
  SendRequestAsync and asserts reply MessageType is Reply (6).
• Integration test —
  Geode.Client.IntegrationTests.PingIntegrationTests against
  apachegeode/geode:latest via Testcontainers, passes in ~150 ms.

Renaming notes vs original task list

Issue task	Delivered as
Transport/TcpConnection.cs	Protocol/TcrConnection.cs (matches cppcache vocabulary)
Transport/Handshake.cs	TcrConnection.HandshakeAsync (private; no separate class)
Transport/ClientProxyMembershipID.cs	Protocol/ClientProxyMembershipIdBuilder.cs
Operations/PingOperation.cs	Protocol/Operations/PingExtensions.cs (extension method)
HandshakeBytesTests.cs (golden bytes)	ClientProxyMembershipIdBuilderTests.cs (structural parse — golden bytes are infeasible because hostname / IP / PID vary per machine)
PingTests.cs	PingIntegrationTests.cs

Side benefits picked up in the same PR

• GeodeException + nuanced exception policy (BCL for transport / API misuse, GeodeException for "server said no").
• GeodeClientOptions + nested PoolOptions / TlsOptions /
  SubscriptionOptions (18 fields imported from cppcache
  SystemProperties, statistics / logging / heap-LRU omitted).
• AddGeodeClient(IConfiguration) DI extension.
• CLAUDE.md handshake spec corrected and pointed at Java sources.

🤖 Generated with Claude Code