HandshakeHandler

veltix.handler.handshake_handler.HandshakeHandler

Manage the version compatibility handshake for a single raw TCP connection. Uses a 3-way protocol to ensure both sides are synchronized:

1. Server → Client : {"v", "pv", "meta"}
2. Client → Server : {"v", "pv", "meta"}
3. Server → Client : {"result": "ok"}

Server mode sends first, then validates client protocol version before acking. Client mode reads server protocol version, validates, sends its version, then waits for the server ack before returning.

__init__

__init__(mode: Mode, bus: VeltixBus) -> None

Initialise the handshake handler for a given role.

Parameters:

Name	Type	Description	Default
mode	Mode	Whether this handler operates as SERVER or CLIENT.	required
bus	VeltixBus	Event bus for emitting handshake events and logging.	required

send_rejection

send_rejection(sock: RawSocket, reason: str) -> bool

Send a rejection payload and close the connection.

Used by the server to explicitly reject a client before the handshake (e.g. when the server is full).

Parameters:

Name	Type	Description	Default
sock	RawSocket	A raw TCP socket conforming to :class:RawSocket.	required
reason	str	Rejection reason string (e.g. "server_full").	required

Returns:

Type	Description
bool	True if the rejection was sent, False on error.

do_server_handshake

do_server_handshake(sock: RawSocket, timeout: float = 5.0) -> bool

Perform the server-side 3-way handshake.

Steps

1. Send {"v": ..., "pv": ..., "meta": {}} to the client.
2. Receive the client's {"v": ..., "pv": ..., "meta": ...} response.
3. Validate the client's protocol version.
4. Send {"result": "ok"} to acknowledge.

Parameters:

Name	Type	Description	Default
sock	RawSocket	A raw TCP socket conforming to :class:RawSocket.	required
timeout	float	Maximum seconds to wait for each recv.	5.0

Returns:

Type	Description
bool	True if the handshake succeeded, False on any failure.

do_client_handshake

do_client_handshake(sock: RawSocket, timeout: float = 5.0) -> tuple[bool, dict[str, Any] | None]

Perform the client-side 3-way handshake.

Steps

1. Receive the server's {"v": ..., "pv": ..., "meta": ...} payload.
2. Validate the server's protocol version.
3. Send {"v": ..., "meta": {}} to the server.
4. Wait for the server's {"result": "ok"} acknowledgment.

Parameters:

Name	Type	Description	Default
sock	RawSocket	A raw TCP socket conforming to :class:RawSocket.	required
timeout	float	Maximum seconds to wait for each recv.	5.0

Returns:

Type	Description
bool	A tuple of (success, meta) where meta is the server's
dict[str, Any] | None	metadata dict on success, or None on failure.