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
This commit is contained in:
Luis Pater
2026-11-08 04:42:54 +08:00
parent 0e07108899
commit f69db99d5e
5 changed files with 244 additions and 28 deletions

View File

@@ -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/<id>` | 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/<id>/install` | POST | Install or update a plugin. |
| `/plugins/<id>/quota` | GET, POST, DELETE | Read, fetch, or reset plugin quota. |

View File

@@ -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)
}

View File

@@ -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
}
}
}
}

View File

@@ -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)
}
}

View File

@@ -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()