Cache

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

Cache providers use the same provider-entry plus app SDK binding pattern as IndexedDB.

Configuring `providers.cache`


providers:
  cache:
    session:
      source:
        package: github.com/your-org/gestalt-cache-provider
        version: 0.0.1
      config:
        namespace: session
 
    rate_limit:
      source:
        package: github.com/your-org/gestalt-cache-provider
        version: 0.0.1
      config:
        namespace: rate_limit
 
apps:
  search:
    source: ./providers/search/manifest.yaml
    cache:
      - session
      - rate_limit

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

Using `Cache` from a plugin

Go


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

Python


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

Rust


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?;

TypeScript


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. App code does not choose backend endpoints directly at runtime. It just opens the bound cache by name.

Building your own cache provider

Manifest

A cache provider manifest declares kind: cache:


kind: cache
source: github.com/your-org/gestalt-cache-provider
version: 0.0.1
displayName: Example Cache
description: Cache provider backed by your cache service.
spec:
  configSchemaPath: ./cache_config.json

Go


package examplecache
 
import (
    "context"
    "time"
 
    gestalt "github.com/valon-technologies/gestalt/sdk/go"
)
 
type ExampleCache struct{}
 
func New() *ExampleCache { return &ExampleCache{} }
 
func (p *ExampleCache) Get(ctx context.Context, key string) ([]byte, bool, error) {
    panic("implement cache get")
}
 
func (p *ExampleCache) GetMany(ctx context.Context, keys []string) (map[string][]byte, error) {
    panic("implement cache get many")
}
 
func (p *ExampleCache) Set(ctx context.Context, key string, value []byte, opts gestalt.CacheSetOptions) error {
    panic("implement cache set")
}
 
func (p *ExampleCache) SetMany(ctx context.Context, entries []gestalt.CacheEntry, opts gestalt.CacheSetOptions) error {
    panic("implement cache set many")
}
 
func (p *ExampleCache) Delete(ctx context.Context, key string) (bool, error) {
    panic("implement cache delete")
}
 
func (p *ExampleCache) DeleteMany(ctx context.Context, keys []string) (int64, error) {
    panic("implement cache delete many")
}
 
func (p *ExampleCache) Touch(ctx context.Context, key string, ttl time.Duration) (bool, error) {
    panic("implement cache touch")
}

Python


import datetime as dt
 
from gestalt import CacheEntry, CacheProvider
 
class ExampleCache(CacheProvider):
    def get(self, key: str) -> bytes | None:
        """Read a value by key."""
        raise NotImplementedError
 
    def get_many(self, keys: list[str]) -> dict[str, bytes]:
        """Read multiple keys in one request."""
        raise NotImplementedError
 
    def set(
        self,
        key: str,
        value: bytes,
        ttl: dt.timedelta | None = None,
    ) -> None:
        """Write a value with an optional TTL."""
        raise NotImplementedError
 
    def set_many(
        self,
        entries: list[CacheEntry],
        ttl: dt.timedelta | None = None,
    ) -> None:
        """Write multiple values with one TTL policy."""
        raise NotImplementedError
 
    def delete(self, key: str) -> bool:
        """Remove one key."""
        raise NotImplementedError
 
    def delete_many(self, keys: list[str]) -> int:
        """Remove multiple keys."""
        raise NotImplementedError
 
    def touch(self, key: str, ttl: dt.timedelta) -> bool:
        """Refresh TTL for an existing key."""
        raise NotImplementedError

Rust


#[derive(Default)]
struct ExampleCache;
 
#[gestalt::async_trait]
impl gestalt::CacheProvider for ExampleCache {
    async fn get(&self, key: &str) -> gestalt::Result<Option<Vec<u8>>> {
        todo!("read a value by key")
    }
 
    async fn get_many(
        &self,
        keys: &[String],
    ) -> gestalt::Result<std::collections::BTreeMap<String, Vec<u8>>> {
        todo!("read multiple keys in one request")
    }
 
    async fn set(
        &self,
        key: &str,
        value: &[u8],
        options: gestalt::CacheSetOptions,
    ) -> gestalt::Result<()> {
        todo!("write a value with an optional TTL")
    }
 
    async fn set_many(
        &self,
        entries: &[gestalt::CacheEntry],
        options: gestalt::CacheSetOptions,
    ) -> gestalt::Result<()> {
        todo!("write multiple values with one TTL policy")
    }
 
    async fn delete(&self, key: &str) -> gestalt::Result<bool> {
        todo!("remove one key")
    }
 
    async fn delete_many(&self, keys: &[String]) -> gestalt::Result<i64> {
        todo!("remove multiple keys")
    }
 
    async fn touch(&self, key: &str, ttl: std::time::Duration) -> gestalt::Result<bool> {
        todo!("refresh TTL for an existing key")
    }
}
 
gestalt::export_cache_provider!(constructor = ExampleCache::default);

TypeScript


import { defineCacheProvider } from "@valon-technologies/gestalt";
 
export const cache = defineCacheProvider({
  async get(key) {
    throw new Error("read a value by key");
  },
 
  async getMany(keys) {
    throw new Error("read multiple keys in one request");
  },
 
  async set(key, value, options) {
    throw new Error("write a value with an optional TTL");
  },
 
  async setMany(entries, options) {
    throw new Error("write multiple values with one TTL policy");
  },
 
  async delete(key) {
    throw new Error("remove one key");
  },
 
  async deleteMany(keys) {
    throw new Error("remove multiple keys");
  },
 
  async touch(key, ttlMs) {
    throw new Error("refresh TTL for an existing key");
  },
});

Release flow

For packaging, lock/sync, and release behavior, see Releasing provider packages.

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.

Cache

Configuring providers.cache

Using Cache from a plugin

Go

Python

Rust

TypeScript

Building your own cache provider

Manifest

Go

Python

Rust

TypeScript

Release flow

What to read next

Configuring `providers.cache`

Using `Cache` from a plugin