v0.3.0

Release Notes

This release is mostly about new features: a JSON command family, a built-in distributed rate limiter, and client-side caching in cluster mode. Cluster routing also got noticeably more forgiving.

• JSON support. The JSON.* surface shipped by Redis 8 and the Valkey Bundle, addressed with JSONPath. Documents stay raw JSON text on the wire, so Sage takes no JSON-library dependency and any structured typing comes from your own codec. See JSON.

• Built-in distributed rate limiter. A token bucket whose state lives on the server, so the limit holds across every process pointed at it. One round trip in steady state, and a decision is a returned value rather than a thrown error. See Rate limiting.

• Client-side caching in cluster mode. Each slot-owning master keeps its own tracking-backed cache, and a cached read routes to the master owning the key's slot. The same call now works unchanged on standalone, master-replica, and cluster clients. See Client-side caching.

• Transparent cross-slot commands. mGet, mSet, exists, del, unlink, and touch may now span slots in a cluster. Sage groups the keys by slot, sends one subcommand per slot, and reassembles the reply (request order restored for mGet, counts summed for the rest). Works inside a pipeline too, and a -TRYAGAIN during resharding is retried for you.

• Self-clearing refusals are retried. -TRYAGAIN, -CLUSTERDOWN, -LOADING, and -MASTERDOWN all mean the server turned the command down before running it, for a reason that goes away on its own. Sage now retries those within the redirect budget instead of surfacing them. See Error handling.

• Opt-in background topology refresh. topologyRefreshInterval on ClusterConfig and MasterReplicaConfig (off by default) polls the topology on a timer, so a replica added to an otherwise healthy shard gets picked up without waiting for a fault to reveal it.

• Numbered databases in Valkey clusters. Set database on a Valkey 9+ cluster configured with cluster-databases, and Sage issues SELECT on every node connection, including after reconnects and redirects.

What's Changed

• Support numbered databases in Valkey clusters by @ghostdogpr in #195
• Support transparent cross-slot commands by @ghostdogpr in #196
• Retry cross-slot commands that fail with -TRYAGAIN during resharding by @ghostdogpr in #198
• Support client-side caching in cluster mode by @ghostdogpr in #205
• Add Redis and Valkey JSON support by @ghostdogpr in #206
• Add a built-in distributed rate limiter by @ghostdogpr in #207
• Pin master-replica topology to supplied seeds by @ghostdogpr in #212
• Reject an empty CLUSTER SLOTS reply by @ghostdogpr in #216
• Throttle the topology refresh a transaction fires on ASK by @ghostdogpr in #221
• Retry a broadcast's node instead of failing the command by @ghostdogpr in #218
• Restore the broadcast refresh after the RefreshPolicy rename by @ghostdogpr in #222
• Add an opt-in background topology refresh by @ghostdogpr in #220
• Retry self-clearing server refusals by @ghostdogpr in #217