Deprecate "ip" in favour of "host" for domain fronting

Per review on #480: warn-and-ignore for the IP-shaped paths,
mirroring the net.Dialer.DualStack precedent — a config that
sets only "ip" will warn at startup and effectively disable
domain-fronting until the user switches to "host".

- mtglib.ProxyOpts: add DomainFrontingHost; mark DomainFrontingIP
  Deprecated and warn-and-drop in NewProxy.
- internal/config: GetDomainFrontingHost returns only
  [domain-fronting].host; deprecated keys are no longer used to
  derive the dial target. runProxy logs a startup warning per
  deprecated key that is set.
- internal/cli: add --domain-fronting-host; --domain-fronting-ip
  flag is parsed only so the runtime warning can fire.
- internal/cli/doctor: redirect the existing 2.3.0 entry at "host"
  and add a 2.4.0 entry for [domain-fronting].ip.
- example.config.toml: mark # ip = ... as deprecated.

example.config.toml

@@ -118,13 +118,16 @@ allow-fallback-on-unknown-dc = false
 #
 # Use `host` — accepts a hostname or a literal IP. Hostnames are resolved
 # at dial time, so a dual-stack DNS record can reach the right backend
-# address family for IPv4 or IPv6 clients. `ip` is kept for backward
-# compatibility (literal IP only). Setting both is an error.
+# address family for IPv4 or IPv6 clients.
 #
 # The hostname from the secret is still used for SNI in the TLS handshake.
 #
 # default value is not set (the secret's hostname is used).
 # host = "fronting-backend"
+
+# Deprecated: use `host`. If `ip` is set, mtg logs a warning at startup
+# and ignores the value (domain-fronting falls back to the secret's
+# hostname unless `host` is also set).
 # ip = "10.10.10.11"
 
 # FakeTLS uses domain fronting protection. So it needs to know a port to

internal/cli/doctor.go

@@ -140,7 +140,18 @@ func (d *Doctor) checkDeprecatedConfig() bool {
 			"when":        "2.3.0",
 			"old":         "domain-fronting-ip",
 			"old_section": "",
-			"new":         "ip",
+			"new":         "host",
+			"new_section": "domain-fronting",
+		})
+	}
+
+	if d.conf.DomainFronting.IP.Value != nil {
+		ok = false
+		tplWDeprecatedConfig.Execute(os.Stdout, map[string]string{ //nolint: errcheck
+			"when":        "2.4.0",
+			"old":         "ip",
+			"old_section": "domain-fronting",
+			"new":         "host",
 			"new_section": "domain-fronting",
 		})
 	}

internal/cli/run_proxy.go

@@ -287,11 +287,23 @@ func warnSNIMismatch(conf *config.Config, ntw mtglib.Network, log mtglib.Logger)
 		"DPI may detect and block the proxy. See 'mtg doctor' for details")
 }
 
