Cache

Cache providers are plugin-bound utilities for short-lived key/value state. They are configured under providers.cache and attached to plugins with plugins.<name>.cache.

Unlike IndexedDB, cache providers are not selected through server.providers. They are only exposed to plugins that request them.

How cache providers work

Each entry under providers.cache defines a named cache backend. Plugins opt into those backends with plugins.<name>.cache, which is just a list of named bindings. Every binding name must already exist under providers.cache, and duplicate bindings are rejected during config validation.

In plugin code you usually open a cache by binding name, such as session or rate_limit. If a plugin binds exactly one cache, the SDKs also support the default unnamed cache handle, but using the explicit binding name is usually clearer.

First-party cache providers

First-party cache providers live under valon-technologies/gestalt-providers/cache.

Configuring providers.cache

providers:
  cache:
    session:
      source: https://artifacts.example.com/cache/valkey/v0.0.1-alpha.1/provider-release.yaml
      config:
        address: ${VALKEY_ADDR}
        database: 0
 
    rate_limit:
      source: https://artifacts.example.com/cache/valkey/v0.0.1-alpha.1/provider-release.yaml
      config:
        address: ${VALKEY_ADDR}
        database: 1
 
plugins:
  search:
    source: ./providers/search/manifest.yaml
    cache:
      - session
      - rate_limit

This example binds two caches into the search plugin. Both bindings use the same provider package, but they point at different logical databases. That is a common pattern for keeping session and rate-limit state separate without introducing a second cache technology.

Using Cache from a plugin

import (
    "context"
    "log"
    "time"
 
    gestalt "github.com/valon-technologies/gestalt/sdk/go"
)
 
ctx := context.Background()
 
cache, err := gestalt.Cache("session")
if err != nil {
    log.Fatal(err)
}
defer cache.Close()
 
if err := cache.Set(ctx, "user:1", []byte("alpha"), gestalt.CacheSetOptions{
    TTL: 5 * time.Minute,
}); err != nil {
    log.Fatal(err)
}
 
value, found, err := cache.Get(ctx, "user:1")
if err != nil {
    log.Fatal(err)
}
_ = value
_ = found

import datetime as dt
import gestalt
 
cache = gestalt.Cache("session")
cache.set("user:1", b"alpha", ttl=dt.timedelta(minutes=5))
value = cache.get("user:1") or b""
cache.close()

use std::time::Duration;
 
use gestalt::{Cache, CacheSetOptions};
 
let mut cache = Cache::connect_named("session").await?;
cache
    .set(
        "user:1",
        b"alpha",
        CacheSetOptions {
            ttl: Some(Duration::from_secs(5 * 60)),
        },
    )
    .await?;
let value = cache.get("user:1").await?;

import { Cache } from "@valon-technologies/gestalt";
 
const cache = new Cache("session");
await cache.set("user:1", new TextEncoder().encode("alpha"), {
  ttlMs: 5 * 60 * 1000,
});
const value = await cache.get("user:1");

The host resolves the configured cache bindings and exposes them to the plugin through the language SDK. Plugin code does not choose raw Redis or Valkey endpoints directly at runtime. It just opens the bound cache by name.

Operational notes

Cache providers are best for short-lived, non-authoritative state such as sessions, idempotency helpers, and rate-limit counters. They remain plugin-bound, so they do not participate in the host-wide server.providers selection model. The exact config block depends on the selected provider package. For the first-party cache/valkey provider, that usually means an address plus any backend-specific connection settings.

Building your own cache provider

For manifests, SDK authoring surfaces, and release flow, see Custom Providers > Cache.

What to read next

If you want the full config reference, read Config File. For plugin-side binding behavior in the broader config model, see Configuration. If you need implementation details, continue to Custom Providers > Cache.