get-db9 0.5.0 → 0.6.0

package/dist/index.cjs

@@ -35,6 +35,8 @@ __export(index_exports, {
   Db9Error: () => Db9Error,
   Db9NotFoundError: () => Db9NotFoundError,
   FileCredentialStore: () => FileCredentialStore,
+  FsClient: () => FsClient,
+  FsError: () => FsError,
   MemoryCredentialStore: () => MemoryCredentialStore,
   createDb9Client: () => createDb9Client,
   defaultCredentialStore: () => defaultCredentialStore,
@@ -303,6 +305,239 @@ function defaultCredentialStore() {
   return new FileCredentialStore();
 }
 
+// src/ws.ts
+var FsError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "FsError";
+    this.code = code;
+  }
+};
+var nextId = 1;
+function nextRequestId() {
+  return String(nextId++);
+}
+function toBase64(data) {
+  const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function fromBase64(b64) {
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(b64, "base64"));
+  }
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+var FsClient = class _FsClient {
+  ws;
+  pending = /* @__PURE__ */ new Map();
+  closed = false;
+  constructor(ws) {
+    this.ws = ws;
+    ws.onmessage = (ev) => {
+      const text = typeof ev.data === "string" ? ev.data : String(ev.data);
+      let resp;
+      try {
+        resp = JSON.parse(text);
+      } catch {
+        return;
+      }
+      const p = this.pending.get(resp.id);
+      if (p) {
+        this.pending.delete(resp.id);
+        p.resolve(resp);
+      }
+    };
+    ws.onclose = () => {
+      this.closed = true;
+      for (const [, p] of this.pending) {
+        p.reject(new FsError("CONNECTION_CLOSED", "WebSocket connection closed"));
+      }
+      this.pending.clear();
+    };
+    ws.onerror = () => {
+    };
+  }
+  /**
+   * Connect to an fs9 WebSocket server.
+   *
+   * @param url WebSocket URL, e.g. `wss://host:5480`
+   * @param WS  WebSocket constructor (native or from `ws` package)
+   */
+  static connect(url, WS) {
+    return new Promise((resolve, reject) => {
+      const ws = new WS(url);
+      ws.onopen = () => {
+        ws.onopen = null;
+        ws.onerror = null;
+        resolve(new _FsClient(ws));
+      };
+      ws.onerror = (ev) => {
+        ws.onopen = null;
+        ws.onerror = null;
+        const msg = ev && typeof ev === "object" && "message" in ev ? String(ev.message) : "WebSocket connection failed";
+        reject(new FsError("CONNECTION_ERROR", msg));
+      };
+    });
+  }
+  /** Authenticate with the server. Must be called first after connect. */
+  async authenticate(username, password) {
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "auth",
+      username,
+      password
+    });
+    if (!resp.ok) {
+      throw new FsError("AUTH_FAILED", this.errorMessage(resp));
+    }
+    const data = resp.data;
+    return {
+      user: String(data?.user ?? ""),
+      tenant: String(data?.tenant ?? ""),
+      keyspace: String(data?.keyspace ?? "")
+    };
+  }
+  /** Get file or directory metadata. */
+  async stat(path) {
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "stat",
+      path
+    });
+    this.expectOk(resp);
+    return resp.data;
+  }
+  /** List directory contents. */
+  async readdir(path) {
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "readdir",
+      path
+    });
+    this.expectOk(resp);
+    const data = resp.data;
+    return data?.entries ?? [];
+  }
+  /** Create a directory. Always recursive (mkdir -p). */
+  async mkdir(path, recursive = true) {
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "mkdir",
+      path,
+      recursive
+    });
+    this.expectOk(resp);
+  }
+  /** Read an entire file, returning raw bytes. */
+  async readFile(path) {
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "read",
+      path
+    });
+    this.expectOk(resp);
+    const data = resp.data;
+    const content = data?.content;
+    if (typeof content !== "string") {
+      throw new FsError("PROTOCOL", "missing content field in read response");
+    }
+    return fromBase64(content);
+  }
+  /** Write (overwrite) a file. Returns bytes written. */
+  async writeFile(path, data) {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data instanceof Uint8Array ? data : new Uint8Array(data);
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "write",
+      path,
+      content: toBase64(bytes),
+      encoding: "base64"
+    });
+    this.expectOk(resp);
+    const result = resp.data;
+    return result?.written ?? bytes.byteLength;
+  }
+  /** Append to a file. Returns bytes written. */
+  async appendFile(path, data) {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data instanceof Uint8Array ? data : new Uint8Array(data);
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "append",
+      path,
+      content: toBase64(bytes),
+      encoding: "base64"
+    });
+    this.expectOk(resp);
+    const result = resp.data;
+    return result?.written ?? bytes.byteLength;
+  }
+  /** Remove a file (non-recursive) or directory (recursive). */
+  async rm(path, recursive = false) {
+    const resp = await this.sendAndRecv(
+      recursive ? { id: nextRequestId(), op: "rm", path, recursive: true } : { id: nextRequestId(), op: "unlink", path }
+    );
+    this.expectOk(resp);
+  }
+  /** Rename (move) a file or directory. */
+  async rename(oldPath, newPath) {
+    const resp = await this.sendAndRecv({
+      id: nextRequestId(),
+      op: "rename",
+      old_path: oldPath,
+      new_path: newPath
+    });
+    this.expectOk(resp);
+  }
+  /** Gracefully close the WebSocket connection. */
+  async close() {
+    if (!this.closed) {
+      this.ws.close();
+    }
+  }
+  // ── internals ──────────────────────────────────────────────────
+  sendAndRecv(request) {
+    if (this.closed) {
+      return Promise.reject(new FsError("CONNECTION_CLOSED", "WebSocket is closed"));
+    }
+    return new Promise((resolve, reject) => {
+      const id = request.id;
+      this.pending.set(id, { resolve, reject });
+      try {
+        this.ws.send(JSON.stringify(request));
+      } catch (err) {
+        this.pending.delete(id);
+        reject(new FsError("CONNECTION_ERROR", String(err)));
+      }
+    });
+  }
+  expectOk(resp) {
+    if (!resp.ok) {
+      const detail = resp.error;
+      throw new FsError(
+        detail?.code ?? "UNKNOWN",
+        detail?.message ?? "unknown error"
+      );
+    }
+  }
+  errorMessage(resp) {
+    const detail = resp.error;
+    return detail ? `${detail.code}: ${detail.message}` : "unknown error";
+  }
+};
+
 // src/client.ts
 function createDb9Client(options = {}) {
   const baseUrl = options.baseUrl ?? "https://db9.shared.aws.tidbcloud.com/api";
@@ -382,44 +617,42 @@ function createDb9Client(options = {}) {
       return operation(newClient);
     }
   }
