Celerity Cache

celerity/cache

Spec Version: v2026-02-27-draft Ecosystem Compatibility: v0 (Current) / v1 (Preview)

blueprint transform: celerity-2026-02-27-draft

The celerity/cache resource type defines an in-memory cache for a Celerity application. Celerity supports Redis OSS-compatible in-memory databases and abstracts the difference between single-instance and cluster topologies.

For Celerity applications, using a cache provides:

• Low-latency data access: In-memory caches provide sub-millisecond read and write latency for frequently accessed data.
• Reduced database load: Caching query results, session data or computed values reduces the load on your primary data stores.
• Session management: Caches are commonly used for managing user sessions, rate limiting and temporary state.
• Topology abstraction: Celerity abstracts the difference between single-instance and cluster mode Redis deployments, allowing you to switch between them without application code changes.

Specification

The specification is the structure of the resource definition that comes under the spec field of the resource in a blueprint. The rest of this section lists fields that are available to configure the celerity/cache resource followed by examples of different configurations for the resource and how the cache behaves in target environments along with additional documentation.

name

A unique name to use for the cache. If a name is not provided, a unique name will be generated based on the blueprint that the cache is defined in.

type

string

clusterMode

Whether to deploy the cache as a cluster with multiple shards and replicas, or as a single instance.

Cluster mode provides higher availability and throughput by distributing data across multiple shards. Single-instance mode is simpler and more cost-effective for development and smaller workloads.

The Celerity SDK cache abstraction handles the difference between single-instance and cluster mode connections transparently — your application code does not need to change when switching modes.

✅ Available in v0

type

boolean

default value

false

engineVersion

The Valkey engine version to use for the cache. Valkey is fully compatible with Redis OSS clients.

✅ Available in v0

type

string

default value

8.2

authMode

The authentication method used to connect to the cache at runtime. This determines how handlers obtain credentials when connecting to the cache.

✅ Available in v0 (AWS) / 🚀 Planned for v1 (Google Cloud, Azure)

type

string

allowed values

password | iam

default value

password

Annotations

There are no annotations required for linking other resources to a celerity/cache resource or modifying the behaviour of a cache resource.

linkSelector.byLabel can be used to target caches from other resource types.

Outputs

Outputs are computed values that are accessible via the {resourceName}.spec.* field accessor in a blueprint substitution. For example, if the resource name is sessionCache, the output would be accessible via ${sessionCache.spec.id}.

id

The ID of the created cache in the target environment.

type

string

examples

arn:aws:elasticache:us-east-1:123456789012:replicationgroup:session-cache (AWS)

projects/my-project/locations/us-central1/instances/session-cache (Google Cloud)

/subscriptions/.../resourceGroups/.../providers/Microsoft.Cache/redis/session-cache (Azure)

host

The primary endpoint for the cache. For cluster mode, this is the configuration endpoint.

type

string

port

The port number for the cache connection.

type

number

default value

6379

Data Types

The celerity/cache resource type does not define custom data types in the blueprint specification. Cache data is stored as Redis-compatible key-value pairs using the Redis data type system (strings, lists, sets, sorted sets, hashes, streams).

Linked From

celerity/handler

When a handler links to a cache, the handler will be configured with permissions and environment variables (or secret store entries) that enable it to connect to the cache. The Celerity SDK provides a thin cache abstraction for common cache operations and a credentials provider for direct Redis client access.

✅ Available in v0

Read more about Celerity handlers

celerity/vpc

When a VPC links to a cache, the cache will be placed within the VPC's private subnets. Caches require VPC placement for secure network access.

✅ Available in v0

Read more about Celerity VPCs

Links To

The celerity/cache resource type does not link to other resources.

Examples

Minimal Cache

version: 2025-11-02
transform: celerity-2026-02-27-draft
resources:
    sessionCache:
        type: "celerity/cache"
        metadata:
            displayName: "Session Cache"
        spec:
            name: "sessions"

Cache with VPC and Handler Link

