Guide

Cache

A serverless cache that works with any cache client and over HTTP. Connect with any cache client, call it over HTTP from anywhere, or use it from a function as env.CACHE.

Create#

Create

cloudhost cache create sessions --memory 128
# created cache sessions (128 MB, eviction on)
#   url:    rediss://default:<token>@sessions.cache.trustpage.ir:6379
#   rest:   https://sessions.cache.trustpage.ir
#   token (shown once): chc_…

Memory is 32, 64 (default), 128 or 256 MB. With eviction (default) old keys go when memory is full; with --no-eviction writes fail instead. An idle cache stops and keeps its data.

Cache clients#

redis-cli --tls -h sessions.cache.trustpage.ir -p 6379 -a $TOKEN
> SET greeting salam
> INCR visits

Port 6379, user default, and a token as the password. Any cache client works.

REST#

curl https://sessions.cache.trustpage.ir \
  -H "Authorization: Bearer $TOKEN" \
  -d '["INCR", "visits"]'
# {"result":1}

Each command is a JSON array sent with POST. /pipeline runs several (up to 1,000) and /multi-exec runs them as one transaction. Good for places with no TCP connections.

Tokens#

Tokens

cloudhost cache tokens sessions               # list
cloudhost cache tokens sessions create --ro   # a read-only token, shown once
cloudhost cache tokens sessions revoke 7e5926b6f29c

Each cache starts with a read-write token named default. Make a read-only token for reports or anything that should only read. Tokens are not rotated: make a new one and revoke the old.

env.CACHE in functions#

type Env = {
  CACHE: {
    get(key: string): Promise<string | null>;
    set(key: string, value: string, opts?: { ex?: number }): Promise<unknown>;
    del(...keys: string[]): Promise<number>;
    incr(key: string): Promise<number>;
    command(args: string[]): Promise<unknown>;
    pipeline(commands: string[][]): Promise<unknown[]>;
  };
};

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const visits = await env.CACHE.incr("visits");
    await env.CACHE.set("last", new Date().toISOString(), { ex: 3600 });
    return Response.json({ visits, hash: await env.CACHE.command(["HGETALL", "settings"]) });
  },
};

The function reads the cache as env.CACHE, with no token. command runs any cache command and pipeline several.

Durability, size and checkpoints#

A write is acknowledged once it is stored durably, so no acknowledged write is lost when a server fails, and the cache opens on another server with the same data. Data may be larger than memory: memory (max_memory_mb) holds the hot data and cold keys are read from storage. Your plan sets the stored-size limit (max_storage_mb); when it is full, writes fail until you raise it or delete keys.

Size

cloudhost cache limits                       # the sizes on your plan
cloudhost cache create sessions --max-storage 1024
cloudhost cache update sessions --max-storage 5120
cloudhost cache stats sessions               # keys, hit rate, stored size of the limit

Checkpoints are kept 7 to 30 days by plan. You can take one now and restore one: over the same cache, which replaces all its data, or with --to into a new cache on the same plan, whose token is shown once.

Checkpoints

cloudhost cache checkpoints sessions
cloudhost cache checkpoint sessions
cloudhost cache restore sessions <checkpoint> --to sessions-copy
cloudhost cache restore sessions <checkpoint>   # replaces its data; asks first

Restoring over the same cache is sensitive: from the dashboard it asks for a second factor. An idle cache is stopped and costs only its storage, per GB-month.

Run a command from the CLI#

run

cloudhost cache run sessions SET greeting salam
cloudhost cache run sessions GET greeting
# salam

cache run runs with your team's credential, not a cache token; so do the dashboard's console and the MCP tool run_cache_command. Commands like DEL and FLUSHDB change data.

cloudhost cache delete sessions deletes the cache with its data; it is refused while a live version binds it.