feat(cache): cache the tenant model provider list in the daemon

[GareArc]

Description

Plugins assigned to a workspace from the enterprise admin console never appear in that workspace's model provider list (ESQ1-190, Zendesk #3547).

Dify caches the per-tenant model provider list in Redis, but enterprise installs plugins by calling this daemon directly, bypassing Dify's API. Dify therefore never learns its own cache is stale, and the newly assigned plugin stays invisible until the TTL expires. A cache is only correct if the system that owns the writes can invalidate it — so the cache moves here.

This is phase 3 of the plan. Phase 2 (langgenius/dify#39632) added flags to disable Dify's caches; this builds the daemon-side replacement so PLUGIN_MODEL_PROVIDERS_CACHE_ENABLED can be turned off.

What changed

• ListModels now reads through helper.CombinedListModelInstallations, mirroring the existing CombinedGetPluginDeclaration / DeletePluginDeclarationCache pair in combined.go.
• Storage is a Redis hash per tenant, field <page>:<pageSize>, so one DEL drops every cached page — no SCAN, no version counter.
• InstallPlugin / UninstallPlugin / UpgradePlugin invalidate it, guarded on the same declaration.Model != nil condition that already guards the AIModelInstallation row writes.
• The invalidation is deferred rather than run after the transaction. A retried install aborts on ErrPluginAlreadyInstalled before reaching any post-transaction code, so a DEL placed there becomes unreachable once it has failed once.
• TTL defaults to 60 minutes, configurable via PLUGIN_MODEL_INSTALLATIONS_CACHE_TTL. It is a safety net behind explicit invalidation, not the primary mechanism.

Separate first commit

parser.UnmarshalJson could never return a slice: validator.Struct rejects any non-struct top-level value, so it always errored before returning, which made cache.GetMapField[[]T] unusable. Slices now skip validation alongside maps and strings. UnmarshalJsonBytes2Slice remains the variant that validates per element.

Type of Change

• Bug fix
• New feature
• Refactor
• Performance improvement
• Other

Essential Checklist

Testing

• I have tested the changes locally and confirmed they work as expected
• I have added unit tests where necessary and they pass successfully

pkg/utils/cache/helper and pkg/utils/parser tests pass locally. The internal/types/models/curd tests require postgres and redis via TestMain, so they run in CI but were not executed locally.

Additional Information

The model schema cache has the same ownership defect but a much narrower blast radius, and it is not what #3547 reports. It moves in a follow-up: #781.

Known and deliberate here:

• cmd/commandline/plugin/cleanup.go deletes AIModelInstallation rows with no invalidation. It initialises only the DB, never Redis, so it cannot invalidate at all — after a manual cleanup run, deleted providers linger for up to the TTL. Consistent with how that CLI already bypasses every other daemon cache.
• Read-repopulate race: a reader holding pre-commit rows can write them back after the DEL. Bounded by the TTL. Same exposure as the existing declaration cache.
• Inert in production until the Dify-side flag is turned off.

[wylswz]

I suggest disabling this cache by default, otherwise the cache size is doubled, i.e., another scaling up needs to be scheduled before deploying to cloud production env.

[Copilot]

Pull request overview

This PR moves ownership of the per-tenant “model provider list” cache into the plugin daemon so enterprise-side installs/upgrades/uninstalls can deterministically invalidate cached model-provider listings, avoiding stale results in Dify’s UI when Dify’s own cache is bypassed.

Changes:

• Added a daemon-side Redis hash cache for tenant model-installation list pages and a helper to serve DB reads through that cache.
• Wired ListModels to use the new cached list helper, and invalidated the cache on install/uninstall/upgrade when model declarations are involved.
• Updated JSON parsing to skip entity validation for slice top-level values so cached []T values can round-trip via cache.GetMapField.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pkg/utils/parser/json.go	Allows unmarshalling slices without struct validation so cache.GetMapField[[]T] can work.
pkg/utils/cache/helper/model_installations.go	Implements tenant model-installation list cache (paged fields in a Redis hash) with TTL and invalidation helper.
pkg/utils/cache/helper/model_installations_test.go	Unit tests for cache hit behavior, page separation, and invalidation.
pkg/utils/cache/helper/keys.go	Adds a tenant-scoped cache key builder for model installations.
internal/types/models/curd/model_installations_cache_test.go	Validates model-installations cache invalidation behavior during install retry scenarios.
internal/types/models/curd/atomic.go	Invalidates the tenant model-installations cache during install/uninstall/upgrade when model declarations are present.
internal/types/app/default.go	Introduces a default config value for the model-installations cache TTL (minutes).
internal/types/app/config.go	Adds the PLUGIN_MODEL_INSTALLATIONS_CACHE_TTL config field.
internal/service/manage_plugin.go	Switches ListModels to use the cached helper-based listing.
internal/core/plugin_manager/manager.go	Applies configured TTL to the helper at daemon startup.
.env.example	Documents/exposes the new TTL environment variable.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dosubot]

📄 Knowledge review

✏️ Documentation updates

1 page was updated by changes in this PR.

Page	Library	Status
cache /dify-plugin-daemon/blob/main/docs/claude/cache.md	dify-plugin-sdks	✅ Updated

📝 cache — changes

@@ -98,6 +98,39 @@
 }
 ```
 
+## Model Installations Cache
+
+The daemon caches per-tenant model provider installation lists in Redis to reduce database queries. The cache is automatically invalidated when plugins with model providers are installed, upgraded, or uninstalled.
+
+### Cache Key Pattern
+
+`model_installations:tenant_id:{tenant_id}` - Redis hash map where each field represents a paginated query result (field format: `{page}:{page_size}`).
+
+### Configuration
+
+Two environment variables control this feature:
+
+- `PLUGIN_MODEL_INSTALLATIONS_CACHE_ENABLED` (default: false) - Enables the cache. Should only be enabled when Dify's own `PLUGIN_MODEL_PROVIDERS_CACHE_ENABLED` is false to avoid duplicating cached data in Redis.
+- `PLUGIN_MODEL_INSTALLATIONS_CACHE_TTL` (default: 1440 minutes / 24 hours) - How long cached data survives without explicit invalidation.
+
+### Helper Functions
+
+```go
+// Retrieves model installations from cache or DB, automatically populating cache on miss
+installations, err := helper.CombinedListModelInstallations(tenantId, page, pageSize)
+
+// Invalidates the entire cache for a tenant
+helper.DeleteModelInstallationsCache(tenantId)
+```
+
+### Automatic Invalidation
+
+The cache is automatically cleared when:
+
+- A plugin with model provider declaration is installed
+- A plugin with model provider declaration is uninstalled
+- A plugin is upgraded (if either old or new version has model provider declaration)
+
 ## Configuration
 
 Initialize Redis client in main:

---