@dbx-tools/appkit (英语)

在 Databricks AppKit 插件启动并使用 AppKit 请求前配置 Lakebase 上下文,键入插件搜索,以及从后端代码中取消 Databricks SDK .

快开始

当 Lakebase 设置必须在插件设置前解决时使用包装 :

import { lakebase, server } from "@databricks/appkit";
import { appkit } from "@dbx-tools/appkit";

await appkit.createApp({
  plugins: [server(), lakebase()],
});

使用这些助手用于 :

• 在 AppKit 设置前自动配置, 特别是 Lakebase/ Postgres env appKit 插件在初始化时读取的值.
• 对 AppKit 请求内可能运行的代码进行运行时安全上下文访问, 或背景脚本.
• 对 AppKit 插件的已键入的插件查找帮助器, 依赖导出 兄弟姐妹插件 .
• 通过共享的Lakebase分辨率 @dbx-tools/core 配置路径, 包括地壳、捆绑和 app.yaml 来源.
• 从网络中取消 SDK 连接 AbortSignal 输入 Databricks SDK 的值 Context 数值.
• Lakebase 计划以及用于应用程序特性的部署的桌布 在插件初始化前必须允许访问.
• AppKit- Global 文件系统缓存,带有用户同化的L1状态, 跨用户无效,和稳定的框架文件系统源.
• 一个截取器上下文 createApp (单位:千美元)interceptor?: Interceptor | Interceptor[](中文(简体) ) 手再加入计算后嵌入的 AppKit 寿命周期钩(onLifecycle,使用 AppKit 属于自己 setup:complete 编号 : server:ready 编号 : shutdown 词汇表). @dbx-tools/tunnel 用于辅助启动和关闭.

使用本地的 AppKit

当您的应用程序在读取所需的 env vars 之前直接使用本地 AppKit createApp() 并不需要在插件导出或配置周围设置额外设置 来源.

当摩擦在护靴和再利用周围时使用此包 :

• AppKit插件在初始化期间读取了Lakebase/Postgres env. 这个包 在设置前解决并应用这些值.
• AppKit 曝光 AppKit 处理器内部的请求上下文 。 这些帮助者制作代码 也可以通过脚本、测试和背景工作打来电话.
• AppKit 插件实例是通用的 。 外观帮手们会保持兄弟相接 访问键入并返回清晰错误.
• 本地 CLI 旗, 捆绑验证输出, 以及 app.yaml 值使用相同的 @dbx-tools/core 配置路径.
• 开口 asUser(req) 抛出外面 NODE_ENV=development 请求时 携带无半用户标志. identity 使回归到 a 配置的、按请求作出的决定,而不是 NODE_ENV 副效应.

通过呼叫者选择湖底路径 :

• 使用本地应用程序 lakebase() 当一个 Databricks App 已经完成时 运行时连接配置 .
• 使用此软件包 appkit.createApp() 当湖底环境值或 赠款必须在 AppKit 插件初始化前解决 .
• 使用 @dbx-tools/ 湖碱 用于了解剖面的发现和 独立节点或Bun代码中的短寿命证书.
• 使用 dbx 湖碱代氧 当外部 PostgreSQL 时 客户端需要回路连接 .

自动配置行为

appkit.createApp 是一个在 AppKit 周围的即时包装 createApp 与 相同的配置和相同的已输入插件- 导出地图 。 它运行 appkit.autoConfigure() 首先这样启用的能力可以充电 插件设置运行前的环境变量.

import { lakebase, server } from "@databricks/appkit";
import { appkit } from "@dbx-tools/appkit";

await appkit.createApp({
  plugins: [server(), lakebase()],
});

当本地 lakebase() 或 β 类型 database() 自动配置解析 Lakebase Postgres 连接设置并补全缺失 PG* 编号 : LAKEBASE_* 变量。 这样可以避免一个插件读取env的启动比赛 在另一个同步设置步骤能够发现它之前. 只有数据库的应用程序解决 在不含蓄地扩大Lakebase赠款的情况下, AppKit 数据库插件 拥有自有之池.

