feat(quic): add experimental client-side connection migration support

Add support for QUIC connection migration, allowing outbound connections
to switch network paths (e.g., from a primary interface to a failover
interface) without disrupting active streams.

This feature leverages quic-go's connection migration APIs (AddPath,
Probe, Switch) introduced in v0.51.0. Migration is opt-in via the
EnableExperimentalConnectionMigration() transport option.

Key changes:
- Add MigratableConn and Path interfaces in core/network
- Add migration event types in core/event
- Implement MigratableConn in QUIC connection via Conn.As()
- Add TransportForMigration to ConnManager for alternate paths
- Add comprehensive tests and documentation

Only client-initiated (outbound) connections support migration per the
QUIC specification. Server-side connections return SupportsMigration() == false.

Signed-off-by: Willian Paixao <willian@ufpa.br>

Author: willianpaixao

core/event/migration.go

@@ -0,0 +1,96 @@
+package event
+
+import (
+	"time"
+
+	"github.com/libp2p/go-libp2p/core/peer"
+
+	ma "github.com/multiformats/go-multiaddr"
+)
+
+// EvtConnectionMigrationStarted is emitted when a connection migration begins.
+// This event would be emitted when AddPath() completes successfully, before
+// the user calls Probe() on the returned path.
+//
+// Note: Event emission is not yet implemented. These types are defined for
+// future use and API stability.
+//
+// This is an EXPERIMENTAL event and may change in future versions.
+type EvtConnectionMigrationStarted struct {
+	// Peer is the remote peer ID of the connection being migrated.
+	Peer peer.ID
+	// ConnID is the unique identifier of the connection.
+	ConnID string
+	// FromLocalAddr is the current local address before migration.
+	FromLocalAddr ma.Multiaddr
+	// ToLocalAddr is the target local address to migrate to.
+	ToLocalAddr ma.Multiaddr
+}
+
+// EvtConnectionMigrationCompleted is emitted when a connection migration succeeds.
+// At this point, the connection is using the new path for all communication.
+//
+// Note: In client-side QUIC migration, only the local address changes. The remote
+// address remains the same since we're changing which local interface we use to
+// reach the same peer.
+//
+// This is an EXPERIMENTAL event and may change in future versions.
+type EvtConnectionMigrationCompleted struct {
+	// Peer is the remote peer ID of the migrated connection.
+	Peer peer.ID
+	// ConnID is the unique identifier of the connection.
+	ConnID string
+	// FromLocalAddr is the previous local address.
+	FromLocalAddr ma.Multiaddr
+	// ToLocalAddr is the new local address after migration.
+	ToLocalAddr ma.Multiaddr
+	// ProbeRTT is the round-trip time measured during path probing.
+	ProbeRTT time.Duration
+}
+
+// EvtConnectionMigrationFailed is emitted when a connection migration fails.
+// The connection may still be usable on the original path, or it may be closed
+// if both the new path and rollback failed.
+//
+// This is an EXPERIMENTAL event and may change in future versions.
+type EvtConnectionMigrationFailed struct {
+	// Peer is the remote peer ID of the connection.
+	Peer peer.ID
+	// ConnID is the unique identifier of the connection.
+	ConnID string
+	// FromLocalAddr is the original local address.
+	FromLocalAddr ma.Multiaddr
+	// ToLocalAddr is the target local address that failed.
+	ToLocalAddr ma.Multiaddr
+	// Error describes why the migration failed.
+	Error error
+	// ConnectionClosed indicates whether the connection was closed due to
+	// the failure (e.g., if rollback to the original path also failed).
+	ConnectionClosed bool
+}
+
+// EvtPathAdded is emitted when a new path is added to a connection.
+// This happens when MigratableConn.AddPath() is called successfully.
+//
+// This is an EXPERIMENTAL event and may change in future versions.
+type EvtPathAdded struct {
+	// Peer is the remote peer ID of the connection.
+	Peer peer.ID
+	// ConnID is the unique identifier of the connection.
+	ConnID string
+	// LocalAddr is the local address of the new path.
+	LocalAddr ma.Multiaddr
+}
+
+// EvtPathRemoved is emitted when a path is removed from a connection.
+// This happens when Path.Close() is called.
+//
+// This is an EXPERIMENTAL event and may change in future versions.
+type EvtPathRemoved struct {
+	// Peer is the remote peer ID of the connection.
+	Peer peer.ID
+	// ConnID is the unique identifier of the connection.
+	ConnID string
+	// LocalAddr is the local address of the removed path.
+	LocalAddr ma.Multiaddr
+}

core/network/migration.go

@@ -0,0 +1,76 @@
+package network
+
+import (
+	"context"
+	"time"
+
+	ma "github.com/multiformats/go-multiaddr"
+)
+
+// PathInfo contains information about a network path.
+//
+// This is an EXPERIMENTAL type and may change in future versions.
+type PathInfo struct {
+	// LocalAddr is the local address of this path.
+	LocalAddr ma.Multiaddr
+	// RemoteAddr is the remote address of this path.
+	RemoteAddr ma.Multiaddr
+	// Active indicates whether this is the currently active path.
+	Active bool
+	// RTT is the round-trip time measured for this path.
+	RTT time.Duration
+}
+
+// Path represents a network path that can be used for connection migration.
+// A path is created via MigratableConn.AddPath() and can be probed and
+// switched to.
+//
+// This is an EXPERIMENTAL interface and may change in future versions.
+type Path interface {
+	// Probe tests the path connectivity by sending a probe packet and
+	// waiting for acknowledgment. This validates that the path is usable
+	// before switching to it.
+	//
+	// The context can be used to set a timeout for the probe operation.
+	Probe(ctx context.Context) error
+
+	// Switch makes this path the active path for the connection.
+	// This should only be called after a successful Probe().
+	// After switching, all subsequent packets will use this path.
+	Switch() error
+
+	// Info returns information about this path.
+	Info() PathInfo
+
+	// Close removes this path from the connection.
+	// If this is the active path, Close will fail; switch to a different
+	// path first.
+	Close() error
+}
+
+// MigratableConn is implemented by connections that support path migration.
+// This allows switching the underlying network path (e.g., from a primary
+// interface to a failover interface) without disrupting active streams.
+//
+// Only client-initiated (outbound) QUIC connections support migration per
+// the QUIC specification.
+//
+// This is an EXPERIMENTAL interface and may change in future versions.
+type MigratableConn interface {
+	// SupportsMigration returns true if this connection supports path migration.
+	// Returns false for server-side connections or when migration is disabled.
+	SupportsMigration() bool
+
+	// AddPath adds a new potential path using the given local address.
+	// The returned Path can be probed and then switched to.
+	//
+	// The context can be used to set a timeout for path creation.
+	AddPath(ctx context.Context, localAddr ma.Multiaddr) (Path, error)
+
+	// ActivePath returns information about the currently active path.
+	ActivePath() PathInfo
+
+	// AvailablePaths returns information about all available paths,
+	// including the active path and any paths added via AddPath().
+	AvailablePaths() []PathInfo
+}