Class ProtocolHandshake

java.lang.Object

com.loomcache.client.ProtocolHandshake

public final class ProtocolHandshake
extends Object

Client-side opt-in initiator for the PROTOCOL_HELLO / PROTOCOL_HELLO_ACK handshake introduced in BLK-2026-04-22-007 Day 1.

Usage: call performHandshake(Socket, EnumSet) immediately after connecting a fresh socket. The helper sends a PROTOCOL_HELLO request, reads the server's PROTOCOL_HELLO_ACK response, validates compatibility via ProtocolNegotiator, and returns the negotiated result. Callers cache the return value on whatever per-connection state they maintain (connection pool, node client, etc.).

Servers that predate Day 1 (no PROTOCOL_HELLO support) respond to the opcode with RESPONSE_ERROR or close the connection; the helper surfaces that as an IOException so callers can either fall back to legacy (silently ignore) or fail hard (strict mode).

Thread-safety: stateless static helper. Safe to invoke from any thread.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	ProtocolHandshake.Result	Outcome of a successful handshake.

Method Summary

Modifier and Type	Method	Description
static ProtocolHandshake.Result	performHandshake(InputStream peerIn, OutputStream peerOut, EnumSet<ProtocolFeatures> localFeatures)	Stream-oriented variant of performHandshake(Socket, EnumSet) for testability (any bidirectional stream pair works — real socket, piped in-process streams, etc.).
static ProtocolHandshake.Result	performHandshake(Socket socket, EnumSet<ProtocolFeatures> localFeatures)	Perform the bidirectional version + feature handshake on a freshly- connected socket.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

performHandshake

public static ProtocolHandshake.Result performHandshake(Socket socket,
 EnumSet<ProtocolFeatures> localFeatures)
                                                 throws IOException

Perform the bidirectional version + feature handshake on a freshly- connected socket.

Parameters:

socket - the open client socket (non-null)

localFeatures - the feature bitmap this client advertises (non-null)

Returns:

the negotiated handshake result (non-null)

Throws:

IOException - if the exchange fails, the peer is incompatible, or the response is not a well-formed PROTOCOL_HELLO_ACK

performHandshake

public static ProtocolHandshake.Result performHandshake(InputStream peerIn,
 OutputStream peerOut,
 EnumSet<ProtocolFeatures> localFeatures)
                                                 throws IOException

Stream-oriented variant of performHandshake(Socket, EnumSet) for testability (any bidirectional stream pair works — real socket, piped in-process streams, etc.).

Parameters:

peerIn - input stream to read the peer's HELLO_ACK (non-null)

peerOut - output stream to write our HELLO request (non-null)

localFeatures - feature bitmap to advertise (non-null, may be empty)

Returns:

the negotiated handshake result

Throws:

IOException - if the exchange fails or the peer is incompatible