Valkey 0.3.1: client-side caching, blocking pools, IAM auth and mTLS

Community
, , , ,
1

Hi everyone,

I wanted to share that valkey.0.3.1 is now on opam.

This is the next release after the 0.2.0 announcement. The short version: a few of the roadmap items from that post are now shipped — client-side caching, blocking-command pools, IAM auth, and mTLS.

opam update
opam install valkey eio_main

Repo and docs: GitHub - avifenesh/ocaml-valkey: Modern Valkey client for OCaml 5 + Eio (RESP3-only). · GitHub

The largest new feature is client-side caching.

valkey now supports Valkey CLIENT TRACKING with a bounded in-process LRU cache, RESP3 invalidation push handling, single-flight protection, optional TTL safety net, and metrics. It works in both standalone and cluster mode, and supports the three tracking shapes I wanted to cover:

  • default tracking
  • BCAST prefix tracking
  • OPTIN tracking

The cluster path was the tricky part. OPTIN reads need CLIENT CACHING YES to stay adjacent to the actual read on the wire, including across MOVED / ASK redirects. That is now handled inside the client rather than pushed onto callers.

The second big addition is a blocking-command pool.

The normal client is still built around multiplexed connections, which is the right shape for regular traffic. But commands such as BLPOP, BRPOP, BLMOVE, BLMPOP, BZPOP*, XREAD BLOCK, and XREADGROUP BLOCK are intentionally blocking on the server side. Sending one of those through the normal multiplexed FIFO can freeze unrelated requests queued behind it.

0.3.x adds a narrow per-node lease pool for those commands. Blocking calls lease an exclusive connection for the duration of the command, while regular traffic continues on the normal client. The pool is bounded, has typed errors, handles topology changes, and is off by default unless configured.

The third addition is IAM auth and mTLS.

There is now a first-class Connection.Auth.provider abstraction instead of only static username/password config. That means every initial handshake and reconnect can pull fresh credentials from a provider.

On top of that, the library now includes:

  • pure OCaml AWS SigV4 signing for ElastiCache IAM auth
  • an auto-refreshing IAM provider
  • Client.connect_with_iam
  • live AUTH refresh support
  • mTLS client certificate configuration via Tls_config.with_client_cert

The IAM path does not depend on the AWS SDK. The signer is implemented in OCaml and tested against AWS SigV4 test vectors.

There were also a few correctness and operability improvements:

  • OpenTelemetry spans for connect, cluster discovery, and topology refresh
  • cache and blocking-pool metric bridges
  • tighter TLS / connection error redaction
  • better MOVED / ASK / topology-refresh behavior under cluster changes
  • fixes around WATCH / MULTI / EXEC when slot ownership changes during an atomic flow
  • more tests around CSC invalidation, cluster migration, blocking-pool behavior, IAM refresh, and mTLS config

0.3.1 itself is a small follow-up to make the opam sandbox tests clean: the mTLS config tests now use committed test fixtures instead of depending on generated certs from the local development scripts.

The project is still alpha, and the API may still change before 1.0, but the surface is getting closer to the shape I originally wanted: an OCaml 5 / Eio-native Valkey client that treats cluster behavior, RESP3, modern Valkey features, and production failure modes as first-class concerns.

I would especially appreciate feedback from people who use OCaml in production on:

  • API shape and naming
  • Eio ergonomics
  • docs clarity
  • whether the caching / blocking-pool / IAM APIs feel natural
  • what should be prioritized before 1.0

Next things on the roadmap are still Valkey module support — JSON, search, bloom — and a deeper pre-1.0 audit pass.

If you try it, I’d love to hear what feels good, what feels awkward, and what is missing.