@zlink-systems/framework-locations-redis 0.25.0 → 0.27.0

package/dist/framework-internal.d.ts

@@ -0,0 +1 @@
+export declare const ZLINK_PROVIDER_MAX_KEY_BYTES: number, ZLINK_PROVIDER_MAX_VALUE_BYTES: number, ZLINK_PROVIDER_MAX_VERSION_BYTES: number, ZLINK_PROVIDER_MAX_WRITE_KEYS: number, ZLINK_PROVIDER_MAX_WRITE_BYTES: number, ZLINK_PROVIDER_MAX_ENCODED_PAGE_BYTES: number, ZLINK_PROVIDER_MAX_SCAN_CURSOR_BYTES: number, ZLINK_PROVIDER_MAX_PAGE_SIZE: number, ZLINK_RELOCATION_MAX_BLOB_REFERENCE_BYTES: number;

package/dist/framework-internal.js

@@ -0,0 +1,12 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLINK_RELOCATION_MAX_BLOB_REFERENCE_BYTES = exports.ZLINK_PROVIDER_MAX_PAGE_SIZE = exports.ZLINK_PROVIDER_MAX_SCAN_CURSOR_BYTES = exports.ZLINK_PROVIDER_MAX_ENCODED_PAGE_BYTES = exports.ZLINK_PROVIDER_MAX_WRITE_BYTES = exports.ZLINK_PROVIDER_MAX_WRITE_KEYS = exports.ZLINK_PROVIDER_MAX_VERSION_BYTES = exports.ZLINK_PROVIDER_MAX_VALUE_BYTES = exports.ZLINK_PROVIDER_MAX_KEY_BYTES = void 0;
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+const requireFramework = (0, node_module_1.createRequire)(__filename);
+const frameworkEntry = requireFramework.resolve('@zlink-systems/framework');
+const internal = requireFramework(node_path_1.default.join(node_path_1.default.dirname(frameworkEntry), 'internal'));
+exports.ZLINK_PROVIDER_MAX_KEY_BYTES = internal.ZLINK_PROVIDER_MAX_KEY_BYTES, exports.ZLINK_PROVIDER_MAX_VALUE_BYTES = internal.ZLINK_PROVIDER_MAX_VALUE_BYTES, exports.ZLINK_PROVIDER_MAX_VERSION_BYTES = internal.ZLINK_PROVIDER_MAX_VERSION_BYTES, exports.ZLINK_PROVIDER_MAX_WRITE_KEYS = internal.ZLINK_PROVIDER_MAX_WRITE_KEYS, exports.ZLINK_PROVIDER_MAX_WRITE_BYTES = internal.ZLINK_PROVIDER_MAX_WRITE_BYTES, exports.ZLINK_PROVIDER_MAX_ENCODED_PAGE_BYTES = internal.ZLINK_PROVIDER_MAX_ENCODED_PAGE_BYTES, exports.ZLINK_PROVIDER_MAX_SCAN_CURSOR_BYTES = internal.ZLINK_PROVIDER_MAX_SCAN_CURSOR_BYTES, exports.ZLINK_PROVIDER_MAX_PAGE_SIZE = internal.ZLINK_PROVIDER_MAX_PAGE_SIZE, exports.ZLINK_RELOCATION_MAX_BLOB_REFERENCE_BYTES = internal.ZLINK_RELOCATION_MAX_BLOB_REFERENCE_BYTES;

package/dist/opaque-redis-scripts.d.ts

@@ -1,5 +1,20 @@
-export declare const OPAQUE_READ_SCRIPT: string;
-export declare const OPAQUE_WRITE_SCRIPT: string;
+export declare const REDIS_STORE_TOKEN: Readonly<{
+    readonly Conflict: "conflict";
+    readonly Backlog: "backlog";
+    readonly Applied: "applied";
+    readonly Expired: "expired";
+    readonly Capacity: "capacity";
+    readonly Page: "page";
+    readonly AlreadyStored: "alreadyStored";
+    readonly Stored: "stored";
+    readonly Missing: "missing";
+    readonly Value: "value";
+    readonly Version: "version";
+    readonly Put: "put";
+    readonly Delete: "delete";
+}>;
+export declare const OPAQUE_READ_SCRIPT: Buffer<ArrayBuffer>;
+export declare const OPAQUE_WRITE_SCRIPT: Buffer<ArrayBuffer>;
 export declare const OPAQUE_SCAN_START_SCRIPT: string;
 export declare const OPAQUE_SCAN_CONTINUE_SCRIPT: string;
 export declare const BLOB_PUT_SCRIPT: string;

package/dist/opaque-redis-scripts.js

