core/: Redesign upgrade::{write_one, write_with_len_prefix, read_one} (#2111)

1. Deprecating the `write_one` function

  Semantically, this function is a composition of `write_with_len_prefix` and
  `io.close()`. This represents a footgun because the `close` functionality is
  not obvious and only mentioned in the docs. Using this function multiple times
  on a single substream will produces hard to debug behaviour.

2. Deprecating `read_one` and `write_with_len_prefix` functions

3. Introducing `write_length_prefixed` and `read_length_prefixed`

- These functions are symmetric and do exactly what you would expect, just
  writing to the socket without closing
- They also have a symmetric interface (no more custom errors, just `io::Error`)

Co-authored-by: Max Inden <mail@max-inden.de>

core/src/upgrade.rs

@@ -80,8 +80,10 @@ pub use self::{
     map::{MapInboundUpgrade, MapOutboundUpgrade, MapInboundUpgradeErr, MapOutboundUpgradeErr},
     optional::OptionalUpgrade,
     select::SelectUpgrade,
-    transfer::{write_one, write_with_len_prefix, write_varint, read_one, ReadOneError, read_varint},
+    transfer::{write_length_prefixed, write_varint, read_length_prefixed, read_varint},
 };
+#[allow(deprecated)]
+pub use self::transfer::ReadOneError;
 
 /// Types serving as protocol names.
 ///