+func warnDeprecatedDomainFronting(conf *config.Config, log mtglib.Logger) {
+	if conf.DomainFrontingIP.Value != nil {
+		log.Warning(`config option "domain-fronting-ip" is deprecated and ignored; use "host" in [domain-fronting] instead`)
+	}
+
+	if conf.DomainFronting.IP.Value != nil {
+		log.Warning(`config option "ip" in [domain-fronting] is deprecated and ignored; use "host" instead`)
+	}
+}
+
 func runProxy(conf *config.Config, version string) error { //nolint: funlen, cyclop
 	logger := makeLogger(conf)
 
 	logger.BindJSON("configuration", conf.String()).Debug("configuration")
 
+	warnDeprecatedDomainFronting(conf, logger)
+
 	eventStream, err := makeEventStream(conf, logger)
 	if err != nil {
 		return fmt.Errorf("cannot build event stream: %w", err)
@@ -343,7 +355,7 @@ func runProxy(conf *config.Config, version string) error { //nolint: funlen, cyc
 		Secret:                      conf.Secret,
 		Concurrency:                 conf.GetConcurrency(mtglib.DefaultConcurrency),
 		DomainFrontingPort:          conf.GetDomainFrontingPort(mtglib.DefaultDomainFrontingPort),
-		DomainFrontingIP:            conf.GetDomainFrontingHost(),
+		DomainFrontingHost:          conf.GetDomainFrontingHost(),
 		DomainFrontingProxyProtocol: conf.GetDomainFrontingProxyProtocol(false),
 		PreferIP:                    conf.PreferIP.Get(mtglib.DefaultPreferIP),
 		AutoUpdate:                  conf.AutoUpdate.Get(false),

internal/cli/simple_run.go

@@ -17,8 +17,9 @@ type SimpleRun struct {
 	Concurrency         uint64        `kong:"name='concurrency',short='c',default='8192',help='Max number of concurrent connection to proxy.'"`                        //nolint: lll
 	TCPBuffer           string        `kong:"name='tcp-buffer',short='b',default='4KB',help='Deprecated and ignored'"`                                                 //nolint: lll
 	PreferIP            string        `kong:"name='prefer-ip',short='i',default='prefer-ipv6',help='IP preference. By default we prefer IPv6 with fallback to IPv4.'"` //nolint: lll
-	DomainFrontingPort  uint64        `kong:"name='domain-fronting-port',short='p',default='443',help='A port to access for domain fronting.'"`                        //nolint: lll
-	DomainFrontingIP    string        `kong:"name='domain-fronting-ip',help='An IP address to use for domain fronting instead of resolving the hostname via DNS.'"`    //nolint: lll
+	DomainFrontingPort  uint64        `kong:"name='domain-fronting-port',short='p',default='443',help='A port to access for domain fronting.'"`                                                                  //nolint: lll
+	DomainFrontingHost  string        `kong:"name='domain-fronting-host',help='Hostname or IP to dial for domain fronting instead of resolving the secret hostname.'"`                                           //nolint: lll
+	DomainFrontingIP    string        `kong:"name='domain-fronting-ip',help='Deprecated: use --domain-fronting-host. Setting this flag logs a warning at startup and the value is ignored.'"`                    //nolint: lll
 	DOHIP               net.IP        `kong:"name='doh-ip',short='n',default='1.1.1.1',help='IP address of DNS-over-HTTP to use.'"`                                    //nolint: lll
 	Timeout             time.Duration `kong:"name='timeout',short='t',default='10s',help='Network timeout to use'"`                                                    //nolint: lll
 	Socks5Proxies       []string      `kong:"name='socks5-proxy',short='s',help='Socks5 proxies to use for network access.'"`                                          //nolint: lll
@@ -48,6 +49,15 @@ func (s *SimpleRun) Run(cli *CLI, version string) error { //nolint: cyclop,funle
 		return fmt.Errorf("incorrect domain-fronting-port: %w", err)
 	}
 
+	if s.DomainFrontingHost != "" {
+		if err := conf.DomainFronting.Host.Set(s.DomainFrontingHost); err != nil {
+			return fmt.Errorf("incorrect domain-fronting-host: %w", err)
+		}
+	}
+
+	// --domain-fronting-ip is deprecated; the value is parsed only so the
+	// runtime check in runProxy can detect it and emit the warn-and-ignore
+	// log message. The value never reaches the dial path.
 	if s.DomainFrontingIP != "" {
 		if err := conf.DomainFrontingIP.Set(s.DomainFrontingIP); err != nil {
 			return fmt.Errorf("incorrect domain-fronting-ip: %w", err)

internal/config/config.go

@@ -118,16 +118,7 @@ func (c *Config) GetDomainFrontingPort(defaultValue uint) uint {
 }
 
 func (c *Config) GetDomainFrontingHost() string {
-	if host := c.DomainFronting.Host.Get(""); host != "" {
-		return host
-	}
-	if ip := c.DomainFronting.IP.Get(nil); ip != nil {
-		return ip.String()
-	}
-	if ip := c.DomainFrontingIP.Get(nil); ip != nil {
-		return ip.String()
-	}
-	return ""
+	return c.DomainFronting.Host.Get("")
 }
 
 func (c *Config) GetDomainFrontingProxyProtocol(defaultValue bool) bool {
@@ -143,10 +134,6 @@ func (c *Config) Validate() error {
 		return fmt.Errorf("incorrect bind-to parameter %s", c.BindTo.String())
 	}
 
-	if c.DomainFronting.Host.Get("") != "" && c.DomainFronting.IP.Get(nil) != nil {
-		return fmt.Errorf("[domain-fronting] host and ip are mutually exclusive; pick one")
-	}
-
 	return nil
 }
 

internal/config/config_test.go

@@ -74,13 +74,14 @@ func (suite *ConfigTestSuite) TestString() {
 	suite.NotEmpty(conf.String())
 }
 
-func (suite *ConfigTestSuite) TestDomainFrontingHostAndIPMutuallyExclusive() {
+func (suite *ConfigTestSuite) TestDomainFrontingIPIgnoredWhenHostSet() {
 	conf, err := config.Parse(suite.ReadConfig("minimal.toml"))
 	suite.NoError(err)
 
 	suite.NoError(conf.DomainFronting.Host.Set("fronting-backend"))
 	suite.NoError(conf.DomainFronting.IP.Set("10.0.0.10"))
-	suite.Error(conf.Validate())
+	suite.NoError(conf.Validate())
+	suite.Equal("fronting-backend", conf.GetDomainFrontingHost())
 }
 
 func (suite *ConfigTestSuite) TestDomainFrontingHostFromTOML() {
@@ -97,11 +98,14 @@ func (suite *ConfigTestSuite) TestDomainFrontingHostAcceptsLiteralIP() {
 	suite.Equal("10.0.0.1", conf.GetDomainFrontingHost())
 }
 
-func (suite *ConfigTestSuite) TestDomainFrontingIPFromTOML() {
+func (suite *ConfigTestSuite) TestDomainFrontingIPIgnoredFromTOML() {
 	conf, err := config.Parse(suite.ReadConfig("domain_fronting_ip.toml"))
 	suite.NoError(err)
 	suite.NoError(conf.Validate())
-	suite.Equal("10.0.0.10", conf.GetDomainFrontingHost())
+	// Deprecated [domain-fronting].ip is parsed but never used to derive
+	// the dial target — the user must migrate to [domain-fronting].host.
+	suite.NotNil(conf.DomainFronting.IP.Get(nil))
+	suite.Equal("", conf.GetDomainFrontingHost())
 }
 
 func (suite *ConfigTestSuite) TestDomainFrontingNotSet() {

mtglib/proxy.go

@@ -344,6 +344,10 @@ func NewProxy(opts ProxyOpts) (*Proxy, error) {
 	logger := opts.getLogger("proxy")
 	updatersLogger := logger.Named("telegram-updaters")
 
+	if opts.DomainFrontingIP != "" {
+		logger.Warning("mtglib.ProxyOpts.DomainFrontingIP is deprecated and ignored; use DomainFrontingHost instead")
+	}
+
 	proxy := &Proxy{
 		ctx:                      ctx,
 		ctxCancel:                cancel,
@@ -355,7 +359,7 @@ func NewProxy(opts ProxyOpts) (*Proxy, error) {
 		eventStream:              opts.EventStream,
 		logger:                   logger,
 		domainFrontingPort:       opts.getDomainFrontingPort(),
-		domainFrontingHost:       opts.DomainFrontingIP,
+		domainFrontingHost:       opts.DomainFrontingHost,
 		tolerateTimeSkewness:     opts.getTolerateTimeSkewness(),
 		idleTimeout:              opts.getIdleTimeout(),
 		handshakeTimeout:         opts.getHandshakeTimeout(),

mtglib/proxy_opts.go

@@ -105,16 +105,24 @@ type ProxyOpts struct {
 	// This is an optional setting.
 	DomainFrontingPort uint
 
-	// DomainFrontingIP is the address to use when connecting to the fronting
-	// domain instead of resolving the hostname from the secret via DNS. It
-	// can be a literal IP or a hostname; hostnames are resolved at dial time
-	// via the native dialer (which honours dual-stack and Happy Eyeballs).
+	// DomainFrontingHost is the address to use when connecting to the
+	// fronting domain instead of resolving the hostname from the secret via
+	// DNS. It can be a literal IP or a hostname; hostnames are resolved at
+	// dial time via the native dialer (which honours dual-stack and Happy
+	// Eyeballs).
 	//
 	// This is useful when DNS resolution of the secret's hostname is blocked
 	// or loops back to this server. The hostname from the secret is still
 	// used for SNI in the TLS handshake.
 	//
 	// This is an optional setting.
+	DomainFrontingHost string
+
+	// DomainFrontingIP previously held the dial target for the fronting
+	// domain. The setting is no longer honoured: setting it logs a warning
+	// at proxy startup and the value is dropped.
+	//
+	// Deprecated: use DomainFrontingHost. Setting this field has no effect.
 	DomainFrontingIP string
 
 	// DomainFrontingProxyProtocol is used if communication between upstream