support IPv6: apply effective IP family consistently; add docs/networking.md

* split htrun init into phase1 (network resolution) and phase2 (clients/runtime)
* apply effective IP family to all HTTP listeners and intra-cluster clients
* fix IPv6 fallback bug where clients could dial v6 after v4 bind
* align AuthN and control transports with resolved networking
------
* docs: add docs/networking.md
------
* part six, prev. commit: f3630bc

Signed-off-by: Alex Aizman <alex.aizman@gmail.com>

Author: alex-aizman

ais/htrun.go

@@ -341,59 +341,13 @@ func (h *htrun) regNetHandlers(networkHandlers []networkHandler) {
 	}
 }
 
-func (h *htrun) init(config *cmn.Config) {
-	// before newTLS() below & before intra-cluster clients
-	if config.Net.HTTP.UseHTTPS {
-		if err := certloader.Init(config.Net.HTTP.Certificate, config.Net.HTTP.CertKey, h.statsT); err != nil {
-			cos.ExitLog(err)
-		}
-	}
-
-	initCtrlClient(config)
-	initDataClient(config)
-
-	load.Init()
-
-	tcpbuf := config.Net.L4.SndRcvBufSize
-	if h.si.IsProxy() {
-		tcpbuf = 0
-	} else if tcpbuf == 0 {
-		tcpbuf = cmn.DefaultSndRcvBufferSize // ditto: targets use AIS default when not configured
-	}
-
-	// PubNet enable tracing when configuration is set.
-	muxers := newMuxers(tracing.IsEnabled())
-	g.netServ.pub = &netServer{muxers: muxers, sndRcvBufSize: tcpbuf, useIPv6: config.Net.UseIPv6}
-	g.netServ.control = g.netServ.pub // if not separately configured, intra-control net is public
-	if config.HostNet.UseIntraControl {
-		// TODO: for now tracing is always disabled for intra-cluster traffic.
-		// Allow enabling through config.
-		muxers = newMuxers(false /*enableTracing*/)
-		g.netServ.control = &netServer{muxers: muxers, sndRcvBufSize: 0, lowLatencyToS: true, useIPv6: config.Net.UseIPv6}
-	}
-	g.netServ.data = g.netServ.control // if not configured, intra-data net is intra-control
-	if config.HostNet.UseIntraData {
-		// TODO: for now tracing is always disabled for intra-data traffic.
-		// Allow enabling through config.
-		muxers = newMuxers(false /*enableTracing*/)
-		g.netServ.data = &netServer{muxers: muxers, sndRcvBufSize: tcpbuf, useIPv6: config.Net.UseIPv6}
-	}
-
-	h.owner.smap = newSmapOwner(config)
-	h.owner.rmd = newRMDOwner(config)
-	h.owner.rmd.load()
-	h.owner.csk.init()
-
-	h.gmm = memsys.PageMM()
-	h.gmm.RegWithHK()
-	h.smm = memsys.ByteMM()
-	h.smm.RegWithHK()
-
-	hk.Reg("rate-limit"+hk.NameSuffix, h.ratelim.housekeep, hk.PruneRateLimiters)
-}
-
-// steps 1 thru 4
-func (h *htrun) initSnode(config *cmn.Config) {
+// resolve node networking and initialize Snode (steps 1 thru 4); in particular:
+// - pick addresses
+// - decide effective IP family
+// - initialize effective networking state (do not mutate config)
+// - init net servers/muxers
+// see also: docs/networking.md
+func (h *htrun) initPhase1(config *cmn.Config) {
 	var (
 		pubAddr  meta.NetInfo
 		pubExtra []meta.NetInfo
@@ -530,6 +484,30 @@ func (h *htrun) initSnode(config *cmn.Config) {
 		copy(h.si.PubExtra, pubExtra)
 		nlog.Infof("%s (multihome) access: %v and %v", cmn.NetPublic, pubAddr, h.si.PubExtra)
 	}
+
+	tcpbuf := config.Net.L4.SndRcvBufSize
+	if h.si.IsProxy() {
+		tcpbuf = 0
+	} else if tcpbuf == 0 {
+		tcpbuf = cmn.DefaultSndRcvBufferSize // ditto: targets use AIS default when not configured
+	}
+
+	// pub-net first
+	muxers := newMuxers(tracing.IsEnabled())
+	g.netServ.pub = &netServer{muxers: muxers, sndRcvBufSize: tcpbuf, useIPv6: useIPv6}
+
+	// intra-control and intra-data
+	// note: separate config and isolated bandwidth - strongly recommended
+	g.netServ.control = g.netServ.pub
+	if config.HostNet.UseIntraControl {
+		muxers = newMuxers(false /*enableTracing*/)
+		g.netServ.control = &netServer{muxers: muxers, sndRcvBufSize: 0, lowLatencyToS: true, useIPv6: useIPv6}
+	}
+	g.netServ.data = g.netServ.control // if not configured, intra-data net is intra-control
+	if config.HostNet.UseIntraData {
+		muxers = newMuxers(false /*enableTracing*/)
+		g.netServ.data = &netServer{muxers: muxers, sndRcvBufSize: tcpbuf, useIPv6: useIPv6}
+	}
 }
 
 func mustDiffer(ip1 meta.NetInfo, port1 int, use1 bool, ip2 meta.NetInfo, port2 int, use2 bool, tag string) {
@@ -541,6 +519,39 @@ func mustDiffer(ip1 meta.NetInfo, port1 int, use1 bool, ip2 meta.NetInfo, port2
 	}
 }
 
+// phase2 init (part of the Run()):
+// - TLS/clients
+// - metadata owners (singletons)
+// - cluster key
+// - housekeep: memsys; rate-limit-prune
+func (h *htrun) initPhase2(config *cmn.Config) {
+	debug.Assert(g.netServ.control != nil && g.netServ.data != nil && g.netServ.pub != nil) // (phase1 above)
+
+	// before newTLS() below & before intra-cluster clients
+	if config.Net.HTTP.UseHTTPS {
+		if err := certloader.Init(config.Net.HTTP.Certificate, config.Net.HTTP.CertKey, h.statsT); err != nil {
+			cos.ExitLog(err)
+		}
+	}
+
+	initCtrlClient(config, g.netServ.control.useIPv6)
+	initDataClient(config, g.netServ.data.useIPv6)
+
+	load.Init()
+
+	h.owner.smap = newSmapOwner(config)
+	h.owner.rmd = newRMDOwner(config)
+	h.owner.rmd.load()
+	h.owner.csk.init()
+
+	h.gmm = memsys.PageMM()
+	h.gmm.RegWithHK()
+	h.smm = memsys.ByteMM()
+	h.smm.RegWithHK()
+
+	hk.Reg("rate-limit"+hk.NameSuffix, h.ratelim.housekeep, hk.PruneRateLimiters)
+}
+
 // at startup, check this Snode vs locally stored Smap replica (NOTE: some errors are FATAL)
 func (h *htrun) loadSmap() (smap *smapX, reliable bool) {
 	smap = newSmap()

ais/http.go

@@ -54,7 +54,7 @@ func handleData(path string, handler func(http.ResponseWriter, *http.Request)) {
 	}
 }
 
-func initCtrlClient(config *cmn.Config) {
+func initCtrlClient(config *cmn.Config, useIPv6 bool) {
 	const (
 		defaultControlWriteBufferSize = 16 * cos.KiB // for more defaults see cmn/network.go
 		defaultControlReadBufferSize  = 16 * cos.KiB
@@ -67,7 +67,7 @@ func initCtrlClient(config *cmn.Config) {
 		IdleConnsPerHost: config.Net.HTTP.MaxIdleConnsPerHost,
 		MaxIdleConns:     config.Net.HTTP.MaxIdleConns,
 		LowLatencyToS:    true,
-		UseIPv6:          config.Net.UseIPv6,
+		UseIPv6:          useIPv6,
 	}
 	if config.Net.HTTP.UseHTTPS {
 		g.client.control = cmn.NewIntraClientTLS(cargs, config)
@@ -77,7 +77,7 @@ func initCtrlClient(config *cmn.Config) {
 }
 
 // wbuf/rbuf - when not configured use AIS defaults (to override the usual 4KB)
-func initDataClient(config *cmn.Config) {
+func initDataClient(config *cmn.Config, useIPv6 bool) {
 	wbuf, rbuf := config.Net.HTTP.WriteBufferSize, config.Net.HTTP.ReadBufferSize
 	if wbuf == 0 {
 		wbuf = cmn.DefaultWriteBufferSize
@@ -92,15 +92,17 @@ func initDataClient(config *cmn.Config) {
 		IdleConnTimeout:  config.Net.HTTP.IdleConnTimeout.D(),
 		IdleConnsPerHost: config.Net.HTTP.MaxIdleConnsPerHost,
 		MaxIdleConns:     config.Net.HTTP.MaxIdleConns,
+		UseIPv6:          useIPv6,
 	}
 	if config.Net.HTTP.UseHTTPS {
 		g.client.data = cmn.NewIntraClientTLS(cargs, config)
 	} else {
 		g.client.data = cmn.NewClient(cargs)
 	}
 
-	// The g.client.data is used for the AWS MPT/presigned URL features.
-	// Enable tracing on the data client to capture traces for related AWS client calls.
+	// TODO:
+	// tracing policy for intra-cluster HTTP (control and data, both)
+	// should be unified; transport streams (and data movers) - are separate
 	g.client.data = tracing.NewTraceableClient(g.client.data)
 }
 

ais/proxy.go

@@ -83,7 +83,7 @@ var _ cos.Runner = (*proxy)(nil)
 func (*proxy) Name() string { return apc.Proxy } // as cos.Runner
 
 func (p *proxy) init(config *cmn.Config) {
-	p.initSnode(config)
+	p.initPhase1(config)
 
 	// (a) get node ID from command-line or env var (see envDaemonID())
 	// (b) load existing ID from config file stored under local config `confdir` (compare w/ target)
@@ -184,7 +184,7 @@ func (p *proxy) pready(smap *smapX, withRR bool /* also check readiness to rebal
 // start proxy runner
 func (p *proxy) Run() error {
 	config := cmn.GCO.Get()
-	p.htrun.init(config)
+	p.htrun.initPhase2(config)
 	p.setusr1()
 	p.owner.bmd = newBMDOwnerPrx(config)
 	p.owner.etl = newEtlMDOwnerPrx(config)

ais/prxauth.go

@@ -87,6 +87,8 @@ const (
 /////////////////
 
 func newAuthManager(config *cmn.Config, statsT stats.Tracker) *authManager {
+	debug.Assert(g.netServ.pub != nil)
+
 	rootCtx, rootCancel := context.WithCancel(context.Background())
 	keyCacheClient := newKeyCacheClient(config, statsT)
 	keyCacheManager := tok.NewKeyCacheManager(config.Auth.OIDC, keyCacheClient, nil, statsT)
@@ -131,7 +133,7 @@ func newKeyCacheClient(config *cmn.Config, statsT stats.Tracker) *http.Client {
 		Timeout:          KeyCacheTimeout,
 		IdleConnsPerHost: KeyCacheIdleConnsPerHost,
 		MaxIdleConns:     maxIdleConns,
-		UseIPv6:          config.Net.UseIPv6,
+		UseIPv6:          g.netServ.pub.useIPv6,
 	}
 	client := cmn.NewClientTLS(transport, tls, false)
 

ais/prxrev.go

@@ -229,7 +229,7 @@ func rpTransport(config *cmn.Config) *http.Transport {
 			IdleConnTimeout:  config.Net.HTTP.IdleConnTimeout.D(),
 			IdleConnsPerHost: config.Net.HTTP.MaxIdleConnsPerHost,
 			MaxIdleConns:     config.Net.HTTP.MaxIdleConns,
-			UseIPv6:          config.Net.UseIPv6,
+			UseIPv6:          g.netServ.control.useIPv6,
 		})
 	)
 	if config.Net.HTTP.UseHTTPS {

ais/target.go

@@ -251,7 +251,7 @@ func (t *target) aisbp() *backend.AISbp {
 //
 
 func (t *target) init(config *cmn.Config) {
-	t.initSnode(config)
+	t.initPhase1(config)
 
 	// (a) get node ID from command-line or env var (see envDaemonID())
 	// (b) load existing node ID (replicated xattr at roots of respective mountpaths)
@@ -376,7 +376,7 @@ func (t *target) Run() error {
 		cos.ExitLog(err)
 	}
 	config := cmn.GCO.Get()
-	t.htrun.init(config)
+	t.htrun.initPhase2(config)
 	t.setusr1()
 
 	core.Tinit(t, config, true /*run hk*/)

ais/tgtobj_internal_test.go

@@ -1,6 +1,6 @@
 // Package ais provides AIStore's proxy and target nodes.
 /*
- * Copyright (c) 2018-2025, NVIDIA CORPORATION. All rights reserved.
+ * Copyright (c) 2018-2026, NVIDIA CORPORATION. All rights reserved.
  */
 package ais
 
@@ -65,13 +65,13 @@ func TestMain(m *testing.M) {
 	config.Log.Level = "3"
 	co := newConfigOwner(config)
 	t = newTarget(co)
-	t.initSnode(config)
+	t.initPhase1(config)
 	tid, _ := initTID(config)
 	t.si.Init(tid, apc.Target)
 
 	fs.Add(testMountpath, t.SID())
 
-	t.htrun.init(config)
+	t.htrun.initPhase2(config)
 	t.ups.t = t
 
 	t.statsT = mock.NewStatsTracker()