Merge pull request #201 from scalarion/feature/token-refresh-callback

Feature/token refresh callback

Author: gonzolino

client.go

@@ -28,6 +28,17 @@ func newClient(ctx context.Context, config *oauth2.Config, token *oauth2.Token)
 	}
 }
 
+// newClientWithCallback creates a new tado° client with token refresh callback.
+// The callback will be invoked whenever the OAuth2 token is automatically refreshed.
+func newClientWithCallback(ctx context.Context, config *oauth2.Config, token *oauth2.Token, callback TokenRefreshCallback) *client {
+	tokenSrc := config.TokenSource(ctx, token)
+	callbackTokenSrc := NewCallbackTokenSource(tokenSrc, callback)
+
+	return &client{
+		http: oauth2.NewClient(ctx, callbackTokenSrc),
+	}
+}
+
 // WithHTTPClient configures the http client to use for tado° API interactions
 func (c *client) WithHTTPClient(httpClient *http.Client) *client {
 	c.http = httpClient

tado.go

@@ -33,6 +33,34 @@ func New(ctx context.Context, config *oauth2.Config, token *oauth2.Token) *Tado
 	}
 }
 
+// NewWithTokenRefreshCallback creates a new tado client with a callback
+// that is invoked whenever OAuth2 tokens are automatically refreshed.
+// This allows applications to persist refreshed tokens to storage.
+//
+// The tado° API uses refresh token rotation, meaning the old refresh token
+// is invalidated when a new one is issued. This makes it critical to save
+// refreshed tokens to prevent re-authentication.
+//
+// Example:
+//
+//	config := gotado.AuthConfig(clientID, "offline_access")
+//	token, _ := config.DeviceAccessToken(ctx, deviceAuth)
+//
+//	callback := func(newToken *oauth2.Token) {
+//	    log.Println("Token refreshed, saving to disk")
+//	}
+//
+//	tado := gotado.NewWithTokenRefreshCallback(ctx, config, token, callback)
+//
+// Note: The callback is called synchronously. If you need to perform
+// heavy processing, consider sending the token to a channel for
+// asynchronous handling.
+func NewWithTokenRefreshCallback(ctx context.Context, config *oauth2.Config, token *oauth2.Token, callback TokenRefreshCallback) *Tado {
+	return &Tado{
+		client: newClientWithCallback(ctx, config, token, callback),
+	}
+}
+
 // Me returns information about the authenticated user.
 func (t *Tado) Me(ctx context.Context) (*User, error) {
 	me := &User{client: t.client}

tokensource.go

@@ -0,0 +1,126 @@
+package gotado
+
+import (
+	"sync"
+
+	"golang.org/x/oauth2"
+)
+
+// TokenRefreshCallback is called whenever a token is automatically refreshed.
+// The callback receives the new token and should persist it to storage.
+//
+// The token passed to the callback contains the essential fields needed for
+// persistence (AccessToken, RefreshToken, TokenType, Expiry, ExpiresIn).
+// Extra fields stored via WithExtra() are intentionally not included to avoid
+// potential race conditions from sharing references to the original token's
+// internal data structures.
+//
+// IMPORTANT: The callback is called synchronously and should return quickly.
+// If heavy processing is needed, consider sending the token to a channel
+// or queue for asynchronous processing.
+type TokenRefreshCallback func(token *oauth2.Token)
+
+// callbackTokenSource wraps an oauth2.TokenSource and calls a callback
+// whenever Token() returns a different token than the previous call.
+// This is useful for persisting refreshed OAuth2 tokens to disk or other storage.
+type callbackTokenSource struct {
+	src       oauth2.TokenSource
+	callback  TokenRefreshCallback
+	mu        sync.Mutex
+	lastToken *oauth2.Token
+}
+
+// Token implements the oauth2.TokenSource interface.
+// It retrieves a token from the underlying source and invokes the callback
+// if the token has changed (either access token or refresh token is different).
+func (cts *callbackTokenSource) Token() (*oauth2.Token, error) {
+	cts.mu.Lock()
+	defer cts.mu.Unlock()
+
+	newToken, err := cts.src.Token()
+	if err != nil {
+		return nil, err
+	}
+
+	// Check if token has changed (different access token or refresh token)
+	// We check both because:
+	// - Access tokens expire frequently (every 10 minutes for tado°)
+	// - Refresh tokens may rotate (tado° uses refresh token rotation)
+	tokenChanged := false
+	if cts.lastToken == nil {
+		tokenChanged = true
+	} else {
+		// Compare access tokens
+		if cts.lastToken.AccessToken != newToken.AccessToken {
+			tokenChanged = true
+		}
+		// Compare refresh tokens (important for token rotation)
+		if cts.lastToken.RefreshToken != newToken.RefreshToken {
+			tokenChanged = true
+		}
+	}
+
+	// Update lastToken if token changed
+	if tokenChanged {
+		cts.lastToken = copyToken(newToken)
+
+		// Invoke callback if provided
+		if cts.callback != nil {
+			// Make a copy of the token to pass to the callback
+			// This prevents the callback from modifying the token
+			tokenCopy := copyToken(newToken)
+			cts.callback(tokenCopy)
+		}
+	}
+
+	return newToken, nil
+}
+
+// NewCallbackTokenSource creates a TokenSource that invokes the provided
+// callback whenever the underlying token is refreshed.
+//
+// This is particularly useful for the tado° API which:
+//   - Has short-lived access tokens (10 minutes)
+//   - Uses refresh token rotation (old refresh token is invalidated when new one is issued)
+//   - Requires offline_access scope for refresh tokens
+//
+// Example usage:
+//
+//	config := gotado.AuthConfig(clientID, "offline_access")
+//	token, _ := config.DeviceAccessToken(ctx, deviceAuth)
+//
+//	callback := func(newToken *oauth2.Token) {
+//	    // Save token to encrypted storage
+//	    log.Println("Token refreshed, saving to disk")
+//	    SaveTokenToFile(newToken)
+//	}
+//
+//	tado := gotado.NewWithTokenRefreshCallback(ctx, config, token, callback)
+func NewCallbackTokenSource(src oauth2.TokenSource, callback TokenRefreshCallback) oauth2.TokenSource {
+	return &callbackTokenSource{
+		src:      src,
+		callback: callback,
+	}
+}
+
+// copyToken creates a copy of an oauth2.Token.
+// This creates a new token with the same field values as the source token.
+//
+// Note: Extra fields stored via WithExtra() are intentionally not copied.
+// The purpose of the callback is to persist the access and refresh tokens
+// for later use. Extra fields are not needed for token storage and excluding
+// them avoids potential race conditions from sharing references to the
+// original token's internal data structures.
+func copyToken(src *oauth2.Token) *oauth2.Token {
+	if src == nil {
+		return nil
+	}
+
+	return &oauth2.Token{
+		AccessToken:  src.AccessToken,
+		TokenType:    src.TokenType,
+		RefreshToken: src.RefreshToken,
+		Expiry:       src.Expiry,
+		ExpiresIn:    src.ExpiresIn,
+	}
+}

tokensource_test.go

@@ -0,0 +1,110 @@
+package gotado
+
+import (
+	"testing"
+	"time"
+
+	"golang.org/x/oauth2"
+)
+
+func TestCopyToken(t *testing.T) {
+	t.Run("NilToken", func(t *testing.T) {
+		copied := copyToken(nil)
+		if copied != nil {
+			t.Error("Expected nil for nil input")
+		}
+	})
+
+	t.Run("BasicFields", func(t *testing.T) {
+		expiry := time.Now().Add(1 * time.Hour)
+		original := &oauth2.Token{
+			AccessToken:  "test_access_token",
+			TokenType:    "Bearer",
+			RefreshToken: "test_refresh_token",
+			Expiry:       expiry,
+		}
+
+		copied := copyToken(original)
+
+		// Verify it's a different object
+		if original == copied {
+			t.Error("Expected different pointer, got same object")
+		}
+
+		// Verify all fields are copied
+		if copied.AccessToken != original.AccessToken {
+			t.Errorf("AccessToken mismatch: got %v, want %v", copied.AccessToken, original.AccessToken)
+		}
+		if copied.TokenType != original.TokenType {
+			t.Errorf("TokenType mismatch: got %v, want %v", copied.TokenType, original.TokenType)
+		}
+		if copied.RefreshToken != original.RefreshToken {
+			t.Errorf("RefreshToken mismatch: got %v, want %v", copied.RefreshToken, original.RefreshToken)
+		}
+		if !copied.Expiry.Equal(original.Expiry) {
+			t.Errorf("Expiry mismatch: got %v, want %v", copied.Expiry, original.Expiry)
+		}
+	})
+
+	t.Run("ExpiresInField", func(t *testing.T) {
+		original := &oauth2.Token{
+			AccessToken: "test_access_token",
+			ExpiresIn:   600,
+		}
+
+		copied := copyToken(original)
+
+		if copied.ExpiresIn != original.ExpiresIn {
+			t.Errorf("ExpiresIn mismatch: got %v, want %v", copied.ExpiresIn, original.ExpiresIn)
+		}
+	})
+
+	t.Run("WithExtraFields", func(t *testing.T) {
+		extraMap := map[string]interface{}{
+			"scope":        "read write",
+			"custom_field": "custom_value",
+			"number":       float64(123),
+		}
+
+		original := (&oauth2.Token{
+			AccessToken:  "test_access_token",
+			TokenType:    "Bearer",
+			RefreshToken: "test_refresh_token",
+		}).WithExtra(extraMap)
+
+		copied := copyToken(original)
+
+		// Verify extra fields are NOT copied (limitation of simple copy)
+		if copied.Extra("scope") != nil {
+			t.Errorf("Extra 'scope' should be nil (not copied), got %v", copied.Extra("scope"))
+		}
+		if copied.Extra("custom_field") != nil {
+			t.Errorf("Extra 'custom_field' should be nil (not copied), got %v", copied.Extra("custom_field"))
+		}
+		if copied.Extra("number") != nil {
+			t.Errorf("Extra 'number' should be nil (not copied), got %v", copied.Extra("number"))
+		}
+	})
+
+	t.Run("IndependentCopy", func(t *testing.T) {
+		original := &oauth2.Token{
+			AccessToken:  "original_access",
+			TokenType:    "Bearer",
+			RefreshToken: "original_refresh",
+		}
+
+		copied := copyToken(original)
+
+		// Modify the original
+		original.AccessToken = "modified_access"
+		original.RefreshToken = "modified_refresh"
+
+		// Verify the copy is not affected
+		if copied.AccessToken != "original_access" {
+			t.Errorf("Copy was affected by original modification: got %v, want %v", copied.AccessToken, "original_access")
+		}
+		if copied.RefreshToken != "original_refresh" {
+			t.Errorf("Copy was affected by original modification: got %v, want %v", copied.RefreshToken, "original_refresh")
+		}
+	})
+}