-  function deriveFs9Url(dbId) {
-    const origin = baseUrl.replace(/\/api\/?$/, "");
-    return `${origin}/fs9/${dbId}`;
-  }
-  function getFsClient(dbId) {
-    const fs9Base = deriveFs9Url(dbId) + "/api/v1";
-    return createHttpClient({
-      baseUrl: fs9Base,
-      fetch: options.fetch,
-      headers: token ? { Authorization: `Bearer ${token}` } : {},
-      timeout: options.timeout,
-      maxRetries: options.maxRetries,
-      retryDelay: options.retryDelay
-    });
+  const fsWsPort = options.wsPort ?? 5480;
+  async function resolveFsConn(dbId) {
+    const creds = await withAuthRetry(
+      (client) => client.get(
+        `/customer/databases/${dbId}/credentials`
+      )
+    );
+    const connStr = creds.connection_string;
+    const hostMatch = connStr.match(/@([^:/?]+)/);
+    const host = hostMatch?.[1];
+    if (!host) {
+      throw new Error(`Cannot parse host from connection string for database '${dbId}'`);
+    }
+    const userMatch = connStr.match(/:\/\/([^:@]+)/);
+    const username = userMatch?.[1] ?? creds.admin_user;
+    const protocol = host === "localhost" || host === "127.0.0.1" ? "ws" : "wss";
+    return {
+      wsUrl: `${protocol}://${host}:${fsWsPort}`,
+      username,
+      password: creds.admin_password
+    };
   }
-  async function withFsAuthRetry(dbId, operation) {
-    if (!token && !tokenLoaded) {
-      await getAuthClient();
+  async function withFsClient(dbId, operation) {
+    const WS = options.WebSocket ?? (typeof globalThis !== "undefined" ? globalThis.WebSocket : void 0);
+    if (!WS) {
+      throw new Error(
+        "WebSocket constructor not available. Pass `WebSocket` in Db9ClientOptions, or use Node 21+ / a browser environment with native WebSocket support, or install the `ws` package for Node 18\u201320."
+      );
     }
-    const client = getFsClient(dbId);
+    const conn = await resolveFsConn(dbId);
+    const client = await FsClient.connect(conn.wsUrl, WS);
     try {
+      await client.authenticate(conn.username, conn.password);
       return await operation(client);
-    } catch (err) {
-      if (!(err instanceof Db9Error) || err.statusCode !== 401) {
-        throw err;
-      }
-      try {
-        if (!refreshPromise) {
-          refreshPromise = refreshAnonymousToken();
-        }
-        await refreshPromise;
-      } catch {
-        throw err;
-      } finally {
-        refreshPromise = null;
-      }
-      const newClient = getFsClient(dbId);
-      return operation(newClient);
+    } finally {
+      await client.close();
     }
   }
   function parseSqlError(raw) {
@@ -440,12 +673,6 @@ function createDb9Client(options = {}) {
     }
     return { message: raw };
   }
-  async function fsStat(dbId, path) {
-    return withFsAuthRetry(
-      dbId,
-      (client) => client.get("/stat", { path })
-    );
-  }
   async function fetchAnonymousSecret() {
     return withAuthRetry(
       (client) => client.post("/customer/anonymous-secret", {})
@@ -519,6 +746,11 @@ function createDb9Client(options = {}) {
           `/customer/databases/${databaseId}/reset-password`
         )
       ),
+      credentials: async (databaseId) => withAuthRetry(
+        (client) => client.get(
+          `/customer/databases/${databaseId}/credentials`
+        )
+      ),
       observability: async (databaseId) => withAuthRetry(
         (client) => client.get(
           `/customer/databases/${databaseId}/observability`
@@ -601,70 +833,84 @@ function createDb9Client(options = {}) {
       }
     },
     fs: {
-      list: async (dbId, path, options2) => {
-        const params = { path };
-        if (options2?.recursive) params.recursive = "true";
-        return withFsAuthRetry(
-          dbId,
-          (client) => client.get("/readdir", params)
-        );
-      },
-      read: async (dbId, path) => {
-        return withFsAuthRetry(dbId, async (client) => {
-          const resp = await client.getRaw("/download", { path });
-          return resp.text();
-        });
-      },
-      readBinary: async (dbId, path) => {
-        return withFsAuthRetry(dbId, async (client) => {
-          const resp = await client.getRaw("/download", { path });
-          return resp.arrayBuffer();
-        });
+      /**
+       * Open a persistent WebSocket connection for multiple fs operations.
+       * Caller is responsible for calling `client.close()` when done.
+       */
+      connect: async (dbId) => {
+        const WS = options.WebSocket ?? (typeof globalThis !== "undefined" ? globalThis.WebSocket : void 0);
+        if (!WS) {
+          throw new Error(
+            "WebSocket constructor not available. Pass `WebSocket` in Db9ClientOptions, or use Node 21+ / a browser environment with native WebSocket support, or install the `ws` package for Node 18\u201320."
+          );
+        }
+        const conn = await resolveFsConn(dbId);
+        const client = await FsClient.connect(conn.wsUrl, WS);
+        await client.authenticate(conn.username, conn.password);
+        return client;
       },
+      /** List directory contents. */
+      list: async (dbId, path) => withFsClient(dbId, (client) => client.readdir(path)),
+      /** Read a file as text (UTF-8). */
+      read: async (dbId, path) => withFsClient(dbId, async (client) => {
+        const bytes = await client.readFile(path);
+        return new TextDecoder().decode(bytes);
+      }),
+      /** Read a file as raw bytes. */
+      readBinary: async (dbId, path) => withFsClient(dbId, (client) => client.readFile(path)),
+      /** Write (overwrite) a file. Accepts string, ArrayBuffer, or Uint8Array. */
       write: async (dbId, path, content) => {
-        const contentType = typeof content === "string" ? "text/plain" : "application/octet-stream";
-        await withFsAuthRetry(
-          dbId,
-          (client) => client.putRaw(`/upload?${new URLSearchParams({ path })}`, content, { "Content-Type": contentType })
-        );
-      },
-      stat: (dbId, path) => {
-        return fsStat(dbId, path);
+        await withFsClient(dbId, (client) => client.writeFile(path, content));
       },
+      /** Append to a file. Returns bytes written. */
+      append: async (dbId, path, content) => withFsClient(dbId, (client) => client.appendFile(path, content)),
+      /** Get file or directory metadata. */
+      stat: async (dbId, path) => withFsClient(dbId, (client) => client.stat(path)),
+      /** Check if a file or directory exists. */
       exists: async (dbId, path) => {
         try {
-          await fsStat(dbId, path);
+          await withFsClient(dbId, (client) => client.stat(path));
           return true;
         } catch (err) {
-          if (err instanceof Db9Error && err.statusCode === 404) {
+          if (err instanceof FsError && err.code === "ENOENT") {
             return false;
           }
           throw err;
         }
       },
+      /** Create a directory (recursive by default). */
       mkdir: async (dbId, path) => {
-        await withFsAuthRetry(
-          dbId,
-          (client) => client.postRaw(`/mkdir?${new URLSearchParams({ path, recursive: "true" })}`)
-        );
+        await withFsClient(dbId, (client) => client.mkdir(path, true));
       },
-      remove: async (dbId, path) => {
-        await withFsAuthRetry(
-          dbId,
-          (client) => client.delRaw("/remove", { path })
-        );
+      /** Remove a file or directory. */
+      remove: async (dbId, path, opts) => {
+        await withFsClient(dbId, (client) => client.rm(path, opts?.recursive ?? false));
       },
-      events: async (dbId, options2) => {
-        const params = {};
-        if (options2?.limit !== void 0) params.limit = String(options2.limit);
-        if (options2?.offset !== void 0) params.offset = String(options2.offset);
-        if (options2?.path) params.path = options2.path;
-        if (options2?.type) params.type = options2.type;
-        return withFsAuthRetry(
-          dbId,
-          (client) => client.get("/events", params)
-        );
+      /** Rename (move) a file or directory. */
+      rename: async (dbId, oldPath, newPath) => {
+        await withFsClient(dbId, (client) => client.rename(oldPath, newPath));
       }
+    },
+    // ── Device Auth Flow ─────────────────────────────────────────
+    deviceAuth: {
+      /** Start device code flow. Returns codes for user to authorize. */
+      createDeviceCode: () => publicClient.post("/customer/device-code"),
+      /** Poll for device token after user authorizes. Returns token or error status. */
+      pollDeviceToken: async (req) => {
+        try {
+          return await publicClient.post("/customer/device-token", req);
+        } catch (err) {
+          if (err instanceof Db9Error && err.statusCode === 400) {
+            const errorType = err.message;
+            if (errorType === "authorization_pending" || errorType === "expired_token" || errorType === "access_denied") {
+              return { error: errorType };
+            }
+          }
+          throw err;
+        }
+      },
+      /** Submit device verification with user credentials. */
+      verifyDevice: (req) => publicClient.post("/customer/device-verify", req)
     }
   };
 }
@@ -710,6 +956,8 @@ function toResult(db) {
   Db9Error,
   Db9NotFoundError,
   FileCredentialStore,
+  FsClient,
+  FsError,
   MemoryCredentialStore,
   createDb9Client,
   defaultCredentialStore,