feat(redis): add custom key groups

This commit is contained in:
Guoyu Su authored and GitHub committed 2026-09-09 14:44:45 +08:00
1 parent a535cf8f51
commit 1cbb5abf3b
53 files changed
+1951 -13

No files matched your search

@@ -0,0 +1,43 @@
import { expect, it } from "vitest";
import { RedisKeyGroupIndex, findRedisOuterGroup } from "../redisKeyGroupIndex";
const work = { current: () => true, yield: async () => {} };
const rules = [
{ id: "a", name: "A", enabled: true, includes: ["a:*"], excludes: [] },
{ id: "empty", name: "Empty", enabled: true, includes: ["missing:*"], excludes: [] },
];
const key = (name: string) => ({ key_raw: btoa(name), key_display: name, key_type: "string", ttl: -1 });
it.each(["list", "tree"] as const)("captures atomic outer boundaries for %s, excluding namespace headers", async (view) => {
const index = new RedisKeyGroupIndex(rules, "Unmatched");
await index.append([key("a:1"), key("a:2"), key("b:1")], work);
const expanded = new Set(['custom:"a"', 'custom:"a":namespace:["a"]', "custom:unmatched"]);
const first = (await index.project(view, ":", expanded, work))!;
expect(first.outerGroups).toHaveLength(3);
expect(first.outerGroups.map((group) => group.row.label)).toEqual(["A", "Empty", "Unmatched"]);
for (const group of first.outerGroups) {
expect(first.rows[group.start]).toBe(group.row);
expect(findRedisOuterGroup(first.outerGroups, group.start)).toBe(group);
expect(findRedisOuterGroup(first.outerGroups, group.end - 0.1)).toBe(group);
}
expect(findRedisOuterGroup(first.outerGroups, -1)).toBeUndefined();
expect(findRedisOuterGroup(first.outerGroups, first.rows.length)).toBeUndefined();
const before = first.outerGroups.map((group) => ({ ...group }));
await index.append([key("a:1"), key("a:2"), key("b:1"), key("a:3")], work);
const collapsed = (await index.project(view, ":", new Set(), work))!;
expect(collapsed.outerGroups.map((group) => group.end - group.start)).toEqual([1, 1, 1]);
expect(first.outerGroups).toEqual(before);
expect(first.outerGroups[0]!.row.count).toBe(2);
expect(collapsed.outerGroups[0]!.row.count).toBe(3);
});
it("keeps million-key boundary storage bounded by groups, including unmatched", async () => {
const index = new RedisKeyGroupIndex(rules, "Unmatched");
const keys = Array.from({ length: 1_000_000 }, (_, n) => key(`a:${n}`));
await index.append(keys, work);
const snapshot = (await index.project("list", ":", new Set(['custom:"a"']), work))!;
expect(snapshot.rows.length).toBe(1_000_002);
expect(snapshot.outerGroups).toHaveLength(2);
expect(findRedisOuterGroup(snapshot.outerGroups, 999_999)?.row.id).toBe('custom:"a"');
expect(findRedisOuterGroup(snapshot.outerGroups, 1_000_001)?.row.label).toBe("Empty");
});
@@ -0,0 +1,94 @@
import { describe, expect, it } from "vitest";
import { compileRedisGroupGlob, compileRedisKeyGroups, defaultRedisKeyGrouping, validateRedisKeyGrouping } from "../redisKeyGrouping";
import { RedisKeyGroupIndex } from "../redisKeyGroupIndex";
import type { RedisKeyInfo } from "@/lib/backend/api";
const raw = (value: string) => btoa(String.fromCharCode(...new TextEncoder().encode(value)));
const key = (name: string): RedisKeyInfo => ({ key_raw: raw(name), key_display: name, key_type: "string", ttl: -1, size: 1 });
const rule = { id: "suffix", name: "Metadata", enabled: true, includes: ["*:redisson_options"], excludes: [] };
const work = { current: () => true, yield: async () => {} };
describe("Redis grouping contracts", () => {
it("is opt-in and rejects malformed edits", () => {
expect(validateRedisKeyGrouping(defaultRedisKeyGrouping()).enabled).toBe(false);
expect(() => validateRedisKeyGrouping({ ...defaultRedisKeyGrouping(), rules: [{ ...rule, includes: [] }] })).toThrow();
expect(() => validateRedisKeyGrouping({ ...defaultRedisKeyGrouping(), rules: [rule, rule] })).toThrow();
expect(() => validateRedisKeyGrouping({ ...defaultRedisKeyGrouping(), version: 2 })).toThrow();
});
it("uses whole-byte glob semantics, escapes and ranges", () => {
const matches = (pattern: string, text: string) => compileRedisGroupGlob(pattern)(new TextEncoder().encode(text));
expect(matches("?", "中")).toBe(false);
expect(matches("???", "中")).toBe(true);
expect(matches("[z-a]", "q")).toBe(true);
expect(matches("[^a]", "b")).toBe(true);
expect(matches("a\\*", "a*")).toBe(true);
expect(matches("a", "ab")).toBe(false);
expect(matches("*", "")).toBe(true);
expect(matches("**", "")).toBe(false);
expect(compileRedisGroupGlob("?")(new Uint8Array([255]))).toBe(true);
expect(matches("*a*a*a*a*a*b", "a".repeat(10000))).toBe(false);
});
it("uses first match and exclusion veto without lossy display text", () => {
const classify = compileRedisKeyGroups([rule, { ...rule, id: "business", includes: [], excludes: ["private:*"] }]);
expect(classify(raw("cache:redisson_options"))).toBe("suffix");
expect(classify(raw("cache:one"))).toBe("business");
expect(classify(raw("private:one"))).toBe(null);
expect(compileRedisKeyGroups([{ ...rule, includes: ["?"], enabled: false }])("/w==")).toBe(null);
});
it("deduplicates append and exposes immutable-length range snapshots", async () => {
const index = new RedisKeyGroupIndex([rule], "Other");
const first = [key("a:redisson_options"), key("b")];
await index.append(first, work);
const expanded = new Set(['custom:"suffix"', "custom:unmatched"]);
const before = (await index.project("list", ":", expanded, work))!;
expect(before.rows.map((row) => row.kind)).toEqual(["virtual-group", "key", "virtual-group", "key"]);
await index.append([...first, first[0]!, key("c")], work);
expect(before.rows.length).toBe(4);
const after = (await index.project("list", ":", expanded, work))!;
expect(after.rows.length).toBe(5);
expect(after.positions.get(`key:${raw("c")}`)).toBe(4);
});
it("scopes namespace IDs by outer group and never produces legacy group nodes", async () => {
const index = new RedisKeyGroupIndex([rule], "Other");
await index.append([key("a:redisson_options"), key("a:other")], work);
const result = (await index.project("tree", ":", new Set(['custom:"suffix"', "custom:unmatched"]), work))!;
expect(new Set(result.rows.map((row) => row.id)).size).toBe(result.rows.length);
expect(result.rows.every((row) => row.kind === "virtual-group")).toBe(true);
const expanded = new Set(result.rows.map((row) => row.id));
const leaves = (await index.project("tree", ":", expanded, work))!;
expect(leaves.rows.filter((row) => row.kind === "key")).toHaveLength(2);
});
it("cancels bounded work and resumes append without duplicates", async () => {
const index = new RedisKeyGroupIndex([], "Other");
const keys = Array.from({ length: 2000 }, (_, i) => key(String(i)));
let alive = true;
expect(
await index.append(keys, {
current: () => alive,
yield: async () => {
alive = false;
},
}),
).toBe(false);
await index.append(keys, work);
const result = (await index.project("list", ":", new Set(["custom:unmatched"]), work))!;
expect(result.rows.length).toBe(2001);
});
it("does not materialize each loaded key again when projecting a large list", async () => {
const index = new RedisKeyGroupIndex([], "Other");
await index.append(
Array.from({ length: 100000 }, (_, i) => key(String(i))),
work,
);
let yields = 0;
const result = (await index.project("list", ":", new Set(["custom:unmatched"]), {
current: () => true,
yield: async () => {
yields++;
},
}))!;
expect(yields).toBe(0);
expect(result.rows.length).toBe(100001);
expect(result.positions.get(`key:${raw("99999")}`)).toBe(100000);
});
});
@@ -0,0 +1,42 @@
import { expect, it } from "vitest";
import { createRedisKeyViewYield } from "../redisKeyViewScheduler";
import { buildRedisKeySnapshotCooperatively } from "../redisKeyTree";
it("uses small checkpoints without paying a task/frame for every checkpoint", async () => {
let clock = 0;
let tasks = 0;
const checkpoint = createRedisKeyViewYield({
now: () => clock,
yieldTask: async () => {
tasks++;
},
budgetMs: 8,
});
for (let i = 0; i < 1000; i++) {
clock += 0.125;
await checkpoint();
}
expect(tasks).toBe(15);
});
it("retains builder cancellation checks before a real task is needed", async () => {
let checks = 0;
let tasks = 0;
const keys = Array.from({ length: 2000 }, (_, i) => ({ key_raw: String(i), key_display: String(i), ttl: -1, key_type: "string" }));
const result = await buildRedisKeySnapshotCooperatively(
[keys],
{ db: 0, flatRows: true, expandAll: false, expandedGroupIds: new Set() },
{
workChunkSize: 512,
shouldContinue: () => ++checks < 5,
yieldControl: createRedisKeyViewYield({
now: () => 0,
yieldTask: async () => {
tasks++;
},
}),
},
);
expect(result).toBeNull();
expect(tasks).toBe(0);
});
@@ -0,0 +1,74 @@
import { expect, it } from "vitest";
import { findRedisHeaderChain, RedisKeyGroupIndex } from "../redisKeyGroupIndex";
import { redisStickyHeaders, redisStickyHeight } from "../redisStickyHeaders";
const work = { current: () => true, yield: async () => {} };
async function fixture() {
const index = new RedisKeyGroupIndex([], "Unmatched");
await index.append(
Array.from({ length: 1000 }, (_, n) => ({ key_display: `a:b:c:d:${n}`, key_raw: btoa(`a:b:c:d:${n}`), ttl: -1, key_type: "string" })),
work,
);
const expanded = new Set(["custom:unmatched"]);
for (const path of [["a"], ["a", "b"], ["a", "b", "c"], ["a", "b", "c", "d"]]) expanded.add(`custom:unmatched:namespace:${JSON.stringify(path)}`);
return { index, expanded, snapshot: (await index.project("tree", ":", expanded, work))! };
}
it("indexes ancestry once per header, with atomic end ranges and no leaf access during lookup", async () => {
const { index, expanded, snapshot } = await fixture();
expect(snapshot.headerBoundaries).toHaveLength(5);
let reads = 0;
const headers = new Proxy(snapshot.headerBoundaries, {
get(target, prop, receiver) {
if (typeof prop === "string" && /^\d+$/.test(prop)) reads++;
return Reflect.get(target, prop, receiver);
},
});
expect(findRedisHeaderChain(headers, 999).map((header) => header.row.label)).toEqual(["Unmatched", "a", "b", "c", "d"]);
expect(reads).toBeLessThanOrEqual(5);
expanded.delete('custom:unmatched:namespace:["a","b"]');
const collapsed = (await index.project("tree", ":", expanded, work))!;
expect(collapsed.headerBoundaries).toHaveLength(3);
expect(snapshot.headerBoundaries[0]!.end).toBe(1005);
expect(findRedisHeaderChain(collapsed.headerBoundaries, 3)).toEqual([]);
});
it("bounds height at zero, one, two and three rows and indicates omitted ancestors", async () => {
const { snapshot } = await fixture();
const sticky = (height: number, scroll = 500) => redisStickyHeaders(snapshot.outerGroups, snapshot.headerBoundaries, scroll, height, true);
expect(sticky(99)).toEqual([]);
expect(sticky(100).map((entry) => entry.row.label)).toEqual(["Unmatched"]);
expect(sticky(200).map((entry) => entry.row.label)).toEqual(["Unmatched", "d"]);
expect(sticky(300).map((entry) => entry.row.label)).toEqual(["Unmatched", "c", "d"]);
expect(sticky(300)[1]!.omitted).toBe(true);
expect(sticky(300)[1]!.path).toBe("Unmatched › a › b › c › d");
expect(redisStickyHeight(sticky(1000))).toBe(90);
expect(sticky(300, 0)).toEqual([]);
expect(redisStickyHeaders(snapshot.outerGroups, snapshot.headerBoundaries, 500, 99, false)).toHaveLength(1);
});
it("retains expanded parents above a collapsed current namespace before compressing", async () => {
const { index, expanded } = await fixture();
expanded.delete('custom:unmatched:namespace:["a","b","c","d"]');
const snapshot = (await index.project("tree", ":", expanded, work))!;
expect(redisStickyHeaders(snapshot.outerGroups, snapshot.headerBoundaries, 60, 300, true).map((entry) => entry.row.label)).toEqual(["Unmatched", "b", "c"]);
});
it("pushes the outgoing sibling behind its parents and never pins the incoming natural header twice", async () => {
const index = new RedisKeyGroupIndex([], "Unmatched");
await index.append(
["a", "b"].flatMap((branch) => Array.from({ length: 10 }, (_, n) => ({ key_display: `p:${branch}:${n}`, key_raw: btoa(`p:${branch}:${n}`), ttl: -1, key_type: "string" }))),
work,
);
const expanded = new Set(["custom:unmatched", 'custom:unmatched:namespace:["p"]', 'custom:unmatched:namespace:["p","a"]', 'custom:unmatched:namespace:["p","b"]']);
const snapshot = (await index.project("tree", ":", expanded, work))!;
const b = snapshot.headerBoundaries.find((header) => header.row.label === "b")!;
const before = redisStickyHeaders(snapshot.outerGroups, snapshot.headerBoundaries, b.start * 30 - 75, 300, true);
expect(before.map((entry) => entry.row.label)).toEqual(["Unmatched", "p", "a"]);
expect(before[2]!.top).toBe(45);
expect(redisStickyHeight(before)).toBe(75);
const aligned = redisStickyHeaders(snapshot.outerGroups, snapshot.headerBoundaries, b.start * 30 - 60, 300, true);
expect(aligned.map((entry) => entry.row.label)).toEqual(["Unmatched", "p"]);
const after = redisStickyHeaders(snapshot.outerGroups, snapshot.headerBoundaries, b.start * 30 - 59, 300, true);
expect(after.map((entry) => entry.row.label)).toEqual(["Unmatched", "p", "b"]);
});
@@ -0,0 +1,255 @@
import type { RedisKeyInfo } from "@/lib/backend/api";
import { compileRedisKeyGroups, type RedisKeyGroupRule } from "./redisKeyGrouping";
export interface RedisVirtualGroupRow {
kind: "virtual-group";
id: string;
label: string;
depth: number;
count: number;
}
export interface RedisGroupedKeyRow {
kind: "key";
id: string;
key: RedisKeyInfo;
label: string;
depth: number;
}
export type RedisGroupedRow = RedisVirtualGroupRow | RedisGroupedKeyRow;
export interface RedisOuterGroupBoundary {
start: number;
end: number;
row: RedisVirtualGroupRow;
}
export interface RedisHeaderBoundary extends RedisOuterGroupBoundary {
parent?: RedisHeaderBoundary;
}
/** Header-only binary lookup plus parent links; never reads leaf rows. */
export function findRedisHeaderChain(headers: readonly RedisHeaderBoundary[], position: number): RedisHeaderBoundary[] {
let low = 0;
let high = headers.length;
while (low < high) {
const mid = (low + high) >>> 1;
if (headers[mid]!.start <= position) low = mid + 1;
else high = mid;
}
let header: RedisHeaderBoundary | undefined = headers[low - 1];
const chain: RedisHeaderBoundary[] = [];
while (header) {
if (position < header.end) chain.push(header);
header = header.parent;
}
return chain.reverse();
}
/** Only searches outer sections (at most 65), never the virtual key source. */
export function findRedisOuterGroup(groups: readonly RedisOuterGroupBoundary[], position: number): RedisOuterGroupBoundary | undefined {
let low = 0;
let high = groups.length - 1;
while (low <= high) {
const mid = (low + high) >>> 1;
const group = groups[mid]!;
if (position < group.start) high = mid - 1;
else if (position >= group.end) low = mid + 1;
else return group;
}
return undefined;
}
interface Namespace {
id: string;
label: string;
count: number;
children: Map<string, Namespace>;
keys: RedisKeyInfo[];
}
interface Group {
id: string;
label: string;
keys: RedisKeyInfo[];
tree?: Namespace;
treeLength: number;
}
export interface GroupWork {
current: () => boolean;
yield: () => Promise<void>;
}
const CHUNK = 512;
/** Non-reactive index: ordinary append batches classify only new identities. */
export class RedisKeyGroupIndex {
readonly groups: Group[];
private readonly classify: ReturnType<typeof compileRedisKeyGroups>;
private readonly byId = new Map<string | null, Group>();
private readonly locations = new Map<string, { group: Group; offset: number; namespace?: Namespace; namespaceOffset?: number }>();
private consumed = 0;
private lastRaw: string | undefined;
constructor(rules: readonly RedisKeyGroupRule[], unmatched: string) {
this.classify = compileRedisKeyGroups(rules);
this.groups = rules
.filter((rule) => rule.enabled)
.map((rule) => {
const group = { id: `custom:${JSON.stringify(rule.id)}`, label: rule.name, keys: [], treeLength: 0 };
this.byId.set(rule.id, group);
return group;
});
const group = { id: "custom:unmatched", label: unmatched, keys: [], treeLength: 0 };
this.byId.set(null, group);
this.groups.push(group);
}
canAppend(keys: readonly RedisKeyInfo[]): boolean {
return keys.length >= this.consumed && (!this.consumed || keys[this.consumed - 1]?.key_raw === this.lastRaw);
}
async append(keys: readonly RedisKeyInfo[], work: GroupWork): Promise<boolean> {
for (let offset = this.consumed; offset < keys.length; ) {
if (!work.current()) return false;
const end = Math.min(offset + CHUNK, keys.length);
for (; offset < end; offset++) {
const key = keys[offset]!;
if (this.locations.has(key.key_raw)) continue;
const group = this.byId.get(this.classify(key.key_raw))!;
this.locations.set(key.key_raw, { group, offset: group.keys.length });
group.keys.push(key);
}
this.consumed = offset;
this.lastRaw = keys[offset - 1]?.key_raw;
if (offset < keys.length) await work.yield();
}
return work.current();
}
async project(view: "list" | "tree", separator: string, expanded: ReadonlySet<string>, work: GroupWork): Promise<{ rows: RedisGroupedRow[]; outerGroups: RedisOuterGroupBoundary[]; headerBoundaries: RedisHeaderBoundary[]; positions: { get: (id: string) => number | undefined } } | null> {
// Row ranges reference canonical key arrays. A million-key list projection
// is O(groups), not O(keys) per incoming batch, and only mounted leaves
// allocate presentation objects. Captured lengths make publication atomic.
const ranges: { start: number; length: number; row?: RedisVirtualGroupRow; keys?: readonly RedisKeyInfo[]; depth: number }[] = [];
const headers = new Map<string, number>();
const outerGroups: RedisOuterGroupBoundary[] = [];
const headerBoundaries: RedisHeaderBoundary[] = [];
const openHeaders: RedisHeaderBoundary[] = [];
const keyRanges = new Map<string, number>();
let length = 0;
let units = 0;
const checkpoint = async () => {
if (++units % CHUNK === 0) await work.yield();
return work.current();
};
const add = (row: RedisVirtualGroupRow) => {
while (openHeaders.length && openHeaders[openHeaders.length - 1]!.row.depth >= row.depth) openHeaders.pop()!.end = length;
const boundary = { start: length, end: length + 1, row, parent: openHeaders[openHeaders.length - 1] };
headerBoundaries.push(boundary);
openHeaders.push(boundary);
headers.set(row.id, length);
ranges.push({ start: length++, length: 1, row, depth: row.depth });
};
const addKeys = (id: string, keys: readonly RedisKeyInfo[], depth: number) => {
keyRanges.set(id, length);
if (keys.length) ranges.push({ start: length, length: keys.length, keys, depth });
length += keys.length;
};
const leaf = (key: RedisKeyInfo, label: string, depth: number): RedisGroupedKeyRow => ({ kind: "key", id: `key:${key.key_raw}`, key, label, depth });
for (const group of this.groups) {
if (!work.current()) return null;
if (group.id === "custom:unmatched" && !group.keys.length) continue;
const previous = outerGroups[outerGroups.length - 1];
if (previous) previous.end = length;
const row: RedisVirtualGroupRow = { kind: "virtual-group", id: group.id, label: group.label, depth: 0, count: group.keys.length };
outerGroups.push({ start: length, end: length + 1, row });
add(row);
if (!expanded.has(group.id)) continue;
if (view === "list" || !separator) {
addKeys(group.id, group.keys, 1);
} else {
// A namespace index is built only for an expanded outer group. It holds
// references to canonical records, not copies of metadata.
group.tree ??= { id: group.id, label: "", count: 0, children: new Map(), keys: [] };
for (let i = group.treeLength; i < group.keys.length; i++) {
const key = group.keys[i]!;
const parts = key.key_display.split(separator);
let node = group.tree;
const path: string[] = [];
node.count++;
for (const part of parts.slice(0, -1)) {
path.push(part);
let child = node.children.get(part);
if (!child) {
child = { id: `${group.id}:namespace:${JSON.stringify(path)}`, label: part, count: 0, children: new Map(), keys: [] };
node.children.set(part, child);
}
child.count++;
node = child;
}
const location = this.locations.get(key.key_raw)!;
location.namespace = node;
location.namespaceOffset = node.keys.length;
node.keys.push(key);
group.treeLength = i + 1;
if (!(await checkpoint())) return null;
}
const stack: { children: Iterator<Namespace>; depth: number }[] = [{ children: group.tree.children.values(), depth: 1 }];
addKeys(group.tree.id, group.tree.keys, 1);
while (stack.length) {
const frame = stack[stack.length - 1]!;
const result = frame.children.next();
if (result.done) {
stack.pop();
continue;
}
const node = result.value;
add({ kind: "virtual-group", id: node.id, label: node.label, depth: frame.depth, count: node.count });
if (expanded.has(node.id)) {
addKeys(node.id, node.keys, frame.depth + 1);
stack.push({ children: node.children.values(), depth: frame.depth + 1 });
}
if (!(await checkpoint())) return null;
}
}
}
const lastGroup = outerGroups[outerGroups.length - 1];
if (lastGroup) lastGroup.end = length;
for (const header of openHeaders) header.end = length;
const at = (index: number): RedisGroupedRow | undefined => {
if (index < 0 || index >= length) return undefined;
let low = 0;
let high = ranges.length - 1;
while (low <= high) {
const mid = (low + high) >>> 1;
const range = ranges[mid]!;
if (index < range.start) high = mid - 1;
else if (index >= range.start + range.length) low = mid + 1;
else {
if (range.row) return range.row;
const key = range.keys![index - range.start]!;
const parts = view === "tree" && separator ? key.key_display.split(separator) : [key.key_display];
return leaf(key, parts[parts.length - 1] ?? "", range.depth);
}
}
return undefined;
};
const rows = new Proxy([] as RedisGroupedRow[], {
get(target, property, receiver) {
if (property === "length") return length;
const n = typeof property === "string" && /^(0|[1-9]\d*)$/.test(property) ? Number(property) : -1;
return n >= 0 ? at(n) : Reflect.get(target, property, receiver);
},
has(target, property) {
const n = typeof property === "string" && /^(0|[1-9]\d*)$/.test(property) ? Number(property) : -1;
return n >= 0 ? n < length : Reflect.has(target, property);
},
});
const positions = {
get: (id: string) => {
if (!id.startsWith("key:")) return headers.get(id);
const location = this.locations.get(id.slice(4));
if (!location) return undefined;
const tree = view === "tree" && !!separator;
const start = keyRanges.get(tree ? (location.namespace?.id ?? "") : location.group.id);
return start === undefined ? undefined : start + (tree ? location.namespaceOffset! : location.offset);
},
};
return work.current() ? { rows, outerGroups, headerBoundaries, positions } : null;
}
}
@@ -0,0 +1,109 @@
/** Connection-persisted rules. Classification never changes Redis keys or SCAN. */
export interface RedisKeyGroupRule {
id: string;
name: string;
enabled: boolean;
includes: string[];
excludes: string[];
}
export interface RedisKeyGrouping {
version: 1;
enabled: boolean;
inner_view: "list" | "tree";
rules: RedisKeyGroupRule[];
}
export function defaultRedisKeyGrouping(): RedisKeyGrouping {
return { version: 1, enabled: false, inner_view: "list", rules: [] };
}
/** Reject invalid edits/imports rather than silently discarding saved rules. */
export function validateRedisKeyGrouping(value: unknown): RedisKeyGrouping {
if (!value || typeof value !== "object") throw new Error("Invalid Redis grouping configuration");
const config = value as Partial<RedisKeyGrouping>;
if (config.version !== 1 || typeof config.enabled !== "boolean" || !["list", "tree"].includes(config.inner_view ?? "") || !Array.isArray(config.rules) || config.rules.length > 64) throw new Error("Invalid Redis grouping configuration");
const ids = new Set<string>();
const rules = config.rules.map((rule) => {
if (!rule || typeof rule.id !== "string" || !rule.id || ids.has(rule.id) || typeof rule.name !== "string" || !rule.name.trim() || typeof rule.enabled !== "boolean") throw new Error("Invalid Redis grouping rule");
ids.add(rule.id);
for (const patterns of [rule.includes, rule.excludes]) {
if (!Array.isArray(patterns) || patterns.length > 64 || patterns.some((pattern) => typeof pattern !== "string" || new TextEncoder().encode(pattern).length > 1024)) throw new Error("Invalid Redis grouping patterns");
}
if (!rule.includes.length && !rule.excludes.length) throw new Error("Empty Redis grouping rule");
return { ...rule, name: rule.name.trim(), includes: [...rule.includes], excludes: [...rule.excludes] };
});
return { version: 1, enabled: config.enabled, inner_view: config.inner_view!, rules };
}
type Token = { kind: "star" } | { kind: "byte"; value: number } | { kind: "any" } | { kind: "class"; values: Set<number>; negate: boolean };
/** Redis MATCH is byte-oriented, including ? and bracket ranges. */
export function compileRedisGroupGlob(pattern: string): (bytes: Uint8Array) => boolean {
const source = new TextEncoder().encode(pattern);
const tokens: Token[] = [];
for (let i = 0; i < source.length; i++) {
const byte = source[i]!;
if (byte === 42) {
if (tokens[tokens.length - 1]?.kind !== "star") tokens.push({ kind: "star" });
} else if (byte === 63) tokens.push({ kind: "any" });
else if (byte === 92 && i + 1 < source.length) tokens.push({ kind: "byte", value: source[++i]! });
else if (byte === 91) {
const values = new Set<number>();
let cursor = i + 1;
const negate = source[cursor] === 94;
if (negate) cursor++;
while (cursor < source.length && source[cursor] !== 93) {
if (source[cursor] === 92 && cursor + 1 < source.length) values.add(source[++cursor]!);
else if (cursor + 2 < source.length && source[cursor + 1] === 45) {
const a = source[cursor]!;
const b = source[cursor + 2]!;
for (let n = Math.min(a, b); n <= Math.max(a, b); n++) values.add(n);
cursor += 2;
} else values.add(source[cursor]!);
cursor++;
}
tokens.push({ kind: "class", values, negate });
i = cursor;
} else tokens.push({ kind: "byte", value: byte });
}
// Greedy star retry is bounded O(pattern * key), not recursive/exponential.
return (bytes) => {
// Redis SCAN special-cases MATCH "*"; other nonempty patterns do not
// match an empty key, even a run of stars such as "**".
if (!bytes.length) return source.length === 0 || pattern === "*";
let p = 0;
let k = 0;
let star = -1;
let retry = 0;
while (k < bytes.length) {
const token = tokens[p];
if (token?.kind === "star") {
star = p++;
retry = k;
continue;
}
if (token && (token.kind === "any" || (token.kind === "byte" && token.value === bytes[k]) || (token.kind === "class" && token.values.has(bytes[k]!) !== token.negate))) {
p++;
k++;
continue;
}
if (star < 0) return false;
p = star + 1;
k = ++retry;
}
while (tokens[p]?.kind === "star") p++;
return p === tokens.length;
};
}
export function compileRedisKeyGroups(rules: readonly RedisKeyGroupRule[]): (keyRaw: string) => string | null {
const compiled = rules.filter((rule) => rule.enabled).map((rule) => ({ id: rule.id, includes: rule.includes.map(compileRedisGroupGlob), excludes: rule.excludes.map(compileRedisGroupGlob) }));
return (keyRaw) => {
const bytes = Uint8Array.from(atob(keyRaw), (char) => char.charCodeAt(0));
for (const rule of compiled) {
if ((!rule.includes.length || rule.includes.some((matches) => matches(bytes))) && !rule.excludes.some((matches) => matches(bytes))) return rule.id;
}
return null;
};
}
@@ -0,0 +1,12 @@
/** Small cancellation checkpoints need not each consume a browser frame. */
export function createRedisKeyViewYield(options: { now?: () => number; yieldTask?: () => Promise<void>; budgetMs?: number } = {}): () => Promise<void> {
const now = options.now ?? (() => performance.now());
const yieldTask = options.yieldTask ?? (() => new Promise<void>((resolve) => setTimeout(resolve, 0)));
const budget = options.budgetMs ?? 8;
let started = now();
return async () => {
if (now() - started < budget) return;
await yieldTask();
started = now();
};
}
@@ -0,0 +1,27 @@
import { findRedisHeaderChain, findRedisOuterGroup, type RedisHeaderBoundary, type RedisOuterGroupBoundary } from "./redisKeyGroupIndex";
export const REDIS_GROUP_ROW_HEIGHT = 30;
export function redisStickyHeaders(outer: readonly RedisOuterGroupBoundary[], headers: readonly RedisHeaderBoundary[], scroll: number, height: number, tree: boolean) {
const size = REDIS_GROUP_ROW_HEIGHT;
const capacity = tree ? Math.min(3, Math.floor((height * 0.3) / size)) : 1;
const group = findRedisOuterGroup(outer, scroll / size);
if (!capacity || !group || group.end <= group.start + 1 || scroll <= group.start * size) return [];
const outerOffset = Math.min(0, group.end * size - scroll - size);
if (!tree) return [{ row: group.row, top: outerOffset, omitted: false, path: group.row.label }];
// Probe only the small overlay band, never the virtual source. Do not cross
// the outer boundary while choosing descendants at a section transition.
const chain = findRedisHeaderChain(headers, Math.min(group.end - 0.001, (scroll + (capacity - 1) * size) / size)).filter((entry) => entry.end > entry.start + 1);
const candidates = chain.length > capacity ? [chain[0]!, ...chain.slice(-(capacity - 1))] : chain;
if (capacity === 1) candidates.splice(1);
const path = chain.map((entry) => entry.row.label).join(" › ");
return candidates.flatMap((entry, slot) => {
const top = slot * size;
if (entry.start * size >= scroll + top || entry.end * size <= scroll + top || entry.end <= entry.start + 1) return [];
return [{ row: entry.row, top: Math.min(top, entry.end * size - scroll - size), omitted: slot === 1 && chain.length > capacity, path }];
});
}
export function redisStickyHeight(sticky: ReturnType<typeof redisStickyHeaders>) {
return sticky.reduce((height, row) => Math.max(height, row.top + REDIS_GROUP_ROW_HEIGHT), 0);
}