Update documentation to the higher standards.

metadata_cache.go

@@ -15,6 +15,8 @@ type MetadataCache struct {
 	stopCleanup         chan struct{}
 }
 
+// NewMetadataCache creates a new MetadataCache instance.
+// It initializes the cache structure and starts the background cleanup goroutine.
 func NewMetadataCache() *MetadataCache {
 	c := &MetadataCache{
 		autoCleanupInterval: 5 * time.Minute,
@@ -24,7 +26,8 @@ func NewMetadataCache() *MetadataCache {
 	return c
 }
 
-// Cleanup removes expired metadata from the cache.
+// Cleanup removes the cached provider metadata if it has expired.
+// This is called periodically by the auto-cleanup goroutine.
 func (c *MetadataCache) Cleanup() {
 	c.mutex.Lock()
 	defer c.mutex.Unlock()
@@ -35,11 +38,31 @@ func (c *MetadataCache) Cleanup() {
 	}
 }
 
+// isCacheValid checks if the cached metadata is present and has not expired.
+// Note: This function assumes the read lock is held or it's called from a context
+// where the lock is already held (like within GetMetadata after locking).
 func (c *MetadataCache) isCacheValid() bool {
 	return c.metadata != nil && time.Now().Before(c.expiresAt)
 }
 
-// GetMetadata retrieves the metadata from cache or fetches it if expired
+// GetMetadata retrieves the OIDC provider metadata.
+// It first checks the cache for valid, non-expired metadata. If found, it's returned immediately.
+// If the cache is empty or expired, it attempts to fetch the metadata from the provider's
+// well-known endpoint using discoverProviderMetadata.
+// If fetching is successful, the new metadata is cached for 1 hour.
+// If fetching fails but valid metadata exists in the cache (even if expired), the cache expiry
+// is extended by 5 minutes, and the cached data is returned to prevent thundering herd issues.
+// If fetching fails and there's no cached data, an error is returned.
+// It employs double-checked locking for thread safety and performance.
+//
+// Parameters:
+//   - providerURL: The base URL of the OIDC provider.
+//   - httpClient: The HTTP client to use for fetching metadata.
+//   - logger: The logger instance for recording errors or warnings.
+//
+// Returns:
+//   - A pointer to the ProviderMetadata struct.
+//   - An error if metadata cannot be retrieved from cache or fetched from the provider.
 func (c *MetadataCache) GetMetadata(providerURL string, httpClient *http.Client, logger *Logger) (*ProviderMetadata, error) {
 	c.mutex.RLock()
 	if c.isCacheValid() {
@@ -76,10 +99,13 @@ func (c *MetadataCache) GetMetadata(providerURL string, httpClient *http.Client,
 	return metadata, nil
 }
 
+// startAutoCleanup starts the background goroutine that periodically calls Cleanup
+// to remove expired metadata from the cache.
 func (c *MetadataCache) startAutoCleanup() {
 	autoCleanupRoutine(c.autoCleanupInterval, c.stopCleanup, c.Cleanup)
 }
 
+// Close stops the automatic cleanup goroutine associated with this metadata cache.
 func (c *MetadataCache) Close() {
 	close(c.stopCleanup)
 }