@@ -1,10 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BLOB_RENEW_SCRIPT = exports.BLOB_READ_SCRIPT = exports.BLOB_PUT_SCRIPT = exports.OPAQUE_SCAN_CONTINUE_SCRIPT = exports.OPAQUE_SCAN_START_SCRIPT = exports.OPAQUE_WRITE_SCRIPT = exports.OPAQUE_READ_SCRIPT = void 0;
+exports.BLOB_RENEW_SCRIPT = exports.BLOB_READ_SCRIPT = exports.BLOB_PUT_SCRIPT = exports.OPAQUE_SCAN_CONTINUE_SCRIPT = exports.OPAQUE_SCAN_START_SCRIPT = exports.OPAQUE_WRITE_SCRIPT = exports.OPAQUE_READ_SCRIPT = exports.REDIS_STORE_TOKEN = void 0;
+const framework_internal_1 = require("./framework-internal");
+const REDIS_MILLISECONDS_PER_SECOND = 1000;
+const REDIS_MICROSECONDS_PER_MILLISECOND = 1000;
+const REDIS_CLEANUP_RETRY_DELAY_MS = 1000;
+const REDIS_EXPIRED_SNAPSHOT_BATCH_SIZE = 128;
+const REDIS_ROW_COMPACTION_ENTRY_LIMIT = 128;
+const REDIS_SCAN_MINIMUM_WORK_BUDGET = 128;
+const REDIS_ENCODED_ITEM_OVERHEAD_BYTES = 128;
+const REDIS_SCAN_WORK_BUDGET_MULTIPLIER = 4;
+const REDIS_CLEANUP_BATCH_SIZE = 32;
+const REDIS_RECORD_RETENTION_MS = 60000;
+const REDIS_SCAN_SNAPSHOT_RETENTION_MS = 60000;
+const REDIS_MAX_SCAN_SNAPSHOTS = 4096;
+const REDIS_UTF8_PREFIX_UPPER_BOUND_BYTE = 0xff;
+exports.REDIS_STORE_TOKEN = Object.freeze({
+    Conflict: 'conflict',
+    Backlog: 'backlog',
+    Applied: 'applied',
+    Expired: 'expired',
+    Capacity: 'capacity',
+    Page: 'page',
+    AlreadyStored: 'alreadyStored',
+    Stored: 'stored',
+    Missing: 'missing',
+    Value: 'value',
+    Version: 'version',
+    Put: 'put',
+    Delete: 'delete'
+});
 const PROLOGUE = `
 if redis.replicate_commands then redis.replicate_commands() end
 local time = redis.call('TIME')
-local nowMs = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)
+local nowMs = tonumber(time[1]) * ${REDIS_MILLISECONDS_PER_SECOND} + math.floor(tonumber(time[2]) / ${REDIS_MICROSECONDS_PER_MILLISECOND})
 `;
 // Shared decode helper. Every opaque row is a Redis ZSET append-log; the
 // member with the highest score (the provider's monotonically increasing
@@ -39,34 +68,40 @@ local function encodeMember(originalKey, bytes, version, expiresAtMs, tombstone)
     })
 end
 `;
-exports.OPAQUE_READ_SCRIPT = PROLOGUE +
+exports.OPAQUE_READ_SCRIPT = Buffer.from(PROLOGUE +
     DECODE_HELPERS +
     `
 local record = liveRecordAt(KEYS[1], nowMs)
 if not record then return {0, nowMs} end
 return {1, nowMs, record[1], record[2], record[3], tostring(tonumber(record[4]))}
-`;
+`);
 // KEYS[1..6] = indexKey, mapKey, cleanupKey, sequenceKey, snapshotExpiryKey,
 // snapshotBoundaryKey (private auxiliary keys, not part of the public
 // contract). KEYS[7..] = the opaque record row keys referenced by
 // conditions/mutations, in the order fixed by ARGV[1]/ARGV[2].
 // ARGV[1] = JSON conditions: ['missing', keyIndex, originalKey]
 //           | ['version', keyIndex, originalKey, expectedVersion]
+//           | ['value', keyIndex, originalKey, expectedBytesArgIndex]
 // ARGV[2] = JSON mutation metadata (no raw bytes, JSON must stay text-safe):
 //           ['put', keyIndex, originalKey, retentionMsOrFalse]
 //           | ['delete', keyIndex, originalKey]