version: 2025-11-02
transform: celerity-2026-02-27-draft
resources:
    appVpc:
        type: "celerity/vpc"
        metadata:
            displayName: "Application VPC"
            labels:
                application: "myapp"
        linkSelector:
            byLabel:
                application: "myapp"
        spec:
            preset: "standard"

    sessionCache:
        type: "celerity/cache"
        metadata:
            displayName: "Session Cache"
            labels:
                application: "myapp"
        spec:
            name: "sessions"

    getSessionHandler:
        type: "celerity/handler"
        metadata:
            displayName: "Get Session"
            labels:
                application: "myapp"
            annotations:
                celerity.handler.http: true
                celerity.handler.http.method: "GET"
                celerity.handler.http.path: "/session"
        linkSelector:
            byLabel:
                application: "myapp"
        spec:
            handler: "handlers.getSession"
            runtime: "nodejs24.x"

    api:
        type: "celerity/api"
        metadata:
            displayName: "API"
            labels:
                application: "myapp"
        linkSelector:
            byLabel:
                application: "myapp"
        spec:
            type: "http"

Cluster Mode Cache

version: 2025-11-02
transform: celerity-2026-02-27-draft
resources:
    productCache:
        type: "celerity/cache"
        metadata:
            displayName: "Product Cache"
            labels:
                application: "catalog"
        spec:
            name: "products"
            clusterMode: true
            engineVersion: "7.1"

Cache with IAM Authentication

✅ Available in v0

version: 2025-11-02
transform: celerity-2026-02-27-draft
resources:
    sessionCache:
        type: "celerity/cache"
        metadata:
            displayName: "Session Cache"
            labels:
                application: "myapp"
        spec:
            name: "sessions"
            authMode: "iam"
            clusterMode: true

When authMode is set to "iam", handlers that link to this cache are automatically granted the IAM permissions required for token-based cache authentication on the target cloud provider. The SDK generates short-lived tokens at runtime — no static passwords are stored or rotated.

Target Environments

Local Development

✅ Available in v0

In the local development environment, caches are backed by a Valkey instance. The same Valkey instance is shared across cache resources and config stores in the local development environment, with namespace isolation to prevent key collisions.

When celerity dev run starts, cache resources are automatically available and connection configuration is injected into your handlers.

AWS

✅ Available in v0

In the AWS environment, caches are backed by Amazon ElastiCache for Redis.

Single Instance Mode

A single ElastiCache replication group with one primary node. Suitable for development, staging and workloads that do not require high availability.

Cluster Mode

An ElastiCache replication group with cluster mode enabled, distributing data across multiple shards with automatic failover. Suitable for production workloads requiring high availability and throughput.

Networking

Caches are placed within the VPC's private subnets when linked to a celerity/vpc resource. Security groups are configured to allow traffic from Lambda functions (or ECS/EKS tasks) to the cache port.

The app deploy configuration can be used to configure the cache with Amazon ElastiCache specific settings such as node type, number of replicas and encryption.

IAM Authentication

✅ Available in v0

When authMode is set to "iam", Celerity enables IAM Authentication on the ElastiCache replication group. An IAM-enabled ElastiCache user is created with the appropriate access string, and the handler's execution role (Lambda or ECS task role) is granted the elasticache:Connect permission scoped to the cache resource and user. The SDK generates short-lived authentication tokens via SigV4 presigned requests at runtime instead of using a static AUTH token.

IAM authentication is supported for both single-instance and cluster mode configurations. Transit encryption (TLS) is automatically enabled when using IAM authentication.

Google Cloud

🚀 Planned for v1 - The Google Cloud deployment target is planned for v1, it may become available in a future v0 evolution.

Caches will be provisioned using Google Cloud Memorystore for Valkey.

When authMode is set to "iam", Celerity enables IAM Authentication on the Memorystore instance. The handler's service account is granted the necessary Memorystore IAM roles. The SDK uses OAuth2 access tokens for authentication at runtime.

Azure

🚀 Planned for v1 - The Azure deployment target is planned for v1, it may become available in a future v0 evolution.

Caches will be provisioned using Azure Cache for Redis.

When authMode is set to "iam", Celerity enables Entra ID Authentication on the Azure Cache for Redis instance. The handler's managed identity is granted cache access, and the SDK fetches access tokens from Entra ID at runtime.

App Deploy Configuration

Configuration specific to a target environment can be defined for celerity/cache resources in the app deploy configuration file.

This section lists the configuration options that can be set in the deployTarget.config object in the app deploy configuration file.

AWS Configuration Options

✅ Available in v0

aws.elasticache.<cacheName>.nodeType

The ElastiCache node type to use for the cache. This determines the compute and memory capacity of each cache node. cacheName is the name (key) of the cache resource in the blueprint.

Deploy Targets

aws, aws-serverless

type

string

default value

cache.t3.micro

examples

