@zeyolabs/kit 0.0.0-stage → 2026.11.5

package/storage/redis/client.ts

@@ -0,0 +1,219 @@
+import type { CfSocket, RedisConfig } from './schema';
+
+import { logger } from '../../monitoring/logger/client';
+import { encodeCommand, parseReply, RespReader, type RespValue } from './protocol';
+
+type Connection = {
+	reader: RespReader;
+	socket: CfSocket;
+	writer: WritableStreamDefaultWriter<Uint8Array>;
+};
+
+/** Two ways a dropped connection surfaces, neither the command's fault: Cloudflare's TCP socket
+ *  throws this exact message when the underlying connection resets (idle timeout, remote reset);
+ *  `RespReader` throws its own "connection closed unexpectedly" (+ "(mid-bulk)") when the socket
+ *  closes cleanly (a `read()` EOF) instead of throwing. Both are worth a same-command retry. */
+function isConnectionLost(err: unknown): boolean {
+	return (
+		err instanceof Error &&
+		(err.message === 'Network connection lost.' ||
+			err.message.startsWith('Redis connection closed unexpectedly'))
+	);
+}
+
+/** `HGETALL`'s flat `[field, value, field, value, ...]` reply as a plain object — `{}` for the
+ *  empty-array reply a nonexistent key gives back. */
+function flattenHash(flat: RespValue[]): Record<string, string> {
+	const out: Record<string, string> = {};
+	for (let i = 0; i < flat.length; i += 2) out[flat[i] as string] = flat[i + 1] as string;
+	return out;
+}
+
+/** Just the shape callers depend on — a test can hand-write a fake object matching this instead
+ *  of constructing `RedisClient` with a fake socket/VPC binding. */
+export interface IRedisClient {
+	close(): Promise<void>;
+	command(args: (number | string)[]): Promise<RespValue>;
+	eval(script: string, keys: string[], args: (number | string)[]): Promise<RespValue>;
+	hDel(key: string, ...fields: string[]): Promise<number>;
+	hGetAll(key: string): Promise<Record<string, string>>;
+	hGetAllMany(keys: string[]): Promise<Record<string, string>[]>;
+	hSet(key: string, fields: Record<string, number | string>): Promise<number>;
+	pipeline(commandsList: (number | string)[][]): Promise<RespValue[]>;
+}
+
+/** Thin Redis client over a hand-rolled RESP2 codec (`./protocol`) — one TCP connection per
+ *  instance, opened lazily on first `command()` and cached for the instance's life. Per-request
+ *  (a Workers TCP socket can't cross requests), same profile as `ManticoreClient`. `HGETALL`/
+ *  `HSET`/`HDEL`/`EVAL` are exposed as typed methods; `command()` is the escape hatch for
+ *  anything else. */
+export class RedisClient implements IRedisClient {
+	private connPromise: null | Promise<Connection> = null;
+	// RESP is one request/reply pair at a time over a single connection — a socket's
+	// ReadableStreamDefaultReader also physically rejects a second concurrent `read()` (`This
+	// ReadableStream only supports a single pending read request at a time`). Callers do issue
+	// concurrent commands on one instance (e.g. a bulk pacing load fires N HGETALLs in parallel),
+	// so every command is queued through this chain to run strictly one at a time regardless of
+	// call order — `.then(task, task)` runs the next task whether the previous one resolved or
+	// rejected, and the reassignment always resolves so one failed command never wedges the queue.
+	private queue: Promise<unknown> = Promise.resolve();
+
+	constructor(private readonly config: RedisConfig) {}
+
+	/** Close the connection if one was opened. Safe when never opened and best-effort — runs in the
+	 *  request-teardown `finally`, so a failed close must not throw. */
+	async close(): Promise<void> {
+		if (!this.connPromise) return;
+		const conn = await this.connPromise.catch(() => null);
+		this.connPromise = null;
+		if (!conn) return;
+		try {
+			await conn.socket.close();
+		} catch {
+			// best-effort teardown — nothing actionable on a failed close
+		}
+	}
+
+	/** Run an arbitrary RESP command — the escape hatch `hGetAll`/`hSet` are built on. Queued (see
+	 *  `queue`) so concurrent callers never share the connection's reader at the same instant. */
+	async command(args: (number | string)[]): Promise<RespValue> {
+		const run = async (): Promise<RespValue> => {
+			const conn = await this.getConnection();
+			await conn.writer.write(encodeCommand(args));
+			return await parseReply(conn.reader);
+		};
+		const attempt = async (): Promise<RespValue> => {
+			try {
+				return await run();
+			} catch (err) {
+				// A dead connection (idle timeout, socket reset) leaves `connPromise` cached but unusable —
+				// drop it so a retry (or the next call, if this was already the retry) reconnects instead
+				// of reusing the same dead connection.
+				this.connPromise = null;
+				if (!isConnectionLost(err)) {
+					await logger.error(err, { op: 'redis', summary: String(args[0]) });
+					throw err;
+				}
+				try {
+					return await run();
+				} catch (retryErr) {
+					this.connPromise = null;
+					await logger.error(retryErr, { op: 'redis', retried: true, summary: String(args[0]) });
+					throw retryErr;
+				}
+			}
+		};
+		const result = this.queue.then(attempt, attempt);
+		this.queue = result.then(
+			() => undefined,
+			() => undefined
+		);
+		return result;
+	}
+
+	/** `EVAL script numkeys key [key ...] arg [arg ...]` — the atomicity primitive for a
+	 *  check-and-mutate a plain `HSET`/`HINCRBY` can't express on its own (Redis runs the whole
+	 *  script as one operation, no other command can interleave). */
+	async eval(script: string, keys: string[], args: (number | string)[]): Promise<RespValue> {
+		return this.command(['EVAL', script, String(keys.length), ...keys, ...args]);
+	}
+
+	/** `HDEL key field [field ...]` — returns the count of fields actually removed. Absent, not
+	 *  empty-string, is how a cleared stamp reads back (matching Postgres NULL, not `''`). */
+	async hDel(key: string, ...fields: string[]): Promise<number> {
+		return (await this.command(['HDEL', key, ...fields])) as number;
+	}
+
+	/** `HGETALL key` as a plain field→value object — `{}` for a nonexistent key, matching Redis'
+	 *  own empty-array reply rather than a null one. */
+	async hGetAll(key: string): Promise<Record<string, string>> {
+		return flattenHash((await this.command(['HGETALL', key])) as RespValue[]);
+	}
+
+	/** `HGETALL` for many keys as one pipelined round trip instead of one round trip per key —
+	 *  same result shape as `Promise.all(keys.map((k) => hGetAll(k)))`, in the same order, but the
+	 *  N commands share a single network round trip (see `pipeline`). Use this over a manual
+	 *  `Promise.all` of `hGetAll` calls whenever `keys.length` isn't always 1 — that pattern is
+	 *  exactly what used to race the shared connection reader before `pipeline` existed. */
+	async hGetAllMany(keys: string[]): Promise<Record<string, string>[]> {
+		if (keys.length === 0) return [];
+		const replies = await this.pipeline(keys.map((key) => ['HGETALL', key]));
+		return replies.map((flat) => flattenHash(flat as RespValue[]));
+	}
+
+	/** `HSET key field value [field value ...]` — returns the count of NEW fields (Redis' own
+	 *  semantics: an existing field being overwritten doesn't count). */
+	async hSet(key: string, fields: Record<string, number | string>): Promise<number> {
+		const args: (number | string)[] = ['HSET', key];
+		for (const [field, value] of Object.entries(fields)) args.push(field, value);
+		return (await this.command(args)) as number;
+	}
+
+	/** Send several commands as one network round trip instead of one round trip per command —
+	 *  all writes go out before any reply is read back; RESP guarantees replies come back in the
+	 *  same order the commands were sent, so `results[i]` answers `commandsList[i]`. Queued the
+	 *  same as `command()` (as one unit — another caller's command can't land in the middle of a
+	 *  pipeline's writes or reads). Prefer a typed wrapper (`hGetAllMany`) over calling this
+	 *  directly where one exists. */
+	async pipeline(commandsList: (number | string)[][]): Promise<RespValue[]> {
+		const run = async (): Promise<RespValue[]> => {
+			const conn = await this.getConnection();
+			for (const args of commandsList) await conn.writer.write(encodeCommand(args));
+			const results: RespValue[] = [];
+			for (let i = 0; i < commandsList.length; i++) {
+				results.push(await parseReply(conn.reader));
+			}
+			return results;
+		};
+		const attempt = async (): Promise<RespValue[]> => {
+			try {
+				return await run();
+			} catch (err) {
+				this.connPromise = null;
+				if (!isConnectionLost(err)) {
+					await logger.error(err, { op: 'redis', summary: `pipeline(${commandsList.length})` });
+					throw err;
+				}
+				try {
+					return await run();
+				} catch (retryErr) {
+					this.connPromise = null;
+					await logger.error(retryErr, {
+						op: 'redis',
+						retried: true,
+						summary: `pipeline(${commandsList.length})`,
+					});
+					throw retryErr;
+				}
+			}
+		};
+		const result = this.queue.then(attempt, attempt);
+		this.queue = result.then(
+			() => undefined,
+			() => undefined
+		);
+		return result;
+	}
+
+	/** Workers' `connect()` requires a non-empty address, but the VPC service routes to its own
+	 *  registered target (`wrangler vpc service list`) and ignores this value — same as
+	 *  `ManticoreClient`. */
+	private async dialVpc(): Promise<CfSocket> {
+		return this.config.vpc.connect('127.0.0.1:6379');
+	}
+
+	private getConnection(): Promise<Connection> {
+		return (this.connPromise ??= (async () => {
+			const socket = await this.dialVpc();
+			const socketReader = socket.readable.getReader();
+			const reader = new RespReader({ read: () => socketReader.read() });
+			const writer = socket.writable.getWriter();
+
+			await writer.write(encodeCommand(['AUTH', this.config.user, this.config.password]));
+			const authReply = await parseReply(reader);
+			if (authReply !== 'OK') throw new Error(`Redis AUTH failed: ${String(authReply)}`);
+
+			return { reader, socket, writer };
+		})());
+	}
+}

