From 6313bc5615df10c5bc3577645e74edb0dcaf0486 Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <mitchell.hashimoto@gmail.com>
Date: Mon, 12 Mar 2018 10:13:44 -0700
Subject: [PATCH] agent: clarified a number of comments per PR feedback

---
 agent/agent_endpoint_test.go          | 5 ++++-
 agent/consul/catalog_endpoint_test.go | 2 --
 agent/dns_test.go                     | 2 +-
 agent/structs/service_definition.go   | 3 ++-
 agent/structs/structs.go              | 3 +++
 5 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/agent/agent_endpoint_test.go b/agent/agent_endpoint_test.go
index 167a233773..d59c804eaa 100644
--- a/agent/agent_endpoint_test.go
+++ b/agent/agent_endpoint_test.go
@@ -1372,6 +1372,9 @@ func TestAgent_RegisterService_ConnectProxy(t *testing.T) {
 	a := NewTestAgent(t.Name(), "")
 	defer a.Shutdown()
 
+	// Register a proxy. Note that the destination doesn't exist here on
+	// this agent or in the catalog at all. This is intended and part
+	// of the design.
 	args := &structs.ServiceDefinition{
 		Kind:             structs.ServiceKindConnectProxy,
 		Name:             "connect-proxy",
@@ -1388,7 +1391,7 @@ func TestAgent_RegisterService_ConnectProxy(t *testing.T) {
 	assert.Nil(err)
 	assert.Nil(obj)
 
-	// Ensure the servie
+	// Ensure the service
 	svc, ok := a.State.Services()["connect-proxy"]
 	assert.True(ok, "has service")
 	assert.Equal(structs.ServiceKindConnectProxy, svc.Kind)
diff --git a/agent/consul/catalog_endpoint_test.go b/agent/consul/catalog_endpoint_test.go
index d08438f9db..7b2247af75 100644
--- a/agent/consul/catalog_endpoint_test.go
+++ b/agent/consul/catalog_endpoint_test.go
@@ -393,7 +393,6 @@ func TestCatalog_Register_ConnectProxy_ACLProxyDestination(t *testing.T) {
 		c.ACLDatacenter = "dc1"
 		c.ACLMasterToken = "root"
 		c.ACLDefaultPolicy = "deny"
-		c.ACLEnforceVersion8 = false
 	})
 	defer os.RemoveAll(dir1)
 	defer s1.Shutdown()
@@ -1802,7 +1801,6 @@ func TestCatalog_ListServiceNodes_ConnectProxy_ACL(t *testing.T) {
 		c.ACLDatacenter = "dc1"
 		c.ACLMasterToken = "root"
 		c.ACLDefaultPolicy = "deny"
-		c.ACLEnforceVersion8 = false
 	})
 	defer os.RemoveAll(dir1)
 	defer s1.Shutdown()
diff --git a/agent/dns_test.go b/agent/dns_test.go
index a501a9c9f7..d897a921e9 100644
--- a/agent/dns_test.go
+++ b/agent/dns_test.go
@@ -1049,7 +1049,7 @@ func TestDNS_ConnectServiceLookup(t *testing.T) {
 	a := NewTestAgent(t.Name(), "")
 	defer a.Shutdown()
 
-	// Register a node with an external service.
+	// Register
 	{
 		args := structs.TestRegisterRequestProxy(t)
 		args.Service.ProxyDestination = "db"
diff --git a/agent/structs/service_definition.go b/agent/structs/service_definition.go
index d469ed5d7a..a10f1527f9 100644
--- a/agent/structs/service_definition.go
+++ b/agent/structs/service_definition.go
@@ -1,6 +1,7 @@
 package structs
 
-// ServiceDefinition is used to JSON decode the Service definitions
+// ServiceDefinition is used to JSON decode the Service definitions. For
+// documentation on specific fields see NodeService which is better documented.
 type ServiceDefinition struct {
 	Kind              ServiceKind
 	ID                string
diff --git a/agent/structs/structs.go b/agent/structs/structs.go
index 40b606d170..95c0ba069d 100644
--- a/agent/structs/structs.go
+++ b/agent/structs/structs.go
@@ -491,6 +491,9 @@ type NodeService struct {
 
 	// ProxyDestination is the name of the service that this service is
 	// a Connect proxy for. This is only valid if Kind is "connect-proxy".
+	// The destination may be a service that isn't present in the catalog.
+	// This is expected and allowed to allow for proxies to come up
+	// earlier than their target services.
 	ProxyDestination string
 
 	RaftIndex