@prezly/theme-kit-nextjs 10.10.1 → 10.11.0

package/README.md

@@ -416,6 +416,42 @@ subject to their configured expiration; do not flush a Redis instance that also
 contains routing data. TTL and query canonicalization are separate policies and
 are unchanged here.
 
+### Memory layer refill and bounds
+
+With both `memory` and `redis` enabled the layers form a stack. A hit found in
+Redis is written back into the in-process layer with the entry's own version
+and retention, so the next request on that runtime is served from memory
+without a Redis round trip or a JSON decode. Before this, a memory entry lost to
+a version change was never refilled and every later read on that pod went to
+Redis. Stale entries are never copied: only a value that passed the version
+check is written back, and a not-found entry keeps its short retention. Only
+layers that implement the optional `lookup` method are refill sources; a
+third-party `Cache` that implements `get` alone is read as before and never
+copied from.
+
+The in-process store is one `Map` per runtime shared by every adapter and
+namespace, bounded to 128 MiB of estimated payload and 20,000 entries by
+default. It evicts the least recently used entry first, deterministically and
+without sorting; a read moves the entry to the most recent position. Pass
+`memory: { maxBytes, maxRecords }` to `PrezlyAdapter.connect` to change the
+bounds; both must be positive integers. `ContentDelivery.inspectSharedMemoryCache()`
+reports the current occupancy.
+
+Redis renewal changed at the same time. Regular content keeps a sliding
+expiry, but instead of an `EXPIRE` on every read, an entry is rewritten with a
+fresh timestamp only once it has consumed half of its lifetime, so a hot key
+costs one write per half-life instead of one per read. The rewrite runs as a
+small Lua script that compares the stored payload with the one that was read,
+so a renewal landing after another pod refreshed the key never puts the older
+payload back. Entries written by older releases carry no timestamp and are
+renewed on their first read. The renewal still reports as the `expire` command
+in telemetry. Not-found entries are never renewed.
+
+The in-process store also refuses two kinds of write: an entry older than the
+one it already holds for that key (a refill that lost a race with an origin
+fetch) and an entry larger than `maxBytes` on its own, which would otherwise
+evict every other tenant and still not fit.
+
 ### Not-found results
 
 `contentDelivery.story()` and `contentDelivery.gallery()` resolve `null` when the

package/build/adapters/prezly/cache/configure.cjs