自动配置是保守的:除非呼叫者通过,否则现有 vars 获胜 在 Databricks App 中跳过 环境。 这使得同一切入点可用于地方发展, Databricks Asset Bundle验证,并部署Apps.

在本地启动时,一个失踪 DATABRICKS_CONFIG_PROFILE 居住人口来自 @dbx-tools/auth捆绑验证运行前的默认配置解析 . 工作空间API呼叫和Lakebase 池名证书使用相同的授权生命周期, 因此,过期的 CLI 刷新符可以引用 databricks auth login 改为 掉进SDK无关的缺省-自动链 部署的应用程序保留 本地 AppKit 认证, 并且不接收配置文件 .

在任何插件存在之前, Boot-time 解析度将作为服务主机运行, 所以 它坐落在AppKit的拦截器链外 它有它自己的超时,和 appkit.autoConfigure() 接受一个 AbortSignal 当一个打电话的人想 早点取消吧.

需要检查或自定义结果时使用下级函数:

import { lakebaseResolver } from "@dbx-tools/appkit";

const resolved = await lakebaseResolver.resolveLakebaseConnection({
  endpoint: process.env.LAKEBASE_ENDPOINT,
  autoCreate: false,
});

lakebaseResolver.applyLakebaseToEnv(resolved);

applyLakebaseEnv() 执行两个步骤并应用完整的组合 Postgres 池 需要,包括 PGUSER。自动配置调用相同的函数,所以调用者 外部 createApp 获得相同的嵌入而不是手卷子集:

const { resolved, user } = await lakebaseResolver.applyLakebaseEnv({ autoCreate: false });

找到它,当其他的东西 lakebase() 插件需要一个工作 泳池 游泳池 游泳池 AppKit 的持续缓存是常见的情况: 它从 环境,以及 createLakebasePool() 抛出,除非 LAKEBASE_ENDPOINT, (中文(简体) ), PGHOST, (中文(简体) ), PGDATABASE,则所有用户名都存在。 数据砖 App postgres 资源绑定供应仅是第一个。 如果缺少一个,缓存会无声地退化 到记忆. @dbx-tools/tunnel检察官办公室的大门叫这个 完全是为了这个 理由,你觉得呢.

配置

appkit.createApp() 接受所有 AppKit 软件 createApp 有,加:

设定 autoConfigure 在未注册的应用程序上 lakebase() 插件但是 仍然希望Lakebase支持的缓存坚持到底。 注入的 AppKit 存储器是 记忆第一:温暖的点击避免持续读取和 last_accessed 写入,同时 变异是连成一团,并写在后面,而不阻碍请求. 当a 湖底水池是持续的水位。 否则缓存会用到 便携式工程扫描磁盘级别 @dbx-tools/cache启用 "env" 在已部署的应用程序内,因为应用程序服务本能不能允许访问 缓存计划反正.

createApp() 当启用 AppKit 缓存时默认安装此存储 呼叫者没有提供 cache.storage保留了呼叫者提供的储存. 本地 AppKit 组成可以直接创建相同的适配器 :

import { cacheStorage } from "@dbx-tools/appkit";

const storage = await cacheStorage.createAppKitCacheStorage();

AppKit 关闭关闭时注入的存储 。 土著成分应称为 close() 当它直接拥有存储器时。 那排水管追踪到书写 在断开持续水平之前工作.

浏览器调试抓取

发展 createApp() 呼叫自动注册隐藏浏览器抓取 路线. @dbx-tools/ui/react 曝光情况 BrowserDebugCaptureButton,记录 边框浏览器、取景口、焦点、输入、指针、触摸、滚动和调整大小 不记录输入值或可打印密钥内容的诊断。 捕获 属于 JSONL 文件 .tmp/debug-captures 在发展中.

当本地 AppKit 组成或自定义时明确注册插件 需要抓取目录 :

import { debugCapture } from "@dbx-tools/appkit/debug";

debugCapture({ directory: ".tmp/browser-captures" });

文件系统缓存插件

登记册 filesCache() 当提供者支持的文件系统共享时 AppKit 寿命周期缓存 :

import { filesCache } from "@dbx-tools/appkit/files-cache";
import { server } from "@databricks/appkit";
import { appkit } from "@dbx-tools/appkit";