{
    "deployTarget": {
        "name": "aws-serverless",
        "appEnv": "production",
        "config": {
            "aws.elasticache.sessionCache.nodeType": "cache.r6g.large"
        }
    }
}

aws.elasticache.<cacheName>.numReplicas

The number of read replicas per shard. In single-instance mode, this creates replicas of the primary node. In cluster mode, this creates replicas per shard. cacheName is the name (key) of the cache resource in the blueprint.

Deploy Targets

aws, aws-serverless

type

number

default value

0 (single-instance mode) / 1 (cluster mode)

examples

{
    "deployTarget": {
        "name": "aws-serverless",
        "appEnv": "production",
        "config": {
            "aws.elasticache.sessionCache.numReplicas": 2
        }
    }
}

aws.elasticache.<cacheName>.numShards

The number of shards in the cluster. Only applicable when clusterMode is true. cacheName is the name (key) of the cache resource in the blueprint.

Deploy Targets

aws, aws-serverless

type

number

default value

3

examples

{
    "deployTarget": {
        "name": "aws-serverless",
        "appEnv": "production",
        "config": {
            "aws.elasticache.sessionCache.numShards": 3
        }
    }
}

aws.elasticache.<cacheName>.automaticFailover

Whether to enable automatic failover for the replication group. Requires at least one replica. Automatically enabled when clusterMode is true. cacheName is the name (key) of the cache resource in the blueprint.

Deploy Targets

aws, aws-serverless

type

boolean

default value

false (single-instance mode) / true (cluster mode)

examples

{
    "deployTarget": {
        "name": "aws-serverless",
        "appEnv": "production",
        "config": {
            "aws.elasticache.sessionCache.automaticFailover": true
        }
    }
}

aws.elasticache.<cacheName>.transitEncryption

Whether to enable encryption in transit (TLS) for the cache. cacheName is the name (key) of the cache resource in the blueprint.

Deploy Targets

aws, aws-serverless

type

boolean

default value

true

examples

{
    "deployTarget": {
        "name": "aws-serverless",
        "appEnv": "production",
        "config": {
            "aws.elasticache.sessionCache.transitEncryption": true
        }
    }
}

aws.elasticache.<cacheName>.atRestEncryption

Whether to enable encryption at rest for the cache. cacheName is the name (key) of the cache resource in the blueprint.

Deploy Targets

aws, aws-serverless

type

boolean

default value

true

examples

{
    "deployTarget": {
        "name": "aws-serverless",
        "appEnv": "production",
        "config": {
            "aws.elasticache.sessionCache.atRestEncryption": true
        }
    }
}

aws.elasticache.<cacheName>.snapshotRetentionDays

The number of days to retain automatic snapshots (backups) of the cache. Set to 0 to disable automatic snapshots. cacheName is the name (key) of the cache resource in the blueprint.

Deploy Targets

aws, aws-serverless

type

number

default value

0

examples

{
    "deployTarget": {
        "name": "aws-serverless",
        "appEnv": "production",
        "config": {
            "aws.elasticache.sessionCache.snapshotRetentionDays": 7
        }
    }
}

aws.elasticache.<cacheName>.evictionPolicy

The eviction policy to use when the cache reaches its memory limit. This maps to the Redis maxmemory-policy configuration parameter. cacheName is the name (key) of the cache resource in the blueprint.

Deploy Targets

aws, aws-serverless

type

string

allowed values

allkeys-lru, allkeys-lfu, allkeys-random, volatile-lru, volatile-lfu, volatile-random, volatile-ttl, noeviction

default value

allkeys-lru

examples

{
    "deployTarget": {
        "name": "aws-serverless",
        "appEnv": "production",
        "config": {
            "aws.elasticache.sessionCache.evictionPolicy": "volatile-ttl"
        }
    }
}

Google Cloud Configuration Options

🚀 Planned for v1 - The Google Cloud deployment targets are planned for v1, they may become available in a future v0 evolution.

Azure Configuration Options

🚀 Planned for v1 - The Azure deployment targets are planned for v1, they may become available in a future v0 evolution.

SDK Operations

The Celerity SDKs provide a cache abstraction covering all five core Redis data structures — strings (key-value), hashes, lists, sets and sorted sets. The abstraction handles connection setup and transparently routes single-key operations in both single-instance and cluster mode.

For language-specific documentation, see Node.js SDK - Cache and Python SDK - Cache.

Core Key-Value Operations

