okengine 0.10.3 → 0.11.0

package/src/drivers/libsql.ts

@@ -1,179 +0,0 @@
-/**
- * `libsql` driver — binds `@libsql/client` (optional peer, dynamic import).
- *
- * Protocol-named: libSQL speaks the sqlite wire dialect plus native ANN
- * vectors (`F32_BLOB` + `libsql_vector_idx` + `vector_top_k`). Classic libSQL
- * only — never the Turso Rust rewrite (`@tursodatabase/database`).
- *
- * Serves both the `sql` facet (same `?` placeholder convention as `sqlite`)
- * and the `index` facet (native ANN, no JS-side distance math).
- *
- * Latency note: local file / `:memory:` opens are in-process like sqlite.
- */
-
-import { customType, sqliteTable, text } from "drizzle-orm/sqlite-core";
-import type {
-  IndexHit,
-  IndexOpenOptions,
-  SqlConnectOptions,
-  SqlConnection,
-  SqlDriver,
-  SqlRow,
-  VectorIndexDriver,
-  VectorIndexStore,
-} from "./types.ts";
-
-/** `@libsql/client` is an optional peer — loaded only when this driver runs. */
-type LibsqlModule = typeof import("@libsql/client");
-
-async function loadLibsql(): Promise<LibsqlModule> {
-  try {
-    return await import("@libsql/client");
-  } catch {
-    throw new Error(
-      "libsql driver: install optional peer `@libsql/client` (bun add @libsql/client)",
-    );
-  }
-}
-
-/** Bare file paths become `file:` URLs; `:memory:` / scheme URLs pass through. */
-function normalizeLibsqlUrl(url: string): string {
-  if (url === ":memory:" || url.includes("://") || url.startsWith("file:")) return url;
-  return `file:${url}`;
-}
-
-/**
- * Open a libSQL connection implementing {@link SqlConnection}.
- *
- * @param options - URL (`:memory:` / `file:…` / `libsql://…`) / role
- */
-export async function connectLibsql(options: SqlConnectOptions = {}): Promise<SqlConnection> {
-  const role = options.role ?? "primary";
-  const { createClient } = await loadLibsql();
-  const client = createClient({ url: normalizeLibsqlUrl(options.url ?? ":memory:") });
-  return {
-    driverId: "libsql",
-    role,
-    async query(sql, params = []) {
-      const rs = await client.execute({ sql, args: params as never });
-      return rs.rows as unknown as SqlRow[];
-    },
-    async exec(sql, params = []) {
-      const rs = await client.execute({ sql, args: params as never });
-      return { changes: rs.rowsAffected };
-    },
-    async close() {
-      client.close();
-    },
-  };
-}
-
-/** Protocol-named libsql sql driver. */
-export const libsqlDriver: SqlDriver = {
-  id: "libsql",
-  facet: "sql",
-  connect: connectLibsql,
-};
-
-/** libSQL native vector column: `F32_BLOB(dims)` (float32, validated by the engine). */
-const f32Blob = customType<{
-  data: readonly number[];
-  driverData: string;
-  config: { dimensions: number };
-}>({
-  dataType(config) {
-    return `F32_BLOB(${config?.dimensions ?? 0})`;
-  },
-  toDriver(value) {
-    return JSON.stringify(value);
-  },
-});
-
-/**
- * Open a libSQL-backed index with native ANN.
- *
- * DDL: `F32_BLOB(dims)` column + `libsql_vector_idx` ANN index (validated
- * against `@libsql/client@0.17`). Queries run `vector_top_k` joined back to
- * the base table — approximate nearest neighbours, never a full scan. Score
- * is cosine similarity (`1 - vector_distance_cos`), matching the memory
- * driver's higher-is-better convention.
- *
- * @param options - Name / dims / shared SQL connection
- */
-export async function openLibsqlIndex(options: IndexOpenOptions): Promise<VectorIndexStore> {
-  const ownsSql = !options.sql;
-  const sql = options.sql ?? (await connectLibsql({ url: options.url }));
-  if (sql.driverId !== "libsql") {
-    if (ownsSql) await sql.close();
-    throw new Error(
-      `libsql index: needs a libsql SQL connection, got "${sql.driverId}" — ` +
-        `set store.sql to "libsql" so the index shares its connection`,
-    );
-  }
-
-  const tableName = `oke_idx_${options.name.replace(/[^a-zA-Z0-9_]/g, "_")}`;
-  const indexName = `${tableName}_vec`;
-  const table = sqliteTable(tableName, {
-    id: text("id").primaryKey(),
-    embedding: f32Blob("embedding", { dimensions: options.dims }).notNull(),
-    meta: text("meta"),
-  });
-
-  await sql.exec(
-    `CREATE TABLE IF NOT EXISTS "${tableName}" (id TEXT PRIMARY KEY, embedding ${table.embedding.getSQLType()} NOT NULL, meta TEXT)`,
-  );
-  // ANN index — fails loud on engines without vector support (never falls back).
-  await sql.exec(
-    `CREATE INDEX IF NOT EXISTS "${indexName}" ON "${tableName}" (libsql_vector_idx(embedding))`,
-  );
-
-  return {
-    driverId: "libsql",
-    async upsert(id, vector, meta) {
-      if (vector.length !== options.dims) {
-        throw new Error(`vector dims ${vector.length} !== index dims ${options.dims}`);
-      }
-      await sql.exec(
-        `INSERT INTO "${tableName}" (id, embedding, meta) VALUES (?, vector32(?), ?) ` +
-          `ON CONFLICT (id) DO UPDATE SET embedding = excluded.embedding, meta = excluded.meta`,
-        [id, JSON.stringify(vector), meta ? JSON.stringify(meta) : null],
-      );
-    },
-    async search(vector, topK = 10): Promise<IndexHit[]> {
-      const k = Math.max(1, Math.floor(topK));
-      const rows = await sql.query(
-        `SELECT t.id AS id, t.meta AS meta, ` +
-          `vector_distance_cos(t.embedding, vector32(?)) AS distance ` +
-          `FROM vector_top_k('${indexName}', vector32(?), ${k}) AS i ` +
-          `JOIN "${tableName}" AS t ON t.rowid = i.id ` +
-          `ORDER BY distance ASC`,
-        [JSON.stringify(vector), JSON.stringify(vector)],
-      );
-      return rows.map((row) => {
-        const metaRaw = row.meta;
-        return {
-          id: String(row.id),
-          score: 1 - Number(row.distance),
-          meta:
-            typeof metaRaw === "string"
-              ? (JSON.parse(metaRaw) as Record<string, unknown>)
-              : undefined,
-        };
-      });
-    },
-    async delete(id) {
-      const result = await sql.exec(`DELETE FROM "${tableName}" WHERE id = ?`, [id]);
-      return result.changes > 0;
-    },
-    async close() {
-      if (ownsSql) await sql.close();
-    },
-  };
-}
-
-/** Protocol-named libsql index driver. */
-export const libsqlIndexDriver: VectorIndexDriver = {
-  id: "libsql",
-  facet: "index",
-  open: openLibsqlIndex,
-};

