Understanding the Cache Package in CasaOS: In-Memory Storage for Performance

The pkg/cache package provides a thread-safe, in-process key-value store that eliminates redundant disk I/O and system calls by caching frequently accessed data such as CPU thermal zones and version strings.

The CasaOS home server operating system relies on the pkg/cache package to minimize expensive recomputation and external requests. This lightweight wrapper around github.com/patrickmn/go-cache creates a centralized, in-memory storage mechanism accessible throughout the service layer. By default, cached entries expire after five minutes with automatic cleanup occurring every minute.

How the Cache Package Works in CasaOS

Cache Initialization and Configuration

In pkg/cache/cache.go, the Init() function instantiates a go-cache instance with a 5-minute default expiration and a 1-minute cleanup interval. This configuration strikes a balance between data freshness and memory efficiency for a home server environment.

Global Access Pattern

The cache becomes globally available during application startup. In main.go, the initialization call service.Cache = cache.Init() assigns the instance to the exported Cache variable declared in service/service.go. This pattern allows any service component to import the service package and interact with the cache without passing references through multiple layers.

Key Use Cases in the CasaOS Codebase

Caching CPU Thermal Zone Paths

Determining the Linux sysfs path for CPU temperature requires scanning system directories, an operation performed in service/system.go. The GetCPUThermalZone function stores the discovered path under the key cpu_thermal_zone using service.Cache.SetDefault(), preventing repeated filesystem traversal on subsequent calls.

Storing System Version Strings

The casa_version key caches the system-wide version string to support health checks and UI components. When the system updates, the UpdateSystemVersion function in service/system.go (lines 73-76) explicitly calls service.Cache.Delete("casa_version") to invalidate stale version data.

General Service-Level Caching

Various services throughout service/*.go utilize Cache.Set, Cache.Get, and Cache.Delete for transient data that does not require persistent disk storage, such as temporary user settings or intermediate computation results.

Implementation Details and Code Examples

The following patterns demonstrate how to interact with the CasaOS cache layer.

Initialize the cache during application startup:

import "github.com/IceWhaleTech/CasaOS/pkg/cache"

func init() {
    // Global cache used by the service layer
    service.Cache = cache.Init()
}

Store values with default expiration:

func cacheCPUPath(path string) {
    const key = "cpu_thermal_zone"
    // Uses the 5-minute expiration defined in cache.Init()
    service.Cache.SetDefault(key, path)
}

Retrieve cached values safely:

func getCachedCPUPath() (string, bool) {
    const key = "cpu_thermal_zone"
    if v, ok := service.Cache.Get(key); ok {
        return v.(string), true
    }
    return "", false
}

Delete entries when data becomes stale:

func clearVersionCache() {
    const key = "casa_version"
    service.Cache.Delete(key)
}

Summary

• The pkg/cache package wraps github.com/patrickmn/go-cache to provide a centralized in-memory store with 5-minute expiration and 1-minute cleanup intervals.
• Initialization occurs in main.go via service.Cache = cache.Init(), making the cache globally accessible through the service package.
• Critical system data like CPU thermal zone paths and version strings are cached in service/system.go to avoid redundant filesystem operations.
• The thread-safe implementation supports concurrent access across multiple services without additional synchronization logic.

Frequently Asked Questions

What is the default expiration time for cached items in CasaOS?

The default expiration is 5 minutes, configured in the Init() function within pkg/cache/cache.go. The underlying library automatically removes expired entries during a cleanup interval of 1 minute.

How does CasaOS handle cache invalidation when system data changes?

Explicit invalidation occurs through the Delete method. For example, service/system.go calls service.Cache.Delete("casa_version") inside UpdateSystemVersion to ensure the version string is refreshed immediately after a system update.

Is the CasaOS cache package thread-safe for concurrent access?

Yes, the cache package is thread-safe. It wraps go-cache, which implements internal locking mechanisms. Multiple services can safely call Get, Set, and Delete operations concurrently without additional synchronization.

Where is the cache instance stored and accessed in the CasaOS architecture?

The singleton instance is stored in the global service.Cache variable declared in service/service.go. This variable is initialized in main.go and imported by service components such as service/system.go to store and retrieve transient data.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}