feat(compat): version compatibility profiles for the Lua sandbox (#25)

* feat(compat): version compatibility profiles for the Lua sandbox

Emulate the Lua sandbox behavior of a chosen Redis/Valkey version. Only
three behaviors actually differ across Redis 6.2-8.x and Valkey:

  - `print` global     -> present only in Redis 6.2
  - `os` library       -> Redis 7.4+ / Valkey 8.0+
  - `server` alias     -> Valkey 8.0+ only (Redis keeps `redis`)

Modeled as three orthogonal flags (COMPAT_PRINT/OS/SERVER_ALIAS) passed as
a u8 bitmask via a new `set_compat()` WASM export, consumed by a shared
`setup_state()` (init/reset deduped). TS exposes `load({ profile, compat })`
where `profile` is a named preset over the version matrix and `compat`
overrides individual flags. Default (no profile) preserves prior behavior
(os + server alias, no print; ~ valkey 8.0).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* refactor(compat): rename profiles to hyphenated names

Drop valkey-7.2 and valkey-8.1; add valkey-9.0. Profile set is now
redis-6.2, redis-7.0, redis-7.2, redis-7.4, redis-8.0, valkey-8.0,
valkey-9.0. valkey-9.0 mirrors valkey-8.0 (no known Lua sandbox delta).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: fatal10110

src/engine.ts

@@ -59,6 +59,8 @@ import type {
   StandaloneOptions,
   RedisProp,
   RedisProps,
+  CompatProfile,
+  CompatOverrides,
 } from "./types.js";
 import {
   decodeReply,
@@ -473,6 +475,44 @@ type MutableHandlers = {
  * const standalone = module.createStandalone();
  * ```
  */
+// Compatibility flag bits — must match the COMPAT_* macros in wasm/src/runtime.c.
+const COMPAT_PRINT = 0x1;
+const COMPAT_OS = 0x2;
+const COMPAT_SERVER_ALIAS = 0x4;
+
+/**
+ * Profile presets -> the three Lua sandbox behavior flags. Mirrors the
+ * Redis/Valkey version matrix (see redis-version-lua-behavior-matrix).
+ */
+const COMPAT_PROFILES: Record<CompatProfile, Required<CompatOverrides>> = {
+  "redis-6.2": { print: true, os: false, serverAlias: false },
+  "redis-7.0": { print: false, os: false, serverAlias: false },
+  "redis-7.2": { print: false, os: false, serverAlias: false },
+  "redis-7.4": { print: false, os: true, serverAlias: false },
+  "redis-8.0": { print: false, os: true, serverAlias: false },
+  "valkey-8.0": { print: false, os: true, serverAlias: true },
+  "valkey-9.0": { print: false, os: true, serverAlias: true },
+};
+
+// Default when no profile is given: preserve the historical behavior (≈ valkey-8.0).
+const COMPAT_DEFAULT: Required<CompatOverrides> = COMPAT_PROFILES["valkey-8.0"];
+
+/** Resolve a profile + per-flag overrides to the u8 bitmask the WASM expects. */
+function resolveCompatFlags(
+  profile?: CompatProfile,
+  overrides?: CompatOverrides,
+): number {
+  const merged = {
+    ...(profile ? COMPAT_PROFILES[profile] : COMPAT_DEFAULT),
+    ...overrides,
+  };
+  return (
+    (merged.print ? COMPAT_PRINT : 0) |
+    (merged.os ? COMPAT_OS : 0) |
+    (merged.serverAlias ? COMPAT_SERVER_ALIAS : 0)
+  );
+}
+
 export class LuaWasmModule {
   private consumed = false;
 
@@ -583,6 +623,12 @@ export class LuaWasmModule {
       );
     }
 
+    if (this.exports._set_compat) {
+      this.exports._set_compat(
+        resolveCompatFlags(this.options.profile, this.options.compat),
+      );
+    }
+
     const initResult = this.exports._init();
     if (typeof initResult === "number" && initResult !== 0) {
       throw new Error("Failed to initialize Lua WASM engine");
@@ -792,4 +838,6 @@ export type {
   LoadOptions,
   RedisProp,
   RedisProps,
+  CompatProfile,
+  CompatOverrides,
 };

src/index.ts

@@ -10,7 +10,9 @@ export type {
   RedisLogHandler,
   StandaloneOptions,
   RedisProp,
-  RedisProps
+  RedisProps,
+  CompatProfile,
+  CompatOverrides
 } from "./types.js";
 import { encodeReplyValue, decodeReply, encodeArgArray } from "./codec.js";
 import type { ReplyValue as ReplyValueType } from "./types.js";

src/loader-core.ts

@@ -71,6 +71,13 @@ export type WasmExports = {
    */
   _set_limits?: (maxFuel: number, maxReplyBytes: number, maxArgBytes: number) => void;
 
+  /**
+   * Select the compatibility profile (which Redis/Valkey version's Lua sandbox
+   * behavior to emulate). Bitmask: 0x1 keep `print`, 0x2 expose `os`, 0x4
+   * `server` alias. Call before _init/_reset.
+   */
+  _set_compat?: (flags: number) => void;
+
   /**
    * Allocate memory in WASM linear memory.
    * @param size - Number of bytes to allocate

src/types.ts

@@ -240,6 +240,35 @@ export type EngineLimits = {
   maxArgBytes?: number;
 };
 
+/**
+ * Named Redis/Valkey compatibility profile. Selects which of the three Lua
+ * sandbox behaviors that differ across versions are emulated. Aliases collapse
+ * to identical behavior (redis-7.0 == redis-7.2; redis-7.4 == redis-8.0;
+ * valkey-8.0 == valkey-9.0). Use {@link CompatOverrides} to tweak a single flag.
+ */
+export type CompatProfile =
+  | "redis-6.2"
+  | "redis-7.0"
+  | "redis-7.2"
+  | "redis-7.4"
+  | "redis-8.0"
+  | "valkey-8.0"
+  | "valkey-9.0";
+
+/**
+ * Fine-grained overrides for the compatibility profile, merged over the
+ * selected {@link CompatProfile} (or the default). These are the only three Lua
+ * sandbox behaviors that actually differ across Redis 6.2-8.x and Valkey.
+ */
+export type CompatOverrides = {
+  /** Keep the Lua `print` global. Only Redis 6.2 did. Default: false. */
+  print?: boolean;
+  /** Expose the (sandboxed) `os` library. Redis 7.4+ / Valkey 8.0+. Default: true. */
+  os?: boolean;
+  /** Expose `server` as an alias of `redis`. Valkey 8.0+ only. Default: true. */
+  serverAlias?: boolean;
+};
+
 /**
  * Configuration options for creating a LuaWasmEngine with host integration.
  *
@@ -275,6 +304,12 @@ export type EngineOptions = {
 
   /** Optional host-injected `redis.*` props (constants and simple stubs). */
   redisProps?: RedisProps;
+
+  /** Redis/Valkey version whose Lua sandbox behavior to emulate. Default: ≈ valkey-8.0. */
+  profile?: CompatProfile;
+
+  /** Per-flag compatibility overrides, merged over `profile` (or the default). */
+  compat?: CompatOverrides;
 };
 
 /**
@@ -308,6 +343,12 @@ export type StandaloneOptions = {
 
   /** Optional host-injected `redis.*` props (constants and simple stubs). */
   redisProps?: RedisProps;
+
+  /** Redis/Valkey version whose Lua sandbox behavior to emulate. Default: ≈ valkey-8.0. */
+  profile?: CompatProfile;
+
+  /** Per-flag compatibility overrides, merged over `profile` (or the default). */
+  compat?: CompatOverrides;
 };
 
 /**
@@ -340,4 +381,10 @@ export type LoadOptions = {
 
   /** Optional host-injected `redis.*` props (constants and simple stubs). */
   redisProps?: RedisProps;
+
+  /** Redis/Valkey version whose Lua sandbox behavior to emulate. Default: ≈ valkey-8.0. */
+  profile?: CompatProfile;
+
+  /** Per-flag compatibility overrides, merged over `profile` (or the default). */
+  compat?: CompatOverrides;
 };

test/engine.test.ts

@@ -6,7 +6,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import test from "node:test";
 import assert from "node:assert/strict";
-import { load, LuaWasmModule } from "../src/index.js";
+import { load, LuaWasmModule, LuaEngine } from "../src/index.js";
 import { LuaWasmEngine, makePropsHandler } from "../src/engine.js";
 import { encodeRedisProps } from "../src/codec.js";
 import type { ReplyValue, RedisHost } from "../src/types.js";
@@ -1341,3 +1341,65 @@ test("redisProps integration: makes injected props readonly under globals protec
   const r = engine.eval("redis.REDIS_VERSION = 'x' return 1") as { err: Buffer };
   assert.ok(r && typeof r === "object" && "err" in r);
 });
+
+// =============================================================================
+// Compatibility profiles (print / os / server alias differ across versions)
+// =============================================================================
+
+type GlobalReadErr = { err: Buffer; meta?: { kind: string; name: string } };
+
+/** Assert reading `name` raises a global-read error (i.e. the global is absent). */
+function assertGlobalAbsent(engine: LuaEngine, name: string): void {
+  const r = engine.eval(`return ${name}`) as GlobalReadErr;
+  assert.ok(r && typeof r === "object" && "err" in r, `${name} should be absent`);
+  assert.equal(r.meta?.kind, "global-read");
+  assert.equal(r.meta?.name, name);
+}
+
+test("compat redis6.2: print kept, os absent, server absent", async () => {
+  const module = await load({ profile: "redis-6.2" });
+  const engine = module.create(createTestHost());
+  assert.equal(engine.eval("return type(print)").toString(), "function");
+  assert.equal(engine.eval("print('x') return 1"), 1); // print runs, returns nil
+  assertGlobalAbsent(engine, "os");
+  assertGlobalAbsent(engine, "server");
+});
+
+test("compat redis7.2: print absent, os absent, server absent", async () => {
+  const module = await load({ profile: "redis-7.2" });
+  const engine = module.create(createTestHost());
+  assertGlobalAbsent(engine, "print");
+  assertGlobalAbsent(engine, "os");
+  assertGlobalAbsent(engine, "server");
+});
+
+test("compat redis8.0: os present, server absent (redis has no server alias)", async () => {
+  const module = await load({ profile: "redis-8.0" });
+  const engine = module.create(createTestHost());
+  assert.equal(engine.eval("return type(os)").toString(), "table");
+  assertGlobalAbsent(engine, "print");
+  assertGlobalAbsent(engine, "server");
+});
+
+test("compat valkey8.0: os present, server aliases redis", async () => {
+  const module = await load({ profile: "valkey-8.0" });
+  const engine = module.create(createTestHost());
+  assert.equal(engine.eval("return type(os)").toString(), "table");
+  assert.equal(engine.eval("return server == redis"), 1);
+  assertGlobalAbsent(engine, "print");
+});
+
+test("compat: per-flag override is merged over the profile", async () => {
+  const module = await load({ profile: "redis-7.2", compat: { os: true } });
+  const engine = module.create(createTestHost());
+  assert.equal(engine.eval("return type(os)").toString(), "table");
+  assertGlobalAbsent(engine, "server"); // unchanged by the override
+});
+
+test("compat: default (no profile) keeps historical behavior", async () => {
+  const module = await load();
+  const engine = module.create(createTestHost());
+  assert.equal(engine.eval("return type(os)").toString(), "table");
+  assert.equal(engine.eval("return server == redis"), 1);
+  assertGlobalAbsent(engine, "print");
+});

wasm/build/build.sh

@@ -44,7 +44,7 @@ emcc -O2 -DENABLE_CJSON_GLOBAL \
   -sEXPORTED_RUNTIME_METHODS="['HEAPU8']" \
   -sINCOMING_MODULE_JS_API="['locateFile','instantiateWasm']" \
   -sINITIAL_MEMORY=67108864 -sMAXIMUM_MEMORY=67108864 \
-  -sEXPORTED_FUNCTIONS="['_init','_reset','_eval','_eval_with_args','_alloc','_free_mem','_set_limits']" \
+  -sEXPORTED_FUNCTIONS="['_init','_reset','_eval','_eval_with_args','_alloc','_free_mem','_set_limits','_set_compat']" \
   -I"$ROOT_DIR/wasm/include" -I"$LUA_SRC_DIR" -I"$REDIS_LUA_DEPS" -I"$REDIS_SRC" \
   "$SRC_DIR/runtime.c" "$SRC_DIR/redis_api.c" $CORE_FILES $LIB_FILES $MODULE_FILES \
   -o "$OUT_DIR/redis_lua.mjs"

wasm/include/abi.h

@@ -63,6 +63,7 @@ PtrLen eval(uint32_t ptr, uint32_t len);
 PtrLen eval_with_args(uint32_t script_ptr, uint32_t script_len, uint32_t args_ptr,
                       uint32_t args_len, uint32_t keys_count);
 void set_limits(uint32_t max_fuel, uint32_t max_reply_bytes, uint32_t max_arg_bytes);
+void set_compat(uint32_t flags);
 uint32_t alloc(uint32_t size);
 void free_mem(uint32_t ptr);