package/src/drivers/sqlite.ts

@@ -1,44 +0,0 @@
-/**
- * `sqlite` driver — binds `bun:sqlite` (never better-sqlite3).
- */
-
-import { Database, type SQLQueryBindings } from "bun:sqlite";
-import type { SqlConnectOptions, SqlConnection, SqlDriver, SqlRow } from "./types.ts";
-
-/**
- * Open a bun:sqlite connection implementing {@link SqlConnection}.
- *
- * @param options - URL (`:memory:` / path) or injected Database
- */
-export async function connectSqlite(options: SqlConnectOptions = {}): Promise<SqlConnection> {
-  const role = options.role ?? "primary";
-  const db =
-    options.client instanceof Database ? options.client : new Database(options.url ?? ":memory:");
-
-  function asBindings(params: readonly unknown[]): SQLQueryBindings[] {
-    return params as SQLQueryBindings[];
-  }
-
-  return {
-    driverId: "sqlite",
-    role,
-    async query(sql, params = []) {
-      const stmt = db.query(sql);
-      return stmt.all(...(asBindings(params) as never[])) as SqlRow[];
-    },
-    async exec(sql, params = []) {
-      const result = db.run(sql, ...(asBindings(params) as never[]));
-      return { changes: result.changes };
-    },
-    async close() {
-      db.close();
-    },
-  };
-}
-
-/** Protocol-named sqlite driver. */
-export const sqliteDriver: SqlDriver = {
-  id: "sqlite",
-  facet: "sql",
-  connect: connectSqlite,
-};

package/src/drivers/vault-openbao.test.ts