@@ -26,7 +26,7 @@ function configure(config) {
   return undefined;
 }
 function configureStorage(config) {
-  var caches = [config.memory ? _themeKitCore.ContentDelivery.createSharedMemoryCache() : undefined, config.redis ? (0, _redis.createRedisCache)(_objectSpread(_objectSpread({
+  var caches = [config.memory ? _themeKitCore.ContentDelivery.createSharedMemoryCache('', typeof config.memory === 'object' ? config.memory : undefined) : undefined, config.redis ? (0, _redis.createRedisCache)(_objectSpread(_objectSpread({
     ttl: DEFAULT_REDIS_CACHE_TTL
   }, config.redis), {}, {
     telemetry: config.telemetry

package/build/adapters/prezly/cache/configure.d.ts

@@ -5,7 +5,12 @@ export interface Configuration {
         prefix?: string;
         ttl?: number;
     };
-    memory?: boolean;
+    /**
+     * In-process cache in front of Redis. `true` uses the default bounds
+     * (128 MiB of estimated payload, 20,000 entries); pass an object to change
+     * them. The store is shared by every adapter in the runtime.
+     */
+    memory?: boolean | ContentDelivery.MemoryCacheOptions;
     latestVersion: Resolvable<number>;
     namespace?: string;
     /** Extra immutable identity for custom fetch implementations. Enables request sharing. */

package/build/adapters/prezly/cache/configure.mjs

@@ -20,7 +20,7 @@ export function configure(config) {
   return undefined;
 }
 function configureStorage(config) {
-  var caches = [config.memory ? ContentDelivery.createSharedMemoryCache() : undefined, config.redis ? createRedisCache(_objectSpread(_objectSpread({
+  var caches = [config.memory ? ContentDelivery.createSharedMemoryCache('', typeof config.memory === 'object' ? config.memory : undefined) : undefined, config.redis ? createRedisCache(_objectSpread(_objectSpread({
     ttl: DEFAULT_REDIS_CACHE_TTL
   }, config.redis), {}, {
     telemetry: config.telemetry

package/build/adapters/prezly/cache/redis.cjs

@@ -19,6 +19,13 @@ function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t =
 function asyncGeneratorStep(n, t, e, r, o, a, c) { try { var i = n[a](c), u = i.value; } catch (n) { return void e(n); } i.done ? t(u) : Promise.resolve(u).then(r, o); }
 function _asyncToGenerator(n) { return function () { var t = this, e = arguments; return new Promise(function (r, o) { var a = n.apply(t, e); function _next(n) { asyncGeneratorStep(a, r, o, _next, _throw, "next", n); } function _throw(n) { asyncGeneratorStep(a, r, o, _next, _throw, "throw", n); } _next(void 0); }); }; }
 var COMMAND_TIMEOUT = 1000;
+/**
+ * Renews an entry only if it is still the one that was read, so a renewal
+ * that lands after a newer write (another pod refreshing the key from origin)
+ * never puts the older payload back. EXPIRE had no such race; a plain SET has.
+ */
+var RENEW_IF_UNCHANGED = "\nif redis.call('GET', KEYS[1]) == ARGV[1] then\n    return redis.call('SET', KEYS[1], ARGV[2], 'EX', ARGV[3])\nend\nreturn nil\n";
+var now = () => Math.floor(Date.now() / 1000);
 var CONNECTIONS = new Map();
 function command(_x, _x2) {
   return _command.apply(this, arguments);
@@ -75,29 +82,72 @@ function createRedisCache(_ref) {
   var connection = client;
   function createCache() {
     var namespacePrefix = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : '';
+    function read(_x3, _x4) {
+      return _read.apply(this, arguments);
+    }
+    function _read() {
+      _read = _asyncToGenerator(function* (key, latestVersion) {
+        if (!connection.isReady) {
+          _themeKitCore.ContentDelivery.emit(telemetry, {
+            type: 'redis_unavailable',
+            command: 'get'
+          });
+          return undefined;
+        }
+        var fullKey = "".concat(namespacePrefix).concat(key);
+        var cached = yield command(() => connection.get(fullKey), telemetry, 'get');
+        if (!cached) return undefined;
+        var entry = JSON.parse(cached);
+        if (entry.version < latestVersion) return undefined;
+        // Sliding expiry applies to regular content only: an entry with its
+        // own short retention must not be renewed to the default lifetime.
+        // Renewal used to be an EXPIRE on every read, doubling the command
+        // rate. Now an entry is rewritten with a fresh timestamp only once it
+        // has consumed half of its lifetime, so a hot key costs one write per
+        // half-life instead of one per read. Entries from older releases
+        // carry no timestamp and are renewed on their first read. A timestamp
+        // in the future (clock skew) is treated as due as well.
+        if (ttl && entry.ttl === undefined) {
+          var time = now();
+          if (entry.written === undefined || entry.written > time || time - entry.written >= ttl / 2) {
+            var renewed = _objectSpread(_objectSpread({}, entry), {}, {
+              written: time
+            });
+            void command(() => connection.eval(RENEW_IF_UNCHANGED, {
+              keys: [fullKey],
+              arguments: [cached, JSON.stringify(renewed), String(ttl)]
+            }), telemetry, 'expire').catch(() => undefined);
+          }
+        }
+        return entry;
+      });
+      return _read.apply(this, arguments);
+    }
     return {
       get(key, latestVersion, onSource) {
         return _asyncToGenerator(function* () {
-          if (!connection.isReady) {
-            _themeKitCore.ContentDelivery.emit(telemetry, {
-              type: 'redis_unavailable',
-              command: 'get'
-            });
-            return undefined;
-          }
-          var cached = yield command(() => connection.get("".concat(namespacePrefix).concat(key)), telemetry, 'get');
-          if (!cached) return undefined;
-          var entry = JSON.parse(cached);
-          if (entry.version < latestVersion) return undefined;
-          // Sliding expiry applies to regular content only. An entry with its
-          // own short retention must not be renewed to the default lifetime.
-          if (ttl && entry.ttl === undefined) {
-            void command(() => connection.expire("".concat(namespacePrefix).concat(key), ttl), telemetry, 'expire').catch(() => undefined);
-          }
+          var entry = yield read(key, latestVersion);
+          if (!entry) return undefined;
           if (onSource) _themeKitCore.ContentDelivery.notify(onSource, 'redis');
           return entry.value;
         })();
       },
+      lookup(key, latestVersion) {
+        return _asyncToGenerator(function* () {
+          var entry = yield read(key, latestVersion);
+          if (!entry) return undefined;
+          // Report what is left of a short retention, so a refilled copy
+          // does not outlive this one. Legacy entries have no timestamp
+          // and report their original retention.
+          var age = entry.written === undefined ? 0 : Math.max(0, now() - entry.written);
+          return {
+            value: entry.value,
+            version: entry.version,
+            ttl: entry.ttl === undefined ? undefined : Math.max(1, entry.ttl - age),
+            layer: 'redis'
+          };
+        })();
+      },
       set(key, value, version, options) {
         return _asyncToGenerator(function* () {
           if (!connection.isReady) {
@@ -110,11 +160,13 @@ function createRedisCache(_ref) {
           // SET EX takes whole seconds; round a fractional hint up, never down.
           var entry = (options === null || options === void 0 ? void 0 : options.ttl) === undefined ? {
             value,
-            version
+            version,
+            written: now()
           } : {
             value,
             version,
-            ttl: Math.max(1, Math.ceil(options.ttl))
+            ttl: Math.max(1, Math.ceil(options.ttl)),
+            written: now()
           };
           yield command(() => {
             var _entry$ttl;

package/build/adapters/prezly/cache/redis.mjs

@@ -12,6 +12,13 @@ import { ContentDelivery } from '@prezly/theme-kit-core';
 import stableStringify from 'json-stable-stringify';
 import { createClient } from 'redis';
 var COMMAND_TIMEOUT = 1000;
+/**
+ * Renews an entry only if it is still the one that was read, so a renewal
+ * that lands after a newer write (another pod refreshing the key from origin)
+ * never puts the older payload back. EXPIRE had no such race; a plain SET has.
+ */
+var RENEW_IF_UNCHANGED = "\nif redis.call('GET', KEYS[1]) == ARGV[1] then\n    return redis.call('SET', KEYS[1], ARGV[2], 'EX', ARGV[3])\nend\nreturn nil\n";
+var now = () => Math.floor(Date.now() / 1000);
 var CONNECTIONS = new Map();
 function command(_x, _x2) {
   return _command.apply(this, arguments);
@@ -68,29 +75,72 @@ export function createRedisCache(_ref) {
   var connection = client;
   function createCache() {
     var namespacePrefix = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : '';
+    function read(_x3, _x4) {
+      return _read.apply(this, arguments);
+    }
+    function _read() {
+      _read = _asyncToGenerator(function* (key, latestVersion) {
+        if (!connection.isReady) {
+          ContentDelivery.emit(telemetry, {
+            type: 'redis_unavailable',
+            command: 'get'
+          });
+          return undefined;
+        }
+        var fullKey = "".concat(namespacePrefix).concat(key);
+        var cached = yield command(() => connection.get(fullKey), telemetry, 'get');
+        if (!cached) return undefined;
+        var entry = JSON.parse(cached);
+        if (entry.version < latestVersion) return undefined;
+        // Sliding expiry applies to regular content only: an entry with its
+        // own short retention must not be renewed to the default lifetime.
+        // Renewal used to be an EXPIRE on every read, doubling the command
+        // rate. Now an entry is rewritten with a fresh timestamp only once it
+        // has consumed half of its lifetime, so a hot key costs one write per
+        // half-life instead of one per read. Entries from older releases
+        // carry no timestamp and are renewed on their first read. A timestamp
+        // in the future (clock skew) is treated as due as well.
+        if (ttl && entry.ttl === undefined) {
+          var time = now();
+          if (entry.written === undefined || entry.written > time || time - entry.written >= ttl / 2) {
+            var renewed = _objectSpread(_objectSpread({}, entry), {}, {
+              written: time
+            });
+            void command(() => connection.eval(RENEW_IF_UNCHANGED, {
+              keys: [fullKey],
+              arguments: [cached, JSON.stringify(renewed), String(ttl)]
+            }), telemetry, 'expire').catch(() => undefined);
+          }
+        }
+        return entry;
+      });
+      return _read.apply(this, arguments);
+    }
     return {
       get(key, latestVersion, onSource) {
         return _asyncToGenerator(function* () {
-          if (!connection.isReady) {
-            ContentDelivery.emit(telemetry, {
-              type: 'redis_unavailable',
-              command: 'get'
-            });
-            return undefined;
-          }
-          var cached = yield command(() => connection.get("".concat(namespacePrefix).concat(key)), telemetry, 'get');
-          if (!cached) return undefined;
-          var entry = JSON.parse(cached);
-          if (entry.version < latestVersion) return undefined;
-          // Sliding expiry applies to regular content only. An entry with its
-          // own short retention must not be renewed to the default lifetime.
-          if (ttl && entry.ttl === undefined) {
-            void command(() => connection.expire("".concat(namespacePrefix).concat(key), ttl), telemetry, 'expire').catch(() => undefined);
-          }
+          var entry = yield read(key, latestVersion);
+          if (!entry) return undefined;
           if (onSource) ContentDelivery.notify(onSource, 'redis');
           return entry.value;
         })();
       },
+      lookup(key, latestVersion) {
+        return _asyncToGenerator(function* () {
+          var entry = yield read(key, latestVersion);
+          if (!entry) return undefined;
+          // Report what is left of a short retention, so a refilled copy
+          // does not outlive this one. Legacy entries have no timestamp
+          // and report their original retention.
+          var age = entry.written === undefined ? 0 : Math.max(0, now() - entry.written);
+          return {
+            value: entry.value,
+            version: entry.version,
+            ttl: entry.ttl === undefined ? undefined : Math.max(1, entry.ttl - age),
+            layer: 'redis'
+          };
+        })();
+      },
       set(key, value, version, options) {
         return _asyncToGenerator(function* () {
           if (!connection.isReady) {
@@ -103,11 +153,13 @@ export function createRedisCache(_ref) {
           // SET EX takes whole seconds; round a fractional hint up, never down.
           var entry = (options === null || options === void 0 ? void 0 : options.ttl) === undefined ? {
             value,
-            version
+            version,
+            written: now()
           } : {
             value,
             version,
-            ttl: Math.max(1, Math.ceil(options.ttl))
+            ttl: Math.max(1, Math.ceil(options.ttl)),
+            written: now()
           };
           yield command(() => {
             var _entry$ttl;

package/build/adapters/prezly/cache/redis.test.cjs

@@ -28,6 +28,9 @@ function connection() {
     set: jest.fn(/*#__PURE__*/_asyncToGenerator(function* () {
       return 'OK';
     })),
+    eval: jest.fn(/*#__PURE__*/_asyncToGenerator(function* () {
+      return 'OK';
+    })),
     expire: jest.fn(/*#__PURE__*/_asyncToGenerator(function* () {
       return true;
     }))
@@ -66,34 +69,136 @@ it('fails open while disconnected without waiting for connection establishment',
   client.isReady = true;
   expect(yield cache.get('key', 1)).toBe('cached');
 }));
-it('preserves namespace, version and sliding expiry and observes expiry rejection', /*#__PURE__*/_asyncToGenerator(function* () {
+it('preserves namespace and version, renews legacy entries in place, and observes renewal rejection', /*#__PURE__*/_asyncToGenerator(function* () {
+  jest.useFakeTimers({
+    now: 1700000000000
+  });
   var _connection2 = connection(),
     client = _connection2.client,
     cache = _connection2.cache;
-  client.expire.mockRejectedValueOnce(new Error('expiry failed'));
+  // A legacy entry (no `written`) is renewed on first read even when the write fails.
+  client.eval.mockRejectedValueOnce(new Error('renewal failed'));
   expect(yield cache.namespace('room').get('key', 2)).toBe('cached');
   expect(client.get).toHaveBeenLastCalledWith('test:room:key');
+  expect(client.eval).toHaveBeenCalledTimes(1);
+  expect(client.eval).toHaveBeenLastCalledWith(expect.stringContaining("redis.call('GET', KEYS[1]) == ARGV[1]"), {
+    keys: ['test:room:key'],
+    arguments: [JSON.stringify({
+      version: 2,
+      value: 'cached'
+    }), JSON.stringify({
+      version: 2,
+      value: 'cached',
+      written: 1700000000
+    }), '300']
+  });
+  expect(client.set).not.toHaveBeenCalled();
+  expect(client.expire).not.toHaveBeenCalled();
   expect(yield cache.get('key', 3)).toBeUndefined();
-  expect(client.expire).toHaveBeenCalledTimes(1);
+  expect(client.eval).toHaveBeenCalledTimes(1);
   yield cache.set('key', 'updated', 3);
   expect(client.set).toHaveBeenLastCalledWith('test:key', JSON.stringify({
     value: 'updated',
-    version: 3
+    version: 3,
+    written: 1700000000
   }), {
     EX: 300
   });
 }));
-it('stores a short-lived entry with its own expiry and never renews it', /*#__PURE__*/_asyncToGenerator(function* () {
+it('renews a regular entry only once it has consumed half of its lifetime, or when its timestamp is in the future', /*#__PURE__*/_asyncToGenerator(function* () {
+  jest.useFakeTimers({
+    now: 1700000000000
+  });
   var _connection3 = connection(),
     client = _connection3.client,
     cache = _connection3.cache;
+  var entry = {
+    value: 'cached',
+    version: 2,
+    written: 1700000000
+  };
+  client.get.mockResolvedValue(JSON.stringify(entry));
+  expect(yield cache.get('key', 2)).toBe('cached');
+  jest.setSystemTime(1700000149000); // 149s later, under half of the 300s ttl
+  expect(yield cache.get('key', 2)).toBe('cached');
+  expect(client.eval).not.toHaveBeenCalled();
+  jest.setSystemTime(1700000150000); // exactly half of the lifetime
+  expect(yield cache.get('key', 2)).toBe('cached');
+  expect(client.eval).toHaveBeenCalledTimes(1);
+  expect(client.eval).toHaveBeenLastCalledWith(expect.any(String), {
+    keys: ['test:key'],
+    arguments: [JSON.stringify(entry), JSON.stringify(_objectSpread(_objectSpread({}, entry), {}, {
+      written: 1700000150
+    })), '300']
+  });
+  client.get.mockResolvedValue(JSON.stringify(_objectSpread(_objectSpread({}, entry), {}, {
+    written: 1700000999
+  }))); // skewed writer
+  expect(yield cache.get('key', 2)).toBe('cached');
+  expect(client.eval).toHaveBeenCalledTimes(2);
+  expect(client.set).not.toHaveBeenCalled();
+  expect(client.expire).not.toHaveBeenCalled();
+}));
+it('exposes the entry version and remaining retention through lookup', /*#__PURE__*/_asyncToGenerator(function* () {
+  var _cache$lookup, _cache$namespace$look, _cache$namespace, _yield$cache$lookup, _cache$lookup2, _cache$lookup3;
+  jest.useFakeTimers({
+    now: 1700000000000
+  });
+  var _connection4 = connection(),
+    client = _connection4.client,
+    cache = _connection4.cache;
+  client.get.mockResolvedValueOnce(JSON.stringify({
+    value: 'cached',
+    version: 2,
+    written: 1700000000
+  }));
+  expect(yield (_cache$lookup = cache.lookup) === null || _cache$lookup === void 0 ? void 0 : _cache$lookup.call(cache, 'key', 2)).toEqual({
+    value: 'cached',
+    version: 2,
+    ttl: undefined,
+    layer: 'redis'
+  });
+  client.get.mockResolvedValueOnce(JSON.stringify({
+    value: null,
+    version: 4,
+    ttl: 60,
+    written: 1699999955
+  }));
+  expect(yield (_cache$namespace$look = (_cache$namespace = cache.namespace('room')).lookup) === null || _cache$namespace$look === void 0 ? void 0 : _cache$namespace$look.call(_cache$namespace, 'missing', 4)).toEqual({
+    value: null,
+    version: 4,
+    ttl: 15,
+    // 45s of the 60s retention consumed
+    layer: 'redis'
+  });
+  client.get.mockResolvedValueOnce(JSON.stringify({
+    value: null,
+    version: 4,
+    ttl: 60
+  }));
+  expect((_yield$cache$lookup = yield (_cache$lookup2 = cache.lookup) === null || _cache$lookup2 === void 0 ? void 0 : _cache$lookup2.call(cache, 'legacy', 4)) === null || _yield$cache$lookup === void 0 ? void 0 : _yield$cache$lookup.ttl).toBe(60);
+  client.get.mockResolvedValueOnce(JSON.stringify({
+    value: 'old',
+    version: 1
+  }));
+  expect(yield (_cache$lookup3 = cache.lookup) === null || _cache$lookup3 === void 0 ? void 0 : _cache$lookup3.call(cache, 'key', 2)).toBeUndefined();
+  expect(client.eval).not.toHaveBeenCalled();
+}));
+it('stores a short-lived entry with its own expiry and never renews it', /*#__PURE__*/_asyncToGenerator(function* () {
+  jest.useFakeTimers({
+    now: 1700000000000
+  });
+  var _connection5 = connection(),
+    client = _connection5.client,
+    cache = _connection5.cache;
   yield cache.set('missing', null, 4, {
     ttl: 60
   });
   expect(client.set).toHaveBeenLastCalledWith('test:missing', JSON.stringify({
     value: null,
     version: 4,
-    ttl: 60
+    ttl: 60,
+    written: 1700000000
   }), {
     EX: 60
   });
@@ -106,6 +211,8 @@ it('stores a short-lived entry with its own expiry and never renews it', /*#__PU
   expect(yield cache.get('missing', 4, onSource)).toBeNull();
   expect(onSource).toHaveBeenCalledWith('redis');
   expect(client.expire).not.toHaveBeenCalled();
+  expect(client.eval).not.toHaveBeenCalled();
+  expect(client.set).toHaveBeenCalledTimes(1); // the initial write only, never a renewal
   client.get.mockResolvedValueOnce(JSON.stringify({
     value: null,
     version: 4,
@@ -114,42 +221,46 @@ it('stores a short-lived entry with its own expiry and never renews it', /*#__PU
   expect(yield cache.get('missing', 5)).toBeUndefined();
 }));
 it('rounds a fractional ttl hint up to whole seconds for SET EX', /*#__PURE__*/_asyncToGenerator(function* () {
-  var _connection4 = connection(),
-    client = _connection4.client,
-    cache = _connection4.cache;
+  jest.useFakeTimers({
+    now: 1700000000000
+  });
+  var _connection6 = connection(),
+    client = _connection6.client,
+    cache = _connection6.cache;
   yield cache.set('short', null, 1, {
     ttl: 0.5
   });
   expect(client.set).toHaveBeenLastCalledWith('test:short', JSON.stringify({
     value: null,
     version: 1,
-    ttl: 1
+    ttl: 1,
+    written: 1700000000
   }), {
     EX: 1
   });
 }));
 it.each([false, 0, ''])('returns a stored %p as a hit', /*#__PURE__*/function () {
-  var _ref8 = _asyncToGenerator(function* (value) {
-    var _connection5 = connection(),
-      client = _connection5.client,
-      cache = _connection5.cache;
+  var _ref1 = _asyncToGenerator(function* (value) {
+    var _connection7 = connection(),
+      client = _connection7.client,
+      cache = _connection7.cache;
     client.get.mockResolvedValueOnce(JSON.stringify({
       value,
       version: 2
     }));
     expect(yield cache.get('key', 2)).toBe(value);
-    expect(client.expire).toHaveBeenCalledTimes(1);
+    expect(client.eval).toHaveBeenCalledTimes(1); // legacy entry renewed in place
   });
   return function (_x) {
-    return _ref8.apply(this, arguments);
+    return _ref1.apply(this, arguments);
   };
 }());
 it.each(['get', 'set'])('times out stalled %s commands without unsafe cancellation and recovers', /*#__PURE__*/function () {
-  var _ref9 = _asyncToGenerator(function* (method) {
+  var _ref10 = _asyncToGenerator(function* (method) {
     jest.useFakeTimers();
-    var _connection6 = connection(),
-      client = _connection6.client,
-      cache = _connection6.cache;
+    var _connection8 = connection(),
+      client = _connection8.client,
+      cache = _connection8.cache;
     var rejectOperation;
     client[method].mockImplementationOnce(() => new Promise((_, reject) => {
       rejectOperation = reject;
@@ -164,13 +275,13 @@ it.each(['get', 'set'])('times out stalled %s commands without unsafe cancellati
     expect(jest.getTimerCount()).toBe(0);
   });
   return function (_x2) {
-    return _ref9.apply(this, arguments);
+    return _ref10.apply(this, arguments);
   };
 }());
 it('does not fragment Redis connections by observer and distinguishes unavailable from commands', /*#__PURE__*/_asyncToGenerator(function* () {
-  var _connection7 = connection(false),
-    client = _connection7.client,
-    options = _connection7.options;
+  var _connection9 = connection(false),
+    client = _connection9.client,
+    options = _connection9.options;
   var events = [];
   var observe = event => {
     events.push(event);

package/build/adapters/prezly/cache/redis.test.mjs

@@ -26,6 +26,9 @@ function connection() {
     set: jest.fn(/*#__PURE__*/_asyncToGenerator(function* () {
       return 'OK';
     })),
+    eval: jest.fn(/*#__PURE__*/_asyncToGenerator(function* () {
+      return 'OK';
+    })),
     expire: jest.fn(/*#__PURE__*/_asyncToGenerator(function* () {
       return true;
     }))
@@ -64,34 +67,136 @@ it('fails open while disconnected without waiting for connection establishment',
   client.isReady = true;
   expect(yield cache.get('key', 1)).toBe('cached');
 }));
-it('preserves namespace, version and sliding expiry and observes expiry rejection', /*#__PURE__*/_asyncToGenerator(function* () {
+it('preserves namespace and version, renews legacy entries in place, and observes renewal rejection', /*#__PURE__*/_asyncToGenerator(function* () {
+  jest.useFakeTimers({
+    now: 1700000000000
+  });
   var _connection2 = connection(),
     client = _connection2.client,
     cache = _connection2.cache;
-  client.expire.mockRejectedValueOnce(new Error('expiry failed'));
+  // A legacy entry (no `written`) is renewed on first read even when the write fails.
+  client.eval.mockRejectedValueOnce(new Error('renewal failed'));
   expect(yield cache.namespace('room').get('key', 2)).toBe('cached');
   expect(client.get).toHaveBeenLastCalledWith('test:room:key');
+  expect(client.eval).toHaveBeenCalledTimes(1);
+  expect(client.eval).toHaveBeenLastCalledWith(expect.stringContaining("redis.call('GET', KEYS[1]) == ARGV[1]"), {
+    keys: ['test:room:key'],
+    arguments: [JSON.stringify({
+      version: 2,
+      value: 'cached'
+    }), JSON.stringify({
+      version: 2,
+      value: 'cached',
+      written: 1700000000
+    }), '300']
+  });
+  expect(client.set).not.toHaveBeenCalled();
+  expect(client.expire).not.toHaveBeenCalled();
   expect(yield cache.get('key', 3)).toBeUndefined();
-  expect(client.expire).toHaveBeenCalledTimes(1);
+  expect(client.eval).toHaveBeenCalledTimes(1);
   yield cache.set('key', 'updated', 3);
   expect(client.set).toHaveBeenLastCalledWith('test:key', JSON.stringify({
     value: 'updated',
-    version: 3
+    version: 3,
+    written: 1700000000
   }), {
     EX: 300
   });
 }));
-it('stores a short-lived entry with its own expiry and never renews it', /*#__PURE__*/_asyncToGenerator(function* () {
+it('renews a regular entry only once it has consumed half of its lifetime, or when its timestamp is in the future', /*#__PURE__*/_asyncToGenerator(function* () {
+  jest.useFakeTimers({
+    now: 1700000000000
+  });
   var _connection3 = connection(),
     client = _connection3.client,
     cache = _connection3.cache;
+  var entry = {
+    value: 'cached',
+    version: 2,
+    written: 1700000000
+  };
+  client.get.mockResolvedValue(JSON.stringify(entry));
+  expect(yield cache.get('key', 2)).toBe('cached');
+  jest.setSystemTime(1700000149000); // 149s later, under half of the 300s ttl
+  expect(yield cache.get('key', 2)).toBe('cached');
+  expect(client.eval).not.toHaveBeenCalled();
+  jest.setSystemTime(1700000150000); // exactly half of the lifetime
+  expect(yield cache.get('key', 2)).toBe('cached');
+  expect(client.eval).toHaveBeenCalledTimes(1);
+  expect(client.eval).toHaveBeenLastCalledWith(expect.any(String), {
+    keys: ['test:key'],
+    arguments: [JSON.stringify(entry), JSON.stringify(_objectSpread(_objectSpread({}, entry), {}, {
+      written: 1700000150
+    })), '300']
+  });
+  client.get.mockResolvedValue(JSON.stringify(_objectSpread(_objectSpread({}, entry), {}, {
+    written: 1700000999
+  }))); // skewed writer
+  expect(yield cache.get('key', 2)).toBe('cached');
+  expect(client.eval).toHaveBeenCalledTimes(2);
+  expect(client.set).not.toHaveBeenCalled();
+  expect(client.expire).not.toHaveBeenCalled();
+}));
+it('exposes the entry version and remaining retention through lookup', /*#__PURE__*/_asyncToGenerator(function* () {
+  var _cache$lookup, _cache$namespace$look, _cache$namespace, _yield$cache$lookup, _cache$lookup2, _cache$lookup3;
+  jest.useFakeTimers({
+    now: 1700000000000
+  });
+  var _connection4 = connection(),
+    client = _connection4.client,
+    cache = _connection4.cache;
+  client.get.mockResolvedValueOnce(JSON.stringify({
+    value: 'cached',
+    version: 2,
+    written: 1700000000
+  }));
+  expect(yield (_cache$lookup = cache.lookup) === null || _cache$lookup === void 0 ? void 0 : _cache$lookup.call(cache, 'key', 2)).toEqual({
+    value: 'cached',
+    version: 2,
+    ttl: undefined,
+    layer: 'redis'
+  });
+  client.get.mockResolvedValueOnce(JSON.stringify({
+    value: null,
+    version: 4,
+    ttl: 60,
+    written: 1699999955
+  }));
+  expect(yield (_cache$namespace$look = (_cache$namespace = cache.namespace('room')).lookup) === null || _cache$namespace$look === void 0 ? void 0 : _cache$namespace$look.call(_cache$namespace, 'missing', 4)).toEqual({
+    value: null,
+    version: 4,
+    ttl: 15,
+    // 45s of the 60s retention consumed
+    layer: 'redis'
+  });
+  client.get.mockResolvedValueOnce(JSON.stringify({
+    value: null,
+    version: 4,
+    ttl: 60
+  }));
+  expect((_yield$cache$lookup = yield (_cache$lookup2 = cache.lookup) === null || _cache$lookup2 === void 0 ? void 0 : _cache$lookup2.call(cache, 'legacy', 4)) === null || _yield$cache$lookup === void 0 ? void 0 : _yield$cache$lookup.ttl).toBe(60);
+  client.get.mockResolvedValueOnce(JSON.stringify({
+    value: 'old',
+    version: 1
+  }));
+  expect(yield (_cache$lookup3 = cache.lookup) === null || _cache$lookup3 === void 0 ? void 0 : _cache$lookup3.call(cache, 'key', 2)).toBeUndefined();
+  expect(client.eval).not.toHaveBeenCalled();
+}));
+it('stores a short-lived entry with its own expiry and never renews it', /*#__PURE__*/_asyncToGenerator(function* () {
+  jest.useFakeTimers({
+    now: 1700000000000
+  });
+  var _connection5 = connection(),
+    client = _connection5.client,
+    cache = _connection5.cache;
   yield cache.set('missing', null, 4, {
     ttl: 60
   });
   expect(client.set).toHaveBeenLastCalledWith('test:missing', JSON.stringify({
     value: null,
     version: 4,
-    ttl: 60
+    ttl: 60,
+    written: 1700000000
   }), {
     EX: 60
   });
@@ -104,6 +209,8 @@ it('stores a short-lived entry with its own expiry and never renews it', /*#__PU
   expect(yield cache.get('missing', 4, onSource)).toBeNull();
   expect(onSource).toHaveBeenCalledWith('redis');
   expect(client.expire).not.toHaveBeenCalled();
+  expect(client.eval).not.toHaveBeenCalled();
+  expect(client.set).toHaveBeenCalledTimes(1); // the initial write only, never a renewal
   client.get.mockResolvedValueOnce(JSON.stringify({
     value: null,
     version: 4,
@@ -112,42 +219,46 @@ it('stores a short-lived entry with its own expiry and never renews it', /*#__PU
   expect(yield cache.get('missing', 5)).toBeUndefined();
 }));
 it('rounds a fractional ttl hint up to whole seconds for SET EX', /*#__PURE__*/_asyncToGenerator(function* () {
-  var _connection4 = connection(),
-    client = _connection4.client,
-    cache = _connection4.cache;
+  jest.useFakeTimers({
+    now: 1700000000000
+  });
+  var _connection6 = connection(),
+    client = _connection6.client,
+    cache = _connection6.cache;
   yield cache.set('short', null, 1, {
     ttl: 0.5
   });
   expect(client.set).toHaveBeenLastCalledWith('test:short', JSON.stringify({
     value: null,
     version: 1,
-    ttl: 1
+    ttl: 1,
+    written: 1700000000
   }), {
     EX: 1
   });
 }));
 it.each([false, 0, ''])('returns a stored %p as a hit', /*#__PURE__*/function () {
-  var _ref8 = _asyncToGenerator(function* (value) {
-    var _connection5 = connection(),
-      client = _connection5.client,
-      cache = _connection5.cache;
+  var _ref1 = _asyncToGenerator(function* (value) {
+    var _connection7 = connection(),
+      client = _connection7.client,
+      cache = _connection7.cache;
     client.get.mockResolvedValueOnce(JSON.stringify({
       value,
       version: 2
     }));
     expect(yield cache.get('key', 2)).toBe(value);
-    expect(client.expire).toHaveBeenCalledTimes(1);
+    expect(client.eval).toHaveBeenCalledTimes(1); // legacy entry renewed in place
   });
   return function (_x) {
-    return _ref8.apply(this, arguments);
+    return _ref1.apply(this, arguments);
   };
 }());
 it.each(['get', 'set'])('times out stalled %s commands without unsafe cancellation and recovers', /*#__PURE__*/function () {
-  var _ref9 = _asyncToGenerator(function* (method) {
+  var _ref10 = _asyncToGenerator(function* (method) {
     jest.useFakeTimers();
-    var _connection6 = connection(),
-      client = _connection6.client,
-      cache = _connection6.cache;
+    var _connection8 = connection(),
+      client = _connection8.client,
+      cache = _connection8.cache;
     var rejectOperation;
     client[method].mockImplementationOnce(() => new Promise((_, reject) => {
       rejectOperation = reject;
@@ -162,13 +273,13 @@ it.each(['get', 'set'])('times out stalled %s commands without unsafe cancellati
     expect(jest.getTimerCount()).toBe(0);
   });
   return function (_x2) {
-    return _ref9.apply(this, arguments);
+    return _ref10.apply(this, arguments);
   };
 }());
 it('does not fragment Redis connections by observer and distinguishes unavailable from commands', /*#__PURE__*/_asyncToGenerator(function* () {
-  var _connection7 = connection(false),
-    client = _connection7.client,
-    options = _connection7.options;
+  var _connection9 = connection(false),
+    client = _connection9.client,
+    options = _connection9.options;
   var events = [];
   var observe = event => {
     events.push(event);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prezly/theme-kit-nextjs",
-  "version": "10.10.1",
+  "version": "10.11.0",
   "description": "Data layer and utility library for developing Prezly themes with NextJS",
   "type": "module",
   "main": "build/index.mjs",
@@ -79,7 +79,7 @@
     "json-stable-stringify": "^1.2.1",
     "redis": "^4.7.0",
     "url-pattern": "^1.0.3",
-    "@prezly/theme-kit-core": "^10.10.1",
+    "@prezly/theme-kit-core": "^10.11.0",
     "@prezly/theme-kit-react": "^10.9.1",
     "@prezly/theme-kit-intl": "^10.9.1"
   },