Address PR review comments

- Reduce token expiry buffer from 5 minutes to 30 seconds (matches SDK standard)
- Add detailed documentation to TokenProviderAuthenticator explaining flow
- Add ctx.Err() check in ExternalTokenProvider for cancellation support
- Rename tokenFunc to tokenSource for better clarity
- Remove duplicate empty token validation from ExternalTokenProvider
- Update tests to reflect changes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: madhav-db

auth/tokenprovider/authenticator.go

@@ -9,7 +9,16 @@ import (
 	"github.com/rs/zerolog/log"
 )
 
-// TokenProviderAuthenticator implements auth.Authenticator using a TokenProvider
+// TokenProviderAuthenticator implements auth.Authenticator using a TokenProvider.
+//
+// Authentication Flow:
+// 1. On each Authenticate() call, retrieves a token from the configured TokenProvider
+// 2. The provider may implement its own caching and refresh logic
+// 3. Validates the returned token is non-empty
+// 4. Sets the Authorization header with the token type and value
+//
+// The authenticator delegates all token management (caching, refresh, expiry)
+// to the underlying TokenProvider implementation.
 type TokenProviderAuthenticator struct {
 	provider TokenProvider
 }

auth/tokenprovider/external.go

@@ -6,41 +6,43 @@ import (
 	"time"
 )
 
-// ExternalTokenProvider provides tokens from an external source (passthrough)
+// ExternalTokenProvider provides tokens from an external source (passthrough).
+// This provider calls a user-supplied function to retrieve tokens on-demand.
 type ExternalTokenProvider struct {
-	tokenFunc func() (string, error)
-	tokenType string
+	tokenSource func() (string, error)
+	tokenType   string
 }
 
 // NewExternalTokenProvider creates a provider that gets tokens from an external function
-func NewExternalTokenProvider(tokenFunc func() (string, error)) *ExternalTokenProvider {
+func NewExternalTokenProvider(tokenSource func() (string, error)) *ExternalTokenProvider {
 	return &ExternalTokenProvider{
-		tokenFunc: tokenFunc,
-		tokenType: "Bearer",
+		tokenSource: tokenSource,
+		tokenType:   "Bearer",
 	}
 }
 
 // NewExternalTokenProviderWithType creates a provider with a custom token type
-func NewExternalTokenProviderWithType(tokenFunc func() (string, error), tokenType string) *ExternalTokenProvider {
+func NewExternalTokenProviderWithType(tokenSource func() (string, error), tokenType string) *ExternalTokenProvider {
 	return &ExternalTokenProvider{
-		tokenFunc: tokenFunc,
-		tokenType: tokenType,
+		tokenSource: tokenSource,
+		tokenType:   tokenType,
 	}
 }
 
 // GetToken retrieves the token from the external source
 func (p *ExternalTokenProvider) GetToken(ctx context.Context) (*Token, error) {
-	if p.tokenFunc == nil {
-		return nil, fmt.Errorf("external token provider: token function is nil")
+	// Check for cancellation first
+	if err := ctx.Err(); err != nil {
+		return nil, fmt.Errorf("external token provider: context cancelled: %w", err)
 	}
 
-	accessToken, err := p.tokenFunc()
-	if err != nil {
-		return nil, fmt.Errorf("external token provider: failed to get token: %w", err)
+	if p.tokenSource == nil {
+		return nil, fmt.Errorf("external token provider: token source is nil")
 	}
 
-	if accessToken == "" {
-		return nil, fmt.Errorf("external token provider: empty token returned")
+	accessToken, err := p.tokenSource()
+	if err != nil {
+		return nil, fmt.Errorf("external token provider: failed to get token: %w", err)
 	}
 
 	return &Token{

auth/tokenprovider/provider.go

@@ -29,8 +29,9 @@ func (t *Token) IsExpired() bool {
 	if t.ExpiresAt.IsZero() {
 		return false // No expiry means token doesn't expire
 	}
-	// Consider token expired 5 minutes before actual expiry for safety
-	return time.Now().Add(5 * time.Minute).After(t.ExpiresAt)
+	// Consider token expired 30 seconds before actual expiry for safety
+	// This matches the standard buffer used by other Databricks SDKs
+	return time.Now().Add(30 * time.Second).After(t.ExpiresAt)
 }
 
 // SetAuthHeader sets the Authorization header on an HTTP request

auth/tokenprovider/provider_test.go

@@ -42,12 +42,12 @@ func TestToken_IsExpired(t *testing.T) {
 			expected: false,
 		},
 		{
-			name: "token_expires_within_5_minutes",
+			name: "token_expires_within_30_seconds",
 			token: &Token{
 				AccessToken: "test-token",
-				ExpiresAt:   time.Now().Add(3 * time.Minute),
+				ExpiresAt:   time.Now().Add(15 * time.Second),
 			},
-			expected: true, // Should be considered expired due to 5-minute buffer
+			expected: true, // Should be considered expired due to 30-second buffer
 		},
 	}
 
@@ -171,17 +171,18 @@ func TestExternalTokenProvider(t *testing.T) {
 		assert.Contains(t, err.Error(), "failed to get token")
 	})
 
-	t.Run("empty_token_error", func(t *testing.T) {
+	t.Run("empty_token_allowed", func(t *testing.T) {
 		tokenFunc := func() (string, error) {
 			return "", nil
 		}
 
 		provider := NewExternalTokenProvider(tokenFunc)
 		token, err := provider.GetToken(context.Background())
 
-		assert.Error(t, err)
-		assert.Nil(t, token)
-		assert.Contains(t, err.Error(), "empty token returned")
+		assert.NoError(t, err)
+		assert.NotNil(t, token)
+		assert.Empty(t, token.AccessToken)
+		// Empty tokens are validated at the authenticator level, not provider level
 	})
 
 	t.Run("nil_function_error", func(t *testing.T) {
@@ -190,7 +191,7 @@ func TestExternalTokenProvider(t *testing.T) {
 
 		assert.Error(t, err)
 		assert.Nil(t, token)
-		assert.Contains(t, err.Error(), "token function is nil")
+		assert.Contains(t, err.Error(), "token source is nil")
 	})
 
 	t.Run("custom_token_type", func(t *testing.T) {