@dbx-tools/lakebox 0.9.131 → 0.9.132

package/README.md

@@ -2,48 +2,146 @@
 
 Connect to, provision, and run commands on Databricks Lakeboxes.
 
-The package provides the Lakebox REST client, lifecycle convergence, and a
-verified SSH session with pooled native OpenSSH or ssh2 command and forwarding
-transport. It has no AppKit, React, or Lakebase dependency. User accounts,
-resource identity, and services belong to `@dbx-tools/appkit-lakebox`.
-
 ## Provision a Lakebox
 
 ```ts
+import { client as authClient } from "@dbx-tools/auth";
 import { LakeboxClient } from "@dbx-tools/lakebox/rest";
 import { ensureLakeboxRunning } from "@dbx-tools/lakebox/lifecycle";
 
-const api = new LakeboxClient(workspaceClient.config);
+const auth = await authClient.createAuthClient({ profile: "MY-PROFILE" });
+const api = new LakeboxClient({
+  host: auth.host,
+  ...(auth.workspaceId ? { workspaceId: auth.workspaceId } : {}),
+  authenticate: async (headers) => {
+    for (const [name, value] of Object.entries(await auth.headers())) {
+      headers.set(name, value);
+    }
+  },
+});
 const entry = await api.create();
 await api.setIdleTimeout(entry.sandboxId, 3_600);
 const running = await ensureLakeboxRunning(api, entry);
 ```
 
 `LakeboxClient` accepts any credential object with `host` and
-`authenticate(headers)`, such as an AppKit or Databricks SDK
-`WorkspaceClient.config`. Use the app service principal for lifecycle calls.
+`authenticate(headers)`. AppKit and the Databricks SDK
+`WorkspaceClient.config` satisfy this contract directly. The example adapts
+`@dbx-tools/auth` for an explicit local profile. Use the app service principal
+for lifecycle calls in a Databricks App.
+
+## Connect and run a command
 
-## Run a command
+Create or load an SSH key, register it with the workspace, verify the gateway
+host key, and close the session when work finishes:
 
 ```ts
+import { SshKeyStore } from "@dbx-tools/lakebox/key-store";
+import type { LakeboxClient, LakeboxEntry } from "@dbx-tools/lakebox/rest";
 import { SshSession } from "@dbx-tools/lakebox/session";
 
-const command = session.execute("sh", ["-lc", "uname -a"], {
-  user: { name: "lakebox-abc1234", home: "/home/lakebox-abc1234" },
-  timeoutMs: 30_000,
-});
-for await (const chunk of command.stdout) process.stdout.write(chunk);
-const result = await command.result;
+export async function runCommand(
+  api: LakeboxClient,
+  running: LakeboxEntry,
+  user: { name: string; home: string },
+): Promise<void> {
+  const owner = "my-service";
+  const keys = new SshKeyStore();
+  const key = await keys.ensureRegistered(api, owner);
+  const gatewayHost = running.gatewayHost ?? key.gatewayHost;
+  if (!gatewayHost) {
+    throw new Error("The Lakebox API did not return an SSH gateway host");
+  }
+
+  const gatewayPort = 2_222;
+  const scope = await api.workspaceScope();
+  const knownHost = await keys.knownHost(scope, owner, gatewayHost, gatewayPort);
+  const session = new SshSession({
+    host: gatewayHost,
+    port: gatewayPort,
+    username: running.sandboxId,
+    privateKey: key.privateKey,
+    privateKeyPath: key.privateKeyPath,
+    knownHostsPath: keys.knownHostsPath(scope, owner, gatewayHost, gatewayPort),
+    connectTimeoutMs: 30_000,
+    sshTransport: "auto",
+    ssh2Patch: "auto",
+    ...(knownHost ? { knownHost } : {}),
+    rememberHost: (fingerprint, hostKey) =>
+      keys.rememberHost(scope, owner, gatewayHost, gatewayPort, fingerprint, hostKey),
+  });
+
+  try {
+    await session.connect();
+    const command = session.execute("sh", ["-lc", "uname -a"], {
+      user,
+      timeoutMs: 30_000,
+    });
+    const result = await command.result;
+    if (!result.success) {
+      throw new Error(result.stderr || `Command exited with ${result.exitCode}`);
+    }
+  } finally {
+    await session.close();
+  }
+}
 ```
 
 Every command clears inherited Databricks credentials and SSH agent variables
-before running. `forwardOut(host, port)` opens a forwarded TCP stream through a
-separate pool, so long-lived WebSockets never consume the warm command
+before it runs. `execute()` returns a live `SshCommand`. Its `stdout` and
+`stderr` fields are async iterables, awaiting the command returns its numeric
+exit code, and `result` returns captured output and timing metadata.
+
+The low-level package doesn't create Linux users. Pass an account that already
+exists on the Lakebox. `@dbx-tools/appkit-lakebox` creates and isolates
+application user accounts before it runs their commands.
+
+`forwardOut(host, port)` opens a forwarded TCP stream through a separate pool.
+Long-lived HTTP and WebSocket streams don't consume the warm command
 connection.
 
