deprecate Normalize and MustNormalize (#4648)

* deprecate normalize and mustnormalize

Signed-off-by: Chris O'Haver <cohaver@infoblox.com>

* add runtime warning

Signed-off-by: Chris O'Haver <cohaver@infoblox.com>

* elaborate runtime warning

Signed-off-by: Chris O'Haver <cohaver@infoblox.com>

* include caller info

Signed-off-by: Chris O'Haver <cohaver@infoblox.com>

6 files changed, 61 insertions, 11 deletions

diff --git a/plugin/forward/setup.go b/plugin/forward/setup.go
index 657d5afd4..3cebfe2d9 100644
--- a/plugin/forward/setup.go
+++ b/plugin/forward/setup.go
@@ -93,7 +93,7 @@ func parseStanza(c *caddy.Controller) (*Forward, error) {
 		return f, c.ArgErr()
 	}
 	origFrom := f.from
-	f.from = plugin.Host(f.from).Normalize()[0] // there can only be one here, won't work with non-octet reverse
+	f.from = plugin.Host(f.from).NormalizeExact()[0] // there can only be one here, won't work with non-octet reverse
 
 	if len(f.from) > 1 {
 		log.Warningf("Unsupported CIDR notation: '%s' expands to multiple zones. Using only '%s'.", origFrom, f.from)
@@ -156,7 +156,7 @@ func parseBlock(c *caddy.Controller, f *Forward) error {
 			return c.ArgErr()
 		}
 		for i := 0; i < len(ignore); i++ {
-			f.ignored = append(f.ignored, plugin.Host(ignore[i]).Normalize()...)
+			f.ignored = append(f.ignored, plugin.Host(ignore[i]).NormalizeExact()...)
 		}
 	case "max_fails":
 		if !c.NextArg() {
diff --git a/plugin/grpc/setup.go b/plugin/grpc/setup.go
index e96527802..44527ca5b 100644
--- a/plugin/grpc/setup.go
+++ b/plugin/grpc/setup.go
@@ -56,7 +56,7 @@ func parseStanza(c *caddy.Controller) (*GRPC, error) {
 	if !c.Args(&g.from) {
 		return g, c.ArgErr()
 	}
-	g.from = plugin.Host(g.from).Normalize()[0] // only the first is used.
+	g.from = plugin.Host(g.from).NormalizeExact()[0] // only the first is used.
 
 	to := c.RemainingArgs()
 	if len(to) == 0 {
@@ -100,7 +100,7 @@ func parseBlock(c *caddy.Controller, g *GRPC) error {
 			return c.ArgErr()
 		}
 		for i := 0; i < len(ignore); i++ {
-			g.ignored = append(g.ignored, plugin.Host(ignore[i]).Normalize()...)
+			g.ignored = append(g.ignored, plugin.Host(ignore[i]).NormalizeExact()...)
 		}
 	case "tls":
 		args := c.RemainingArgs()
diff --git a/plugin/loop/setup.go b/plugin/loop/setup.go
index 13551c2b6..6af7b3baa 100644
--- a/plugin/loop/setup.go
+++ b/plugin/loop/setup.go
@@ -70,7 +70,7 @@ func parse(c *caddy.Controller) (*Loop, error) {
 		}
 
 		if len(c.ServerBlockKeys) > 0 {
-			zones = plugin.Host(c.ServerBlockKeys[0]).Normalize()
+			zones = plugin.Host(c.ServerBlockKeys[0]).NormalizeExact()
 		}
 	}
 	return New(zones[0]), nil
diff --git a/plugin/normalize.go b/plugin/normalize.go
index 10a60a806..b46966b74 100644
--- a/plugin/normalize.go
+++ b/plugin/normalize.go
@@ -3,10 +3,12 @@ package plugin
 import (
 	"fmt"
 	"net"
+	"runtime"
 	"strconv"
 	"strings"
 
 	"github.com/coredns/coredns/plugin/pkg/cidr"
+	"github.com/coredns/coredns/plugin/pkg/log"
 	"github.com/coredns/coredns/plugin/pkg/parse"
 
 	"github.com/miekg/dns"
@@ -63,8 +65,56 @@ type (
 
 // Normalize will return the host portion of host, stripping
 // of any port or transport. The host will also be fully qualified and lowercased.
+// An empty string is returned on failure
+// Deprecated: use OriginsFromArgsOrServerBlock or NormalizeExact
+func (h Host) Normalize() string {
+	var caller string
+	if _, file, line, ok := runtime.Caller(1); ok {
+		caller = fmt.Sprintf("(%v line %d) ", file, line)
+	}
+	log.Warning("An external plugin " + caller + "is using the deprecated function Normalize. " +
+		"This will be removed in a future versions of CoreDNS. The plugin should be updated to use " +
+		"OriginsFromArgsOrServerBlock or NormalizeExact instead.")
+
+	s := string(h)
+	_, s = parse.Transport(s)
+
+	// The error can be ignored here, because this function is called after the corefile has already been vetted.
+	hosts, _, err := SplitHostPort(s)
+	if err != nil {
+		return ""
+	}
+	return Name(hosts[0]).Normalize()
+}
+
+// MustNormalize will return the host portion of host, stripping
+// of any port or transport. The host will also be fully qualified and lowercased.
+// An error is returned on error
+// Deprecated: use OriginsFromArgsOrServerBlock or NormalizeExact
+func (h Host) MustNormalize() (string, error) {
+	var caller string
+	if _, file, line, ok := runtime.Caller(1); ok {
+		caller = fmt.Sprintf("(%v line %d) ", file, line)
+	}
+	log.Warning("An external plugin " + caller + "is using the deprecated function MustNormalize. " +
+		"This will be removed in a future versions of CoreDNS. The plugin should be updated to use " +
+		"OriginsFromArgsOrServerBlock or NormalizeExact instead.")
+
+	s := string(h)
+	_, s = parse.Transport(s)
+
+	// The error can be ignored here, because this function is called after the corefile has already been vetted.
+	hosts, _, err := SplitHostPort(s)
+	if err != nil {
+		return "", err
+	}
+	return Name(hosts[0]).Normalize(), nil
+}
+
+// NormalizeExact will return the host portion of host, stripping
+// of any port or transport. The host will also be fully qualified and lowercased.
 // An empty slice is returned on failure
-func (h Host) Normalize() []string {
+func (h Host) NormalizeExact() []string {
 	// The error can be ignored here, because this function should only be called after the corefile has already been vetted.
 	s := string(h)
 	_, s = parse.Transport(s)
@@ -126,13 +176,13 @@ func OriginsFromArgsOrServerBlock(args, serverblock []string) []string {
 		s := make([]string, len(serverblock))
 		copy(s, serverblock)
 		for i := range s {
-			s[i] = Host(s[i]).Normalize()[0] // expansion of these already happened in dnsserver/registrer.go
+			s[i] = Host(s[i]).NormalizeExact()[0] // expansion of these already happened in dnsserver/register.go
 		}
 		return s
 	}
 	s := []string{}
 	for i := range args {
-		sx := Host(args[i]).Normalize()
+		sx := Host(args[i]).NormalizeExact()
 		if len(sx) == 0 {
 			continue // silently ignores errors.
 		}
diff --git a/plugin/normalize_test.go b/plugin/normalize_test.go
index ac761f7ea..434bfb6f2 100644
--- a/plugin/normalize_test.go
+++ b/plugin/normalize_test.go
@@ -71,7 +71,7 @@ func TestNameNormalize(t *testing.T) {
 	}
 }
 
-func TestHostNormalize(t *testing.T) {
+func TestHostNormalizeExact(t *testing.T) {
 	tests := []struct {
 		in  string
 		out []string
@@ -85,7 +85,7 @@ func TestHostNormalize(t *testing.T) {
 	}
 
 	for i := range tests {
-		actual := Host(tests[i].in).Normalize()
+		actual := Host(tests[i].in).NormalizeExact()
 		expected := tests[i].out
 		sort.Strings(expected)
 		for j := range expected {
diff --git a/plugin/pkg/fall/fall.go b/plugin/pkg/fall/fall.go
index dd42f8e04..f819f99b6 100644
--- a/plugin/pkg/fall/fall.go
+++ b/plugin/pkg/fall/fall.go
@@ -33,7 +33,7 @@ func (f F) Through(qname string) bool {
 func (f *F) setZones(zones []string) {
 	z := []string{}
 	for i := range zones {
-		z = append(z, plugin.Host(zones[i]).Normalize()...)
+		z = append(z, plugin.Host(zones[i]).NormalizeExact()...)
 	}
 	f.Zones = z
 }