add support for transient connections

network/conn.go

@@ -19,6 +19,7 @@ type Conn interface {
 
 	ConnSecurity
 	ConnMultiaddrs
+	ConnStat
 
 	// ID returns an identifier that uniquely identifies this Conn within this
 	// host, during this run. Connection IDs may repeat across restarts.
@@ -29,9 +30,6 @@ type Conn interface {
 
 	// GetStreams returns all open streams over this conn.
 	GetStreams() []Stream
-
-	// Stat stores metadata pertaining to this conn.
-	Stat() Stat
 }
 
 // ConnSecurity is the interface that one can mix into a connection interface to
@@ -61,3 +59,9 @@ type ConnMultiaddrs interface {
 	// with this connection
 	RemoteMultiaddr() ma.Multiaddr
 }
+
+// ConnStat is an interface mixin for connection types that provide connection statistics.
+type ConnStat interface {
+	// Stat stores metadata pertaining to this conn.
+	Stat() Stat
+}

network/context.go

@@ -13,9 +13,11 @@ var DialPeerTimeout = 60 * time.Second
 type noDialCtxKey struct{}
 type dialPeerTimeoutCtxKey struct{}
 type forceDirectDialCtxKey struct{}
+type useTransientCtxKey struct{}
 
 var noDial = noDialCtxKey{}
 var forceDirectDial = forceDirectDialCtxKey{}
+var useTransient = useTransientCtxKey{}
 
 // EXPERIMENTAL
 // WithForceDirectDial constructs a new context with an option that instructs the network
@@ -66,3 +68,18 @@ func GetDialPeerTimeout(ctx context.Context) time.Duration {
 func WithDialPeerTimeout(ctx context.Context, timeout time.Duration) context.Context {
 	return context.WithValue(ctx, dialPeerTimeoutCtxKey{}, timeout)
 }
+
+// WithUseTransient constructs a new context with an option that instructs the network
+// that it is acceptable to use a transient connection when opening a new stream.
+func WithUseTransient(ctx context.Context, reason string) context.Context {
+	return context.WithValue(ctx, useTransient, reason)
+}
+
+// GetUseTransient returns true if the use transient option is set in the context.
+func GetUseTransient(ctx context.Context) (usetransient bool, reason string) {
+	v := ctx.Value(useTransient)
+	if v != nil {
+		return true, v.(string)
+	}
+	return false, ""
+}

network/errors.go

@@ -8,3 +8,7 @@ var ErrNoRemoteAddrs = errors.New("no remote addresses")
 // ErrNoConn is returned when attempting to open a stream to a peer with the NoDial
 // option and no usable connection is available.
 var ErrNoConn = errors.New("no usable connection to peer")
+
+// ErrTransientConn is returned when attempting to open a stream to a peer with only a transient
+// connection, without specifying the UseTransient option.
+var ErrTransientConn = errors.New("transient connection to peer")

network/network.go

@@ -103,6 +103,8 @@ type Stat struct {
 	Direction Direction
 	// Opened is the timestamp when this connection was opened.
 	Opened time.Time
+	// Transient indicates that this connection is transient and may be closed soon.
+	Transient bool
 	// Extra stores additional metadata about this connection.
 	Extra map[interface{}]interface{}
 }