+## Stop or delete a Lakebox
+
+Use lifecycle convergence when you need to wait for a terminal state:
+
+```ts
+import { ensureLakeboxStopped } from "@dbx-tools/lakebox/lifecycle";
+import type { LakeboxClient, LakeboxEntry } from "@dbx-tools/lakebox/rest";
+
+export async function stopAndDelete(api: LakeboxClient, running: LakeboxEntry): Promise<void> {
+  const stopped = await ensureLakeboxStopped(api, running);
+  await api.delete(stopped.sandboxId);
+}
+```
+
+`stop()` preserves the persistent Lakebox filesystem. `delete()` permanently
+removes the Lakebox and its data.
+
 ## Configuration
 
-| Field | Values | Default |
-| --- | --- | --- |
+| Field          | Values                    | Default                                   |
+| -------------- | ------------------------- | ----------------------------------------- |
 | `sshTransport` | `auto`, `openssh`, `ssh2` | `auto` prefers native OpenSSH with SOCKS5 |
-| `ssh2Patch` | `auto`, `true`, `false` | `auto` patches only in development |
+| `ssh2Patch`    | `auto`, `true`, `false`   | `auto` patches only in development        |
+
+`SshSessionOptions` also requires the gateway host and port, Lakebox ID as the
+SSH username, private key material, key and known-host paths, and a connection
+timeout. `SshKeyStore` stores keys and gateway fingerprints under
+`~/.dbx-tools/lakebox` unless you pass another root.
+
+## Understand lifecycle and transport limits
+
+- `ensureLakeboxRunning()` and `ensureLakeboxStopped()` poll for up to five
+  minutes.
+- The REST client doesn't map users, persist app resource identity, or manage
+  services. Use [@dbx-tools/appkit-lakebox](../appkit-lakebox/README.md) for
+  those application-level capabilities.
+- The command pool keeps one tested connection warm and grows to 10
+  connections. Forwarding uses a separate pool with no minimum.
+- Each borrowed SSH resource handles one operation and is destroyed after that
+  command or forwarded stream. A failed forwarding open retries once with a new
+  resource. Established streams and commands aren't replayed.
+- `auto` selects native OpenSSH when it is available and selects ssh2
+  otherwise. It doesn't switch transports after a runtime failure.
+- `close()` cancels active commands, closes transport pools, and waits for an
+  in-progress connection attempt to settle.

package/index.ts

@@ -3,7 +3,7 @@
 // Hand edits are overwritten on the next watch; this file is read-only.
 
 export const PACKAGE_IDENTIFIER = "@dbx-tools/lakebox";
-export const PACKAGE_VERSION = "0.9.131";
+export const PACKAGE_VERSION = "0.9.132";
 export * as keyStore from "./src/key-store.ts";
 export * as lifecycle from "./src/lifecycle.ts";
 export * as rest from "./src/rest.ts";

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 export declare const PACKAGE_IDENTIFIER = "@dbx-tools/lakebox";
-export declare const PACKAGE_VERSION = "0.9.131";
+export declare const PACKAGE_VERSION = "0.9.132";
 export * as keyStore from "./src/key-store.ts";
 export * as lifecycle from "./src/lifecycle.ts";
 export * as rest from "./src/rest.ts";

package/lib/index.js

@@ -2,7 +2,7 @@
 // Regenerated from the exporting modules in ./src.
 // Hand edits are overwritten on the next watch; this file is read-only.
 export const PACKAGE_IDENTIFIER = "@dbx-tools/lakebox";
-export const PACKAGE_VERSION = "0.9.131";
+export const PACKAGE_VERSION = "0.9.132";
 export * as keyStore from "./src/key-store.js";
 export * as lifecycle from "./src/lifecycle.js";
 export * as rest from "./src/rest.js";
