From 04acd2c2791adc9a7d003950a7fbc9de9539fa9b Mon Sep 17 00:00:00 2001
From: Jorropo <jorropo.pgm@gmail.com>
Date: Fri, 28 Feb 2020 01:24:08 +0100
Subject: [PATCH] Adding QTransport interfaces.

There is also more additional new interface.
---
 transport/transport.go | 76 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 75 insertions(+), 1 deletion(-)

diff --git a/transport/transport.go b/transport/transport.go
index 39a8fd38..0371c726 100644
--- a/transport/transport.go
+++ b/transport/transport.go
@@ -28,6 +28,9 @@ var AcceptTimeout = 60 * time.Second
 // capabilities required by libp2p: stream multiplexing, encryption and
 // peer authentication.
 //
+// DEPREACATED try to use QCapableConn instead, using this will result in
+// wrong transport choice when trying to pick a good one.
+//
 // These capabilities may be natively provided by the transport, or they
 // may be shimmed via the "connection upgrade" process, which converts a
 // "raw" network connection into one that supports such capabilities by
@@ -44,6 +47,55 @@ type CapableConn interface {
 	Transport() Transport
 }
 
+// Quality is an estimation of how bad the connection will be.
+// It must be short and fast to run.
+// Lower is the returned score, better we expect the connection to be.
+// Don't implement a pinging/monitoring algorithm quality must be deterministic.
+//
+// To see where to place your transport on the scale take a look at this (note:
+// a proto with a Quality twice bigger is not twice slower or twice worst, it is
+// just worst, like the place on a leaderboard):
+// - TCP, 2^31, multiplexed stated continuous protocol (stream have fight for a
+//   place in the underlying protocol)
+// - QUIC, 2^30, async stated discontinuous protocol (stream doesn't have to
+//   fight but there is time taken to open the connection and stream)
+// - Circuit, router underlying connection quality + the number of hops * 8
+//   (that consider that all router are equal but there is really no better than
+//   pinging/monitoring to know that) + 2^16 (base circuit value).
+//
+// Its also not needed to follow that closely, thing can be added if a proto add
+// some overhead :
+// - WS tcp score + 50
+// - WSS ws score + 150
+//
+// If conn is on a private network Quality() must divide score by 2^8 (shift
+// right by 8).
+// If conn is on the loopback Quality() must divide score by 2^16 (shift right
+// by 16).
+//
+// QCapableConn embed CapableConn but with `Quality() uint32` support.
+type QCapableConn interface {
+	CapableConn
+
+	// Quality returns the Quality we can expect from the connection to this peer.
+	// That must be deterministic and fast.
+	Quality() uint32
+}
+
+// Score is used by transport to returns expectation about connection
+type Score struct {
+	// Score of the future connection, must not change once the connection is
+	// actualy created
+	Quality uint32
+	// True if quality was actualy calculable (it may only be calculable with an
+	// open connection).
+	// Note: if IsQuality == true swarm will be able to cancel the dial if a
+	// better transport is found.
+	IsQuality bool
+	// Number of file descriptor expected to be open.
+	Fd uint8
+}
+
 // Transport represents any device by which you can connect to and accept
 // connections from other peers.
 //
@@ -55,11 +107,30 @@ type CapableConn interface {
 // stream multiplexing and connection security (encryption and authentication).
 //
 // For a conceptual overview, see https://docs.libp2p.io/concepts/transport/
+//
+// DEPREACATED try to use QTransport instead, using this will result in
+// wrong transport choice when trying to pick a good one.
 type Transport interface {
+	BaseTransport
+
 	// Dial dials a remote peer. It should try to reuse local listener
 	// addresses if possible but it may choose not to.
 	Dial(ctx context.Context, raddr ma.Multiaddr, p peer.ID) (CapableConn, error)
+}
+
+type QTransport interface {
+	BaseTransport
+
+	// Dial dials a remote peer. It should try to reuse local listener
+	// addresses if possible but it may choose not to.
+	Dial(ctx context.Context, raddr ma.Multiaddr, p peer.ID) (QCapableConn, error)
 
+	// Score returns the Quality we can expect from the connection to this peer.
+	// That must be deterministic and fast.
+	Score(raddr ma.Multiaddr, p peer.ID) (Score, error)
+}
+
+type BaseTransport interface {
 	// CanDial returns true if this transport knows how to dial the given
 	// multiaddr.
 	//
@@ -109,5 +180,8 @@ type TransportNetwork interface {
 	// local multiaddr and pick the *last* protocol registered with a proxy
 	// transport, if any. Otherwise, it'll pick the transport registered to
 	// handle the last protocol in the multiaddr.
-	AddTransport(t Transport) error
+	//
+	// Even if BaseTransport are accepted its needed to be able to cast to
+	// Transport or QTransport.
+	AddTransport(t BaseTransport) error
 }