await appkit.createApp({
  plugins: [server(), filesCache()],
});

插件会曝光 forScope({ host, workspaceId?, userKey, ttlMs? }),哪个 返回时 FileSystemCache (单位:千美元) @dbx-tools/shared-fs fs.cache()。 。 。 . 值被主机,可选的工作空间代号,以及归属用户所隔离. A 类 批量无效清除了当前用户范围的匹配密钥,而不包含 共享授权敏感值.

forFileSystem(scope, { paths, key? }, load) 保留一个框架文件系统 用于同一用户和挂载路径的源. key 独立框架 在相同路径上使用不同政策的事例。 这提供了框架 例如, Mastra 是一个稳定的源身份, 跨越页面刷新和转折而不 引入第二个解析目录缓存 .

值和所保留的文件系统源使用有边框的进程-本地缓存存储. 没有写到Lakebase或另一个持久水平。 应用程序重新启动和 复制式更改从冷文件系统缓存开始.

此缓存有意与应用程序缓存适配器相分离. FilesCachePlugin 仍为本地文件系统的单一应用程序生命时间所有者 值而不是每个工作空间创建一个缓存或持续 授权敏感文件系统状态 .

lakebaseResolver.resolveLakebaseConnection() 接受:

解析期间读取的环境变量:

已解析的值会被写回 process.env 以 lakebaseResolver.applyLakebaseToEnv(),从不覆盖变量 已经设置。 这个功能涵盖一切,但 PGUSER,则需要 等着. lakebaseResolver.applyLakebaseEnv() 解析并应用完整集.

解析本地和捆绑配置

配置为 @dbx-tools/core,不通过此套件再出口. 它的默认优先级是常量配置, 进程 env, .env组合 config.env,则 app.yaml 编号 : app.yml。 。 。 .

import { configUtils } from "@dbx-tools/core";

const warehouseId = configUtils.resolveValue("DATABRICKS_WAREHOUSE_ID", {
  data: { DATABRICKS_WAREHOUSE_ID: flags.warehouse },
});

在 CLI 中使用此功能, 并设置本地和本地操作相同的脚本 数据砖App部署. configUtils.bundleFile() 曝光已验证的捆绑 输出时 configUtils.appFile() 曝光解析 App YAML. 两个缓存都成功, 缺少,且进程寿命结果无效.

解析湖基地址

pgaddress.parseAddress() 接受资源路径, Postgres URL, 赤裸 Lakebase主机和部分投入。 它让解脱者有一个共同的形状,没有 要求用户记住一个犬形格式.

import { pgaddress } from "@dbx-tools/appkit";

pgaddress.parseAddress(
  "postgresql://[email protected]/databricks_postgres?sslmode=require",
);

pgaddress.parseResourcePath() 当您特别期望一个 projects/<id>/branches/<id>/endpoints/<id> 数值.

安全使用 AppKit 执行上下文

appkit.tryGetExecutionContext() 返回活动的 AppKit 请求上下文 代码在 AppKit 下运行,并且 undefined 别的地方 这让图书馆 在应用程序中保留 OBO 认证,同时仍在使用脚本.

import { appkit } from "@dbx-tools/appkit";
import { createWorkspaceClient } from "@databricks/appkit";

const client = appkit.tryGetExecutionContext()?.client ?? createWorkspaceClient();

appkit.ensureInitialized() 懒散地初始化 AppKit 运行时状态 在可能提前运行的代码路径中查找上下文.

适应 Databricks SDK 取消

Databricks SDK 呼叫接受一个 Context。许多应用程序和网络API使用 AbortSignal。 。 。 . databricks.toContext() 连接两个.

import { databricks } from "@dbx-tools/appkit";

await client.apiClient.request(
  {
    path: "/api/2.0/serving-endpoints",
    method: "GET",
    headers: new Headers(),
    raw: false,
  },
  databricks.toContext(request.signal),
);

查找兄弟姐妹插件

AppKit的插件映射是故意通用的. pluginRegistry.data(), (中文(简体) ), pluginRegistry.instance(),以及 pluginRegistry.require() 继续打字, 制作得更好 缺少所需插件时出错 .

