@dbx-tools/appkit 0.6.58 → 0.6.60

package/package.json

@@ -28,8 +28,8 @@
   },
   "dependencies": {
     "@databricks/sdk-experimental": "^0.17.0",
-    "@dbx-tools/core": "0.6.58",
-    "@dbx-tools/shared-core": "0.6.58",
+    "@dbx-tools/core": "0.6.60",
+    "@dbx-tools/shared-core": "0.6.60",
     "yaml": "^2.9.0",
     "zod": "4.3.6"
   },
@@ -47,7 +47,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.6.58",
+  "version": "0.6.60",
   "types": "./lib/index.d.ts",
   "type": "module",
   "exports": {

package/src/create-app.ts

@@ -21,17 +21,20 @@
  * @module
  */
 
-import { createApp as appkitCreateApp, getUsernameWithApiLookup } from "@databricks/appkit";
+import { createApp as appkitCreateApp } from "@databricks/appkit";
 // AppKit's root barrel re-exports `PluginData` but not `PluginMap`; the package
 // publishes this subpath for exactly that type.
 import type { PluginMap } from "@databricks/appkit/dist/shared/src/plugin";
 import { async, log } from "@dbx-tools/shared-core";
 
 import {
-  applyLakebaseToEnv,
-  resolveLakebaseConnection,
-  type LakebaseConnection,
-} from "./lakebase-resolver.ts";
+  createInterceptorContext,
+  type Interceptor,
+  type InterceptorRuntime,
+  lifecycleBridge,
+  type ResolvedAppEnv,
+} from "./interceptor.ts";
+import { applyLakebaseEnv, type LakebaseConnection } from "./lakebase-resolver.ts";
 import { provisionCacheSchema } from "./provision.ts";
 
 type AppKitCreateAppConfig = NonNullable<Parameters<typeof appkitCreateApp>[0]>;
@@ -67,6 +70,13 @@ export type CreateAppConfig<T extends AppKitPlugins = AppKitPlugins> = Omit<
   onPluginsReady?: (appkit: PluginMap<T>) => void | Promise<void>;
   /** Auto-configuration to run before AppKit boots. Defaults to `"provision"`. */
   autoConfigure?: AutoConfigureMode | false;
+  /**
+   * One or many {@link Interceptor}s handed an {@link InterceptorContext} once
+   * auto-configuration has computed the env. Each receives the resolved env, an
+   * AppKit-lifecycle hook, and `bindProcess` for concurrently-style supervision -
+   * see `./interceptor`. The tunnel is the primary consumer.
+   */
+  interceptor?: Interceptor | Interceptor[];
 };
 
 const logger = log.logger("create-app");
@@ -107,7 +117,7 @@ function usesPlugin<T extends AppKitPlugins>(
 export async function autoConfigure<T extends AppKitPlugins>(
   config?: CreateAppConfig<T>,
   signal?: AbortSignal,
-): Promise<void> {
+): Promise<LakebaseConnection | undefined> {
   const mode = config?.autoConfigure ?? DEFAULT_AUTO_CONFIGURE;
   const explicit = config?.autoConfigure !== undefined;
   const lakebasePluginPresent = usesPlugin(config, LAKEBASE_PLUGIN);
@@ -118,7 +128,7 @@ export async function autoConfigure<T extends AppKitPlugins>(
       provisioned: false,
       skippedReason: mode === false ? "disabled" : "no lakebase plugin",
     });
-    return;
+    return undefined;
   }
 
   const controller = new AbortController();