@@ -12,4 +12,4 @@ export { SshKeyStore } from "./src/key-store.js";
 export { LakeboxEntrySchema, LakeboxSshKeySchema, LakeboxApiError, LakeboxClient } from "./src/rest.js";
 export { SshSession } from "./src/session.js";
 export { SshTransportModeSchema, Ssh2PatchModeSchema } from "./src/transport.js";
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxNQUFNLENBQUMsTUFBTSxrQkFBa0IsR0FBRyxvQkFBb0IsQ0FBQztBQUN2RCxNQUFNLENBQUMsTUFBTSxlQUFlLEdBQUcsU0FBUyxDQUFDO0FBQ3pDLE9BQU8sS0FBSyxRQUFRLE1BQU0sb0JBQW9CLENBQUM7QUFDL0MsT0FBTyxLQUFLLFNBQVMsTUFBTSxvQkFBb0IsQ0FBQztBQUNoRCxPQUFPLEtBQUssSUFBSSxNQUFNLGVBQWUsQ0FBQztBQUN0QyxPQUFPLEtBQUssT0FBTyxNQUFNLGtCQUFrQixDQUFDO0FBQzVDLE9BQU8sS0FBSyxTQUFTLE1BQU0sb0JBQW9CLENBQUM7QUFDaEQsT0FBTyxFQUFFLFdBQVcsRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBQ2pELE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxtQkFBbUIsRUFBRSxlQUFlLEVBQUUsYUFBYSxFQUFFLE1BQU0sZUFBZSxDQUFDO0FBRXhHLE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUU5QyxPQUFPLEVBQUUsc0JBQXNCLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdFTkVSQVRFRCBieSBwcm9qZW4gd2F0Y2ggLSBETyBOT1QgRURJVC5cbi8vIFJlZ2VuZXJhdGVkIGZyb20gdGhlIGV4cG9ydGluZyBtb2R1bGVzIGluIC4vc3JjLlxuLy8gSGFuZCBlZGl0cyBhcmUgb3ZlcndyaXR0ZW4gb24gdGhlIG5leHQgd2F0Y2g7IHRoaXMgZmlsZSBpcyByZWFkLW9ubHkuXG5cbmV4cG9ydCBjb25zdCBQQUNLQUdFX0lERU5USUZJRVIgPSBcIkBkYngtdG9vbHMvbGFrZWJveFwiO1xuZXhwb3J0IGNvbnN0IFBBQ0tBR0VfVkVSU0lPTiA9IFwiMC45LjEzMVwiO1xuZXhwb3J0ICogYXMga2V5U3RvcmUgZnJvbSBcIi4vc3JjL2tleS1zdG9yZS50c1wiO1xuZXhwb3J0ICogYXMgbGlmZWN5Y2xlIGZyb20gXCIuL3NyYy9saWZlY3ljbGUudHNcIjtcbmV4cG9ydCAqIGFzIHJlc3QgZnJvbSBcIi4vc3JjL3Jlc3QudHNcIjtcbmV4cG9ydCAqIGFzIHNlc3Npb24gZnJvbSBcIi4vc3JjL3Nlc3Npb24udHNcIjtcbmV4cG9ydCAqIGFzIHRyYW5zcG9ydCBmcm9tIFwiLi9zcmMvdHJhbnNwb3J0LnRzXCI7XG5leHBvcnQgeyBTc2hLZXlTdG9yZSB9IGZyb20gXCIuL3NyYy9rZXktc3RvcmUudHNcIjtcbmV4cG9ydCB7IExha2Vib3hFbnRyeVNjaGVtYSwgTGFrZWJveFNzaEtleVNjaGVtYSwgTGFrZWJveEFwaUVycm9yLCBMYWtlYm94Q2xpZW50IH0gZnJvbSBcIi4vc3JjL3Jlc3QudHNcIjtcbmV4cG9ydCB0eXBlIHsgTGFrZWJveEVudHJ5LCBMYWtlYm94U3NoS2V5LCBMYWtlYm94QXV0aCB9IGZyb20gXCIuL3NyYy9yZXN0LnRzXCI7XG5leHBvcnQgeyBTc2hTZXNzaW9uIH0gZnJvbSBcIi4vc3JjL3Nlc3Npb24udHNcIjtcbmV4cG9ydCB0eXBlIHsgU3NoU2Vzc2lvbk9wdGlvbnMgfSBmcm9tIFwiLi9zcmMvc2Vzc2lvbi50c1wiO1xuZXhwb3J0IHsgU3NoVHJhbnNwb3J0TW9kZVNjaGVtYSwgU3NoMlBhdGNoTW9kZVNjaGVtYSB9IGZyb20gXCIuL3NyYy90cmFuc3BvcnQudHNcIjtcbmV4cG9ydCB0eXBlIHsgU3NoVHJhbnNwb3J0TW9kZSwgU3NoMlBhdGNoTW9kZSB9IGZyb20gXCIuL3NyYy90cmFuc3BvcnQudHNcIjtcbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxNQUFNLENBQUMsTUFBTSxrQkFBa0IsR0FBRyxvQkFBb0IsQ0FBQztBQUN2RCxNQUFNLENBQUMsTUFBTSxlQUFlLEdBQUcsU0FBUyxDQUFDO0FBQ3pDLE9BQU8sS0FBSyxRQUFRLE1BQU0sb0JBQW9CLENBQUM7QUFDL0MsT0FBTyxLQUFLLFNBQVMsTUFBTSxvQkFBb0IsQ0FBQztBQUNoRCxPQUFPLEtBQUssSUFBSSxNQUFNLGVBQWUsQ0FBQztBQUN0QyxPQUFPLEtBQUssT0FBTyxNQUFNLGtCQUFrQixDQUFDO0FBQzVDLE9BQU8sS0FBSyxTQUFTLE1BQU0sb0JBQW9CLENBQUM7QUFDaEQsT0FBTyxFQUFFLFdBQVcsRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBQ2pELE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxtQkFBbUIsRUFBRSxlQUFlLEVBQUUsYUFBYSxFQUFFLE1BQU0sZUFBZSxDQUFDO0FBRXhHLE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUU5QyxPQUFPLEVBQUUsc0JBQXNCLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdFTkVSQVRFRCBieSBwcm9qZW4gd2F0Y2ggLSBETyBOT1QgRURJVC5cbi8vIFJlZ2VuZXJhdGVkIGZyb20gdGhlIGV4cG9ydGluZyBtb2R1bGVzIGluIC4vc3JjLlxuLy8gSGFuZCBlZGl0cyBhcmUgb3ZlcndyaXR0ZW4gb24gdGhlIG5leHQgd2F0Y2g7IHRoaXMgZmlsZSBpcyByZWFkLW9ubHkuXG5cbmV4cG9ydCBjb25zdCBQQUNLQUdFX0lERU5USUZJRVIgPSBcIkBkYngtdG9vbHMvbGFrZWJveFwiO1xuZXhwb3J0IGNvbnN0IFBBQ0tBR0VfVkVSU0lPTiA9IFwiMC45LjEzMlwiO1xuZXhwb3J0ICogYXMga2V5U3RvcmUgZnJvbSBcIi4vc3JjL2tleS1zdG9yZS50c1wiO1xuZXhwb3J0ICogYXMgbGlmZWN5Y2xlIGZyb20gXCIuL3NyYy9saWZlY3ljbGUudHNcIjtcbmV4cG9ydCAqIGFzIHJlc3QgZnJvbSBcIi4vc3JjL3Jlc3QudHNcIjtcbmV4cG9ydCAqIGFzIHNlc3Npb24gZnJvbSBcIi4vc3JjL3Nlc3Npb24udHNcIjtcbmV4cG9ydCAqIGFzIHRyYW5zcG9ydCBmcm9tIFwiLi9zcmMvdHJhbnNwb3J0LnRzXCI7XG5leHBvcnQgeyBTc2hLZXlTdG9yZSB9IGZyb20gXCIuL3NyYy9rZXktc3RvcmUudHNcIjtcbmV4cG9ydCB7IExha2Vib3hFbnRyeVNjaGVtYSwgTGFrZWJveFNzaEtleVNjaGVtYSwgTGFrZWJveEFwaUVycm9yLCBMYWtlYm94Q2xpZW50IH0gZnJvbSBcIi4vc3JjL3Jlc3QudHNcIjtcbmV4cG9ydCB0eXBlIHsgTGFrZWJveEVudHJ5LCBMYWtlYm94U3NoS2V5LCBMYWtlYm94QXV0aCB9IGZyb20gXCIuL3NyYy9yZXN0LnRzXCI7XG5leHBvcnQgeyBTc2hTZXNzaW9uIH0gZnJvbSBcIi4vc3JjL3Nlc3Npb24udHNcIjtcbmV4cG9ydCB0eXBlIHsgU3NoU2Vzc2lvbk9wdGlvbnMgfSBmcm9tIFwiLi9zcmMvc2Vzc2lvbi50c1wiO1xuZXhwb3J0IHsgU3NoVHJhbnNwb3J0TW9kZVNjaGVtYSwgU3NoMlBhdGNoTW9kZVNjaGVtYSB9IGZyb20gXCIuL3NyYy90cmFuc3BvcnQudHNcIjtcbmV4cG9ydCB0eXBlIHsgU3NoVHJhbnNwb3J0TW9kZSwgU3NoMlBhdGNoTW9kZSB9IGZyb20gXCIuL3NyYy90cmFuc3BvcnQudHNcIjtcbiJdfQ==

package/package.json

@@ -25,9 +25,9 @@
     "vitest": "3.2.4"
   },
   "dependencies": {
-    "@dbx-tools/core": "^0.9.131",
-    "@dbx-tools/shared-core": "^0.9.131",
-    "@dbx-tools/shared-lakebox": "^0.9.131",
+    "@dbx-tools/core": "^0.9.132",
+    "@dbx-tools/shared-core": "^0.9.132",
+    "@dbx-tools/shared-lakebox": "^0.9.132",
     "generic-pool": "^3.9.0",
     "socks": "^2.8.10",
     "ssh2": "^1.17.0",
@@ -71,7 +71,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.131",
+  "version": "0.9.132",
   "types": "./lib/index.d.ts",
   "dbxToolsConfig": {
     "tags": [