Add comments for robot cache refresh behavior

Author: guettli

hcloud/instances_util.go

@@ -103,6 +103,7 @@ func getRobotServerByName(c robot.Client, node *corev1.Node) (server *hrobotmode
 		}
 	}
 
+	// No matching Robot server exists for this node, even after refreshing the cached list.
 	return nil, nil
 }
 

internal/robot/adapter.go

@@ -5,6 +5,7 @@ import (
 	hrobotmodels "github.com/syself/hrobot-go/models"
 )
 
+// adapter wraps hrobot.RobotClient so it satisfies this package's Client interface.
 type adapter struct {
 	hrobot.RobotClient
 }

internal/robot/cache.go

@@ -20,6 +20,7 @@ type cacheRobotClient struct {
 	servers     []hrobotmodels.Server
 	serversByID map[int]*hrobotmodels.Server
 
+	// forcedRefreshServerNames tracks which node names already triggered a forced refresh within the current cache timeout window.
 	forcedRefreshServerNames map[string]time.Time
 }
 
@@ -62,6 +63,7 @@ func (c *cacheRobotClient) ServerGetList() ([]hrobotmodels.Server, error) {
 	return c.servers, nil
 }
 
+// ServerGetListForceRefresh refreshes the server list immediately, unless the same node already forced a refresh within the current cache timeout window.
 func (c *cacheRobotClient) ServerGetListForceRefresh(nodeName string) ([]hrobotmodels.Server, error) {
 	c.mutex.Lock()
 	defer c.mutex.Unlock()
@@ -114,6 +116,7 @@ func (c *cacheRobotClient) refreshCache() error {
 	return nil
 }
 
+// nodeHasAlreadyForcedRefresh reports whether this node already triggered a forced refresh within the current cache timeout window and drops expired entries.
 func (c *cacheRobotClient) nodeHasAlreadyForcedRefresh(nodeName string) bool {
 	forcedAt, found := c.forcedRefreshServerNames[nodeName]
 	if !found {
@@ -128,6 +131,7 @@ func (c *cacheRobotClient) nodeHasAlreadyForcedRefresh(nodeName string) bool {
 	return true
 }
 
+// currentTime centralizes access to the clock so tests can inject a deterministic time source via c.now.
 func (c *cacheRobotClient) currentTime() time.Time {
 	if c.now == nil {
 		return time.Now()

internal/robot/cache_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/hetznercloud/hcloud-cloud-controller-manager/internal/mocks"
 )
 
+// TestCacheClientServerGetListForceRefreshSkipsRepeatedNameWithinTimeout verifies that repeated forced refreshes for the same node name reuse the cached result until the timeout expires.
 func TestCacheClientServerGetListForceRefreshSkipsRepeatedNameWithinTimeout(t *testing.T) {
 	now := time.Date(2026, time.April, 7, 13, 0, 0, 0, time.UTC)
 	mockClient := &mocks.RobotClient{}
@@ -36,6 +37,7 @@ func TestCacheClientServerGetListForceRefreshSkipsRepeatedNameWithinTimeout(t *t
 	mockClient.AssertNumberOfCalls(t, "ServerGetList", 1)
 }
 
+// TestCacheClientServerGetListForceRefreshExpiresPerName verifies that a node name can trigger another forced refresh after its timeout window has expired.
 func TestCacheClientServerGetListForceRefreshExpiresPerName(t *testing.T) {
 	now := time.Date(2026, time.April, 7, 13, 0, 0, 0, time.UTC)
 	mockClient := &mocks.RobotClient{}

internal/robot/ratelimit.go

@@ -44,6 +44,7 @@ func (c *rateLimitClient) ServerGetList() ([]hrobotmodels.Server, error) {
 	return servers, err
 }
 
+// ServerGetListForceRefresh applies the same rate-limit guard to forced refreshes before delegating to the wrapped client.
 func (c *rateLimitClient) ServerGetListForceRefresh(nodeName string) ([]hrobotmodels.Server, error) {
 	if c.isExceeded() {
 		return nil, c.getRateLimitError()