package/storage/redis/protocol.ts

@@ -0,0 +1,119 @@
+// Hand-rolled RESP2 (Redis Serialization Protocol) codec — no Redis client runs on Workers (no
+// Node `net`), same reasoning as `packages/core/server/mail/imap/client.ts`'s own hand-rolled
+// IMAP parser over raw `cloudflare:sockets`. RESP2 is small enough (a handful of type-prefixed
+// lines) that hand-rolling it is less risk than gambling on an npm client's socket-shim
+// compatibility with the Workers runtime.
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export type RespValue = null | number | RespValue[] | string;
+
+/** Matches `packages/core/server/mail/imap/protocol.ts`'s `ByteSource` shape — a thin seam over a
+ *  `ReadableStreamDefaultReader<Uint8Array>` (real sockets) or a mock (tests). */
+export type ByteSource = { read(): Promise<{ done: boolean; value?: Uint8Array }> };
+
+/** Encode a command as a RESP2 array of bulk strings — the standard Redis request form
+ *  (`*<argc>\r\n$<len>\r\n<bytes>\r\n...`). Every arg is sent as a bulk string regardless of type;
+ *  Redis itself is untyped on the wire. */
+export function encodeCommand(args: (number | string)[]): Uint8Array {
+	const parts: Uint8Array[] = [encoder.encode(`*${args.length}\r\n`)];
+	for (const arg of args) {
+		const bytes = encoder.encode(String(arg));
+		parts.push(encoder.encode(`$${bytes.length}\r\n`), bytes, encoder.encode('\r\n'));
+	}
+	const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+	let offset = 0;
+	for (const part of parts) {
+		out.set(part, offset);
+		offset += part.length;
+	}
+	return out;
+}
+
+/** Buffers raw bytes off a `ByteSource` and slices out RESP frames (a line, or an exact-length
+ *  bulk payload) without decoding anything it doesn't have to — a bulk string's `$<len>` is a BYTE
+ *  length, so this must stay byte-buffered rather than accumulating a JS string (which the IMAP
+ *  reader can get away with, since IMAP literals are ASCII-length-prefixed text). */
+export class RespReader {
+	private buf = new Uint8Array(0);
+	private offset = 0;
+
+	constructor(private readonly source: ByteSource) {}
+
+	/** Read exactly `n` bytes, then discard the trailing CRLF a RESP bulk string always carries. */
+	async readExact(n: number): Promise<Uint8Array> {
+		while (this.buf.length - this.offset < n + 2) {
+			if (!(await this.fill())) throw new Error('Redis connection closed unexpectedly (mid-bulk)');
+		}
+		const bytes = this.buf.subarray(this.offset, this.offset + n);
+		this.offset += n + 2;
+		return bytes;
+	}
+
+	/** Read one CRLF-terminated line, without the CRLF. */
+	async readLine(): Promise<Uint8Array> {
+		for (;;) {
+			const idx = this.indexOfCrlf();
+			if (idx !== -1) {
+				const line = this.buf.subarray(this.offset, idx);
+				this.offset = idx + 2;
+				return line;
+			}
+			if (!(await this.fill())) throw new Error('Redis connection closed unexpectedly');
+		}
+	}
+
+	private async fill(): Promise<boolean> {
+		const { done, value } = await this.source.read();
+		if (done) return false;
+		if (value && value.length > 0) {
+			const merged = new Uint8Array(this.buf.length - this.offset + value.length);
+			merged.set(this.buf.subarray(this.offset));
+			merged.set(value, this.buf.length - this.offset);
+			this.buf = merged;
+			this.offset = 0;
+		}
+		return true;
+	}
+
+	private indexOfCrlf(): number {
+		for (let i = this.offset; i < this.buf.length - 1; i++) {
+			if (this.buf[i] === 13 && this.buf[i + 1] === 10) return i;
+		}
+		return -1;
+	}
+}
+
+/** Parse one RESP2 reply — recurses for `*` (array). A `-` (error) reply throws rather than
+ *  returning, since every caller needs to treat a Redis-level error as a failure, not a value to
+ *  branch on. */
+export async function parseReply(reader: RespReader): Promise<RespValue> {
+	const line = await reader.readLine();
+	const type = line[0];
+	const rest = decoder.decode(line.subarray(1));
+	switch (type) {
+		case 0x2b: // '+' simple string
+			return rest;
+		case 0x2d: // '-' error
+			throw new Error(`Redis error: ${rest}`);
+		case 0x3a: // ':' integer
+			return Number(rest);
+		case 0x24: {
+			// '$' bulk string
+			const len = Number(rest);
+			if (len === -1) return null;
+			return decoder.decode(await reader.readExact(len));
+		}
+		case 0x2a: {
+			// '*' array
+			const count = Number(rest);
+			if (count === -1) return null;
+			const items: RespValue[] = [];
+			for (let i = 0; i < count; i++) items.push(await parseReply(reader));
+			return items;
+		}
+		default:
+			throw new Error(`Redis protocol error: unexpected reply type ${String.fromCharCode(type)}`);
+	}
+}

