patchwork-os 0.2.0-beta.6.canary.21 → 0.2.0-beta.6.canary.23

package/dist/connectors/redis.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Redis connector — read-only operations against a Redis server.
+ *
+ * Auth: connection URL (redis:// or rediss://) optionally with password.
+ *   - Stored: getSecretJsonSync("redis") → RedisTokens
+ *
+ * Tools (READ-ONLY only — no SET/DEL/FLUSHDB/CONFIG mutators):
+ *   info, dbsize, keys (SCAN-based), type, get, hgetall, lrange,
+ *   smembers, zrange, ttl, command_run (allowlist-gated)
+ *
+ * Driver loaded lazily via `await import("redis")` (node-redis v4+).
+ * Hermetic tests inject a fake module via `__setRedisModuleForTest`.
+ *
+ * Extends BaseConnector for unified status, error normalization,
+ * token persistence. apiCall is unused because Redis is not HTTP —
+ * errors flow through normalizeError directly.
+ */
+import { type AuthContext, BaseConnector, type ConnectorError, type ConnectorStatus } from "./baseConnector.js";
+export interface RedisTokens {
+    url: string;
+    username?: string;
+    password?: string;
+    database?: number;
+    tls?: boolean;
+    connected_at: string;
+}
+/** Minimal subset of the node-redis v4 client surface we exercise. */
+export interface RedisClientLike {
+    connect(): Promise<unknown>;
+    quit(): Promise<unknown>;
+    ping(): Promise<string>;
+    info(section?: string): Promise<string>;
+    dbSize(): Promise<number>;
+    type(key: string): Promise<string>;
+    get(key: string): Promise<string | null>;
+    hGetAll(key: string): Promise<Record<string, string>>;
+    lRange(key: string, start: number, stop: number): Promise<string[]>;
+    sMembers(key: string): Promise<string[]>;
+    zRangeWithScores(key: string, start: number, stop: number): Promise<Array<{
+        value: string;
+        score: number;
+    }>>;
+    zRange(key: string, start: number, stop: number): Promise<string[]>;
+    ttl(key: string): Promise<number>;
+    scan(cursor: number | string, opts?: {
+        MATCH?: string;
+        COUNT?: number;
+    }): Promise<{
+        cursor: number | string;
+        keys: string[];
+    }>;
+    sendCommand(args: string[]): Promise<unknown>;
+    on(event: string, listener: (...args: unknown[]) => void): unknown;
+}
+export interface RedisModuleLike {
+    createClient(opts: {
+        url: string;
+        username?: string;
+        password?: string;
+        database?: number;
+    }): RedisClientLike;
+}
+/** Test-only: inject a fake `redis` module so tests run hermetically. */
+export declare function __setRedisModuleForTest(mod: RedisModuleLike | null): void;
+/**
+ * Commands the connector permits. First token is matched case-insensitively.
+ * Multi-word commands (e.g. "DEBUG OBJECT") match against the first token
+ * AND the joined first-two-token form so callers can issue either shape.
+ */
+export declare const READ_ONLY_COMMANDS: ReadonlySet<string>;
+export declare function isReadOnlyCommand(cmd: string, args?: string[]): boolean;
+export declare function loadTokens(): RedisTokens | null;
+export declare function saveTokens(tokens: RedisTokens): void;
+export declare function clearTokens(): void;
+export declare function parseInfo(raw: string): Record<string, string>;
+export declare class RedisConnector extends BaseConnector {
+    readonly providerName = "redis";
+    protected cachedTokens: RedisTokens | null;
+    private client;
+    protected getOAuthConfig(): null;
+    authenticate(): Promise<AuthContext>;
+    /** Get (or lazily create + connect) the singleton client. */
+    getClient(): Promise<RedisClientLike>;
+    /** Tear down the client (used by disconnect HTTP handler + tests). */
+    disconnect(): Promise<void>;
+    healthCheck(): Promise<{
+        ok: boolean;
+        error?: ConnectorError;
+    }>;
+    normalizeError(error: unknown): ConnectorError;
+    getStatus(): ConnectorStatus;
+    info(section?: string): Promise<Record<string, string>>;
+    dbsize(): Promise<number>;
+    /**
+     * SCAN-based key iteration. Never uses `KEYS *` because that blocks the
+     * server. Stops once `limit` keys are gathered OR the cursor wraps to 0.
+     */
+    keys(pattern: string, limit?: number): Promise<string[]>;
+    type(key: string): Promise<string>;
+    get(key: string): Promise<string | null>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    lrange(key: string, start?: number, stop?: number): Promise<string[]>;
+    smembers(key: string, limit?: number): Promise<string[]>;
+    zrange(key: string, start?: number, stop?: number, withScores?: boolean): Promise<Array<{
+        value: string;
+        score: number;
+    }> | string[]>;
+    ttl(key: string): Promise<number>;
+    /**
+     * Generic escape hatch. The command MUST appear in the read-only allowlist.
+     * Anything else is rejected before it ever touches the wire.
+     */
+    command_run(cmd: string, args?: string[]): Promise<unknown>;
+}
+/** Hide the password from any redis:// URL before logging or display. */
+export declare function redactUrl(url: string): string;
+export declare function getRedisConnector(): RedisConnector;
+export declare function resetRedisConnector(): Promise<void>;
+export { loadTokens as isConnected };
+export interface ConnectorHandlerResult {
+    status: number;
+    body: string;
+    contentType?: string;
+}
+/**
+ * POST /connections/redis/connect
+ *   { url: "redis://...", username?, password?, database?, tls? }
+ *
+ * Verifies the URL by opening a transient client and PINGing. Stores tokens
+ * on success.
+ */
+export declare function handleRedisConnect(body: string): Promise<ConnectorHandlerResult>;
+/**
+ * POST /connections/redis/test — verify stored connection still works.
+ */
+export declare function handleRedisTest(): Promise<ConnectorHandlerResult>;
+/**
+ * DELETE /connections/redis — remove stored tokens and tear down the client.
+ */
+export declare function handleRedisDisconnect(): Promise<ConnectorHandlerResult>;

package/dist/connectors/redis.js

@@ -0,0 +1,571 @@
+/**
+ * Redis connector — read-only operations against a Redis server.
+ *
+ * Auth: connection URL (redis:// or rediss://) optionally with password.
+ *   - Stored: getSecretJsonSync("redis") → RedisTokens
+ *
+ * Tools (READ-ONLY only — no SET/DEL/FLUSHDB/CONFIG mutators):
+ *   info, dbsize, keys (SCAN-based), type, get, hgetall, lrange,
+ *   smembers, zrange, ttl, command_run (allowlist-gated)
+ *
+ * Driver loaded lazily via `await import("redis")` (node-redis v4+).
+ * Hermetic tests inject a fake module via `__setRedisModuleForTest`.
+ *
+ * Extends BaseConnector for unified status, error normalization,
+ * token persistence. apiCall is unused because Redis is not HTTP —
+ * errors flow through normalizeError directly.
+ */
+import { BaseConnector, } from "./baseConnector.js";
+import { deleteSecretJsonSync, getSecretJsonSync, storeSecretJsonSync, } from "./tokenStorage.js";
+// ------------------------------------------------------------------ lazy driver
+let _injectedModule = null;
+/** Test-only: inject a fake `redis` module so tests run hermetically. */
+export function __setRedisModuleForTest(mod) {
+    _injectedModule = mod;
+}
+async function loadRedisModule() {
+    if (_injectedModule)
+        return _injectedModule;
+    try {
+        // The `redis` package is an optional peer — typecheck environments may
+        // not have it installed. The runtime guard below catches the missing
+        // module and tells the operator to install it.
+        // @ts-expect-error optional peer; resolved at runtime
+        const mod = (await import("redis"));
+        if (!mod || typeof mod.createClient !== "function") {
+            throw new Error("redis module missing createClient export");
+        }
+        return mod;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Redis driver not installed (${msg}). Run: npm install redis`);
+    }
+}
+// ------------------------------------------------------------------ read-only allowlist
+/**
+ * Commands the connector permits. First token is matched case-insensitively.
+ * Multi-word commands (e.g. "DEBUG OBJECT") match against the first token
+ * AND the joined first-two-token form so callers can issue either shape.
+ */
+export const READ_ONLY_COMMANDS = new Set([
+    "GET",
+    "MGET",
+    "EXISTS",
+    "TYPE",
+    "TTL",
+    "PTTL",
+    "HGET",
+    "HGETALL",
+    "HMGET",
+    "HKEYS",
+    "HVALS",
+    "HLEN",
+    "HEXISTS",
+    "LRANGE",
+    "LLEN",
+    "LINDEX",
+    "SMEMBERS",
+    "SCARD",
+    "SISMEMBER",
+    "ZRANGE",
+    "ZREVRANGE",
+    "ZSCORE",
+    "ZCARD",
+    "ZRANGEBYSCORE",
+    "SCAN",
+    "HSCAN",
+    "SSCAN",
+    "ZSCAN",
+    "DBSIZE",
+    "INFO",
+    "PING",
+    "CLIENT",
+    "MEMORY",
+    "DEBUG OBJECT",
+]);
+export function isReadOnlyCommand(cmd, args = []) {
+    if (typeof cmd !== "string" || cmd.length === 0)
+        return false;
+    const head = cmd.trim().toUpperCase();
+    if (READ_ONLY_COMMANDS.has(head))
+        return true;
+    // Two-word form (e.g. "DEBUG OBJECT")
+    if (args.length > 0 && typeof args[0] === "string") {
+        const joined = `${head} ${args[0].toUpperCase()}`;
+        if (READ_ONLY_COMMANDS.has(joined))
+            return true;
+    }
+    return false;
+}
+// ------------------------------------------------------------------ token helpers
+export function loadTokens() {
+    return getSecretJsonSync("redis");
+}
+export function saveTokens(tokens) {
+    storeSecretJsonSync("redis", tokens);
+}
+export function clearTokens() {
+    deleteSecretJsonSync("redis");
+}
+// ------------------------------------------------------------------ INFO parsing
+export function parseInfo(raw) {
+    const out = {};
+    for (const line of raw.split(/\r?\n/)) {
+        if (!line || line.startsWith("#"))
+            continue;
+        const idx = line.indexOf(":");
+        if (idx <= 0)
+            continue;
+        const k = line.slice(0, idx).trim();
+        const v = line.slice(idx + 1).trim();
+        if (k)
+            out[k] = v;
+    }
+    return out;
+}
+// ------------------------------------------------------------------ connector
+export class RedisConnector extends BaseConnector {
+    providerName = "redis";
+    cachedTokens = null;
+    client = null;
+    getOAuthConfig() {
+        return null;
+    }
+    async authenticate() {
+        const tokens = loadTokens();
+        if (!tokens) {
+            throw new Error("Redis not connected. Run: patchwork connect redis  (provide URL)");
+        }
+        this.cachedTokens = tokens;
+        // Redis isn't a bearer-token API; the auth context is informational.
+        return { token: tokens.password ?? "" };
+    }
+    /** Get (or lazily create + connect) the singleton client. */
+    async getClient() {
+        if (this.client)
+            return this.client;
+        const tokens = this.cachedTokens ?? loadTokens();
+        if (!tokens) {
+            throw new Error("Redis not connected. Run: patchwork connect redis  (provide URL)");
+        }
+        this.cachedTokens = tokens;
+        const mod = await loadRedisModule();
+        const client = mod.createClient({
+            url: tokens.url,
+            username: tokens.username,
+            password: tokens.password,
+            database: tokens.database,
+        });
+        // Swallow background error events so an idle connection drop doesn't
+        // bubble up as an unhandled error; commands surface their own errors.
+        try {
+            client.on("error", () => { });
+        }
+        catch {
+            /* some fakes don't implement .on */
+        }
+        await client.connect();
+        this.client = client;
+        return client;
+    }
+    /** Tear down the client (used by disconnect HTTP handler + tests). */
+    async disconnect() {
+        const c = this.client;
+        this.client = null;
+        if (!c)
+            return;
+        try {
+            await c.quit();
+        }
+        catch {
+            /* ignore quit errors */
+        }
+    }
+    async healthCheck() {
+        try {
+            const c = await this.getClient();
+            const pong = await c.ping();
+            if (typeof pong === "string" && pong.toUpperCase() === "PONG") {
+                return { ok: true };
+            }
+            return {
+                ok: false,
+                error: {
+                    code: "provider_error",
+                    message: `Unexpected PING reply: ${String(pong)}`,
+                    retryable: false,
+                },
+            };
+        }
+        catch (err) {
+            return { ok: false, error: this.normalizeError(err) };
+        }
+    }
+    normalizeError(error) {
+        const msg = error instanceof Error ? error.message : String(error ?? "unknown");
+        if (/WRONGPASS|NOAUTH/i.test(msg)) {
+            return {
+                code: "auth_expired",
+                message: "Redis authentication failed",
+                retryable: false,
+                suggestedAction: "Reconnect: patchwork connect redis",
+            };
+        }
+        if (/NOPERM/i.test(msg)) {
+            return {
+                code: "permission_denied",
+                message: "Redis user lacks permission for this command",
+                retryable: false,
+            };
+        }
+        if (/ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EHOSTUNREACH/i.test(msg)) {
+            return {
+                code: "network_error",
+                message: `Cannot reach Redis server: ${msg}`,
+                retryable: true,
+            };
+        }
+        return {
+            code: "provider_error",
+            message: msg,
+            retryable: false,
+        };
+    }
+    getStatus() {
+        const tokens = loadTokens();
+        return {
+            id: "redis",
+            status: tokens ? "connected" : "disconnected",
+            lastSync: tokens?.connected_at,
+            workspace: tokens ? redactUrl(tokens.url) : undefined,
+        };
+    }
+    // ---------------------------------------------------------------- read ops
+    async info(section) {
+        const c = await this.getClient();
+        try {
+            const raw = section ? await c.info(section) : await c.info();
+            return parseInfo(raw);
+        }
+        catch (err) {
+            throw new Error(this.normalizeError(err).message);
+        }
+    }
+    async dbsize() {
+        const c = await this.getClient();
+        try {
+            return await c.dbSize();
+        }
+        catch (err) {
+            throw new Error(this.normalizeError(err).message);
+        }
+    }
+    /**
+     * SCAN-based key iteration. Never uses `KEYS *` because that blocks the
+     * server. Stops once `limit` keys are gathered OR the cursor wraps to 0.
+     */
+    async keys(pattern, limit = 100) {
+        if (typeof pattern !== "string" || pattern.length === 0) {
+            throw new Error("pattern must be a non-empty string");
+        }
+        const cap = Math.max(1, Math.min(limit, 10_000));
+        const c = await this.getClient();
+        const collected = [];
+        let cursor = 0;
+        try {
+            // Guard against pathological servers that never wrap by capping iterations.
+            for (let i = 0; i < 1000; i++) {
+                const res = await c.scan(cursor, { MATCH: pattern, COUNT: 100 });
+                if (Array.isArray(res.keys)) {
+                    for (const k of res.keys) {
+                        collected.push(k);
+                        if (collected.length >= cap)
+                            return collected;
+                    }
+                }
+                cursor = res.cursor;
+                // node-redis returns cursor 0 (number or string) when iteration done.
+                if (cursor === 0 || cursor === "0")
+                    break;
+            }
+            return collected;
+        }
+        catch (err) {
+            throw new Error(this.normalizeError(err).message);
+        }
+    }
+    async type(key) {
+        const c = await this.getClient();
+        try {
+            return await c.type(key);
+        }
+        catch (err) {
+            throw new Error(this.normalizeError(err).message);
+        }
+    }
+    async get(key) {
+        const c = await this.getClient();
+        try {
+            const t = await c.type(key);
+            if (t !== "string" && t !== "none") {
+                throw new Error(`WRONGTYPE: GET only supports string keys (key is ${t})`);
+            }
+            return await c.get(key);
+        }
+        catch (err) {
+            throw new Error(this.normalizeError(err).message);
+        }
+    }
+    async hgetall(key) {
+        const c = await this.getClient();
+        try {
+            return await c.hGetAll(key);
+        }
+        catch (err) {
+            throw new Error(this.normalizeError(err).message);
+        }
+    }
+    async lrange(key, start = 0, stop = 99) {
+        const c = await this.getClient();
+        try {
+            return await c.lRange(key, start, stop);
+        }
+        catch (err) {
+            throw new Error(this.normalizeError(err).message);
+        }
+    }
+    async smembers(key, limit = 100) {
+        const c = await this.getClient();
+        try {
+            const all = await c.sMembers(key);
+            const cap = Math.max(1, Math.min(limit, 10_000));
+            return all.slice(0, cap);
+        }
+        catch (err) {
+            throw new Error(this.normalizeError(err).message);
+        }
+    }
+    async zrange(key, start = 0, stop = 99, withScores = true) {
+        const c = await this.getClient();
+        try {
+            if (withScores)
+                return await c.zRangeWithScores(key, start, stop);
+            return await c.zRange(key, start, stop);
+        }
+        catch (err) {
+            throw new Error(this.normalizeError(err).message);
+        }
+    }
+    async ttl(key) {
+        const c = await this.getClient();
+        try {
+            return await c.ttl(key);
+        }
+        catch (err) {
+            throw new Error(this.normalizeError(err).message);
+        }
+    }
+    /**
+     * Generic escape hatch. The command MUST appear in the read-only allowlist.
+     * Anything else is rejected before it ever touches the wire.
+     */
+    async command_run(cmd, args = []) {
+        if (!isReadOnlyCommand(cmd, args)) {
+            const err = {
+                code: "permission_denied",
+                message: `Command "${cmd}" is not in the read-only allowlist`,
+                retryable: false,
+                suggestedAction: "Patchwork Redis connector is read-only; use a separate tool for mutations.",
+            };
+            throw new Error(err.message);
+        }
+        if (!Array.isArray(args)) {
+            throw new Error("args must be an array of strings");
+        }
+        for (const a of args) {
+            if (typeof a !== "string") {
+                throw new Error("all args must be strings");
+            }
+        }
+        const c = await this.getClient();
+        try {
+            return await c.sendCommand([cmd, ...args]);
+        }
+        catch (err) {
+            throw new Error(this.normalizeError(err).message);
+        }
+    }
+}
+// ------------------------------------------------------------------ helpers
+/** Hide the password from any redis:// URL before logging or display. */
+export function redactUrl(url) {
+    try {
+        const u = new URL(url);
+        if (u.password)
+            u.password = "***";
+        return u.toString();
+    }
+    catch {
+        return url;
+    }
+}
+// ------------------------------------------------------------------ singleton
+let _instance = null;
+export function getRedisConnector() {
+    if (!_instance)
+        _instance = new RedisConnector();
+    return _instance;
+}
+export async function resetRedisConnector() {
+    if (_instance) {
+        try {
+            await _instance.disconnect();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    _instance = null;
+}
+export { loadTokens as isConnected };
+function jsonRes(status, body) {
+    return {
+        status,
+        contentType: "application/json",
+        body: JSON.stringify(body),
+    };
+}
+/**
+ * POST /connections/redis/connect
+ *   { url: "redis://...", username?, password?, database?, tls? }
+ *
+ * Verifies the URL by opening a transient client and PINGing. Stores tokens
+ * on success.
+ */
+export async function handleRedisConnect(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return jsonRes(400, { ok: false, error: "Invalid JSON body" });
+    }
+    if (typeof parsed.url !== "string" || parsed.url.length === 0) {
+        return jsonRes(400, {
+            ok: false,
+            error: 'Missing "url" (e.g. redis://localhost:6379 or rediss://...)',
+        });
+    }
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(parsed.url);
+    }
+    catch {
+        return jsonRes(400, { ok: false, error: "Malformed Redis URL" });
+    }
+    if (parsedUrl.protocol !== "redis:" && parsedUrl.protocol !== "rediss:") {
+        return jsonRes(400, {
+            ok: false,
+            error: 'URL must use the "redis://" or "rediss://" scheme',
+        });
+    }
+    const tokens = {
+        url: parsed.url,
+        username: typeof parsed.username === "string" ? parsed.username : undefined,
+        password: typeof parsed.password === "string" ? parsed.password : undefined,
+        database: typeof parsed.database === "number" && Number.isInteger(parsed.database)
+            ? parsed.database
+            : undefined,
+        tls: parsed.tls === true || parsedUrl.protocol === "rediss:",
+        connected_at: new Date().toISOString(),
+    };
+    let mod;
+    try {
+        mod = await loadRedisModule();
+    }
+    catch (err) {
+        return jsonRes(500, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+    const client = mod.createClient({
+        url: tokens.url,
+        username: tokens.username,
+        password: tokens.password,
+        database: tokens.database,
+    });
+    try {
+        try {
+            client.on("error", () => { });
+        }
+        catch {
+            /* fakes may lack .on */
+        }
+        await client.connect();
+        const pong = await client.ping();
+        if (typeof pong !== "string" || pong.toUpperCase() !== "PONG") {
+            return jsonRes(401, {
+                ok: false,
+                error: `Unexpected PING reply: ${String(pong)}`,
+            });
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const status = /WRONGPASS|NOAUTH/i.test(msg) ? 401 : 502;
+        try {
+            await client.quit();
+        }
+        catch {
+            /* ignore */
+        }
+        return jsonRes(status, { ok: false, error: msg });
+    }
+    try {
+        await client.quit();
+    }
+    catch {
+        /* ignore */
+    }
+    saveTokens(tokens);
+    await resetRedisConnector();
+    return jsonRes(200, {
+        ok: true,
+        workspace: redactUrl(tokens.url),
+        connectedAt: tokens.connected_at,
+    });
+}
+/**
+ * POST /connections/redis/test — verify stored connection still works.
+ */
+export async function handleRedisTest() {
+    const tokens = loadTokens();
+    if (!tokens) {
+        return jsonRes(400, { ok: false, error: "Redis not connected" });
+    }
+    try {
+        const connector = getRedisConnector();
+        const check = await connector.healthCheck();
+        return jsonRes(check.ok ? 200 : 401, {
+            ok: check.ok,
+            ...(check.ok ? {} : { error: check.error?.message }),
+        });
+    }
+    catch (err) {
+        return jsonRes(500, {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/**
+ * DELETE /connections/redis — remove stored tokens and tear down the client.
+ */
+export async function handleRedisDisconnect() {
+    clearTokens();
+    await resetRedisConnector();
+    return jsonRes(200, { ok: true });
+}
+//# sourceMappingURL=redis.js.map