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

package/src/opaque-store.ts

@@ -1,3 +1,12 @@
+import {
+  ZLINK_PROVIDER_MAX_KEY_BYTES,
+  ZLINK_PROVIDER_MAX_VALUE_BYTES,
+  ZLINK_PROVIDER_MAX_VERSION_BYTES,
+  ZLINK_PROVIDER_MAX_WRITE_KEYS,
+  ZLINK_PROVIDER_MAX_WRITE_BYTES,
+  ZLINK_PROVIDER_MAX_SCAN_CURSOR_BYTES,
+  ZLINK_PROVIDER_MAX_PAGE_SIZE
+} from './framework-internal';
 import { createHash, randomUUID } from 'node:crypto';
 import type {
   ZLinkLocationStore,
@@ -13,6 +22,7 @@ import type {
 import type { ZLinkRedisLocationOptions } from './redis-options';
 import { RedisConnection } from './redis-connection';
 import {
+  REDIS_STORE_TOKEN,
   OPAQUE_READ_SCRIPT,
   OPAQUE_SCAN_CONTINUE_SCRIPT,
   OPAQUE_SCAN_START_SCRIPT,
@@ -20,10 +30,6 @@ import {
 } from './opaque-redis-scripts';
 import { asArray, asString, toNumber } from './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
@@ -82,6 +88,7 @@ export class ZLinkRedisLocationStore implements ZLinkLocationStore {
         [
           JSON.stringify(encoded.conditions),
           JSON.stringify(encoded.mutations),
+          ...encoded.expectedBytes,
           ...encoded.putBytes
         ],
         signal
@@ -89,11 +96,11 @@ export class ZLinkRedisLocationStore implements ZLinkLocationStore {
     );
     const storeNow = fromUnixMs(toNumber(result[1]));
     const outcome = asString(result[0]);
-    if (outcome === 'conflict') return { kind: 'conflict', storeNow };
-    if (outcome === 'backlog') {
+    if (outcome === REDIS_STORE_TOKEN.Conflict) return { kind: 'conflict', storeNow };
+    if (outcome === REDIS_STORE_TOKEN.Backlog) {
       throw new Error('Redis Location Store version backlog is full.');
     }
-    if (outcome !== 'applied') {
+    if (outcome !== REDIS_STORE_TOKEN.Applied) {
       throw new Error('Redis Location Store returned an unrecognized write outcome.');
     }
     const putVersions = [];
@@ -121,6 +128,9 @@ export class ZLinkRedisLocationStore implements ZLinkLocationStore {
       );
     }
     const cursor = parseCursor(request.cursor);
+    if (cursor === undefined) {
+      return { kind: 'expired' };
+    }
     return await this.readScanPage(
       cursor.snapshotId,
       await this.connection.eval(
@@ -139,11 +149,11 @@ export class ZLinkRedisLocationStore implements ZLinkLocationStore {
   private async readScanPage(snapshotId: string, raw: unknown): Promise<ZLinkStoreScanResult> {
     const result = asArray(raw);
     const outcome = asString(result[0]);
-    if (outcome === 'expired') return { kind: 'expired' };
-    if (outcome === 'capacity') {
+    if (outcome === REDIS_STORE_TOKEN.Expired) return { kind: 'expired' };
+    if (outcome === REDIS_STORE_TOKEN.Capacity) {
       throw new Error('Redis Location Store snapshot capacity is full.');
     }
-    if (outcome !== 'page') {
+    if (outcome !== REDIS_STORE_TOKEN.Page) {
       throw new Error('Redis Location Store returned an unrecognized scan outcome.');
     }
     const storeNow = fromUnixMs(toNumber(result[1]));
@@ -222,6 +232,7 @@ interface EncodedWrite {
   readonly keys: readonly string[];
   readonly conditions: readonly unknown[];
   readonly mutations: readonly unknown[];
+  readonly expectedBytes: readonly Buffer[];
   readonly putBytes: readonly Buffer[];
 }
 
@@ -235,43 +246,62 @@ function encodeWrite(request: ZLinkStoreWriteRequest): EncodedWrite {
     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 > ZLINK_PROVIDER_MAX_WRITE_KEYS) {
+    throw new RangeError(
+      `Location Store write exceeds ${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: Buffer[] = [];
   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];
+    if (condition.kind === 'missing') return [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 [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 [REDIS_STORE_TOKEN.Version, keyIndex.get(key), key, expected];
   });
   const putBytes: Buffer[] = [];
   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);
+    if (mutation.kind === 'delete') return [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 [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 > ZLINK_PROVIDER_MAX_WRITE_BYTES) {
+    throw new RangeError(
+      `Location Store write exceeds ${ZLINK_PROVIDER_MAX_WRITE_BYTES / (1024 * 1024)} MiB encoded input.`
+    );
   }
-  return { keys, conditions, mutations, putBytes };
+  return { keys, conditions, mutations, expectedBytes, putBytes };
 }
 
 function requireScanRequest(request: ZLinkStoreScanRequest): void {
-  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') > ZLINK_PROVIDER_MAX_KEY_BYTES) {
+    throw new RangeError(
+      `Location Store scan prefix exceeds ${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 > ZLINK_PROVIDER_MAX_PAGE_SIZE
+  ) {
+    throw new RangeError(
+      `Location Store scan limit must be in 1..${ZLINK_PROVIDER_MAX_PAGE_SIZE}.`
+    );
   }
   if (request.cursor !== undefined) requireCursor(request.cursor);
 }
@@ -279,8 +309,10 @@ function requireScanRequest(request: ZLinkStoreScanRequest): void {
 function requireKey(key: ZLinkStoreKey): string {
   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 > ZLINK_PROVIDER_MAX_KEY_BYTES) {
+    throw new RangeError(
+      `Location Store key must contain 1..${ZLINK_PROVIDER_MAX_KEY_BYTES.toLocaleString('en-US')} UTF-8 bytes.`
+    );
   }
   return value;
 }
@@ -294,8 +326,10 @@ function requireMatchingKey(actual: string, expected: string): void {
 function requireVersion(version: ZLinkStoreVersion): string {
   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 > ZLINK_PROVIDER_MAX_VERSION_BYTES) {
+    throw new RangeError(
+      `Location Store version must contain 1..${ZLINK_PROVIDER_MAX_VERSION_BYTES.toLocaleString('en-US')} UTF-8 bytes.`
+    );
   }
   return value;
 }
@@ -303,26 +337,38 @@ function requireVersion(version: ZLinkStoreVersion): string {
 function requireCursor(cursor: ZLinkStoreScanCursor): string {
   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 > ZLINK_PROVIDER_MAX_SCAN_CURSOR_BYTES) {
+    throw new RangeError(
+      `Location Store cursor must contain 1..${ZLINK_PROVIDER_MAX_SCAN_CURSOR_BYTES.toLocaleString('en-US')} UTF-8 bytes.`
+    );
   }
   return value;
 }
 
-function requireValue(bytes: Uint8Array, retentionMs: number | undefined): void {
-  if (bytes.byteLength > MAX_VALUE_BYTES) {
-    throw new RangeError('Location Store value exceeds 1 MiB.');
+function requireValue(bytes: Uint8Array, retentionMs: number | undefined): number | undefined {
+  if (bytes.byteLength > ZLINK_PROVIDER_MAX_VALUE_BYTES) {
+    throw new RangeError(
+      `Location Store value exceeds ${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: ZLinkStoreScanCursor): {
-  readonly snapshotId: string;
-  readonly lastKey: string;
-} {
-  const value = requireCursor(cursor);
+function parseCursor(cursor: ZLinkStoreScanCursor):
+  | {
+      readonly snapshotId: string;
+      readonly lastKey: string;
+    }
+  | undefined {
+  const value = cursor.value;
   const separator = value.lastIndexOf(':');
   const snapshotId = separator < 0 ? '' : value.slice(0, separator);
   const lastKeyHex = separator < 0 ? '' : value.slice(separator + 1);
@@ -331,7 +377,7 @@ function parseCursor(cursor: ZLinkStoreScanCursor): {
     !/^[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/src/redis-connection.ts

@@ -48,7 +48,7 @@ export class RedisConnection {
   }
 
   async eval(
-    script: string,
+    script: RedisCommandValue,
     keys: readonly string[],
     args: readonly RedisCommandValue[],
     signal?: AbortSignal

package/src/relocation-store.ts

@@ -1,3 +1,4 @@
+import { ZLINK_RELOCATION_MAX_BLOB_REFERENCE_BYTES } from './framework-internal';
 import type {
   ZLinkBlobPutResult,
   ZLinkBlobReadResult,
@@ -7,7 +8,12 @@ import type {
 } from '@zlink-systems/framework';
 import type { ZLinkRedisRelocationOptions } from './redis-options';
 import { RedisConnection } from './redis-connection';
-import { BLOB_PUT_SCRIPT, BLOB_READ_SCRIPT, BLOB_RENEW_SCRIPT } from './opaque-redis-scripts';
+import {
+  REDIS_STORE_TOKEN,
+  BLOB_PUT_SCRIPT,
+  BLOB_READ_SCRIPT,
+  BLOB_RENEW_SCRIPT
+} from './opaque-redis-scripts';
 import { asArray, asString, toNumber } from './redis-values';
 
 const MAX_ENCODED_BLOB_BYTES = 64 * 1024 * 1024 + 23;
@@ -42,11 +48,11 @@ export class ZLinkRedisRelocationStore implements ZLinkRelocationStore {
         signal
       )
     );
-    const kind = asString(result[0]);
+    const outcome = asString(result[0]);
     const storeNow = fromUnixMs(toNumber(result[1]));
-    if (kind === 'conflict') return { kind, storeNow };
+    if (outcome === REDIS_STORE_TOKEN.Conflict) return { kind: 'conflict', storeNow };
     return {
-      kind: kind === 'alreadyStored' ? 'alreadyStored' : 'stored',
+      kind: outcome === REDIS_STORE_TOKEN.AlreadyStored ? 'alreadyStored' : 'stored',
       storeNow,
       expiresAt: fromUnixMs(toNumber(result[2]))
     };
@@ -108,23 +114,31 @@ export class ZLinkRedisRelocationStore implements ZLinkRelocationStore {
 function requireReference(reference: ZLinkBlobReference): string {
   const value = reference.value;
   const bytes = Buffer.byteLength(value, 'utf8');
-  if (bytes < 1 || bytes > 4_096) {
-    throw new RangeError('Relocation Store reference must contain 1..4,096 UTF-8 bytes.');
+  if (bytes < 1 || bytes > ZLINK_RELOCATION_MAX_BLOB_REFERENCE_BYTES) {
+    throw new RangeError(
+      `Relocation Store reference must contain 1..${ZLINK_RELOCATION_MAX_BLOB_REFERENCE_BYTES.toLocaleString('en-US')} UTF-8 bytes.`
+    );
   }
   return value;
 }
 
 function requirePayload(payload: Uint8Array): void {
   if (payload.byteLength > MAX_ENCODED_BLOB_BYTES) {
-    throw new RangeError('Relocation Store encoded blob exceeds 64 MiB + 23 bytes.');
+    throw new RangeError(
+      `Relocation Store encoded blob exceeds ${Math.floor(MAX_ENCODED_BLOB_BYTES / (1024 * 1024))} MiB + ${MAX_ENCODED_BLOB_BYTES % (1024 * 1024)} bytes.`
+    );
   }
 }
 
 function requireRetention(retentionMs: number): number {
-  if (!Number.isSafeInteger(retentionMs) || retentionMs < 1) {
-    throw new RangeError('Relocation Store retention must be a positive safe integer.');
+  if (
+    !Number.isFinite(retentionMs) ||
+    retentionMs <= 0 ||
+    !Number.isSafeInteger(Math.ceil(retentionMs))
+  ) {
+    throw new RangeError('Relocation Store retention must round to a positive safe integer.');
   }
-  return retentionMs;
+  return Math.ceil(retentionMs);
 }
 
 function asBuffer(value: unknown): Buffer {