package/storage/redis/schema.ts

@@ -0,0 +1,17 @@
+/** A Cloudflare socket (from a VPC Service `.connect()` or `cloudflare:sockets`'s `connect()`):
+ *  Web streams, the same shape either way — see `packages/core/server/mail/imap/client.ts` for
+ *  the same technique against a different wire protocol. */
+export type CfSocket = {
+	close(): Promise<void>;
+	readable: ReadableStream<Uint8Array>;
+	writable: WritableStream<Uint8Array>;
+};
+
+/** Resolved Redis connection config — `vpc`'s `.connect()` opens a raw socket to Redis's `:6379`
+ *  listener. The caller reads it off its own `EnvStore` (`env.vpc('REDIS_VPC')`), not a binding
+ *  name for this client to look up itself. Same shape as `ManticoreConfig`'s `vpc` field. */
+export type RedisConfig = {
+	password: string;
+	user: string;
+	vpc: Fetcher;
+};

package/storage/redis/testing.ts

@@ -0,0 +1,122 @@
+import type { RedisClient } from './client';
+import type { RespValue } from './protocol';
+
+type StringEntry = { expiresAt?: number; value: string };
+
+/** In-memory `RedisClient` stand-in for tests: `hSet`/`hGetAll`/`hGetAllMany`/`hDel`/`command`/
+ *  `pipeline` round-trip for real, no live connection needed. The returned client also carries a
+ *  `reset()` that clears all keys, so a caller doesn't have to destructure `{ client, reset }`
+ *  apart -- `const redis = mockRedis(); ...; redis.reset();`.
+ *
+ *  `RedisClient` is a class with private fields (`connPromise`/`queue`), so no plain object can
+ *  structurally satisfy it -- the `as unknown as RedisClient` cast below is required, not a
+ *  shortcut. What that cast does hide is method *coverage*: every method on the cast object must
+ *  actually behave like the real one, or a caller that reaches past `hSet`/`hGetAll` (e.g. the
+ *  raw `command()` escape hatch `typed-rows.service.server.ts` uses for `SET ... EX`) gets a
+ *  silent `undefined is not a function` instead of a compile error. `command()`/`pipeline()` are
+ *  real here for exactly that reason; `eval()` throws instead of faking a Lua interpreter, since
+ *  nothing in this codebase calls it yet. */
+export function mockRedis(): RedisClient & { reset: () => void } {
+	const hashes = new Map<string, Record<string, string>>();
+	const strings = new Map<string, StringEntry>();
+
+	const hGetAll = async (key: string): Promise<Record<string, string>> => ({
+		...(hashes.get(key) ?? {}),
+	});
+	const hSet = async (key: string, fields: Record<string, number | string>): Promise<number> => {
+		const hash = hashes.get(key) ?? {};
+		let added = 0;
+		for (const [field, value] of Object.entries(fields)) {
+			if (!(field in hash)) added++;
+			hash[field] = String(value);
+		}
+		hashes.set(key, hash);
+		return added;
+	};
+	const hDel = async (key: string, ...fields: string[]): Promise<number> => {
+		const hash = hashes.get(key);
+		if (!hash) return 0;
+		let removed = 0;
+		for (const field of fields) {
+			if (field in hash) {
+				delete hash[field];
+				removed++;
+			}
+		}
+		return removed;
+	};
+
+	// Not a real RESP dispatcher -- just the commands this codebase actually issues via the raw
+	// escape hatch (SET/GET, with SET's optional `EX <seconds>` ttl) plus HSET/HGETALL/HDEL routed
+	// through the same maps the typed methods use, so mixing `command()` and `hSet()` on one fake
+	// sees one consistent store. Add a case if a future caller needs one -- the default throws
+	// instead of silently no-op'ing so a gap here fails loud, at the call site, immediately.
+	const command = async (args: (number | string)[]): Promise<RespValue> => {
+		const [cmd, ...rest] = args.map(String);
+		switch (cmd.toUpperCase()) {
+			case 'DEL': {
+				const [key] = rest;
+				const existed = strings.delete(key);
+				return existed ? 1 : 0;
+			}
+			case 'GET': {
+				const [key] = rest;
+				const entry = strings.get(key);
+				if (!entry) return null;
+				if (entry.expiresAt !== undefined && entry.expiresAt <= Date.now()) {
+					strings.delete(key);
+					return null;
+				}
+				return entry.value;
+			}
+			case 'HDEL': {
+				const [key, ...fields] = rest;
+				return hDel(key, ...fields);
+			}
+			case 'HGETALL': {
+				const [key] = rest;
+				return Object.entries(await hGetAll(key)).flat();
+			}
+			case 'HSET': {
+				const [key, ...pairs] = rest;
+				const fields: Record<string, string> = {};
+				for (let i = 0; i < pairs.length; i += 2) fields[pairs[i]] = pairs[i + 1];
+				return hSet(key, fields);
+			}
+			case 'SET': {
+				const [key, value, ...opts] = rest;
+				const exIndex = opts.findIndex((o) => o.toUpperCase() === 'EX');
+				const ttlSeconds = exIndex >= 0 ? Number(opts[exIndex + 1]) : undefined;
+				strings.set(key, {
+					expiresAt: ttlSeconds !== undefined ? Date.now() + ttlSeconds * 1000 : undefined,
+					value,
+				});
+				return 'OK';
+			}
+			default:
+				throw new Error(`mockRedis(): unhandled command "${cmd}" -- add a case if a test needs it`);
+		}
+	};
+
+	return {
+		close: async () => {},
+		command,
+		eval: async () => {
+			throw new Error('mockRedis(): eval() is not implemented -- no test needs Lua scripting yet');
+		},
+		hDel,
+		hGetAll,
+		hGetAllMany: async (keys: string[]): Promise<Record<string, string>[]> =>
+			Promise.all(keys.map((key) => hGetAll(key))),
+		hSet,
+		pipeline: async (commandsList: (number | string)[][]): Promise<RespValue[]> => {
+			const results: RespValue[] = [];
+			for (const args of commandsList) results.push(await command(args));
+			return results;
+		},
+		reset: () => {
+			hashes.clear();
+			strings.clear();
+		},
+	} as unknown as RedisClient & { reset: () => void };
+}