@@ -126,24 +136,22 @@ export async function autoConfigure<T extends AppKitPlugins>(
   async.tieAbortSignal(controller, AbortSignal.timeout(AUTO_CONFIGURE_TIMEOUT_MS));
 
   const provision = mode === "provision";
-  await autoConfigureLakebase(provision, controller.signal);
+  const resolved = await autoConfigureLakebase(provision, controller.signal);
   logger.info("ready", { autoConfigure: mode, lakebasePluginPresent, provisioned: provision });
+  return resolved;
 }
 
 /**
  * Resolve Lakebase Postgres connection info, write the resolved values to
  * `process.env`, and return the record. Used by {@link autoConfigure}; call
- * {@link resolveLakebaseConnection} and {@link applyLakebaseToEnv} directly when
- * finer control is needed.
+ * {@link applyLakebaseEnv} directly when finer control is needed (a different
+ * `autoCreate` policy, or a caller that wants the env without booting AppKit).
  */
 async function autoConfigureLakebase(
   provision: boolean,
   signal: AbortSignal,
 ): Promise<LakebaseConnection> {
-  const resolved = await resolveLakebaseConnection(undefined, signal);
-  applyLakebaseToEnv(resolved);
-  const user = await getUsernameWithApiLookup({});
-  if (user) process.env.PGUSER ??= user;
+  const { resolved, user } = await applyLakebaseEnv(undefined, signal);
   logger.info("env updated", { ...redactLakebaseConnection(resolved), user });
   if (provision) {
     await provisionCacheSchema(user, logger);
@@ -163,10 +171,31 @@ function redactLakebaseConnection(resolved: LakebaseConnection): Record<string,
   };
 }
 