• get(key) — Get a value by key. Returns null if the key does not exist.
• set(key, value, options?) — Set a value with an optional TTL and conditional flags. options.ttl specifies time-to-live in seconds. options.nx only sets the key if it does not already exist. options.xx only sets the key if it already exists. Returns true if the value was set, false otherwise.
• delete(key) — Delete a value by key. Returns true if the key existed and was deleted.
• ttl(key) — Get the remaining time-to-live in seconds for a key. Returns -1 if the key exists but has no expiry, -2 if the key does not exist.
• getSet(key, value) — Atomically set a new value and return the old value. Returns null if the key did not previously exist.
• append(key, value) — Append a string to an existing value. Returns the length of the string after appending. Creates the key with the given value if it does not exist.

Batch Key-Value Operations

Batch operations over multiple keys. When all keys share a hash slot the SDK uses the native Redis command with full atomicity. When keys span slots the SDK groups by slot and executes each group atomically via a Lua script — cross-slot atomicity is not guaranteed.

• mget(keys) — Get multiple values in a single call. Returns an array in the same order as the input keys, with null for keys that do not exist.
• mset(entries) — Set multiple key-value pairs in a single call. Each entry is a key-value pair.
• mdelete(keys) — Delete multiple keys in a single call. Returns the total number of keys that were deleted.

Key Management Operations

• exists(key) — Check if a key exists. Returns true if the key exists.
• expire(key, seconds) — Set a TTL on an existing key. Returns true if the timeout was set, false if the key does not exist.
• persist(key) — Remove the TTL from a key, making it persistent. Returns true if the timeout was removed, false if the key does not exist or has no TTL.
• type(key) — Get the data type stored at a key (string, list, set, zset, hash). Returns null if the key does not exist.
• rename(key, newKey) — Rename a key. Throws an error if the source key does not exist. In cluster mode, both keys must resolve to the same hash slot.
• scan(options?) — Incrementally iterate over keys. Returns an async iterable of key names. options.match is a glob-style pattern (e.g. session:*). options.count is a hint for how many keys to return per iteration. options.type filters by data type. In cluster mode, the SDK scans all master nodes in parallel and merges results into a single iterable.

Atomic Counter Operations

• incr(key, amount?) — Atomically increment an integer value by amount (default 1). Returns the new value. Creates the key with value 0 before incrementing if it does not exist.
• decr(key, amount?) — Atomically decrement an integer value by amount (default 1). Returns the new value. Creates the key with value 0 before decrementing if it does not exist.
• incrFloat(key, amount) — Atomically increment a floating-point value. Returns the new value. Creates the key with value 0 before incrementing if it does not exist.

Hash Operations

Hashes store field-value pairs under a single key. Ideal for structured objects (e.g. user profiles, session data) without serialising the entire value to a string.

• hashGet(key, field) — Get the value of a single field. Returns null if the key or field does not exist.
• hashSet(key, fields) — Set one or more fields. fields is an object of field-value pairs. Creates the hash if it does not exist.
• hashDelete(key, fields) — Remove one or more fields. Returns the number of fields that were removed.
• hashGetAll(key) — Get all fields and values. Returns an empty object if the key does not exist or the hash has no fields.
• hashExists(key, field) — Check if a field exists in a hash.
• hashIncr(key, field, amount?) — Atomically increment an integer field by amount (default 1). Returns the new value. Creates the field with value 0 before incrementing if it does not exist.
• hashKeys(key) — Get all field names. Returns an empty array if the key does not exist.
• hashLen(key) — Get the number of fields in a hash. Returns 0 if the key does not exist.

List Operations

Lists are ordered collections supporting push and pop from both ends. Useful for queues, recent-activity feeds and bounded buffers.

• listPush(key, values, end?) — Push one or more values onto a list. end is "right" (default, tail) or "left" (head). Returns the length of the list after the push.
• listPop(key, end?, count?) — Remove and return elements from a list. end is "left" (default, head) or "right" (tail). count defaults to 1. Returns an empty array if the key does not exist.
• listRange(key, start, stop) — Get elements by index range. 0 is the first element, -1 is the last. Does not modify the list.
• listLen(key) — Get the length of a list. Returns 0 if the key does not exist.
• listTrim(key, start, stop) — Trim a list to the specified range, removing all elements outside it. Commonly combined with listPush to maintain bounded lists (e.g. push then listTrim(key, 0, 99) for a 100-element cap).
• listIndex(key, index) — Get an element by its index. Returns null if the index is out of range or the key does not exist.

Set Operations