package/utils/crypto.ts

@@ -0,0 +1,36 @@
+import { sha256 } from '@oslojs/crypto/sha2';
+import { constantTimeEqual } from '@oslojs/crypto/subtle';
+import { decodeHex, encodeHexLowerCase } from '@oslojs/encoding';
+
+/** Small, dependency-free crypto primitives shared across every realm that mints or verifies a
+ *  secret (order links, cron/webhook headers, …) — a plain object of pure functions, not a
+ *  service: nothing here reads a binding or holds state. A `Crypto` helper, minus the
+ *  token-at-rest `encrypt`/`decrypt` this project has no use for. */
+export const Crypto = {
+	/** sha256 of a secret, hex-encoded — what's actually stored (never the raw secret), so a
+	 *  leaked DB row can't be replayed. Pair with `verifySecret` to check one back. */
+	hashSecret(secret: string): string {
+		return encodeHexLowerCase(sha256(new TextEncoder().encode(secret)));
+	},
+
+	/** A fresh, random, hex-encoded secret of `byteLength` bytes (defaults to 32 — 256 bits). */
+	getRandomSecret(byteLength = 32): string {
+		return encodeHexLowerCase(crypto.getRandomValues(new Uint8Array(byteLength)));
+	},
+
+	/** Constant-time string compare for secret-guarded routes/webhooks (a cron-secret header, a
+	 *  webhook's clientState, …). Returns `false` (never throws) on a length mismatch, so this is
+	 *  safe on arbitrary header/query input. */
+	timingSafeEquals(a: string, b: string): boolean {
+		const enc = new TextEncoder();
+		return constantTimeEqual(enc.encode(a), enc.encode(b));
+	},
+
+	/** Constant-time check that `secret` hashes to `hash` (as produced by `hashSecret`) — never a
+	 *  plain `===` on the derived hash, or a failed check's timing could leak how many leading
+	 *  bytes matched. */
+	verifySecret(secret: string, hash: string): boolean {
+		const provided = sha256(new TextEncoder().encode(secret));
+		return constantTimeEqual(provided, decodeHex(hash));
+	},
+};