@@ -1,97 +0,0 @@
-/**
- * OpenBao vault driver — KV v2 read + write/delete + fail-loud semantics.
- */
-
-import { describe, expect, test } from "bun:test";
-import { OpenBaoUnavailableError, openbaoVaultDriver } from "./vault-openbao.ts";
-
-/** Scripted fetch: LIST + per-key GET, then capture writes/deletes. */
-function fakeKv(
-  seed: Record<string, string>,
-  calls: { method: string; path: string; body?: string }[],
-) {
-  return (async (input: string | URL | Request, init?: RequestInit) => {
-    const url = new URL(String(input));
-    const method = init?.method ?? "GET";
-    calls.push({
-      method,
-      path: url.pathname + url.search,
-      body: typeof init?.body === "string" ? init.body : undefined,
-    });
-    const mount = "/v1/secret";
-    if (method === "GET" && url.pathname === `${mount}/metadata`) {
-      return Response.json({ data: { keys: Object.keys(seed) } });
-    }
-    if (method === "GET" && url.pathname.startsWith(`${mount}/data/`)) {
-      const name = decodeURIComponent(url.pathname.slice(`${mount}/data/`.length));
-      if (!(name in seed)) return new Response("{}", { status: 404 });
-      return Response.json({ data: { data: { value: seed[name] } } });
-    }
-    if (method === "POST" && url.pathname.startsWith(`${mount}/data/`)) {
-      return new Response(null, { status: 204 });
-    }
-    if (method === "DELETE" && url.pathname.startsWith(`${mount}/data/`)) {
-      return new Response(null, { status: 204 });
-    }
-    return new Response("{}", { status: 404 });
-  }) as typeof globalThis.fetch;
-}
-
-describe("openbao vault driver", () => {
-  test("LIST + GET loads all keys", async () => {
-    const calls: { method: string; path: string; body?: string }[] = [];
-    const bag = await openbaoVaultDriver.open({
-      url: "http://127.0.0.1:8200",
-      token: "app-tok",
-      fetch: fakeKv({ STRIPE_KEY: "sk_live", DATABASE_URL: "postgres://x" }, calls),
-    });
-    expect(bag.get("STRIPE_KEY")).toBe("sk_live");
-    expect([...bag.names()].sort()).toEqual(["DATABASE_URL", "STRIPE_KEY"]);
-  });
-
-  test("set POSTs KV v2 data payload", async () => {
-    const calls: { method: string; path: string; body?: string }[] = [];
-    const bag = await openbaoVaultDriver.open({
-      url: "http://127.0.0.1:8200",
-      token: "app-tok",
-      fetch: fakeKv({ STRIPE_KEY: "sk_live" }, calls),
-    });
-    bag.set?.("STRIPE_KEY", "sk_rotated");
-    await Bun.sleep(0);
-    const writeCall = calls.find((c) => c.method === "POST");
-    expect(writeCall?.path).toBe("/v1/secret/data/STRIPE_KEY");
-    expect(writeCall?.body).toBe(JSON.stringify({ data: { value: "sk_rotated" } }));
-    expect(bag.get("STRIPE_KEY")).toBe("sk_rotated");
-  });
-
-  test("unreachable remote fails loud (no soft-empty bag)", async () => {
-    let failed: unknown;
-    try {
-      await openbaoVaultDriver.open({
-        url: "http://127.0.0.1:9",
-        token: "app-tok",
-        fetch: (async () => {
-          throw new Error("connect ECONNREFUSED");
-        }) as unknown as typeof globalThis.fetch,
-      });
-    } catch (err) {
-      failed = err;
-    }
-    expect(failed).toBeInstanceOf(OpenBaoUnavailableError);
-  });
-
-  test("sealed / 5xx on GET fails loud", async () => {
-    const fetchFn = (async (input: string | URL | Request) => {
-      const url = String(input);
-      if (url.includes("metadata")) return Response.json({ data: { keys: ["STRIPE_KEY"] } });
-      return new Response("sealed", { status: 503 });
-    }) as typeof globalThis.fetch;
-    let failed: unknown;
-    try {
-      await openbaoVaultDriver.open({ url: "http://127.0.0.1:8200", token: "t", fetch: fetchFn });
-    } catch (err) {
-      failed = err;
-    }
-    expect(failed).toBeInstanceOf(OpenBaoUnavailableError);
-  });
-});

package/src/drivers/vault-openbao.ts

