Add structured handshake rejections

[Mayank808]

Why

Custom handshake handlers can only return a River failure code. Applications must put specific failure states in error strings and parse those strings for retry decisions. We can log application specific errors which will improve logging and error handling flows.

Current specific use case is for terminal errors happening on river handshakes we want to close the river connection we have no way to differentiate between a handshake error that is terminal vs error retry

What changed

Custom handshake handlers can now return rejectHandshake({ code, message, extras }). River sends these optional details in failed handshake responses and exposes them in protocol error events and logs. Existing handlers that return a River failure code continue to work without changes.

Tests cover initial handshakes, re-handshakes, and compatibility with old clients and servers. The protocol and handshake documentation describe the new payload.

Versioning

• Breaking protocol change
• Breaking ts/js API change

~ written by Zerg 👾 (wp-8f1d1ac5)

[wernst]

What do you think about making this just extras: unknown? I think at this point we're at the application boundary and we dont need to be prescriptive about shape. This is up to the app dev.

[Mayank808]

I think that also works but might lead to a lot of application specific structures and duplication that we would have to keep track of. I think having some structure enforced in a details package could lead to bit more conformity in the codebase later on especially when this is only being used for error cases. But let me know this is a easy change and more about style preferences of the team