@voltro/kv 0.86.0 → 0.88.0

package/dist/cacheAtomicScript.js

@@ -0,0 +1,326 @@
+import { CACHE_FENCE_RETENTION_MS as e } from "./cacheAtomicProtocol.js";
+// src/cacheAtomicScript.ts
+var t = String.raw`
+local c = cjson.decode(ARGV[1])
+local policy = ARGV[2] and cjson.decode(ARGV[2]) or {}
+local function invalid() error('Invalid atomic cache command or state.') end
+local function null(x) return x == nil or x == cjson.null end
+local function reply(status, value)
+  local encoded = cjson.encode({ status = status, value = value == nil and cjson.null or value })
+  if policy.maxReplyBytes and string.len(encoded) > policy.maxReplyBytes then
+    return cjson.encode({ status = 'limit', value = cjson.null })
+  end
+  return encoded
+end
+local function id(s)
+  if type(s) ~= 'string' or #s == 0 or #s % 2 ~= 0 or not string.match(s, '^[a-f0-9]+$') then invalid() end
+  return s
+end
+local function version(s)
+  if type(s) ~= 'string' or #s ~= 36 or string.sub(s, 9, 9) ~= '-' or string.sub(s, 14, 14) ~= '-'
+    or string.sub(s, 19, 19) ~= '-' or string.sub(s, 24, 24) ~= '-' then invalid() end
+  local hex = string.gsub(s, '-', '')
+  if #hex ~= 32 or not string.match(hex, '^[a-f0-9]+$') then invalid() end
+  return s
+end
+local function array(a, check)
+  if type(a) ~= 'table' then invalid() end
+  for k, v in pairs(a) do
+    if type(k) ~= 'number' or k % 1 ~= 0 or k < 1 or k > #a then invalid() end
+    check(v)
+  end
+  return a
+end
+local function ids(a)
+  array(a, id)
+  for i = 2, #a do if a[i - 1] >= a[i] then invalid() end end
+  return a
+end
+local function snapshot(s)
+  if null(s) then return nil end
+  if type(s) ~= 'table' then invalid() end
+  version(s.version); ids(s.tags)
+  return s
+end
+local function member(s)
+  if type(s) ~= 'string' or string.sub(s, 37, 37) ~= ':' then invalid() end
+  return version(string.sub(s, 1, 36)), id(string.sub(s, 38))
+end
+local function equalTags(a, b)
+  if #a ~= #b then return false end
+  for i = 1, #a do if a[i] ~= b[i] then return false end end
+  return true
+end
+local function same(a, b)
+  if null(a) or null(b) then return null(a) and null(b) end
+  return a.version == b.version and equalTags(a.tags, b.tags)
+end
+local function contains(a, wanted)
+  for _, v in ipairs(a) do if v == wanted then return true end end
+  return false
+end
+if #KEYS < 1 or type(c) ~= 'table' or type(c.op) ~= 'string' then invalid() end
+local function fields(value, names)
+  if type(value) ~= 'table' then invalid() end
+  local allowed = {}
+  for _, name in ipairs(names) do allowed[name] = true; if value[name] == nil then invalid() end end
+  for name, _ in pairs(value) do if not allowed[name] then invalid() end end
+end
+local layouts = {
+  revision = { 'op' }, fence = { 'op' }, inspect = { 'op', 'key' }, ['inspect-values'] = { 'op', 'keys' },
+  read = { 'op', 'key', 'snapshot' }, tag = { 'op', 'tag' }, scan = { 'op', 'cursor' },
+  write = { 'op', 'key', 'snapshot', 'version', 'revision', 'tags', 'value', 'ttlMs', 'fence' },
+  remove = { 'op', 'key', 'snapshot', 'revision' },
+  invalidate = { 'op', 'tag', 'members', 'snapshots', 'revision' },
+  clear = { 'op', 'keys', 'revision' },
+}
+if not layouts[c.op] then invalid() end
+fields(c, layouts[c.op])
+if type(policy) ~= 'table' then invalid() end
+for name, value in pairs(policy) do
+  if name ~= 'maxReplyBytes' and name ~= 'maxTagMembers' then invalid() end
+  local minimum = name == 'maxReplyBytes' and 128 or 1
+  if type(value) ~= 'number' or value < minimum or value % 1 ~= 0 or value > 9007199254740991 then invalid() end
+end
+local root = KEYS[1]
+if string.sub(root, -2) ~= ':r' then invalid() end
+local space = string.sub(root, 1, #root - 2)
+local declared = {}
+for _, key in ipairs(KEYS) do if declared[key] then invalid() end; declared[key] = key end
+local needed = { [root] = true }
+local function needValue(k) needed[space .. ':v:' .. id(k)] = true end
+local function needTag(t) needed[space .. ':t:' .. id(t)] = true end
+local function needEpoch(t) needed[space .. ':e:' .. id(t)] = true end
+local function counter(n)
+  if type(n) ~= 'number' or n < 0 or n % 1 ~= 0 or n > 9007199254740991 then invalid() end
+  return n
+end
+local function needSnapshot(s)
+  if not null(s) then fields(s, { 'version', 'tags' }) end
+  local value = snapshot(s)
+  if value then for _, tag in ipairs(value.tags) do needTag(tag) end end
+end
+if c.op == 'fence' then needed[space .. ':s'] = true
+elseif c.op == 'inspect' then needValue(c.key)
+elseif c.op == 'inspect-values' then ids(c.keys); for _, key in ipairs(c.keys) do needValue(key) end
+elseif c.op == 'read' then needValue(c.key); needSnapshot(c.snapshot)
+elseif c.op == 'write' then
+  needValue(c.key); needSnapshot(c.snapshot); ids(c.tags)
+  for _, tag in ipairs(c.tags) do needTag(tag) end
+  version(c.version); version(c.revision)
+  if not null(c.fence) then counter(c.fence); for _, tag in ipairs(c.tags) do needEpoch(tag) end end
+  if not null(c.snapshot) and c.snapshot.version == c.version then invalid() end
+  if type(c.value) ~= 'string' or not null(c.ttlMs) and (type(c.ttlMs) ~= 'number' or c.ttlMs < 0 or c.ttlMs % 1 ~= 0 or c.ttlMs > 9007199254740991) then invalid() end
+elseif c.op == 'remove' then needValue(c.key); needSnapshot(c.snapshot); version(c.revision)
+elseif c.op == 'tag' then needTag(c.tag)
+elseif c.op == 'invalidate' then
+  needTag(c.tag); version(c.revision); needed[space .. ':s'] = true; needEpoch(c.tag)
+  local memberKeys = {}
+  array(c.members, function(m) local _, key = member(m); memberKeys[key] = true end)
+  for i = 2, #c.members do if c.members[i - 1] >= c.members[i] then invalid() end end
+  array(c.snapshots, function(s)
+    fields(s, { 'key', 'snapshot' }); needValue(s.key); needSnapshot(s.snapshot)
+    if not memberKeys[s.key] then invalid() end; memberKeys[s.key] = nil
+  end)
+  for _ in pairs(memberKeys) do invalid() end
+  for i = 2, #c.snapshots do if c.snapshots[i - 1].key >= c.snapshots[i].key then invalid() end end
+elseif c.op == 'clear' then
+  if not null(c.revision) then version(c.revision) end
+  -- KEYS may carry a registry prefix; ARGV retains caller-logical keys.
+  -- The canonical cache token binds those two domains exactly, without
+  -- accepting a foreign connection prefix or another cache namespace.
+  local logicalRoot = string.match(root, '({voltro:cache:atomic:[a-f0-9]+}:r)$')
+  if not logicalRoot then invalid() end
+  id(string.match(logicalRoot, '^{voltro:cache:atomic:([a-f0-9]+)}:r$'))
+  local logicalSpace = string.sub(logicalRoot, 1, #logicalRoot - 2)
+  local selected = {}
+  array(c.keys, function(key)
+    if type(key) ~= 'string' then invalid() end
+    local kind = string.sub(key, 1, #space + 3)
+    if key ~= root and kind ~= space .. ':v:' and kind ~= space .. ':t:' then
+      local logicalKind = string.sub(key, 1, #logicalSpace + 3)
+      if key == logicalRoot then key = root
+      elseif logicalKind == logicalSpace .. ':v:' or logicalKind == logicalSpace .. ':t:' then
+        key = space .. string.sub(key, #logicalSpace + 1)
+      else invalid() end
+    end
+    if selected[key] then invalid() end
+    selected[key] = true
+    if key ~= root then
+      local prefix = string.sub(key, 1, #space + 3)
+      if prefix ~= space .. ':v:' and prefix ~= space .. ':t:' then invalid() end
+      id(string.sub(key, #space + 4)); needed[key] = true
+    end
+  end)
+  for i = 2, #c.keys do if c.keys[i - 1] >= c.keys[i] then invalid() end end
+elseif c.op == 'scan' then
+  if type(c.cursor) ~= 'string' or not string.match(c.cursor, '^%d+$') or #c.cursor > 20
+    or #c.cursor > 1 and string.sub(c.cursor, 1, 1) == '0'
+    or #c.cursor == 20 and c.cursor > '18446744073709551615' then invalid() end
+elseif c.op ~= 'revision' then invalid() end
+for key, _ in pairs(needed) do if not declared[key] then invalid() end end
+for key, _ in pairs(declared) do if not needed[key] then invalid() end end
+local function valueKey(k) local key = declared[space .. ':v:' .. k]; if not key then invalid() end; return key end
+local function tagKey(t) local key = declared[space .. ':t:' .. t]; if not key then invalid() end; return key end
+local function epochKey(t) local key = declared[space .. ':e:' .. t]; if not key then invalid() end; return key end
+local function sequence()
+  local key = declared[space .. ':s']; if not key then invalid() end
+  local raw = redis.call('GET', key)
+  if not raw then return 0, key end
+  return counter(tonumber(raw)), key
+end
+local RETENTION = ${e}
+local function keyType(k)
+  local t = redis.call('TYPE', k)
+  return type(t) == 'table' and t.ok or t
+end
+for _, key in ipairs(KEYS) do
+  if c.op ~= 'clear' then
+    local t = keyType(key)
+    local kind = string.sub(key, #space + 1, #space + 3)
+    local wanted = key == root or key == space .. ':s' or kind == ':v:' or kind == ':e:'
+    if t ~= 'none' and (wanted and t ~= 'string' or not wanted and t ~= 'zset') then invalid() end
+  end
+end
+local function entry(k)
+  local raw = redis.call('GET', valueKey(k))
+  if not raw then return nil end
+  local e = cjson.decode(raw)
+  fields(e, { 'version', 'tags', 'value' })
+  snapshot(e)
+  if type(e.value) ~= 'string' then invalid() end
+  return e
+end
+local function meta(e) return e and { version = e.version, tags = e.tags } or cjson.null end
+local tm = redis.call('TIME')
+local now = tonumber(tm[1]) * 1000 + math.floor(tonumber(tm[2]) / 1000)
+local NOEXP = 9000000000000000
+if c.op == 'write' and not null(c.ttlMs) and c.ttlMs > NOEXP - now - 1 then invalid() end
+local function touch(tag)
+  local key = tagKey(tag)
+  redis.call('ZREMRANGEBYSCORE', key, '-inf', string.format('%.0f', now))
+  local top = redis.call('ZREVRANGE', key, 0, 0, 'WITHSCORES')
+  if #top == 0 then redis.call('DEL', key)
+  elseif tonumber(top[2]) >= NOEXP then redis.call('PERSIST', key)
+  else redis.call('PEXPIRE', key, math.max(1, math.ceil(tonumber(top[2]) - now))) end
+end
+local function detach(k, e)
+  local m = e.version .. ':' .. k
+  for _, tag in ipairs(e.tags) do redis.call('ZREM', tagKey(tag), m); touch(tag) end
+end
+if c.op == 'revision' then
+  return reply('ok', redis.call('GET', root) or cjson.null)
+elseif c.op == 'fence' then
+  local n = sequence()
+  return reply('ok', n)
+elseif c.op == 'inspect' then return reply('ok', meta(entry(c.key)))
+elseif c.op == 'inspect-values' then
+  local out = {}
+  for _, key in ipairs(c.keys) do table.insert(out, { key = key, snapshot = meta(entry(key)) }) end
+  return reply('ok', out)
+elseif c.op == 'tag' then return reply('ok', redis.call('ZRANGE', tagKey(c.tag), 0, -1))
+elseif c.op == 'scan' then
+  local escaped = {}
+  for i = 1, #space do
+    local char = string.sub(space, i, i)
+    if char == '\\' or char == '*' or char == '?' or char == '[' or char == ']' then table.insert(escaped, '\\') end
+    table.insert(escaped, char)
+  end
+  local page = redis.call('SCAN', c.cursor, 'MATCH', table.concat(escaped) .. ':*', 'COUNT', 200)
+  local relative = {}
+  for _, key in ipairs(page[2]) do table.insert(relative, string.sub(key, #space + 1)) end
+  return reply('ok', { cursor = page[1], keys = relative })
+elseif c.op == 'read' then
+  local e = entry(c.key)
+  if not e then return reply('ok') end
+  if not same(e, c.snapshot) then return reply('conflict') end
+  local m = e.version .. ':' .. c.key
+  for _, tag in ipairs(e.tags) do
+    local score = redis.call('ZSCORE', tagKey(tag), m)
+    if not score or tonumber(score) <= now then return reply('ok') end
+  end
+  return reply('ok', e.value)
+elseif c.op == 'write' or c.op == 'remove' then
+  -- A compute fenced before an invalidation of one of its tags is void: its
+  -- value may predate the write that invalidated it. Nothing changes.
+  if c.op == 'write' and not null(c.fence) then
+    for _, tag in ipairs(c.tags) do
+      local raw = redis.call('GET', epochKey(tag))
+      if raw and counter(tonumber(raw)) > c.fence then return reply('ok', 0) end
+    end
+  end
+  local old = entry(c.key)
+  if not same(old, c.snapshot) then return reply('conflict') end
+  if c.op == 'remove' or c.ttlMs == 0 then
+    if not old then return reply('ok', 0) end
+    redis.call('SET', root, c.revision)
+    local removed = redis.call('DEL', valueKey(c.key))
+    detach(c.key, old)
+    return reply('ok', removed)
+  end
+  if policy.maxTagMembers then
+    local oldMember = old and old.version .. ':' .. c.key or nil
+    local nextMember = c.version .. ':' .. c.key
+    for _, tag in ipairs(c.tags) do
+      local key = tagKey(tag)
+      local count = redis.call('ZCOUNT', key, '(' .. string.format('%.0f', now), '+inf')
+      local prior = oldMember and redis.call('ZSCORE', key, oldMember) or nil
+      local next = redis.call('ZSCORE', key, nextMember)
+      if prior and tonumber(prior) > now then count = count - 1 end
+      if not next or tonumber(next) <= now then count = count + 1 end
+      if count > policy.maxTagMembers then return reply('limit') end
+    end
+  end
+  -- Revise first: even an interrupted/erroring writer invalidates clear snapshots.
+  redis.call('SET', root, c.revision)
+  local expires = null(c.ttlMs) and NOEXP or now + c.ttlMs
+  local m = c.version .. ':' .. c.key
+  -- Prepare independent new memberships. No old live membership is removed yet.
+  for _, tag in ipairs(c.tags) do redis.call('ZADD', tagKey(tag), expires, m); touch(tag) end
+  local raw = cjson.encode({ version = c.version, tags = c.tags, value = c.value })
+  if null(c.ttlMs) then redis.call('SET', valueKey(c.key), raw)
+  else redis.call('PSETEX', valueKey(c.key), c.ttlMs, raw) end
+  if old then detach(c.key, old) end
+  return reply('ok', 1)
+elseif c.op == 'invalidate' then
+  local tag = tagKey(c.tag)
+  if redis.call('ZCARD', tag) ~= #c.members then return reply('conflict') end
+  for _, m in ipairs(c.members) do if not redis.call('ZSCORE', tag, m) then return reply('conflict') end end
+  local expected = {}
+  for _, s in ipairs(c.snapshots) do expected[s.key] = s.snapshot end
+  local selected = {}
+  for _, m in ipairs(c.members) do
+    local v, k = member(m)
+    if not selected[k] then
+      local e = entry(k)
+      if e and e.version == v and contains(e.tags, c.tag) then
+        if not same(e, expected[k]) then return reply('conflict') end
+        selected[k] = e
+      end
+    end
+  end
+  redis.call('SET', root, c.revision)
+  local n, sequenceKey = sequence()
+  redis.call('SET', sequenceKey, n + 1)
+  redis.call('SET', epochKey(c.tag), n + 1, 'PX', RETENTION)
+  local removed = 0
+  for k, e in pairs(selected) do
+    removed = removed + redis.call('DEL', valueKey(k))
+    detach(k, e)
+  end
+  redis.call('DEL', tag)
+  return reply('ok', removed)
+elseif c.op == 'clear' then
+  local observed = redis.call('GET', root) or cjson.null
+  if observed ~= c.revision then return reply('conflict') end
+  -- DEL is bounded per native command; all keys were declared before execution.
+  for first = 1, #KEYS, 500 do
+    local batch = {}
+    for i = first, math.min(first + 499, #KEYS) do table.insert(batch, KEYS[i]) end
+    redis.call('DEL', unpack(batch))
+  end
+  return reply('ok')
+end
+invalid()
+`;
+export { t as CACHE_ATOMIC_SCRIPT };

