feat(auth): deduplicate concurrent refresh token requests with singleflight

- Introduced `singleflight.Group` to prevent redundant token refresh calls across multiple auth implementations (`antigravity`, `kimi`, `xai`, `codex`).
- Added tests to verify shared upstream calls during concurrent refresh requests.
- Refactored token refresh logic to centralize and standardize deduplication mechanisms.

Author: luispater

internal/auth/codex/openai_auth.go

@@ -17,6 +17,7 @@ import (
 	"github.com/router-for-me/CLIProxyAPI/v7/internal/config"
 	"github.com/router-for-me/CLIProxyAPI/v7/internal/util"
 	log "github.com/sirupsen/logrus"
+	"golang.org/x/sync/singleflight"
 )
 
 // OAuth configuration constants for OpenAI Codex
@@ -34,6 +35,8 @@ type CodexAuth struct {
 	httpClient *http.Client
 }
 
+var codexRefreshGroup singleflight.Group
+
 // NewCodexAuth creates a new CodexAuth service instance.
 // It initializes an HTTP client with proxy settings from the provided configuration.
 func NewCodexAuth(cfg *config.Config) *CodexAuth {
@@ -187,33 +190,52 @@ func (o *CodexAuth) RefreshTokens(ctx context.Context, refreshToken string) (*Co
 	if refreshToken == "" {
 		return nil, fmt.Errorf("refresh token is required")
 	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
 
+	result, err, _ := codexRefreshGroup.Do(refreshToken, func() (interface{}, error) {
+		return o.refreshTokensSingleFlight(context.WithoutCancel(ctx), refreshToken)
+	})
+	if err != nil {
+		return nil, err
+	}
+	tokenData, ok := result.(*CodexTokenData)
+	if !ok || tokenData == nil {
+		return nil, fmt.Errorf("token refresh failed: invalid single-flight result")
+	}
+	return tokenData, nil
+}
+
+func (o *CodexAuth) refreshTokensSingleFlight(ctx context.Context, refreshToken string) (*CodexTokenData, error) {
 	data := url.Values{
 		"client_id":     {ClientID},
 		"grant_type":    {"refresh_token"},
 		"refresh_token": {refreshToken},
 		"scope":         {"openid profile email"},
 	}
 
-	req, err := http.NewRequestWithContext(ctx, "POST", TokenURL, strings.NewReader(data.Encode()))
-	if err != nil {
-		return nil, fmt.Errorf("failed to create refresh request: %w", err)
+	req, errReq := http.NewRequestWithContext(ctx, "POST", TokenURL, strings.NewReader(data.Encode()))
+	if errReq != nil {
+		return nil, fmt.Errorf("failed to create refresh request: %w", errReq)
 	}
 
 	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
 	req.Header.Set("Accept", "application/json")
 
-	resp, err := o.httpClient.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("token refresh request failed: %w", err)
+	resp, errDo := o.httpClient.Do(req)
+	if errDo != nil {
+		return nil, fmt.Errorf("token refresh request failed: %w", errDo)
 	}
 	defer func() {
-		_ = resp.Body.Close()
+		if errClose := resp.Body.Close(); errClose != nil {
+			log.Errorf("token refresh response body close error: %v", errClose)
+		}
 	}()
 
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return nil, fmt.Errorf("failed to read refresh response: %w", err)
+	body, errRead := io.ReadAll(resp.Body)
+	if errRead != nil {
+		return nil, fmt.Errorf("failed to read refresh response: %w", errRead)
 	}
 
 	if resp.StatusCode != http.StatusOK {
@@ -228,14 +250,14 @@ func (o *CodexAuth) RefreshTokens(ctx context.Context, refreshToken string) (*Co
 		ExpiresIn    int    `json:"expires_in"`
 	}
 
-	if err = json.Unmarshal(body, &tokenResp); err != nil {
-		return nil, fmt.Errorf("failed to parse refresh response: %w", err)
+	if errUnmarshal := json.Unmarshal(body, &tokenResp); errUnmarshal != nil {
+		return nil, fmt.Errorf("failed to parse refresh response: %w", errUnmarshal)
 	}
 
 	// Extract account ID from ID token
-	claims, err := ParseJWTToken(tokenResp.IDToken)
-	if err != nil {
-		log.Warnf("Failed to parse refreshed ID token: %v", err)
+	claims, errParseJWT := ParseJWTToken(tokenResp.IDToken)
+	if errParseJWT != nil {
+		log.Warnf("Failed to parse refreshed ID token: %v", errParseJWT)
 	}
 
 	accountID := ""

internal/auth/codex/openai_auth_test.go

@@ -5,10 +5,13 @@ import (
 	"io"
 	"net/http"
 	"strings"
+	"sync"
 	"sync/atomic"
 	"testing"
+	"time"
 
 	"github.com/router-for-me/CLIProxyAPI/v7/internal/config"
+	"golang.org/x/sync/singleflight"
 )
 
 type roundTripFunc func(*http.Request) (*http.Response, error)
@@ -17,6 +20,10 @@ func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
 	return f(req)
 }
 
+func resetCodexRefreshGroupForTest() {
+	codexRefreshGroup = singleflight.Group{}
+}
+
 func TestRefreshTokensWithRetry_NonRetryableOnlyAttemptsOnce(t *testing.T) {
 	var calls int32
 	auth := &CodexAuth{
@@ -45,6 +52,71 @@ func TestRefreshTokensWithRetry_NonRetryableOnlyAttemptsOnce(t *testing.T) {
 	}
 }
 
+func TestRefreshTokens_DeduplicatesConcurrentRefreshAcrossInstances(t *testing.T) {
+	resetCodexRefreshGroupForTest()
+	t.Cleanup(resetCodexRefreshGroupForTest)
+
+	var calls int32
+	started := make(chan struct{})
+	release := make(chan struct{})
+	var once sync.Once
+
+	transport := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		atomic.AddInt32(&calls, 1)
+		once.Do(func() { close(started) })
+		<-release
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Body: io.NopCloser(strings.NewReader(`{
+				"access_token":"new-access",
+				"refresh_token":"new-refresh",
+				"token_type":"Bearer",
+				"expires_in":3600
+			}`)),
+			Header:  make(http.Header),
+			Request: req,
+		}, nil
+	})
+	authA := &CodexAuth{httpClient: &http.Client{Transport: transport}}
+	authB := &CodexAuth{httpClient: &http.Client{Transport: transport}}
+
+	results := make(chan *CodexTokenData, 2)
+	errs := make(chan error, 2)
+	runRefresh := func(auth *CodexAuth, launched chan<- struct{}) {
+		if launched != nil {
+			close(launched)
+		}
+		tokenData, errRefresh := auth.RefreshTokens(context.Background(), "shared-refresh-token")
+		results <- tokenData
+		errs <- errRefresh
+	}
+
+	go runRefresh(authA, nil)
+	<-started
+
+	secondLaunched := make(chan struct{})
+	go runRefresh(authB, secondLaunched)
+	<-secondLaunched
+	time.Sleep(20 * time.Millisecond)
+	if got := atomic.LoadInt32(&calls); got != 1 {
+		t.Fatalf("expected concurrent refresh to share a single upstream call, got %d", got)
+	}
+	close(release)
+
+	for i := 0; i < 2; i++ {
+		if errRefresh := <-errs; errRefresh != nil {
+			t.Fatalf("expected refresh to succeed, got %v", errRefresh)
+		}
+		tokenData := <-results
+		if tokenData == nil || tokenData.AccessToken != "new-access" || tokenData.RefreshToken != "new-refresh" {
+			t.Fatalf("unexpected token data: %#v", tokenData)
+		}
+	}
+	if got := atomic.LoadInt32(&calls); got != 1 {
+		t.Fatalf("expected both refresh callers to share a single upstream call, got %d", got)
+	}
+}
+
 func TestNewCodexAuthWithProxyURL_OverrideDirectDisablesProxy(t *testing.T) {
 	cfg := &config.Config{SDKConfig: config.SDKConfig{ProxyURL: "http://proxy.example.com:8080"}}
 	auth := NewCodexAuthWithProxyURL(cfg, "direct")

internal/auth/kimi/kimi.go

@@ -18,6 +18,7 @@ import (
 	"github.com/router-for-me/CLIProxyAPI/v7/internal/config"
 	"github.com/router-for-me/CLIProxyAPI/v7/internal/util"
 	log "github.com/sirupsen/logrus"
+	"golang.org/x/sync/singleflight"
 )
 
 const (
@@ -39,6 +40,8 @@ const (
 	refreshThresholdSeconds = 300
 )
 
+var kimiRefreshGroup singleflight.Group
+
 // KimiAuth handles Kimi authentication flow.
 type KimiAuth struct {
 	deviceClient *DeviceFlowClient
@@ -341,6 +344,28 @@ func (c *DeviceFlowClient) exchangeDeviceCode(ctx context.Context, deviceCode st
 
 // RefreshToken exchanges a refresh token for a new access token.
 func (c *DeviceFlowClient) RefreshToken(ctx context.Context, refreshToken string) (*KimiTokenData, error) {
+	if strings.TrimSpace(refreshToken) == "" {
+		return nil, fmt.Errorf("kimi: refresh token is required")
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	refreshToken = strings.TrimSpace(refreshToken)
+
+	result, err, _ := kimiRefreshGroup.Do(refreshToken, func() (interface{}, error) {
+		return c.refreshTokenSingleFlight(context.WithoutCancel(ctx), refreshToken)
+	})
+	if err != nil {
+		return nil, err
+	}
+	tokenData, ok := result.(*KimiTokenData)
+	if !ok || tokenData == nil {
+		return nil, fmt.Errorf("kimi: refresh token failed: invalid single-flight result")
+	}
+	return tokenData, nil
+}
+
+func (c *DeviceFlowClient) refreshTokenSingleFlight(ctx context.Context, refreshToken string) (*KimiTokenData, error) {
 	data := url.Values{}
 	data.Set("client_id", kimiClientID)
 	data.Set("grant_type", "refresh_token")

internal/auth/kimi/kimi_refresh_test.go

@@ -0,0 +1,89 @@
+package kimi
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"golang.org/x/sync/singleflight"
+)
+
+type kimiRoundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f kimiRoundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return f(req)
+}
+
+func resetKimiRefreshGroupForTest() {
+	kimiRefreshGroup = singleflight.Group{}
+}
+
+func TestRefreshToken_DeduplicatesConcurrentRefreshAcrossInstances(t *testing.T) {
+	resetKimiRefreshGroupForTest()
+	t.Cleanup(resetKimiRefreshGroupForTest)
+
+	var calls int32
+	started := make(chan struct{})
+	release := make(chan struct{})
+	var once sync.Once
+
+	transport := kimiRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		atomic.AddInt32(&calls, 1)
+		once.Do(func() { close(started) })
+		<-release
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Body: io.NopCloser(strings.NewReader(`{
+				"access_token":"new-access",
+				"refresh_token":"new-refresh",
+				"token_type":"Bearer",
+				"expires_in":3600
+			}`)),
+			Header:  make(http.Header),
+			Request: req,
+		}, nil
+	})
+	clientA := &DeviceFlowClient{httpClient: &http.Client{Transport: transport}}
+	clientB := &DeviceFlowClient{httpClient: &http.Client{Transport: transport}}
+
+	results := make(chan *KimiTokenData, 2)
+	errs := make(chan error, 2)
+	runRefresh := func(client *DeviceFlowClient, launched chan<- struct{}) {
+		if launched != nil {
+			close(launched)
+		}
+		tokenData, errRefresh := client.RefreshToken(context.Background(), "shared-refresh-token")
+		results <- tokenData
+		errs <- errRefresh
+	}
+
+	go runRefresh(clientA, nil)
+	<-started
+
+	secondLaunched := make(chan struct{})
+	go runRefresh(clientB, secondLaunched)
+	<-secondLaunched
+	time.Sleep(20 * time.Millisecond)
+	if got := atomic.LoadInt32(&calls); got != 1 {
+		t.Fatalf("expected concurrent refresh to share a single upstream call, got %d", got)
+	}
+	close(release)
+
+	for i := 0; i < 2; i++ {
+		if errRefresh := <-errs; errRefresh != nil {
+			t.Fatalf("expected refresh to succeed, got %v", errRefresh)
+		}
+		tokenData := <-results
+		if tokenData == nil || tokenData.AccessToken != "new-access" || tokenData.RefreshToken != "new-refresh" {
+			t.Fatalf("unexpected token data: %#v", tokenData)
+		}
+	}
+	if got := atomic.LoadInt32(&calls); got != 1 {
+		t.Fatalf("expected both refresh callers to share a single upstream call, got %d", got)
+	}
+}

internal/auth/xai/xai.go

@@ -14,13 +14,16 @@ import (
 	"github.com/router-for-me/CLIProxyAPI/v7/internal/config"
 	"github.com/router-for-me/CLIProxyAPI/v7/internal/util"
 	log "github.com/sirupsen/logrus"
+	"golang.org/x/sync/singleflight"
 )
 
 // XAIAuth performs xAI OAuth discovery, token exchange, and refresh.
 type XAIAuth struct {
 	httpClient *http.Client
 }
 
+var xaiRefreshGroup singleflight.Group
+
 // NewXAIAuth creates an xAI OAuth helper using config proxy settings.
 func NewXAIAuth(cfg *config.Config) *XAIAuth {
 	return NewXAIAuthWithProxyURL(cfg, "")
@@ -180,17 +183,37 @@ func (a *XAIAuth) RefreshTokens(ctx context.Context, refreshToken, tokenEndpoint
 	if strings.TrimSpace(refreshToken) == "" {
 		return nil, fmt.Errorf("xai token refresh: refresh token is required")
 	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	refreshToken = strings.TrimSpace(refreshToken)
 	if strings.TrimSpace(tokenEndpoint) == "" {
 		discovery, errDiscover := a.Discover(ctx)
 		if errDiscover != nil {
 			return nil, errDiscover
 		}
 		tokenEndpoint = discovery.TokenEndpoint
 	}
+	tokenEndpoint = strings.TrimSpace(tokenEndpoint)
+
+	result, err, _ := xaiRefreshGroup.Do(refreshToken, func() (interface{}, error) {
+		return a.refreshTokensSingleFlight(context.WithoutCancel(ctx), refreshToken, tokenEndpoint)
+	})
+	if err != nil {
+		return nil, err
+	}
+	tokenData, ok := result.(*TokenData)
+	if !ok || tokenData == nil {
+		return nil, fmt.Errorf("xai token refresh failed: invalid single-flight result")
+	}
+	return tokenData, nil
+}
+
+func (a *XAIAuth) refreshTokensSingleFlight(ctx context.Context, refreshToken, tokenEndpoint string) (*TokenData, error) {
 	form := url.Values{
 		"grant_type":    {"refresh_token"},
 		"client_id":     {ClientID},
-		"refresh_token": {strings.TrimSpace(refreshToken)},
+		"refresh_token": {refreshToken},
 	}
 	return a.postTokenForm(ctx, tokenEndpoint, form)
 }