From f69db99d5ebb9f0a68ea2e6741257968eb27536d Mon Sep 17 00:00:00 2001 From: Luis Pater Date: Sun, 8 Nov 2026 04:42:54 +0800 Subject: [PATCH] feat(plugin-store): support opt-in release cache refresh on store listing - Accept refresh=true or refresh=1 on the plugin store listing endpoint to bypass the 1-hour latest-release cache TTL for installed plugins. - Track last check timestamps on release cache entries with a 10-second per-key refresh floor while preserving GitHub rate-limit cooldowns and in-flight coalescing. - Add unit tests and update v8 management API documentation for the refresh query parameter. Closes: #7333 --- docs/management-api-v8.md | 2 +- .../api/handlers/management/plugin_store.go | 10 +- .../management/plugin_store_release.go | 36 ++-- .../management/plugin_store_release_test.go | 155 ++++++++++++++++-- .../handlers/management/plugin_store_test.go | 69 ++++++++ 5 files changed, 244 insertions(+), 28 deletions(-) diff --git a/docs/management-api-v8.md b/docs/management-api-v8.md index f91304442d..790e70add7 100644 --- a/docs/management-api-v8.md +++ b/docs/management-api-v8.md @@ -114,7 +114,7 @@ retain the corresponding business operation's fields. | `/oauth/callback` | GET, POST | Submit an OAuth callback. | | `/plugins` | GET | List installed plugins. | | `/plugins/` | DELETE | Delete a plugin. | -| `/plugins/store` | GET | List the plugin store. | +| `/plugins/store` | GET | List the plugin store (supports optional `?refresh=true` to bypass cached release checks). | | `/plugins/store//install` | POST | Install or update a plugin. | | `/plugins//quota` | GET, POST, DELETE | Read, fetch, or reset plugin quota. | diff --git a/internal/api/handlers/management/plugin_store.go b/internal/api/handlers/management/plugin_store.go index ec2470f80f..c9295f0c51 100644 --- a/internal/api/handlers/management/plugin_store.go +++ b/internal/api/handlers/management/plugin_store.go @@ -158,7 +158,7 @@ func (h *Handler) ListPluginStore(c *gin.Context) { } } client := h.newPluginStoreClient(proxyURL, "", storeAuth) - latestVersions := h.latestPluginVersions(c.Request.Context(), client, latestInput) + latestVersions := h.latestPluginVersions(c.Request.Context(), client, latestInput, pluginStoreForceRefresh(c)) entries := make([]pluginStoreListEntry, 0, len(plugins)) for index, item := range plugins { @@ -220,6 +220,14 @@ func (h *Handler) ListPluginStore(c *gin.Context) { }) } +func pluginStoreForceRefresh(c *gin.Context) bool { + if c == nil { + return false + } + refresh := strings.TrimSpace(c.Query("refresh")) + return strings.EqualFold(refresh, "true") || refresh == "1" +} + func (h *Handler) InstallPluginFromStore(c *gin.Context) { h.installPluginFromStore(c, runtime.GOOS, runtime.GOARCH) } diff --git a/internal/api/handlers/management/plugin_store_release.go b/internal/api/handlers/management/plugin_store_release.go index 1e64dcf05a..62e0546523 100644 --- a/internal/api/handlers/management/plugin_store_release.go +++ b/internal/api/handlers/management/plugin_store_release.go @@ -13,11 +13,13 @@ import ( const ( pluginReleaseCacheTTL = time.Hour pluginReleaseFailureCacheTTL = 30 * time.Second + pluginReleaseRefreshFloor = 10 * time.Second pluginReleaseConcurrency = 2 ) type pluginReleaseCacheEntry struct { version string + checkedAt time.Time nextCheckAt time.Time } @@ -64,7 +66,7 @@ func (cache *pluginReleaseCache) cached(client pluginstore.Client, plugin plugin } // latestPluginVersions preserves catalog order, including skipped placeholders. -func (h *Handler) latestPluginVersions(ctx context.Context, client pluginstore.Client, plugins []pluginstore.Plugin) []string { +func (h *Handler) latestPluginVersions(ctx context.Context, client pluginstore.Client, plugins []pluginstore.Plugin, force bool) []string { versions := make([]string, len(plugins)) var wg sync.WaitGroup for index, plugin := range plugins { @@ -74,14 +76,14 @@ func (h *Handler) latestPluginVersions(ctx context.Context, client pluginstore.C wg.Add(1) go func(index int) { defer wg.Done() - versions[index] = h.latestPluginVersion(ctx, client, plugins[index]) + versions[index] = h.latestPluginVersion(ctx, client, plugins[index], force) }(index) } wg.Wait() return versions } -func (h *Handler) latestPluginVersion(ctx context.Context, client pluginstore.Client, plugin pluginstore.Plugin) string { +func (h *Handler) latestPluginVersion(ctx context.Context, client pluginstore.Client, plugin pluginstore.Plugin, force bool) string { if pluginstore.PluginInstallType(plugin) != pluginstore.InstallTypeGitHubRelease { return "" } @@ -95,7 +97,12 @@ func (h *Handler) latestPluginVersion(ctx context.Context, client pluginstore.Cl for { cache.mu.Lock() entry = cache.entries[key] - if cache.now().Before(entry.nextCheckAt) || ctx.Err() != nil { + now := cache.now() + fresh := now.Before(entry.nextCheckAt) + if force { + fresh = !entry.checkedAt.IsZero() && now.Before(entry.checkedAt.Add(pluginReleaseRefreshFloor)) + } + if fresh || ctx.Err() != nil { cache.mu.Unlock() return entry.version } @@ -137,18 +144,21 @@ func (h *Handler) latestPluginVersion(ctx context.Context, client pluginstore.Cl version, errRelease = pluginstore.ReleaseVersion(release) } if ctx.Err() == nil { - ttl := pluginReleaseFailureCacheTTL - if errRelease != nil { - log.WithError(errRelease).WithField("plugin_id", plugin.ID).Warn("pluginstore: failed to fetch latest release") - } else { - entry.version = version - ttl = pluginReleaseCacheTTL - } // Start the TTL when the lookup finishes, not when it was queued. - entry.nextCheckAt = cache.now().Add(ttl) + now := cache.now() + entry.checkedAt = now var rateLimit *pluginstore.RateLimitError - if errors.As(errRelease, &rateLimit) { + if errRelease == nil { + entry.version = version + entry.nextCheckAt = now.Add(pluginReleaseCacheTTL) + } else if errors.As(errRelease, &rateLimit) { + log.WithError(errRelease).WithField("plugin_id", plugin.ID).Warn("pluginstore: failed to fetch latest release") entry.nextCheckAt = rateLimit.RetryAt + } else { + log.WithError(errRelease).WithField("plugin_id", plugin.ID).Warn("pluginstore: failed to fetch latest release") + if next := now.Add(pluginReleaseFailureCacheTTL); next.After(entry.nextCheckAt) { + entry.nextCheckAt = next + } } } } diff --git a/internal/api/handlers/management/plugin_store_release_test.go b/internal/api/handlers/management/plugin_store_release_test.go index 82bf26250e..d0ea54ea84 100644 --- a/internal/api/handlers/management/plugin_store_release_test.go +++ b/internal/api/handlers/management/plugin_store_release_test.go @@ -134,7 +134,7 @@ func TestPluginReleaseCacheRetainsSuccessAndUsesCompletionTime(t *testing.T) { })} check := func(want string, wantCalls int) { t.Helper() - if got := h.latestPluginVersion(context.Background(), client, plugin); got != want || calls != wantCalls { + if got := h.latestPluginVersion(context.Background(), client, plugin, false); got != want || calls != wantCalls { t.Fatalf("version=%q calls=%d, want %q/%d", got, calls, want, wantCalls) } } @@ -176,11 +176,11 @@ func TestPluginReleaseCacheCoalescesConcurrentLookups(t *testing.T) { h := &Handler{} plugin := pluginstore.Plugin{Repository: "https://github.com/test/plugin"} results := make(chan string, 21) - go func() { results <- h.latestPluginVersion(context.Background(), client, plugin) }() + go func() { results <- h.latestPluginVersion(context.Background(), client, plugin, false) }() <-started for range 20 { ctx := &pluginReleaseWaitContext{Context: context.Background(), waiting: make(chan struct{})} - go func() { results <- h.latestPluginVersion(ctx, client, plugin) }() + go func() { results <- h.latestPluginVersion(ctx, client, plugin, false) }() <-ctx.waiting } close(release) @@ -211,11 +211,11 @@ func TestPluginReleaseCacheCanceledLeaderHandsOffToFollower(t *testing.T) { ctx, cancel := context.WithCancel(context.Background()) defer cancel() leaderResult := make(chan string, 1) - go func() { leaderResult <- h.latestPluginVersion(ctx, client, plugin) }() + go func() { leaderResult <- h.latestPluginVersion(ctx, client, plugin, false) }() <-started waitCtx := &pluginReleaseWaitContext{Context: context.Background(), waiting: make(chan struct{})} followerResult := make(chan string, 1) - go func() { followerResult <- h.latestPluginVersion(waitCtx, client, plugin) }() + go func() { followerResult <- h.latestPluginVersion(waitCtx, client, plugin, false) }() <-waitCtx.waiting cancel() if got := <-leaderResult; got != "" { @@ -237,13 +237,13 @@ func TestPluginReleaseCacheCanceledFollowerDoesNotCancelLeader(t *testing.T) { h := &Handler{} plugin := pluginstore.Plugin{Repository: "https://github.com/test/plugin"} leaderResult := make(chan string, 1) - go func() { leaderResult <- h.latestPluginVersion(context.Background(), client, plugin) }() + go func() { leaderResult <- h.latestPluginVersion(context.Background(), client, plugin, false) }() <-started ctx, cancel := context.WithCancel(context.Background()) defer cancel() waitCtx := &pluginReleaseWaitContext{Context: ctx, waiting: make(chan struct{})} followerResult := make(chan string, 1) - go func() { followerResult <- h.latestPluginVersion(waitCtx, client, plugin) }() + go func() { followerResult <- h.latestPluginVersion(waitCtx, client, plugin, false) }() <-waitCtx.waiting cancel() if got := <-followerResult; got != "" { @@ -269,7 +269,7 @@ func TestPluginReleaseCacheSharesConcurrencyAndCancelsQueuedLookup(t *testing.T) results := make(chan string, pluginReleaseConcurrency) for index := range pluginReleaseConcurrency { go func() { - results <- h.latestPluginVersion(context.Background(), client, pluginstore.Plugin{Repository: fmt.Sprintf("https://github.com/test/plugin-%d", index)}) + results <- h.latestPluginVersion(context.Background(), client, pluginstore.Plugin{Repository: fmt.Sprintf("https://github.com/test/plugin-%d", index)}, false) }() } for range pluginReleaseConcurrency { @@ -280,7 +280,7 @@ func TestPluginReleaseCacheSharesConcurrencyAndCancelsQueuedLookup(t *testing.T) waitCtx := &pluginReleaseWaitContext{Context: ctx, waiting: make(chan struct{})} queuedResult := make(chan string, 1) plugin := pluginstore.Plugin{Repository: "https://github.com/test/queued"} - go func() { queuedResult <- h.latestPluginVersion(waitCtx, client, plugin) }() + go func() { queuedResult <- h.latestPluginVersion(waitCtx, client, plugin, false) }() <-waitCtx.waiting cancel() if got := <-queuedResult; got != "" || calls.Load() != pluginReleaseConcurrency { @@ -290,7 +290,7 @@ func TestPluginReleaseCacheSharesConcurrencyAndCancelsQueuedLookup(t *testing.T) for range pluginReleaseConcurrency { <-results } - if got := h.latestPluginVersion(context.Background(), client, plugin); got != "1.0.0" || calls.Load() != pluginReleaseConcurrency+1 { + if got := h.latestPluginVersion(context.Background(), client, plugin, false); got != "1.0.0" || calls.Load() != pluginReleaseConcurrency+1 { t.Fatalf("canceled lookup was negatively cached: version=%q calls=%d", got, calls.Load()) } } @@ -310,7 +310,7 @@ func TestPluginReleaseCacheSeparatesCredentialsAndEgress(t *testing.T) { client.ResolvedAuth = []pluginstore.ResolvedAuthConfig{{Match: "https://api.github.com/", Type: pluginstore.AuthTypeGitHubToken, Token: pluginstore.Secret(token)}} client.ResolvedAuthExpiresAt = time.Now().Add(time.Hour) } - if got := h.latestPluginVersion(context.Background(), client, plugin); got != "1.0.0" { + if got := h.latestPluginVersion(context.Background(), client, plugin, false); got != "1.0.0" { t.Fatalf("version = %q", got) } } @@ -318,7 +318,7 @@ func TestPluginReleaseCacheSeparatesCredentialsAndEgress(t *testing.T) { t.Fatalf("calls = %d, want 3", calls.Load()) } client.NetworkScope = "other-proxy" - h.latestPluginVersion(context.Background(), client, plugin) + h.latestPluginVersion(context.Background(), client, plugin, false) if calls.Load() != 4 { t.Fatalf("calls after proxy change = %d, want 4", calls.Load()) } @@ -352,7 +352,7 @@ func TestPluginReleaseChecksStopQueuedRequestsDuringCooldown(t *testing.T) { h.pluginReleases.entries[pluginReleaseKey(client, plugins[index])] = pluginReleaseCacheEntry{version: "1.0.0"} } result := make(chan []string, 1) - go func() { result <- h.latestPluginVersions(context.Background(), client, plugins) }() + go func() { result <- h.latestPluginVersions(context.Background(), client, plugins, false) }() for range pluginReleaseConcurrency { <-started } @@ -463,3 +463,132 @@ func TestListPluginStoreUsesCachedUninstalledVersionWithoutRefresh(t *testing.T) t.Fatalf("plugins=%#v requests=%v", body.Plugins, httpClient.counts) } } + +func listPluginStoreWithQueryForTest(t *testing.T, h *Handler, query string) pluginStoreListResponse { + t.Helper() + rec := httptest.NewRecorder() + c, _ := gin.CreateTestContext(rec) + c.Request = httptest.NewRequest(http.MethodGet, "/v8/management/plugins/store"+query, nil) + h.ListPluginStore(c) + if rec.Code != http.StatusOK { + t.Fatalf("status = %d; body=%s", rec.Code, rec.Body.String()) + } + var body pluginStoreListResponse + if errDecode := json.Unmarshal(rec.Body.Bytes(), &body); errDecode != nil { + t.Fatal(errDecode) + } + return body +} + +func TestListPluginStoreRefreshBypassesCacheWithFloor(t *testing.T) { + t.Parallel() + now := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) + releaseTag := "v0.1.0" + var releaseCalls int + h := &Handler{ + cfg: &config.Config{Plugins: config.PluginsConfig{ + Dir: writeManagementPluginFile(t, "sample-provider-v0.1.0"), + }}, + pluginReleases: pluginReleaseCache{nowFunc: func() time.Time { return now }}, + pluginStoreHTTPClient: pluginReleaseDoerFunc(func(req *http.Request) (*http.Response, error) { + if req.URL.Host != "api.github.com" { + return fakePluginStoreHTTPClient{pluginstore.DefaultRegistryURL: registryJSON(t)}.Do(req) + } + releaseCalls++ + return pluginReleaseResponse(releaseTag), nil + }), + } + + body := listPluginStoreWithQueryForTest(t, h, "") + if body.Plugins[0].Version != "0.1.0" || body.Plugins[0].UpdateAvailable || releaseCalls != 1 { + t.Fatalf("initial entry=%#v releaseCalls=%d", body.Plugins[0], releaseCalls) + } + + releaseTag = "v0.2.0" + now = now.Add(time.Minute) + body = listPluginStoreWithQueryForTest(t, h, "") + if body.Plugins[0].Version != "0.1.0" || body.Plugins[0].UpdateAvailable || releaseCalls != 1 { + t.Fatalf("cached entry=%#v releaseCalls=%d, want cached 0.1.0 without network call", body.Plugins[0], releaseCalls) + } + + body = listPluginStoreWithQueryForTest(t, h, "?refresh=true") + if body.Plugins[0].Version != "0.2.0" || !body.Plugins[0].UpdateAvailable || releaseCalls != 2 { + t.Fatalf("refreshed entry=%#v releaseCalls=%d, want 0.2.0 with update_available=true and 2 calls", body.Plugins[0], releaseCalls) + } + + releaseTag = "v0.3.0" + now = now.Add(5 * time.Second) + body = listPluginStoreWithQueryForTest(t, h, "?refresh=true") + if body.Plugins[0].Version != "0.2.0" || releaseCalls != 2 { + t.Fatalf("floor-throttled entry=%#v releaseCalls=%d, want 0.2.0 and 2 calls within 10s floor", body.Plugins[0], releaseCalls) + } + + now = now.Add(5 * time.Second) + body = listPluginStoreWithQueryForTest(t, h, "?refresh=1") + if body.Plugins[0].Version != "0.3.0" || !body.Plugins[0].UpdateAvailable || releaseCalls != 3 { + t.Fatalf("refresh=1 entry=%#v releaseCalls=%d, want 0.3.0 and 3 calls after 10s floor", body.Plugins[0], releaseCalls) + } +} + +func TestListPluginStoreRefreshPreservesRateLimiterAndSkipsUninstalled(t *testing.T) { + t.Parallel() + now := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) + reset := time.Now().Add(time.Hour).Truncate(time.Second) + registry := pluginstore.Registry{ + SchemaVersion: pluginstore.SchemaVersion, + Plugins: []pluginstore.Plugin{ + { + ID: "installed-plugin", Name: "Installed", Description: "Installed plugin", Author: "owner", + Version: "0.1.0", Repository: "https://github.com/owner/installed-plugin", + }, + { + ID: "uninstalled-plugin", Name: "Uninstalled", Description: "Uninstalled plugin", Author: "owner", + Version: "0.1.0", Repository: "https://github.com/owner/uninstalled-plugin", + }, + }, + } + registryBytes, errMarshal := json.Marshal(registry) + if errMarshal != nil { + t.Fatal(errMarshal) + } + var releaseCalls int + rateLimited := false + h := &Handler{ + cfg: &config.Config{Plugins: config.PluginsConfig{ + Dir: writeManagementPluginFile(t, "installed-plugin-v0.1.0"), + }}, + pluginReleases: pluginReleaseCache{nowFunc: func() time.Time { return now }}, + pluginStoreRateLimiter: &pluginstore.GitHubRateLimiter{}, + pluginStoreHTTPClient: pluginReleaseDoerFunc(func(req *http.Request) (*http.Response, error) { + if req.URL.Host != "api.github.com" { + return fakePluginStoreHTTPClient{pluginstore.DefaultRegistryURL: registryBytes}.Do(req) + } + releaseCalls++ + if !rateLimited { + return pluginReleaseResponse("v0.2.0"), nil + } + headers := make(http.Header) + headers.Set("X-RateLimit-Remaining", "0") + headers.Set("X-RateLimit-Reset", strconv.FormatInt(reset.Unix(), 10)) + return &http.Response{StatusCode: http.StatusForbidden, Header: headers, Body: io.NopCloser(strings.NewReader("limited"))}, nil + }), + } + + body := listPluginStoreWithQueryForTest(t, h, "?refresh=true") + if body.Plugins[0].Version != "0.2.0" || body.Plugins[1].Version != "0.1.0" || releaseCalls != 1 { + t.Fatalf("first refresh plugins=%#v releaseCalls=%d, want installed=0.2.0 uninstalled=0.1.0 calls=1", body.Plugins, releaseCalls) + } + + rateLimited = true + now = now.Add(time.Minute) + body = listPluginStoreWithQueryForTest(t, h, "?refresh=true") + if body.Plugins[0].Version != "0.2.0" || releaseCalls != 2 { + t.Fatalf("rate-limited refresh plugins=%#v releaseCalls=%d, want cached 0.2.0 and 2 calls", body.Plugins, releaseCalls) + } + + now = now.Add(time.Minute) + body = listPluginStoreWithQueryForTest(t, h, "?refresh=true") + if body.Plugins[0].Version != "0.2.0" || releaseCalls != 2 { + t.Fatalf("cooldown refresh plugins=%#v releaseCalls=%d, want rate limiter to block network call during cooldown", body.Plugins, releaseCalls) + } +} diff --git a/internal/api/handlers/management/plugin_store_test.go b/internal/api/handlers/management/plugin_store_test.go index 4669b73935..18b7a613ca 100644 --- a/internal/api/handlers/management/plugin_store_test.go +++ b/internal/api/handlers/management/plugin_store_test.go @@ -16,6 +16,7 @@ import ( "strings" "sync" "testing" + "time" "github.com/gin-gonic/gin" "github.com/router-for-me/CLIProxyAPI/v8/internal/config" @@ -402,6 +403,74 @@ func TestListPluginStoreShowsLatestReleaseVersionAndCaches(t *testing.T) { } } +func TestListPluginStoreRefreshQueryBypassesCache(t *testing.T) { + t.Parallel() + + now := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) + httpClient := &countingPluginStoreHTTPClient{responses: fakePluginStoreHTTPClient{ + "https://registry.example/registry.json": registryJSON(t), + "https://api.github.com/repos/author-name/cliproxy-sample-provider-plugin/releases/latest": []byte(`{ + "tag_name": "v0.1.0", + "assets": [] + }`), + }} + h := &Handler{ + cfg: &config.Config{ + Plugins: config.PluginsConfig{ + Enabled: true, + Dir: writeManagementPluginFile(t, "sample-provider-v0.1.0"), + }, + }, + configFilePath: writeTestConfigFile(t), + pluginStoreRegistryURL: "https://registry.example/registry.json", + pluginStoreHTTPClient: httpClient, + pluginReleases: pluginReleaseCache{nowFunc: func() time.Time { return now }}, + } + + listWithQuery := func(query string) pluginStoreListResponse { + t.Helper() + rec := httptest.NewRecorder() + c, _ := gin.CreateTestContext(rec) + c.Request = httptest.NewRequest(http.MethodGet, "/v8/management/plugins/store"+query, nil) + h.ListPluginStore(c) + if rec.Code != http.StatusOK { + t.Fatalf("status = %d, want %d; body=%s", rec.Code, http.StatusOK, rec.Body.String()) + } + var body pluginStoreListResponse + if errDecode := json.Unmarshal(rec.Body.Bytes(), &body); errDecode != nil { + t.Fatalf("Unmarshal() error = %v; body=%s", errDecode, rec.Body.String()) + } + return body + } + + body := listWithQuery("") + if body.Plugins[0].Version != "0.1.0" || body.Plugins[0].UpdateAvailable { + t.Fatalf("initial plugin = %#v, want 0.1.0 without update", body.Plugins[0]) + } + + httpClient.mu.Lock() + httpClient.responses["https://api.github.com/repos/author-name/cliproxy-sample-provider-plugin/releases/latest"] = []byte(`{ + "tag_name": "v0.2.0", + "assets": [] + }`) + httpClient.mu.Unlock() + + now = now.Add(pluginReleaseRefreshFloor) + body = listWithQuery("?refresh=false") + if body.Plugins[0].Version != "0.1.0" || body.Plugins[0].UpdateAvailable { + t.Fatalf("refresh=false plugin = %#v, want cached 0.1.0", body.Plugins[0]) + } + + body = listWithQuery("?refresh=true") + if body.Plugins[0].Version != "0.2.0" || !body.Plugins[0].UpdateAvailable { + t.Fatalf("refresh=true plugin = %#v, want refreshed 0.2.0 with update_available=true", body.Plugins[0]) + } + releaseCalls := httpClient.count("https://api.github.com/repos/author-name/cliproxy-sample-provider-plugin/releases/latest") + if releaseCalls != 2 { + t.Fatalf("latest release fetched %d times, want 2", releaseCalls) + } +} + func TestListPluginStoreFallsBackToRegistryVersion(t *testing.T) { t.Parallel()