@@ -1,143 +0,0 @@
-/**
- * `openbao` vault driver — OpenBao (Vault-compatible) KV v2 HTTP API.
- *
- * Protocol-named; image/vendor choice lives in `images`.
- */
-
-import type { VaultBag, VaultDriver, VaultOpenOptions } from "./vault-types.ts";
-
-/** Error thrown when the remote OpenBao is unreachable / sealed / errors. */
-export class OpenBaoUnavailableError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "OpenBaoUnavailableError";
-  }
-}
-
-/**
- * OpenBao KV-v2 bag. Reads are loaded at open when `url` + `token` resolve;
- * writes (`set` / `delete`) hit the HTTP API directly.
- *
- * When `url` and `token` are provided, an unreachable, sealed, or erroring
- * OpenBao is **fatal** (fail-loud) — the bag never silently degrades to an
- * empty / seed-only view.
- *
- * For boot validation the runtime passes declared names; this driver loads
- * all keys under `mount` when the LIST API is available, else falls back to
- * GETs for the seed names.
- */
-export const openbaoVaultDriver: VaultDriver = {
-  id: "openbao",
-  async open(options: VaultOpenOptions = {}): Promise<VaultBag> {
-    const url = options.url?.replace(/\/$/, "");
-    const token = options.token;
-    const mount = options.mount ?? "secret";
-    const fetchFn = options.fetch ?? globalThis.fetch;
-    const map = new Map<string, string>(
-      Object.entries(options.secrets ?? {}).filter(
-        (e): e is [string, string] => typeof e[1] === "string",
-      ),
-    );
-
-    const remote = url !== undefined && token !== undefined;
-    let mutableRemote = false;
-
-    if (remote && url !== undefined && token !== undefined) {
-      const headers = { "X-Vault-Token": token };
-      const base = `${url}/v1/${mount}`;
-
-      async function listNames(): Promise<string[]> {
-        const res = await fetchFn(`${base}/metadata?list=true`, { headers });
-        if (!res.ok) return [];
-        const body = (await res.json()) as { data?: { keys?: string[] } };
-        return (body.data?.keys ?? []).map((k) => k.replace(/\/$/, ""));
-      }
-
-      async function readName(name: string): Promise<boolean> {
-        const res = await fetchFn(`${base}/data/${encodeURIComponent(name)}`, { headers });
-        if (res.status === 404) return false;
-        if (!res.ok) {
-          throw new OpenBaoUnavailableError(
-            `openbao vault: GET ${name} failed (${res.status}) — sealed or unauthorized?`,
-          );
-        }
-        const body = (await res.json()) as { data?: { data?: Record<string, unknown> } };
-        const data = body.data?.data ?? {};
-        const value =
-          typeof data.value === "string"
-            ? data.value
-            : typeof data[name] === "string"
-              ? (data[name] as string)
-              : JSON.stringify(data);
-        map.set(name, value);
-        return true;
-      }
-
-      // LIST when the token has metadata list; otherwise only fetch the
-      // seed/declared names so a least-privilege token still works. A
-      // connection-level failure here must never degrade to an empty bag.
-      let names: string[] = [];
-      try {
-        names = await listNames();
-      } catch (err) {
-        if (map.size === 0) {
-          throw new OpenBaoUnavailableError(
-            `openbao vault: unreachable at ${url} — ${err instanceof Error ? err.message : String(err)}`,
-          );
-        }
-        // Fall through: LIST denied but we still have declared names to GET.
-      }
-      if (names.length > 0) {
-        for (const key of names) await readName(key);
-        mutableRemote = true;
-      } else if (map.size > 0) {
-        for (const name of map.keys()) await readName(name);
-        mutableRemote = true;
-      }
-    }
-
-    return {
-      driverId: "openbao",
-      get(name) {
-        return map.get(name);
-      },
-      names() {
-        return [...map.keys()];
-      },
-      ...(mutableRemote && url !== undefined && token !== undefined
-        ? {
-            set(name: string, value: string) {
-              void (async () => {
-                const res = await fetchFn(`${url}/v1/${mount}/data/${encodeURIComponent(name)}`, {
-                  method: "POST",
-                  headers: { "X-Vault-Token": token, "content-type": "application/json" },
-                  body: JSON.stringify({ data: { value } }),
-                });
-                if (!res.ok) {
-                  throw new OpenBaoUnavailableError(
-                    `openbao vault: write ${name} failed (${res.status})`,
-                  );
-                }
-                map.set(name, value);
-              })();
-            },
-            delete(name: string) {
-              const had = map.delete(name);
-              void (async () => {
-                const res = await fetchFn(`${url}/v1/${mount}/data/${encodeURIComponent(name)}`, {
-                  method: "DELETE",
-                  headers: { "X-Vault-Token": token },
-                });
-                if (!res.ok && res.status !== 404) {
-                  throw new OpenBaoUnavailableError(
-                    `openbao vault: delete ${name} failed (${res.status})`,
-                  );
-                }
-              })();
-              return had;
-            },
-          }
-        : {}),
-    };
-  },
-};