admit
Screens an incoming Iam handshake before it is accepted. The default admits every well-formed handshake - today's behaviour. A malformed Iam (a missing or empty name, or a credential slot that is present but empty) never reaches here: the server answers it REFUSED malformed first, from any origin, so name is never empty and credential is "" only when the client sent none. Override to validate credential (an opaque token the client supplied, empty if it sent none) or to refuse for application reasons (over capacity, banned): return Admission.Refused and the client receives REFUSED <reason> as a typed HandshakeRefusedException, with nothing registered and no onClientConnect call. This replaces the old "reply REGISTERED then silently drop the client" pattern for a connect-time refusal.
Runs inline on the common listener thread (like onClientConnect), so it must return promptly - a blocking credential lookup stalls inbound handling for every client. Do fast, local checks here; hand a slow verification to another thread and gate on its cached result.
Called only for a first well-formed Iam from an unknown origin - not for a retransmit from an already-registered origin, and never for a malformed line. Called for a same-name reconnect from a new origin before the stale registration is superseded, so refusing it leaves the existing connection intact.
A thrown exception is caught, logged, and the handshake is dropped (no reply, no registration); the client sees a timeout and may retry.
Return
Admission.Admitted to accept, Admission.Refused to reject
Parameters
the client's chosen name; never empty
the client's observed post-NAT origin
the opaque token from Iam <name> <credential>, verbatim; the empty string only if the client sent Iam <name> with no credential slot (a present-but-empty slot is malformed and never reaches here). A custom implementation must tolerate arbitrary/garbage credential strings (a legacy client may put an unrelated trailing token there).