+/** Build the {@link ResolvedAppEnv} interceptors read, from the auto-config result. */
+function resolvedAppEnv(lakebase: LakebaseConnection | undefined): ResolvedAppEnv {
+  return {
+    ...(lakebase ? { lakebase } : {}),
+    ...(process.env.DATABRICKS_HOST ? { databricksHost: process.env.DATABRICKS_HOST } : {}),
+  };
+}
+
+/** Normalize the `interceptor?: Interceptor | Interceptor[]` option to an array. */
+function interceptorList(interceptor: CreateAppConfig["interceptor"]): Interceptor[] {
+  if (!interceptor) return [];
+  return Array.isArray(interceptor) ? interceptor : [interceptor];
+}
+
 /**
  * Auto-configuring drop-in for AppKit's `createApp`: same config, same typed
  * plugin-export map, with {@link autoConfigure} run first.
  *
+ * When {@link CreateAppConfig.interceptor}s are given, each is invoked with an
+ * {@link InterceptorContext} AFTER auto-configuration computes the env and BEFORE
+ * AppKit boots - so an interceptor can read the resolved connection, register
+ * lifecycle handlers, and `bindProcess` a child. A hidden {@link lifecycleBridge}
+ * plugin is injected so those `onLifecycle` handlers fire on the genuine AppKit
+ * events; it has no exports, so the returned {@link PluginMap} is unchanged.
+ *
  * @example
  * import { createApp } from "@dbx-tools/appkit";
  * import { lakebase, server } from "@databricks/appkit";
@@ -176,8 +205,26 @@ function redactLakebaseConnection(resolved: LakebaseConnection): Record<string,
 export async function createApp<T extends AppKitPlugins>(
   config?: CreateAppConfig<T>,
 ): Promise<PluginMap<T>> {
-  await autoConfigure(config);
+  const lakebase = await autoConfigure(config);
   const appConfig = { ...config };
   delete appConfig.autoConfigure;
+  delete appConfig.interceptor;
+
+  const interceptors = interceptorList(config?.interceptor);
+  if (interceptors.length === 0) {
+    return appkitCreateApp<T>(appConfig);
+  }
+
+  // Build the context from the computed env, run each interceptor (they register
+  // lifecycle handlers + bind processes), then inject the bridge that relays the
+  // REAL AppKit lifecycle into `runtime.emitLifecycle` during its `setup()`.
+  const runtime: InterceptorRuntime = createInterceptorContext(resolvedAppEnv(lakebase));
+  for (const interceptor of interceptors) {
+    await interceptor(runtime.context);
+  }
+  // Append the bridge to the plugins tuple. It is hidden and exports nothing, so
+  // the returned map still matches `PluginMap<T>`; the cast (through `unknown`) is
+  // only because appending widens the tuple type beyond `T`.
+  appConfig.plugins = [...(appConfig.plugins ?? []), lifecycleBridge({ runtime })] as unknown as T;
   return appkitCreateApp<T>(appConfig);
 }

package/src/identity.ts

@@ -20,7 +20,7 @@
  * where a missing token means something is wrong. It is fatal for an app whose
  * traffic legitimately arrives WITHOUT one:
  *
- *   - a public tunnel (`@dbx-tools/cli-tunnel`), where callers authenticate by
+ *   - a public tunnel (`@dbx-tools/tunnel`), where callers authenticate by
  *     email OTP and no OBO token exists to forward - the gate can prove WHO the
  *     caller is, but it cannot mint a Databricks credential for them;
  *   - any reverse proxy, webhook, or bot channel (`POST /api/teams/messages`)
@@ -41,7 +41,7 @@
  *
  * `"auto"` decides per REQUEST, not per boot, because a single container serves
  * both doors at once - the tunnel gate and the platform front door share a port
- * (see `@dbx-tools/cli-tunnel`). A boot-time flag would have to be wrong for one
+ * (see `@dbx-tools/tunnel`). A boot-time flag would have to be wrong for one
  * of them.
  *
  * What the service principal does NOT change is WHO the request belongs to. The

package/src/interceptor.ts

@@ -0,0 +1,261 @@
+/**
+ * The `createApp` INTERCEPTOR context: an in-process handle an app hands to
+ * add-ons (the tunnel, chiefly) so they can read the env auto-configuration
+ * computed, hook AppKit's lifecycle, and supervise sibling child processes as one
+ * unit - concurrently-style, where any death takes the whole set down.
+ *
+ * An interceptor is a plain function `(ctx) => void | Promise<void>` passed to
+ * {@link CreateAppConfig.interceptor} ("one or many"). {@link createApp} runs each
+ * one AFTER auto-configuration has populated `process.env` but as part of booting
+ * the app, so an interceptor sees the resolved connection and can bind processes
+ * before or during setup.
+ *
+ * The names here mirror AppKit's own vocabulary rather than inventing parallel
+ * ones: {@link LifecycleEvent} and {@link InterceptorContext.onLifecycle} are the
+ * exact shape of `PluginContext.onLifecycle` (`setup:complete` / `server:ready` /
+ * `shutdown`). The bridge that makes that hook reachable from OUTSIDE a plugin -
+ * where interceptors run - is {@link lifecycleBridge}, a tiny internal plugin
+ * {@link createApp} injects to capture `this.context` and relay its events.
+ *
+ * @module
+ */
+
+import type { ChildProcess } from "node:child_process";
+import { Plugin, toPlugin, type BasePluginConfig, type PluginManifest } from "@databricks/appkit";
+import { log } from "@dbx-tools/shared-core";
+import type { LakebaseConnection } from "./lakebase-resolver.ts";
+
+const logger = log.logger("interceptor");
+
+/**
+ * AppKit's plugin-lifecycle events, verbatim from `PluginContext`
+ * (`node_modules/@databricks/appkit/.../core/plugin-context.d.ts`). Re-declared
+ * structurally rather than imported because `PluginContext` is not in the
+ * package's `exports` map (the same reason {@link PluginContextLike} exists in
+ * `./plugin`).
+ *
+ * - `setup:complete` - every plugin's `setup()` has resolved.
+ * - `server:ready` - the `server()` plugin is listening (never fires for a
+ *   serverless app, e.g. the tunnel gate).
+ * - `shutdown` - the app is tearing down.
+ */
+export type LifecycleEvent = "setup:complete" | "server:ready" | "shutdown";
+
+/** A lifecycle subscriber. Errors are logged, not propagated (matches AppKit). */
+export type LifecycleHandler = () => void | Promise<void>;
+
+/**
+ * The env auto-configuration resolved before boot, exposed to interceptors so
+ * they read COMPUTED values instead of re-reading `process.env` themselves.
+ *
+ * `lakebase` is the resolved Postgres connection when Lakebase auto-config ran
+ * (see `create-app`'s `autoConfigure`), else `undefined`. `databricksHost` is the
+ * workspace host as resolved into the environment (`DATABRICKS_HOST`), which the
+ * tunnel interceptor both reads and, when it must, sets.
+ */
+export interface ResolvedAppEnv {
+  /** Resolved Lakebase connection, when auto-config resolved one. */
+  readonly lakebase?: LakebaseConnection;
+  /** Resolved Databricks workspace host (`DATABRICKS_HOST`), when known. */
+  readonly databricksHost?: string;
+}
+
+/**
+ * A process {@link InterceptorContext.bindProcess} can supervise. A bare
+ * `node:child_process` `ChildProcess` (e.g. portr) satisfies this, and so does
+ * `@dbx-tools/core`'s `spawn()` result (a `ChildProcessResult` IS a
+ * `ChildProcess`) - one code path handles both.
+ */
+export type BindableProcess = Pick<ChildProcess, "pid" | "kill" | "killed" | "once">;
+
+/**
+ * The handle passed to each interceptor.
+ *
+ * @example
+ * import { createApp } from "@dbx-tools/appkit";
+ *
+ * await createApp({
+ *   plugins: [server()],
+ *   interceptor: (ctx) => {
+ *     const portr = spawnPortr(ctx.env.databricksHost);
+ *     ctx.bindProcess(portr);            // app <-> portr live/die together
+ *     ctx.onLifecycle("shutdown", () => portr.kill("SIGTERM"));
+ *   },
+ * });
+ */
+export interface InterceptorContext {
+  /** The env auto-configuration computed before boot. */
+  readonly env: ResolvedAppEnv;
+  /**
+   * Subscribe to an AppKit lifecycle event. Mirrors `PluginContext.onLifecycle`;
+   * the injected {@link lifecycleBridge} relays the real events here once the app
+   * boots. A handler registered for an event that already fired is NOT called
+   * retroactively (same semantics as AppKit).
+   */
+  onLifecycle(event: LifecycleEvent, fn: LifecycleHandler): void;
+  /**
+   * Broadcast a termination signal from the main app to every bound process.
+   * Called automatically when this process receives `SIGINT`/`SIGTERM`/`SIGHUP`;
+   * exposed so an interceptor can trigger teardown itself.
+   */
+  broadcastSignal(signal: NodeJS.Signals): void;
+  /**
+   * Supervise a child process alongside the app, concurrently-style: signals pass
+   * through, and if EITHER the child or the app dies the whole set comes down.
+   * Generalizes the tunnel's old hand-rolled `superviseExit`. Safe to call for
+   * several children; teardown is idempotent.
+   */
+  bindProcess(child: BindableProcess): void;
+}
+
+/** A single interceptor, or several. The `createApp` `interceptor?:` option. */
+export type Interceptor = (ctx: InterceptorContext) => void | Promise<void>;
+
+/** How long bound children get to exit on `SIGTERM` before the app force-exits. */
+const TEARDOWN_GRACE_MS = 3000;
+
+/** The signals that trigger teardown when the MAIN process receives them. */
+const TEARDOWN_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const;
+
+/**
+ * The mutable machinery behind an {@link InterceptorContext}. Split out so
+ * {@link createInterceptorContext} can hand the public context to interceptors
+ * while `create-app` retains the `emitLifecycle` side-channel the bridge drives.
+ */
+export interface InterceptorRuntime {
+  /** The context handed to each interceptor. */
+  readonly context: InterceptorContext;
+  /** Fire a lifecycle event to every subscriber (called by {@link lifecycleBridge}). */
+  emitLifecycle(event: LifecycleEvent): Promise<void>;
+}
+
+/**
+ * Build an {@link InterceptorContext} + its {@link InterceptorRuntime}.
+ *
+ * Teardown is the generalized `superviseExit`: the first child exit or main-process
+ * termination signal flips a one-shot guard, `SIGTERM`s the other bound children,
+ * then `process.exit`s after {@link TEARDOWN_GRACE_MS} (an `unref`'d timer, so it
+ * never itself holds the loop open). The process-signal listeners are installed
+ * lazily on the first `bindProcess` so an app that binds nothing is untouched.
+ */
+export function createInterceptorContext(env: ResolvedAppEnv): InterceptorRuntime {
+  const handlers = new Map<LifecycleEvent, LifecycleHandler[]>();
+  const children = new Set<BindableProcess>();
+  let shuttingDown = false;
+  let signalsBound = false;
+
+  const teardown = (code: number): void => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    for (const child of children) {
+      if (!child.killed) child.kill("SIGTERM");
+    }
+    setTimeout(() => process.exit(code), TEARDOWN_GRACE_MS).unref();
+  };
+
+  const broadcastSignal = (signal: NodeJS.Signals): void => {
+    for (const child of children) {
+      if (!child.killed) child.kill(signal);
+    }
+    teardown(0);
+  };
+
+  const bindProcessSignals = (): void => {
+    if (signalsBound) return;
+    signalsBound = true;
+    for (const signal of TEARDOWN_SIGNALS) {
+      process.on(signal, () => broadcastSignal(signal));
+    }
+  };
+
+  const bindProcess = (child: BindableProcess): void => {
+    bindProcessSignals();
+    children.add(child);
+    child.once("exit", (code) => {
+      logger.warn("bound process exited; tearing down the app", { code });
+      teardown(typeof code === "number" ? code : 1);
+    });
+  };
+
+  const onLifecycle = (event: LifecycleEvent, fn: LifecycleHandler): void => {
+    const list = handlers.get(event);
+    if (list) list.push(fn);
+    else handlers.set(event, [fn]);
+  };
+
+  const emitLifecycle = async (event: LifecycleEvent): Promise<void> => {
+    const list = handlers.get(event);
+    if (!list) return;
+    for (const fn of list) {
+      try {
+        await fn();
+      } catch (error) {
+        // Match AppKit: a failing lifecycle handler is logged, never fatal, and
+        // never blocks its siblings.
+        logger.warn("lifecycle handler failed", { event, error });
+      }
+    }
+  };
+
+  const context: InterceptorContext = {
+    env,
+    onLifecycle,
+    broadcastSignal,
+    bindProcess,
+  };
+
+  return { context, emitLifecycle };
+}
+
+/** Config for {@link LifecycleBridgePlugin}: the sink its captured events flow to. */
+interface LifecycleBridgeConfig extends BasePluginConfig {
+  /** The runtime whose `emitLifecycle` receives the real AppKit events. */
+  runtime?: InterceptorRuntime;
+}
+
+/**
+ * Structural shape of the `PluginContext.onLifecycle` we bridge. Mirrors only the
+ * one method we touch (like {@link PluginContextLike} in `./plugin`), since
+ * AppKit's `PluginContext` is not importable from the package's `exports`.
+ */
+interface LifecycleContextLike {
+  onLifecycle(event: LifecycleEvent, fn: LifecycleHandler): void;
+}
+
+function hasOnLifecycle(context: unknown): context is LifecycleContextLike {
+  return typeof (context as LifecycleContextLike | undefined)?.onLifecycle === "function";
+}
+
+/**
+ * The internal plugin {@link createApp} injects to make AppKit's lifecycle
+ * reachable from interceptor code. On `setup()` it reads its own `this.context`
+ * (the real `PluginContext`) and forwards each {@link LifecycleEvent} to the
+ * interceptor runtime, so `ctx.onLifecycle(...)` handlers fire on the genuine
+ * events. It owns no routes, config surface, or exports.
+ */
+export class LifecycleBridgePlugin extends Plugin<LifecycleBridgeConfig> {
+  static manifest = {
+    name: "dbxToolsLifecycleBridge",
+    displayName: "Lifecycle Bridge",
+    description: "Relays AppKit lifecycle events to the createApp interceptor context.",
+    stability: "beta",
+    hidden: true,
+    resources: { required: [], optional: [] },
+  } satisfies PluginManifest<"dbxToolsLifecycleBridge">;
+
+  override async setup(): Promise<void> {
+    const runtime = this.config.runtime;
+    if (!runtime) return;
+    if (!hasOnLifecycle(this.context)) {
+      logger.debug("no PluginContext.onLifecycle to bridge; interceptor lifecycle events inert");
+      return;
+    }
+    const events: LifecycleEvent[] = ["setup:complete", "server:ready", "shutdown"];
+    for (const event of events) {
+      this.context.onLifecycle(event, () => runtime.emitLifecycle(event));
+    }
+  }
+}
+
+/** Factory for the injected {@link LifecycleBridgePlugin}. */
+export const lifecycleBridge = toPlugin(LifecycleBridgePlugin);

