handshake

fun handshake(name: String, timeoutMillis: Int = HANDSHAKE_TIMEOUT_MILLIS, credential: String = ""): Result<Unit>(source)

Sends Iam <name> (or Iam <name> <credential>) and blocks (up to timeoutMillis) for the server's reply, on this same socket. One-shot; call once, before start.

This call is one-shot: a HandshakeRefusedException raised for a bad credential will recur on a retry with the same credential; a refusal for capacity (Admission.Refused) may not.

Return

Result.success once the server has replied this build's exact REGISTERED 2; or Result.failure holding a HandshakeRefusedException if the server replied REFUSED <reason>; or an IncompatibleProtocolException if the server's REGISTERED reply announces a different wire-protocol major (a bare REGISTERED from a pre-2.0 server, or REGISTERED n, n != 2); or the failure that prevented it (including a timeout - the server never replied)

Parameters

name

this client's chosen name

timeoutMillis

how long to wait for the server's reply before failing

credential

an opaque token forwarded verbatim in the Iam line to the server's MultiConnectionUDPServer.admit; the default (empty string) sends the plain Iam <name>. Must be whitespace-free (base64url-encode a structured or binary credential).