peer/server: Split handshake to synchronous func.

[davecgh]

This requires #3631.

The current design where the handshake happens asynchronously when the async I/O is started is less than ideal and is quite brittle. It also significantly complicates everything as evidenced by several minor bugs over the years that have resulted from faulty assumptions which directly stem from its asynchronous nature.

For an example of some of the complexity it causes, it means that a bunch of additional flags are required that solely related to the handshake. Namely, whether or not the version if known, whether the verack has been received, and whether the handshake is done. Then, because it's all happening asynchronously, later code has to be vigilant about checking that those events have happened.

All of this complexity can entirely be avoided by simply requiring a successful synchronous handshake to take place prior to starting async I/O.

With that in mind, this significantly reworks the way the handshake is handled so that happens via a separate blocking method and removes async handlers which are no longer required as a result.

The changes have been split in a series a commits to ease the review. Each commit fully compiles, passes all tests, and describes the changes in detail.

The following is a high level overview of the changes:

• Introduce programmatically detectable errors consistent with other code throughout the repository
• Accept connection in constructors instead of a separate AssociateConnection
• Move the handshake code to a separate blocking method named Handshake that accepts a callback to invoke with the
  received version message
  • The new method returns an error that callers can use to reliably detect a failed handshake
  • The callback can return an error to cause the handshake to fail and pass the error along to the caller
• Make the initial handshake block until both the version and verack message are received
• Any further received version or verack messages in the async I/O handlers are now unconditionally an error
• Removes the OnVersion and OnVerAck async listeners that no longer apply
• Removes the VersionKnown, VerAckReceived, and HandshakeDone methods and associated internal fields that no longer apply
• Updates the calling server code thread the overall process context down to the Handshake and Run methods
• Adds several additional tests for correctness
• Updates the example to clearly show the new semantics
• Includes extra documentation to elucidate the exact requirements for establishing a new peer as well as exactly which properties the caller can and can't rely on during the handshake
• Other docs and test cleanup to help make them a little more modern

[jholdstock]

Whats the benefit of repeating? Isn't this just testing the same code path twice?

[davecgh]

It is calling the same funcs, but in a different order. That isn't at all obvious, especially at this point in the sequence of commits since the handshake is all happening asynchronously. I think maybe it is more obvious in a later commit when it switches over to the synchronous handshake.

The outbound peer always goes first, so, in the case of the first sequence, the inbound peer is already established and blocking on readRemoteVersionMsg until the outbound peer sends the version message at which point the handshake process proceeds and it ends up failing to produce its own local version message.

In the other direction, the peer fails when attempting to go first (via writeLocalVersionMsg).

So, in other words, it forces them both to fail for slightly different reasons depending on which one is going first.

[davecgh]

Thanks for the thorough review. I've addressed most of the feedback. I'll address the rest a bit later.

[davecgh]

It is calling the same funcs, but in a different order. That isn't at all obvious, especially at this point in the sequence of commits since the handshake is all happening asynchronously. I think maybe it is more obvious in a later commit when it switches over to the synchronous handshake.

The outbound peer always goes first, so, in the case of the first sequence, the inbound peer is already established and blocking on readRemoteVersionMsg until the outbound peer sends the version message at which point the handshake process proceeds and it ends up failing to produce its own local version message.

In the other direction, the peer fails when attempting to go first (via writeLocalVersionMsg).

So, in other words, it forces them both to fail for slightly different reasons depending on which one is going first.