Sets are unordered collections of unique strings. Useful for tagging, tracking unique visitors and membership checks.

• setAdd(key, members) — Add one or more members. Returns the number of members that were added (excluding already-existing members).
• setRemove(key, members) — Remove one or more members. Returns the number of members that were removed.
• setMembers(key) — Get all members. Returns an empty array if the key does not exist.
• setIsMember(key, member) — Check if a value is a member of a set.
• setLen(key) — Get the number of members. Returns 0 if the key does not exist.
• setUnion(keys) — Return the union of multiple sets. Does not store the result. In cluster mode, all keys must share a hash slot.
• setIntersect(keys) — Return the intersection of multiple sets. Does not store the result. In cluster mode, all keys must share a hash slot.
• setDiff(keys) — Return the difference of the first set against all subsequent sets. Does not store the result. In cluster mode, all keys must share a hash slot.

Sorted Set Operations

Sorted sets are sets where each member has an associated numeric score, maintained in score order. Useful for leaderboards, priority queues, time-series indexes and rate-limiting windows.

• sortedSetAdd(key, members) — Add one or more {member, score} entries. Returns the number of new members added (not counting score updates to existing members).
• sortedSetRemove(key, members) — Remove one or more members. Returns the number of members removed.
• sortedSetScore(key, member) — Get the score of a member. Returns null if the member or key does not exist.
• sortedSetRank(key, member, reverse?) — Get the 0-based rank of a member. When reverse is true, ranks by descending score. Returns null if the member does not exist.
• sortedSetRange(key, start, stop, options?) — Get members by rank range. 0 is the lowest-score element, -1 is the last. options.reverse reverses the order. options.withScores returns objects with member and score.
• sortedSetRangeByScore(key, min, max, options?) — Get members within a score range. min and max can be numbers or "-inf" / "+inf". options.reverse reverses the order. options.withScores returns objects with member and score. options.offset and options.count provide pagination within the range.
• sortedSetIncr(key, member, amount) — Atomically increment the score of a member. Returns the new score. Creates the member with the given amount as its score if it does not exist.
• sortedSetLen(key) — Get the number of members. Returns 0 if the key does not exist.
• sortedSetCountByScore(key, min, max) — Count members within a score range without retrieving them.
• sortedSetRemoveByRank(key, start, stop) — Remove all members within a rank range. Returns the number of members removed.
• sortedSetRemoveByScore(key, min, max) — Remove all members within a score range. Returns the number of members removed.

Transaction Operations

Pipeline transactions execute multiple commands atomically via Redis MULTI/EXEC. All commands are queued — not executed — until the callback returns, at which point they are submitted as a single atomic batch.

• transaction(fn) — Execute queued commands atomically. The callback receives a transaction builder with write-only operations. Returns a result object containing per-command results in the order commands were queued.

The transaction builder supports all write operations from the cache abstraction: set, delete, getSet, append, incr, decr, incrFloat, hashSet, hashDelete, hashIncr, listPush, listTrim, setAdd, setRemove, sortedSetAdd, sortedSetRemove, sortedSetIncr, expire, persist, and rename. Each method returns the builder for chaining.

Read operations (get, mget, hashGet, hashGetAll, etc.) are not available within a transaction because Redis queues all commands server-side and only returns results after EXEC.

Credentials Provider

The credentials provider returns connection details for creating your own Redis client. This gives you direct access to advanced Redis features that are not covered by the SDK abstraction — including pub/sub, streams, WATCH-based optimistic locking, Lua scripting, pipelining, geo commands, HyperLogLog and bitmaps. Note that using the credentials provider directly means your application code may need changes if you switch between single-instance and cluster mode, as cluster mode requires cluster-aware client configuration.

The configuration object shape depends on the authMode:

password mode (default):

• host — Cache endpoint (configuration endpoint for cluster mode)
• port — Cache port
• tls — Whether TLS is enabled
• clusterMode — Whether the cache is in cluster mode
• authMode — "password"
• authToken — AUTH password/token (may be absent for local development with no auth)

iam mode ✅ Available in v0:

• host — Cache endpoint (configuration endpoint for cluster mode)
• port — Cache port
• tls — Always true (IAM auth requires TLS on all providers)
• clusterMode — Whether the cache is in cluster mode
• user — IAM-mapped cache user ID
• authMode — "iam"
• getToken() — Returns a fresh short-lived authentication token. The SDK handles caching and refresh internally, fetching a new token when the current one is within ~1 minute of expiry.