-// ARGV[3..] = one raw-bytes argument per 'put' mutation, in mutation order.
-exports.OPAQUE_WRITE_SCRIPT = PROLOGUE +
-    DECODE_HELPERS +
+// ARGV[3..] = raw expected bytes for 'value' conditions, then raw bytes for
+//             'put' mutations, each in request order.
+const PRUNE_HISTORY_HELPER = `
+local function pruneHistory(rowKey, minimumBoundary)
+    if minimumBoundary then
+        local anchor = redis.call('ZREVRANGEBYSCORE', rowKey, minimumBoundary, '-inf', 'WITHSCORES', 'LIMIT', 0, 1)
+        if #anchor == 2 then
+            redis.call('ZREMRANGEBYSCORE', rowKey, '-inf', '(' .. anchor[2])
+        end
+    else
+        redis.call('ZREMRANGEBYRANK', rowKey, 0, -2)
+    end
+end
+`;
+const CLEANUP_AND_BOUNDARY = PRUNE_HISTORY_HELPER +
     `
-local indexKey = KEYS[1]
-local mapKey = KEYS[2]
-local cleanupKey = KEYS[3]
-local sequenceKey = KEYS[4]
-local snapshotExpiryKey = KEYS[5]
-local snapshotBoundaryKey = KEYS[6]
-
-local expiredSnapshots = redis.call('ZRANGEBYSCORE', snapshotExpiryKey, '-inf', nowMs, 'LIMIT', 0, 128)
+local expiredSnapshots = redis.call('ZRANGEBYSCORE', snapshotExpiryKey, '-inf', nowMs, 'LIMIT', 0, ${REDIS_EXPIRED_SNAPSHOT_BATCH_SIZE})
 for _, snapshotId in ipairs(expiredSnapshots) do
     redis.call('ZREM', snapshotExpiryKey, snapshotId)
     redis.call('ZREM', snapshotBoundaryKey, snapshotId)
@@ -75,7 +110,7 @@ local minimumBoundary = nil
 local boundaryEntry = redis.call('ZRANGE', snapshotBoundaryKey, 0, 0, 'WITHSCORES')
 if #boundaryEntry == 2 then minimumBoundary = tonumber(boundaryEntry[2]) end
 
-local due = redis.call('ZRANGEBYSCORE', cleanupKey, '-inf', nowMs, 'LIMIT', 0, 32)
+local due = redis.call('ZRANGEBYSCORE', cleanupKey, '-inf', nowMs, 'LIMIT', 0, ${REDIS_CLEANUP_BATCH_SIZE})
 for _, original in ipairs(due) do
     local rowKey = redis.call('HGET', mapKey, original)
     local members = {}
@@ -87,23 +122,20 @@ for _, original in ipairs(due) do
         redis.call('HDEL', mapKey, original)
         redis.call('ZREM', cleanupKey, original)
     elseif minimumBoundary then
-        local anchor = redis.call('ZREVRANGEBYSCORE', rowKey, minimumBoundary, '-inf', 'WITHSCORES', 'LIMIT', 0, 1)
-        if #anchor == 2 then
-            redis.call('ZREMRANGEBYSCORE', rowKey, '-inf', '(' .. anchor[2])
-        end
-        redis.call('ZADD', cleanupKey, nowMs + 1000, original)
+        pruneHistory(rowKey, minimumBoundary)
+        redis.call('ZADD', cleanupKey, nowMs + ${REDIS_CLEANUP_RETRY_DELAY_MS}, original)
     else
         local record = decodeMember(members[1])
         local expiresAtMs = tonumber(record[4])
-        if record[5] == true or (expiresAtMs > 0 and expiresAtMs + 60000 <= nowMs) then
+        if record[5] == true or (expiresAtMs > 0 and expiresAtMs + ${REDIS_RECORD_RETENTION_MS} <= nowMs) then
             redis.call('DEL', rowKey)
             redis.call('ZREM', indexKey, original)
             redis.call('HDEL', mapKey, original)
             redis.call('ZREM', cleanupKey, original)
         else
-            redis.call('ZREMRANGEBYRANK', rowKey, 0, -2)
+            pruneHistory(rowKey, minimumBoundary)
             if expiresAtMs > 0 then
-                redis.call('ZADD', cleanupKey, math.max(nowMs + 1000, expiresAtMs + 60000), original)
+                redis.call('ZADD', cleanupKey, math.max(nowMs + ${REDIS_CLEANUP_RETRY_DELAY_MS}, expiresAtMs + ${REDIS_RECORD_RETENTION_MS}), original)
             else
                 redis.call('ZREM', cleanupKey, original)
             end
@@ -111,36 +143,55 @@ for _, original in ipairs(due) do
     end
 end
 
+`;
+exports.OPAQUE_WRITE_SCRIPT = Buffer.from(PROLOGUE +
+    DECODE_HELPERS +
+    `
+local indexKey = KEYS[1]
+local mapKey = KEYS[2]
+local cleanupKey = KEYS[3]
+local sequenceKey = KEYS[4]
+local snapshotExpiryKey = KEYS[5]
+local snapshotBoundaryKey = KEYS[6]
+
+` +
+    CLEANUP_AND_BOUNDARY +
+    `
 local conditions = cjson.decode(ARGV[1])
 local mutations = cjson.decode(ARGV[2])
 
 for _, condition in ipairs(conditions) do
     local record = liveRecordAt(KEYS[condition[2] + 6], nowMs)
     local currentVersion = record and record[3] or nil
-    if condition[1] == 'missing' then
-        if currentVersion ~= nil then return {'conflict', nowMs} end
+    if condition[1] == '${exports.REDIS_STORE_TOKEN.Missing}' then
+        if currentVersion ~= nil then return {'${exports.REDIS_STORE_TOKEN.Conflict}', nowMs} end
+    elseif condition[1] == '${exports.REDIS_STORE_TOKEN.Value}' then
+        if not record or record[2] ~= ARGV[condition[4]] then
+            return {'${exports.REDIS_STORE_TOKEN.Conflict}', nowMs}
+        end
     elseif currentVersion ~= condition[4] then
-        return {'conflict', nowMs}
+        return {'${exports.REDIS_STORE_TOKEN.Conflict}', nowMs}
     end
 end
 
 for _, mutation in ipairs(mutations) do
     local rowKey = KEYS[mutation[2] + 6]
-    if not minimumBoundary then
-        redis.call('ZREMRANGEBYRANK', rowKey, 0, -2)
-    end
-    if redis.call('ZCARD', rowKey) >= 128 then
-        return {'backlog', nowMs}
+    pruneHistory(rowKey, minimumBoundary)
+    if redis.call('ZCARD', rowKey) >= ${REDIS_ROW_COMPACTION_ENTRY_LIMIT} then
+        return {'${exports.REDIS_STORE_TOKEN.Backlog}', nowMs}
     end
 end
 
 local sequence = tostring(redis.call('INCR', sequenceKey))
 local byteArg = 3
-local result = {'applied', nowMs}
+for _, condition in ipairs(conditions) do
+    if condition[1] == '${exports.REDIS_STORE_TOKEN.Value}' then byteArg = byteArg + 1 end
+end
+local result = {'${exports.REDIS_STORE_TOKEN.Applied}', nowMs}
 for _, mutation in ipairs(mutations) do
     local rowKey = KEYS[mutation[2] + 6]
     local originalKey = mutation[3]
-    if mutation[1] == 'put' then
+    if mutation[1] == '${exports.REDIS_STORE_TOKEN.Put}' then
         local bytes = ARGV[byteArg]
         byteArg = byteArg + 1
         local retention = mutation[4]
@@ -156,105 +207,66 @@ for _, mutation in ipairs(mutations) do
         redis.call('ZADD', indexKey, 0, originalKey)
         redis.call('HSET', mapKey, originalKey, rowKey)
     end
-    local dueAt = nowMs + 1000
+    local dueAt = nowMs + ${REDIS_CLEANUP_RETRY_DELAY_MS}
     local scheduled = redis.call('ZSCORE', cleanupKey, originalKey)
     if not scheduled or tonumber(scheduled) > dueAt then
         redis.call('ZADD', cleanupKey, dueAt, originalKey)
     end
 end
 return result
-`;
+`);
 // Shared body for point-in-time paged scanning. KEYS[1]=indexKey,
 // KEYS[2]=mapKey, KEYS[3]=snapshotKey, KEYS[4]=cleanupKey,
 // KEYS[5]=sequenceKey, KEYS[6]=snapshotExpiryKey, KEYS[7]=snapshotBoundaryKey.
 const SCAN_CLEANUP_AND_BOUNDARY = DECODE_HELPERS +
     `
-local expiredSnapshots = redis.call('ZRANGEBYSCORE', KEYS[6], '-inf', nowMs, 'LIMIT', 0, 128)
-for _, expiredId in ipairs(expiredSnapshots) do
-    redis.call('ZREM', KEYS[6], expiredId)
-    redis.call('ZREM', KEYS[7], expiredId)
-end
-local minimumBoundary = nil
-local boundaryEntry = redis.call('ZRANGE', KEYS[7], 0, 0, 'WITHSCORES')
-if #boundaryEntry == 2 then minimumBoundary = tonumber(boundaryEntry[2]) end
-
-local due = redis.call('ZRANGEBYSCORE', KEYS[4], '-inf', nowMs, 'LIMIT', 0, 32)
-for _, original in ipairs(due) do
-    local rowKey = redis.call('HGET', KEYS[2], original)
-    local members = {}
-    if rowKey then
-        members = redis.call('ZREVRANGE', rowKey, 0, 0, 'WITHSCORES')
-    end
-    if #members == 0 then
-        redis.call('ZREM', KEYS[1], original)
-        redis.call('HDEL', KEYS[2], original)
-        redis.call('ZREM', KEYS[4], original)
-    elseif minimumBoundary then
-        local anchor = redis.call('ZREVRANGEBYSCORE', rowKey, minimumBoundary, '-inf', 'WITHSCORES', 'LIMIT', 0, 1)
-        if #anchor == 2 then
-            redis.call('ZREMRANGEBYSCORE', rowKey, '-inf', '(' .. anchor[2])
-        end
-        redis.call('ZADD', KEYS[4], nowMs + 1000, original)
-    else
-        local record = decodeMember(members[1])
-        local expiresAtMs = tonumber(record[4])
-        if record[5] == true or (expiresAtMs > 0 and expiresAtMs + 60000 <= nowMs) then
-            redis.call('DEL', rowKey)
-            redis.call('ZREM', KEYS[1], original)
-            redis.call('HDEL', KEYS[2], original)
-            redis.call('ZREM', KEYS[4], original)
-        else
-            redis.call('ZREMRANGEBYRANK', rowKey, 0, -2)
-            if expiresAtMs > 0 then
-                redis.call('ZADD', KEYS[4], math.max(nowMs + 1000, expiresAtMs + 60000), original)
-            else
-                redis.call('ZREM', KEYS[4], original)
-            end
-        end
-    end
-end
-`;
+local indexKey = KEYS[1]
+local mapKey = KEYS[2]
+local cleanupKey = KEYS[4]
+local snapshotExpiryKey = KEYS[6]
+local snapshotBoundaryKey = KEYS[7]
+` +
+    CLEANUP_AND_BOUNDARY;
 const SCAN_PAGE_READ = `
 local metadata = redis.call('HMGET', KEYS[3], 'now', 'boundary', 'prefix')
 if not metadata[1] or metadata[3] ~= prefix then
     redis.call('ZREM', KEYS[6], snapshotId)
     redis.call('ZREM', KEYS[7], snapshotId)
-    return {'expired'}
+    return {'${exports.REDIS_STORE_TOKEN.Expired}'}
 end
 local snapshotNow = tonumber(metadata[1])
 local boundary = tonumber(metadata[2])
-local lower = '-'
+local lower = '[' .. prefix
+local upper = '[' .. prefix .. string.char(${REDIS_UTF8_PREFIX_UPPER_BOUND_BYTE})
 if string.len(lastKey) > 0 then lower = '(' .. lastKey end
-local workLimit = math.max(limit * 4, 128)
-local originals = redis.call('ZRANGEBYLEX', KEYS[1], lower, '+', 'LIMIT', 0, workLimit + 1)
+local workLimit = math.max(limit * ${REDIS_SCAN_WORK_BUDGET_MULTIPLIER}, ${REDIS_SCAN_MINIMUM_WORK_BUDGET})
+local originals = redis.call('ZRANGEBYLEX', KEYS[1], lower, upper, 'LIMIT', 0, workLimit + 1)
 local emitted = 0
 local encodedBytes = 0
 local examined = 0
-local result = {'page', tostring(snapshotNow), ''}
+local result = {'${exports.REDIS_STORE_TOKEN.Page}', tostring(snapshotNow), ''}
 while examined < #originals and examined < workLimit and emitted < limit do
     local original = originals[examined + 1]
     examined = examined + 1
-    if string.sub(original, 1, string.len(prefix)) == prefix then
-        local rowKey = redis.call('HGET', KEYS[2], original)
-        if rowKey then
-            local members = redis.call('ZREVRANGEBYSCORE', rowKey, boundary, '-inf', 'LIMIT', 0, 1)
-            if #members > 0 then
-                local record = decodeMember(members[1])
-                local expiresAtMs = tonumber(record[4])
-                if record[1] == original and record[5] ~= true
-                    and (expiresAtMs == 0 or expiresAtMs > snapshotNow) then
-                    local itemBytes = string.len(original) + string.len(record[2]) + string.len(record[3]) + 128
-                    if emitted > 0 and encodedBytes + itemBytes > 4194304 then
-                        examined = examined - 1
-                        break
-                    end
-                    table.insert(result, original)
-                    table.insert(result, record[2])
-                    table.insert(result, record[3])
-                    table.insert(result, tostring(expiresAtMs))
-                    encodedBytes = encodedBytes + itemBytes
-                    emitted = emitted + 1
+    local rowKey = redis.call('HGET', KEYS[2], original)
+    if rowKey then
+        local members = redis.call('ZREVRANGEBYSCORE', rowKey, boundary, '-inf', 'LIMIT', 0, 1)
+        if #members > 0 then
+            local record = decodeMember(members[1])
+            local expiresAtMs = tonumber(record[4])
+            if record[1] == original and record[5] ~= true
+                and (expiresAtMs == 0 or expiresAtMs > snapshotNow) then
+                local itemBytes = string.len(original) + string.len(record[2]) + string.len(record[3]) + ${REDIS_ENCODED_ITEM_OVERHEAD_BYTES}
+                if emitted > 0 and encodedBytes + itemBytes > ${framework_internal_1.ZLINK_PROVIDER_MAX_ENCODED_PAGE_BYTES} then
+                    examined = examined - 1
+                    break
                 end
+                table.insert(result, original)
+                table.insert(result, record[2])
+                table.insert(result, record[3])
+                table.insert(result, tostring(expiresAtMs))
+                encodedBytes = encodedBytes + itemBytes
+                emitted = emitted + 1
             end
         end
     end
@@ -280,14 +292,14 @@ local limit = tonumber(ARGV[2])
 local snapshotId = ARGV[3]
 local lastKey = ''
 
-if redis.call('ZCARD', KEYS[6]) >= 4096 then
-    return {'capacity'}
+if redis.call('ZCARD', KEYS[6]) >= ${REDIS_MAX_SCAN_SNAPSHOTS} then
+    return {'${exports.REDIS_STORE_TOKEN.Capacity}'}
 end
 redis.call('DEL', KEYS[3])
 local boundary = tonumber(redis.call('GET', KEYS[5]) or '0')
 redis.call('HSET', KEYS[3], 'now', tostring(nowMs), 'boundary', tostring(boundary), 'prefix', prefix)
-redis.call('PEXPIRE', KEYS[3], 60000)
-redis.call('ZADD', KEYS[6], nowMs + 60000, snapshotId)
+redis.call('PEXPIRE', KEYS[3], ${REDIS_SCAN_SNAPSHOT_RETENTION_MS})
+redis.call('ZADD', KEYS[6], nowMs + ${REDIS_SCAN_SNAPSHOT_RETENTION_MS}, snapshotId)
 redis.call('ZADD', KEYS[7], boundary, snapshotId)
 ` +
     SCAN_PAGE_READ;
@@ -303,7 +315,7 @@ local snapshotId = ARGV[4]
 if redis.call('EXISTS', KEYS[3]) == 0 then
     redis.call('ZREM', KEYS[6], snapshotId)
     redis.call('ZREM', KEYS[7], snapshotId)
-    return {'expired'}
+    return {'${exports.REDIS_STORE_TOKEN.Expired}'}
 end
 ` +
     SCAN_PAGE_READ;
@@ -317,15 +329,15 @@ exports.BLOB_PUT_SCRIPT = PROLOGUE +
 local existing = redis.call('GET', KEYS[1])
 if existing then
     if existing ~= ARGV[1] then
-        return {'conflict', nowMs}
+        return {'${exports.REDIS_STORE_TOKEN.Conflict}', nowMs}
     end
     local ttl = redis.call('PTTL', KEYS[1])
     local expiresAtMs = nowMs + math.max(ttl, 0)
-    return {'alreadyStored', nowMs, tostring(expiresAtMs)}
+    return {'${exports.REDIS_STORE_TOKEN.AlreadyStored}', nowMs, tostring(expiresAtMs)}
 end
 local retentionMs = tonumber(ARGV[2])
 redis.call('SET', KEYS[1], ARGV[1], 'PX', retentionMs)
-return {'stored', nowMs, tostring(nowMs + retentionMs)}
+return {'${exports.REDIS_STORE_TOKEN.Stored}', nowMs, tostring(nowMs + retentionMs)}
 `;
 exports.BLOB_READ_SCRIPT = PROLOGUE +
     `

package/dist/opaque-store.js

@@ -1,13 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkRedisLocationStore = void 0;
+const framework_internal_1 = require("./framework-internal");
 const node_crypto_1 = require("node:crypto");
 const redis_connection_1 = require("./redis-connection");
 const opaque_redis_scripts_1 = require("./opaque-redis-scripts");
 const redis_values_1 = require("./redis-values");
-const MAX_VALUE_BYTES = 1024 * 1024;
-const MAX_WRITE_KEYS = 2_048;
-const MAX_WRITE_BYTES = 4 * 1024 * 1024;
 // {prefix}:{zlink-location-v3}:opaque:{sha256hex(preimage)} is the public
 // contract (21-location-runtime.md#2.4, 22-location-store-redis.md#7). The
 // braces are a Redis Cluster hash tag: every key this provider's scripts
@@ -54,16 +52,17 @@ class ZLinkRedisLocationStore {
         ], [
             JSON.stringify(encoded.conditions),
             JSON.stringify(encoded.mutations),
+            ...encoded.expectedBytes,
             ...encoded.putBytes
         ], signal));
         const storeNow = fromUnixMs((0, redis_values_1.toNumber)(result[1]));
         const outcome = (0, redis_values_1.asString)(result[0]);
-        if (outcome === 'conflict')
+        if (outcome === opaque_redis_scripts_1.REDIS_STORE_TOKEN.Conflict)
             return { kind: 'conflict', storeNow };
-        if (outcome === 'backlog') {
+        if (outcome === opaque_redis_scripts_1.REDIS_STORE_TOKEN.Backlog) {
             throw new Error('Redis Location Store version backlog is full.');
         }
-        if (outcome !== 'applied') {
+        if (outcome !== opaque_redis_scripts_1.REDIS_STORE_TOKEN.Applied) {
             throw new Error('Redis Location Store returned an unrecognized write outcome.');
         }
         const putVersions = [];
@@ -82,6 +81,9 @@ class ZLinkRedisLocationStore {
             return await this.readScanPage(snapshotId, await this.connection.eval(opaque_redis_scripts_1.OPAQUE_SCAN_START_SCRIPT, this.scanKeys(snapshotId), [request.prefix, String(request.limit), snapshotId], signal));
         }
         const cursor = parseCursor(request.cursor);
+        if (cursor === undefined) {
+            return { kind: 'expired' };
+        }
         return await this.readScanPage(cursor.snapshotId, await this.connection.eval(opaque_redis_scripts_1.OPAQUE_SCAN_CONTINUE_SCRIPT, this.scanKeys(cursor.snapshotId), [request.prefix, cursor.lastKey, String(request.limit), cursor.snapshotId], signal));
     }
     async dispose() {
@@ -90,12 +92,12 @@ class ZLinkRedisLocationStore {
     async readScanPage(snapshotId, raw) {
         const result = (0, redis_values_1.asArray)(raw);
         const outcome = (0, redis_values_1.asString)(result[0]);
-        if (outcome === 'expired')
+        if (outcome === opaque_redis_scripts_1.REDIS_STORE_TOKEN.Expired)
             return { kind: 'expired' };
-        if (outcome === 'capacity') {
+        if (outcome === opaque_redis_scripts_1.REDIS_STORE_TOKEN.Capacity) {
             throw new Error('Redis Location Store snapshot capacity is full.');
         }
-        if (outcome !== 'page') {
+        if (outcome !== opaque_redis_scripts_1.REDIS_STORE_TOKEN.Page) {
             throw new Error('Redis Location Store returned an unrecognized scan outcome.');
         }
         const storeNow = fromUnixMs((0, redis_values_1.toNumber)(result[1]));
@@ -168,44 +170,53 @@ function encodeWrite(request) {
         throw new RangeError('Location Store condition and mutation keys must be unique.');
     }
     const keys = [...new Set([...conditionKeys, ...mutationKeys])];
-    if (keys.length > MAX_WRITE_KEYS) {
-        throw new RangeError('Location Store write exceeds 2,048 unique keys.');
+    if (keys.length > framework_internal_1.ZLINK_PROVIDER_MAX_WRITE_KEYS) {
+        throw new RangeError(`Location Store write exceeds ${framework_internal_1.ZLINK_PROVIDER_MAX_WRITE_KEYS.toLocaleString('en-US')} unique keys.`);
     }
     // Row keys are appended after the six fixed auxiliary keys; the script
     // adds 6 to this 1-based index before indexing into KEYS.
     const keyIndex = new Map(keys.map((key, index) => [key, index + 1]));
     let encodedBytes = 0;
+    const expectedBytes = [];
     const conditions = request.conditions.map((condition) => {
         const key = requireKey(condition.key);
         encodedBytes += Buffer.byteLength(key, 'utf8');
         if (condition.kind === 'missing')
-            return ['missing', keyIndex.get(key), key];
+            return [opaque_redis_scripts_1.REDIS_STORE_TOKEN.Missing, keyIndex.get(key), key];
+        if (condition.kind === 'value') {
+            requireValue(condition.expected, undefined);
+            encodedBytes += condition.expected.byteLength;
+            expectedBytes.push(Buffer.from(condition.expected));
+            return [opaque_redis_scripts_1.REDIS_STORE_TOKEN.Value, keyIndex.get(key), key, expectedBytes.length + 2];
+        }
         const expected = requireVersion(condition.expected);
         encodedBytes += Buffer.byteLength(expected, 'utf8');
-        return ['version', keyIndex.get(key), key, expected];
+        return [opaque_redis_scripts_1.REDIS_STORE_TOKEN.Version, keyIndex.get(key), key, expected];
     });
     const putBytes = [];
     const mutations = request.mutations.map((mutation) => {
         const key = requireKey(mutation.key);
         encodedBytes += Buffer.byteLength(key, 'utf8');
         if (mutation.kind === 'delete')
-            return ['delete', keyIndex.get(key), key];
-        requireValue(mutation.bytes, mutation.retentionMs);
+            return [opaque_redis_scripts_1.REDIS_STORE_TOKEN.Delete, keyIndex.get(key), key];
+        const retentionMs = requireValue(mutation.bytes, mutation.retentionMs);
         encodedBytes += mutation.bytes.byteLength;
         putBytes.push(Buffer.from(mutation.bytes));
-        return ['put', keyIndex.get(key), key, mutation.retentionMs ?? false];
+        return [opaque_redis_scripts_1.REDIS_STORE_TOKEN.Put, keyIndex.get(key), key, retentionMs ?? false];
     });
-    if (encodedBytes > MAX_WRITE_BYTES) {
-        throw new RangeError('Location Store write exceeds 4 MiB encoded input.');
+    if (encodedBytes > framework_internal_1.ZLINK_PROVIDER_MAX_WRITE_BYTES) {
+        throw new RangeError(`Location Store write exceeds ${framework_internal_1.ZLINK_PROVIDER_MAX_WRITE_BYTES / (1024 * 1024)} MiB encoded input.`);
     }
-    return { keys, conditions, mutations, putBytes };
+    return { keys, conditions, mutations, expectedBytes, putBytes };
 }
 function requireScanRequest(request) {
-    if (Buffer.byteLength(request.prefix, 'utf8') > 1_024) {
-        throw new RangeError('Location Store scan prefix exceeds 1,024 UTF-8 bytes.');
+    if (Buffer.byteLength(request.prefix, 'utf8') > framework_internal_1.ZLINK_PROVIDER_MAX_KEY_BYTES) {
+        throw new RangeError(`Location Store scan prefix exceeds ${framework_internal_1.ZLINK_PROVIDER_MAX_KEY_BYTES.toLocaleString('en-US')} UTF-8 bytes.`);
     }
-    if (!Number.isSafeInteger(request.limit) || request.limit < 1 || request.limit > 1_000) {
-        throw new RangeError('Location Store scan limit must be in 1..1000.');
+    if (!Number.isSafeInteger(request.limit) ||
+        request.limit < 1 ||
+        request.limit > framework_internal_1.ZLINK_PROVIDER_MAX_PAGE_SIZE) {
+        throw new RangeError(`Location Store scan limit must be in 1..${framework_internal_1.ZLINK_PROVIDER_MAX_PAGE_SIZE}.`);
     }
     if (request.cursor !== undefined)
         requireCursor(request.cursor);
@@ -213,8 +224,8 @@ function requireScanRequest(request) {
 function requireKey(key) {
     const value = key.value;
     const bytes = Buffer.byteLength(value, 'utf8');
-    if (bytes < 1 || bytes > 1_024) {
-        throw new RangeError('Location Store key must contain 1..1,024 UTF-8 bytes.');
+    if (bytes < 1 || bytes > framework_internal_1.ZLINK_PROVIDER_MAX_KEY_BYTES) {
+        throw new RangeError(`Location Store key must contain 1..${framework_internal_1.ZLINK_PROVIDER_MAX_KEY_BYTES.toLocaleString('en-US')} UTF-8 bytes.`);
     }
     return value;
 }
@@ -226,36 +237,40 @@ function requireMatchingKey(actual, expected) {
 function requireVersion(version) {
     const value = version.value;
     const bytes = Buffer.byteLength(value, 'utf8');
-    if (bytes < 1 || bytes > 4_096) {
-        throw new RangeError('Location Store version must contain 1..4,096 UTF-8 bytes.');
+    if (bytes < 1 || bytes > framework_internal_1.ZLINK_PROVIDER_MAX_VERSION_BYTES) {
+        throw new RangeError(`Location Store version must contain 1..${framework_internal_1.ZLINK_PROVIDER_MAX_VERSION_BYTES.toLocaleString('en-US')} UTF-8 bytes.`);
     }
     return value;
 }
 function requireCursor(cursor) {
     const value = cursor.value;
     const bytes = Buffer.byteLength(value, 'utf8');
-    if (bytes < 1 || bytes > 4_096) {
-        throw new RangeError('Location Store cursor must contain 1..4,096 UTF-8 bytes.');
+    if (bytes < 1 || bytes > framework_internal_1.ZLINK_PROVIDER_MAX_SCAN_CURSOR_BYTES) {
+        throw new RangeError(`Location Store cursor must contain 1..${framework_internal_1.ZLINK_PROVIDER_MAX_SCAN_CURSOR_BYTES.toLocaleString('en-US')} UTF-8 bytes.`);
     }
     return value;
 }
 function requireValue(bytes, retentionMs) {
-    if (bytes.byteLength > MAX_VALUE_BYTES) {
-        throw new RangeError('Location Store value exceeds 1 MiB.');
+    if (bytes.byteLength > framework_internal_1.ZLINK_PROVIDER_MAX_VALUE_BYTES) {
+        throw new RangeError(`Location Store value exceeds ${framework_internal_1.ZLINK_PROVIDER_MAX_VALUE_BYTES / (1024 * 1024)} MiB.`);
     }
-    if (retentionMs !== undefined && (!Number.isSafeInteger(retentionMs) || retentionMs < 1)) {
-        throw new RangeError('Location Store retention must be a positive safe integer.');
+    if (retentionMs !== undefined &&
+        (!Number.isFinite(retentionMs) ||
+            retentionMs <= 0 ||
+            !Number.isSafeInteger(Math.ceil(retentionMs)))) {
+        throw new RangeError('Location Store retention must round to a positive safe integer.');
     }
+    return retentionMs === undefined ? undefined : Math.ceil(retentionMs);
 }
 function parseCursor(cursor) {
-    const value = requireCursor(cursor);
+    const value = cursor.value;
     const separator = value.lastIndexOf(':');
     const snapshotId = separator < 0 ? '' : value.slice(0, separator);
     const lastKeyHex = separator < 0 ? '' : value.slice(separator + 1);
     if (!/^[0-9a-f-]{36}$/.test(snapshotId) ||
         !/^[0-9a-f]*$/.test(lastKeyHex) ||
         lastKeyHex.length % 2 !== 0) {
-        throw new RangeError('Location Store scan cursor is invalid.');
+        return undefined;
     }
     return { snapshotId, lastKey: Buffer.from(lastKeyHex, 'hex').toString('utf8') };
 }

package/dist/redis-connection.d.ts

@@ -10,7 +10,7 @@ export declare class RedisConnection {
     private readonly operationTimeoutMs?;
     constructor(options: ZLinkRedisLocationOptions | ZLinkRedisRelocationOptions);
     command(args: RedisCommandValue[], signal?: AbortSignal): Promise<unknown>;
-    eval(script: string, keys: readonly string[], args: readonly RedisCommandValue[], signal?: AbortSignal): Promise<unknown>;
+    eval(script: RedisCommandValue, keys: readonly string[], args: readonly RedisCommandValue[], signal?: AbortSignal): Promise<unknown>;
     dispose(): Promise<void>;
     private connected;
 }