package/dist/cacheAtomicState.js

@@ -0,0 +1,140 @@
+import { CACHE_FENCE_RETENTION_MS as e, CacheAtomicProtocolError as t, cacheAtomicKeys as n, cacheAtomicMember as r, cacheAtomicMembership as i, cacheAtomicSnapshot as a, decodeCacheAtomicCommand as o, decodeCacheAtomicPolicy as s } from "./cacheAtomicProtocol.js";
+// src/cacheAtomicState.ts
+var c = 9e15, l = () => {
+	throw new t();
+}, u = (t, u, d, f = {}) => {
+	let p = o(d), m = s(f);
+	if (!Number.isSafeInteger(t.now) || t.now < 0 || t.now >= c) return l();
+	let h = u[0];
+	if (h === void 0) return l();
+	let g = n(h, p), _ = new Set(u);
+	if (u.length !== g.length || _.size !== u.length || g.some((e) => !_.has(e))) return l();
+	let v = h.slice(0, -2), y = (e) => `${v}:v:${e}`, b = (e) => `${v}:t:${e}`, x = `${v}:s`, S = (e) => `${v}:e:${e}`, C = (e) => e === h || e === x || e.startsWith(`${v}:v:`) || e.startsWith(`${v}:e:`);
+	if (p.op !== "clear") for (let e of u) {
+		let n = t.kind(e);
+		if (n !== "none" && n !== (C(e) ? "string" : "zset")) return l();
+	}
+	let w = (e) => {
+		if (e === null) return 0;
+		let t = Number(e);
+		return Number.isSafeInteger(t) && t >= 0 ? t : l();
+	}, T = (e) => {
+		let n = t.get(y(e));
+		if (n === null) return null;
+		let r;
+		try {
+			r = JSON.parse(n);
+		} catch {
+			return l();
+		}
+		if (typeof r != "object" || !r || Array.isArray(r)) return l();
+		let i = r;
+		if (Object.keys(i).length !== 3 || typeof i.value != "string") return l();
+		let o = a({
+			version: i.version,
+			tags: i.tags
+		});
+		return o === null ? l() : {
+			...o,
+			value: i.value
+		};
+	}, E = (e, t) => e === null || t === null ? e === t : e.version === t.version && e.tags.length === t.tags.length && e.tags.every((e, n) => e === t.tags[n]), D = (e) => e === null ? null : {
+		version: e.version,
+		tags: e.tags
+	}, O = (e, t = null) => {
+		let n = JSON.stringify({
+			status: e,
+			value: t
+		});
+		return m.maxReplyBytes !== void 0 && new TextEncoder().encode(n).length > m.maxReplyBytes ? JSON.stringify({
+			status: "limit",
+			value: null
+		}) : n;
+	}, k = (e) => {
+		let n = b(e);
+		for (let e of t.members(n)) e.score <= t.now && t.removeMember(n, e.member);
+		let r = t.members(n);
+		if (r.length === 0) {
+			t.remove(n);
+			return;
+		}
+		let i = -Infinity;
+		for (let e of r) i = Math.max(i, e.score);
+		t.expire(n, i >= c ? null : Math.max(1, Math.ceil(i - t.now)));
+	}, A = (e, n) => {
+		for (let r of n.tags) t.removeMember(b(r), i(e, n.version)), k(r);
+	}, j = (e) => t.set(h, e.revision);
+	switch (p.op) {
+		case "revision": return O("ok", t.get(h));
+		case "fence": return O("ok", w(t.get(x)));
+		case "inspect": return O("ok", D(T(p.key)));
+		case "inspect-values": return O("ok", p.keys.map((e) => ({
+			key: e,
+			snapshot: D(T(e))
+		})));
+		case "tag": return O("ok", t.members(b(p.tag)).slice().sort((e, t) => e.score - t.score || (e.member < t.member ? -1 : +(e.member > t.member))).map((e) => e.member));
+		case "scan": return p.cursor === "0" ? O("ok", {
+			cursor: "0",
+			keys: t.keys().filter((e) => e.startsWith(`${v}:`)).map((e) => e.slice(v.length))
+		}) : l();
+		case "read": {
+			let e = T(p.key);
+			if (e === null) return O("ok");
+			if (!E(e, p.snapshot)) return O("conflict");
+			let n = i(p.key, e.version);
+			return e.tags.some((e) => !t.members(b(e)).some((e) => e.member === n && e.score > t.now)) ? O("ok") : O("ok", e.value);
+		}
+		case "write":
+		case "remove": {
+			if (p.op === "write" && p.fence !== null) {
+				let e = p.fence;
+				if (p.tags.some((n) => w(t.get(S(n))) > e)) return O("ok", 0);
+			}
+			let e = T(p.key);
+			if (!E(e, p.snapshot)) return O("conflict");
+			if (p.op === "remove" || p.ttlMs === 0) {
+				if (e === null) return O("ok", 0);
+				j(p);
+				let n = t.remove(y(p.key));
+				return A(p.key, e), O("ok", n);
+			}
+			if (p.ttlMs !== null && p.ttlMs > c - t.now - 1) return l();
+			if (m.maxTagMembers !== void 0) for (let n of p.tags) {
+				let r = t.members(b(n)).filter((e) => e.score > t.now), a = e === null ? null : i(p.key, e.version), o = i(p.key, p.version);
+				if (r.length - +!!r.some((e) => e.member === a) + +!r.some((e) => e.member === o) > m.maxTagMembers) return O("limit");
+			}
+			j(p);
+			for (let e of p.tags) t.addMember(b(e), i(p.key, p.version), p.ttlMs === null ? c : t.now + p.ttlMs), k(e);
+			return t.set(y(p.key), JSON.stringify({
+				version: p.version,
+				tags: p.tags,
+				value: p.value
+			}), p.ttlMs ?? void 0), e !== null && A(p.key, e), O("ok", 1);
+		}
+		case "invalidate": {
+			let n = t.members(b(p.tag));
+			if (n.length !== p.members.length || p.members.some((e) => !n.some((t) => t.member === e))) return O("conflict");
+			let i = /* @__PURE__ */ new Map(), a = new Map(p.snapshots.map((e) => [e.key, e.snapshot]));
+			for (let e of p.members) {
+				let t = r(e);
+				if (i.has(t.key)) continue;
+				let n = T(t.key);
+				if (n !== null && n.version === t.version && n.tags.includes(p.tag)) {
+					if (!E(n, a.get(t.key) ?? null)) return O("conflict");
+					i.set(t.key, n);
+				}
+			}
+			j(p);
+			let o = w(t.get(x)) + 1;
+			t.set(x, String(o)), t.set(S(p.tag), String(o), e);
+			let s = 0;
+			for (let [e, n] of i) s += t.remove(y(e)), A(e, n);
+			return t.remove(b(p.tag)), O("ok", s);
+		}
+		case "clear":
+			if (t.get(h) !== p.revision) return O("conflict");
+			for (let e of u) t.remove(e);
+			return O("ok");
+	}
+};
+export { u as applyCacheAtomicCommand };