package/src/lakebase-resolver.ts

@@ -38,6 +38,7 @@
 import {
   ConfigurationError,
   ExecutionError,
+  getUsernameWithApiLookup,
   getWorkspaceClient,
   ValidationError,
 } from "@databricks/appkit";
@@ -383,6 +384,9 @@ export async function resolveLakebaseConnection(
  * (which reads env directly) picks them up during its own `setup()`.
  * Existing env values are preserved; only missing keys are filled in,
  * which keeps explicit overrides authoritative.
+ *
+ * This does NOT set `PGUSER`, which needs an await - see
+ * {@link applyLakebaseEnv} for the complete set a Postgres pool requires.
  */
 export function applyLakebaseToEnv(resolved: LakebaseConnection): void {
   if (resolved.endpoint) process.env.LAKEBASE_ENDPOINT ??= resolved.endpoint;
@@ -392,6 +396,40 @@ export function applyLakebaseToEnv(resolved: LakebaseConnection): void {
   process.env.PGSSLMODE ??= resolved.sslMode;
 }
 
+/**
+ * Resolve the connection AND apply every Postgres env var a Lakebase pool needs,
+ * returning the resolved connection plus the username that was applied.
+ *
+ * This is the whole set, which is the point of having one function for it:
+ * `createLakebasePool()` throws unless `LAKEBASE_ENDPOINT`, `PGHOST`,
+ * `PGDATABASE`, **and** a username (`PGUSER`, or `DATABRICKS_CLIENT_ID` for a
+ * service principal) are all present, and a Databricks App `postgres` resource
+ * binding supplies only the first. Anything that wants a working pool - the
+ * `lakebase` plugin, or AppKit's PERSISTENT cache, which quietly degrades to
+ * in-memory when the pool cannot be built - needs all four, so callers should not
+ * pair {@link applyLakebaseToEnv} with their own username lookup.
+ *
+ * `PGUSER` is applied with `??=` like the rest, so an explicitly configured value
+ * stays authoritative. The lookup returns `undefined` rather than throwing when it
+ * cannot determine a user, leaving the pool to resolve its own.
+ *
+ * @example
+ * import { lakebaseResolver } from "@dbx-tools/appkit";
+ *
+ * // Enough for `createLakebasePool()` to build a pool.
+ * const { user } = await lakebaseResolver.applyLakebaseEnv({ autoCreate: false });
+ */
+export async function applyLakebaseEnv(
+  config?: LakebaseResolverInputs,
+  signal?: AbortSignal,
+): Promise<{ resolved: LakebaseConnection; user?: string }> {
+  const resolved = await resolveLakebaseConnection(config, signal);
+  applyLakebaseToEnv(resolved);
+  const user = await getUsernameWithApiLookup({});
+  if (user) process.env.PGUSER ??= user;
+  return { resolved, ...(user ? { user } : {}) };
+}
+
 type WorkspaceClient = ReturnType<typeof getWorkspaceClient>;
 
 /** The SDK `Context` accepted by the workspace client's own copy of the SDK. */