add comments

Signed-off-by: Dan Bond <danbond@protonmail.com>

.changelog/17171.txt

@@ -1,3 +1,3 @@
 ```release-note:improvement
-agent: prevent very old servers re-joining a cluster with stale data 
+agent: add a configurable maximimum age (default: 7 days) to prevent servers re-joining a cluster with stale data 
 ```

agent/agent.go

@@ -4597,8 +4597,9 @@ func (a *Agent) checkServerLastSeen() error {
 		return fmt.Errorf("error reading server metadata: %w", err)
 	}
 
-	if err := md.CheckLastSeen(a.config.ServerRejoinAgeMax); err != nil {
-		return fmt.Errorf("error: server will not rejoin: %w", err)
+	maxAge := a.config.ServerRejoinAgeMax
+	if md.IsLastSeenStale(maxAge) {
+		return fmt.Errorf("error: server is older than specified %s max age, will not rejoin", maxAge)
 	}
 
 	return nil

agent/consul/server_metadata.go

@@ -5,34 +5,37 @@ package consul
 
 import (
 	"encoding/json"
-	"fmt"
 	"io"
 	"os"
 	"time"
 )
 
+// ServerMetadataFile is the name of the file on disk that server metadata
+// should be written to.
 const ServerMetadataFile = "server_metadata.json"
 
-// ServerMetadata ...
+// ServerMetadata represents specific metadata about a running server.
 type ServerMetadata struct {
+	// LastSeenUnix is the timestamp a server was last seen, in Unix format.
 	LastSeenUnix int64 `json:"last_seen_unix"`
 }
 
-func (md *ServerMetadata) CheckLastSeen(d time.Duration) error {
+// IsLastSeenStale checks whether the last seen timestamp is older than a given duration.
+func (md *ServerMetadata) IsLastSeenStale(d time.Duration) bool {
 	lastSeen := time.Unix(md.LastSeenUnix, 0)
 	maxAge := time.Now().Add(-d)
 
-	if lastSeen.Before(maxAge) {
-		return fmt.Errorf("server is older than specified %s max age", d)
-	}
-
-	return nil
+	return lastSeen.Before(maxAge)
 }
 
+// OpenServerMetadata is a helper function for opening the server metadata file
+// with the correct permissions.
 func OpenServerMetadata(filename string) (io.WriteCloser, error) {
 	return os.OpenFile(filename, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600)
 }
 
+// ReadServerMetadata is a helper function for reading the contents of a server
+// metadata file and unmarshaling the data from JSON.
 func ReadServerMetadata(filename string) (*ServerMetadata, error) {
 	b, err := os.ReadFile(filename)
 	if err != nil {
@@ -47,6 +50,7 @@ func ReadServerMetadata(filename string) (*ServerMetadata, error) {
 	return &md, nil
 }
 
+// WriteServerMetadata writes server metadata to a file in JSON format.
 func WriteServerMetadata(w io.Writer) error {
 	md := &ServerMetadata{
 		LastSeenUnix: time.Now().Unix(),

agent/consul/server_metadata_test.go

@@ -27,24 +27,24 @@ func (m *mockServerMetadataWriter) Write(p []byte) (n int, err error) {
 func TestServerMetadata(t *testing.T) {
 	now := time.Now()
 
-	t.Run("TestCheckLastSeenError", func(t *testing.T) {
+	t.Run("TestIsLastSeenStaleTrue", func(t *testing.T) {
 		// Create a server that is 24 hours old.
 		md := &ServerMetadata{
 			LastSeenUnix: now.Add(-24 * time.Hour).Unix(),
 		}
 
-		err := md.CheckLastSeen(1 * time.Hour)
-		assert.Error(t, err)
+		ok := md.IsLastSeenStale(1 * time.Hour)
+		assert.True(t, ok)
 	})
 
-	t.Run("TestCheckLastSeenOK", func(t *testing.T) {
+	t.Run("TestIsLastSeenStaleFalse", func(t *testing.T) {
 		// Create a server that is 24 hours old.
 		md := &ServerMetadata{
 			LastSeenUnix: now.Add(-1 * time.Hour).Unix(),
 		}
 
-		err := md.CheckLastSeen(24 * time.Hour)
-		assert.NoError(t, err)
+		ok := md.IsLastSeenStale(24 * time.Hour)
+		assert.False(t, ok)
 	})
 }