import { lakebase } from "@databricks/appkit";
import { pluginRegistry } from "@dbx-tools/appkit";

const lake = pluginRegistry.instance(this.context, lakebase);
const pool = lake?.exports().pool;

const required = pluginRegistry.require(this.context, lakebase, "my-plugin").exports();

在 AppKit 插件中使用此功能, 该插件依赖兄弟式插件导出, 但不应该 硬码注册名称或在每个呼叫站点投放. 需要缺失 插件丢弃 AppKit 的 ConfigurationError,同时命名呼叫者和 要注册的插件 .

湖泊基地出入

createApp({ autoConfigure: "provision" }) 包括现有 appkit 财务报告和审定财务报表 mastra_instance 计划 添加应用程序计划或单个表格 lakebaseProvisionTargets,或设置 CSV DBX_TOOLS_APPKIT_LAKEBASE_PROVISION_TARGETS 变量。 确切的重复为 已删除.

整个Schema的赠款在自己的交易中居于首位。 当成功的时候, 方案下的表格目标被跳过。 当它失败了,因为当地 身份可以修改表格,但不能修改整个计划,失败会被记录 将独立尝试明确的表格目标。 缺少计划 表格被调试记录并跳出 .

await appkit.createApp({
  autoConfigure: "provision",
  lakebaseProvisionTargets: ["reporting", "operations.events"],
  plugins: [lakebase()],
});

provision.provisionLakebaseAccess() 揭发同一位来电者 已经解决了湖基连接环境值.

import { provision } from "@dbx-tools/appkit";

await provision.provisionLakebaseAccess("[email protected]", [
  "appkit",
  "mastra_instance",
  "reporting",
  "operations.events",
]);

通过第三个参数来报告您自己日志的进度 。 规定 在 Databricks App 中跳过,目标失败被记录而非 丢出如此退化的缓存 永远不会阻止启动.

选择请求身份

AppKit 给出了插件的两个身份: 环境服务上下文( app's own) 和每个请求用户的上下文输入 asUser(req), (中文(简体) ), 使用 Databricks 前门的标志认证半边( OBO) 前进 x-forwarded-access-token当信头缺席时, AppKit 的 行为完全取决于 NODE_ENV数字 :

那个投球对前门后面的应用程序很合适 里面有缺失的活物 意味着有东西坏了 对合法交易的应用程序来说是致命的 抵达时没有一条,比如一条公用地道 电话通过电子邮件认证 代码(@dbx-tools/隧道)或经认证的网页或机器人 频道. 这些应用程序不能运行 NODE_ENV=development 只是为了得到 反倒,因为那面旗子也会放松 安全的饼干和解锁其他 惟有逃生舱门.

identity 该决定明确表明:

import { identity } from "@dbx-tools/appkit";

const mode = identity.resolveIdentityMode(config.identity, "MY_APP_IDENTITY");

// One call decides whether this request enters `asUser`.
const scoped = identity.useServicePrincipal(mode, req) ? this : this.asUser(req);
const rows = await scoped.executeQuery(sql);

auto 确定每个请求,而不是每个靴子,因为一个容器可以同时服务 出站口:隧道出站口和站台前门共用一个出站口. A 类 时空旗帜对其中一个来说是错的 未确认 配置值丢出a ConfigurationError 而不是倒回去,因为 a 类型("obo", (中文(简体) ), "sp") 否则会继续服务于选项本身的错误 被设定为避免.

作为服务主运行不会改变哪个用户拥有请求. 打电话的人还是来了 x-forwarded-user 编号 : x-forwarded-email (读出) 与 identity.requestUserId() 编号 : requestUserEmail()所以记忆线, 缓存命名空间, 和痕量归属保留每个用户 。 只有数据砖 证书是共享的. appkit.createApp() 邮票发送的电子邮件,或用户 当没有电子邮件时 ID 在每一个本地 HTTP 请求根上作为 打开几何 user.id。 。 。 . @dbx-tools/appkit-mastra 揭发证书 选择为 genieIdentity 选项.

模块

自动配置的外壳化包装是 校对:soup高层代理成分 进入 @dbx-tools/appkit-mastra (英语)。 。 。 .