feat(plugin): expose a read-only schema metadata host API

This commit is contained in:
jearhe authored and GitHub committed 2026-09-23 12:51:23 +08:00
1 parent 2f960f104c
commit d5a05a9884
40 files changed
+1445 -86

No files matched your search

@@ -2,6 +2,7 @@ import type { InstalledPlugin, PluginBinaryEvent, PluginEvent, PluginUiAssetPayl
import { clonePluginData, snapshotPluginWorkbenchContext } from "./pluginData";
import { MAX_PLUGIN_PLAN_SQL_CHARS, MAX_PLUGIN_PLAN_TIMEOUT_MS, PLUGIN_PLAN_PERMISSION, type PluginPlanCapabilities, type PluginPlanRequest, type PluginPlanResult } from "@/types/pluginPlan";
import { createPluginAiConversation, type AiPluginConversationRequest } from "@/lib/ai/aiPluginConversation";
import { MAX_PLUGIN_SCHEMA_METADATA_NAME_CHARS, PLUGIN_SCHEMA_METADATA_CAPABILITY, PLUGIN_SCHEMA_METADATA_PERMISSION, type PluginTableContext, type PluginTableMetadata } from "@/types/pluginSchemaMetadata";
const PLUGIN_MESSAGE_SOURCE = "dbx-plugin";
const HOST_MESSAGE_SOURCE = "dbx-host";
@@ -109,6 +110,8 @@ export interface PluginHostBridgeApi {
* generates and owns the EXPLAIN statement; the plugin cannot pass one.
*/
explainPlan?(request: PluginPlanRequest): Promise<PluginPlanResult>;
/** Read-only table schema metadata over an already-open Host connection. */
getTableMetadata?(context: PluginTableContext): Promise<PluginTableMetadata>;
closeTab?(): Promise<void> | void;
/** Persist plugin bytes through the host's native save dialog. Resolves null when the user cancels. */
saveFile?(pluginId: string, request: PluginSaveFileRequest, data: Uint8Array): Promise<PluginSaveFileResult | null>;
@@ -249,6 +252,7 @@ export class PluginHostBridge {
capabilities: {
downloadFile: !!this.api.downloadFile,
planApi: !!this.api.getPlanCapabilities && !!this.api.explainPlan,
[PLUGIN_SCHEMA_METADATA_CAPABILITY]: !!this.api.getTableMetadata,
storage: !!this.api.storageGet && !!this.api.storageSet && !!this.api.storageDelete,
ai: !!this.api.openAiConversation,
},
@@ -399,6 +403,11 @@ export class PluginHostBridge {
if (!this.api.explainPlan) throw new Error("Host plan API is unavailable");
return this.api.explainPlan(requirePluginPlanRequest(requireRecord(params, "host.explainPlan params")));
}
if (method === "host.getTableMetadata") {
this.requirePermission(PLUGIN_SCHEMA_METADATA_PERMISSION);
if (!this.api.getTableMetadata) throw new Error("Host schema metadata API is unavailable");
return this.api.getTableMetadata(requirePluginTableContext(requireRecord(params, "host.getTableMetadata params")));
}
if (method === "host.saveFile") {
const input = isRecord(params) ? params : {};
// The sandboxed iframe cannot trigger downloads (WKWebView cancels blob
@@ -817,6 +826,8 @@ export function pluginSdkSource(initialTheme?: PluginBridgeTheme): string {
// its intent, and the host refuses anything other than "estimated".
getPlanCapabilities: (connectionId) => request('host.getPlanCapabilities', { connectionId }),
explainPlan: (planRequest) => request('host.explainPlan', planRequest),
// Read-only metadata; the host enforces the permission and open-session gate.
getTableMetadata: (tableContext) => request('host.getTableMetadata', tableContext),
saveFile: (options = {}, data) => {
if (data === undefined) return request('host.saveFile', options);
if (typeof data === 'string') return request('host.saveFile', { ...(options || {}), dataBase64: data });
@@ -947,6 +958,34 @@ function optionalPluginPlanScope(value: unknown, label: string): string | undefi
return value.trim() ? requirePluginPlanIdentifier(value, label) : undefined;
}
function requirePluginTableContext(input: Record<string, unknown>): PluginTableContext {
const context: PluginTableContext = {
connectionId: requirePluginSchemaMetadataIdentifier(input.connectionId, "connectionId"),
table: requirePluginSchemaMetadataIdentifier(input.table, "table"),
};
const database = optionalPluginSchemaMetadataIdentifier(input.database, "database");
const schema = optionalPluginSchemaMetadataIdentifier(input.schema, "schema");
if (database !== undefined) context.database = database;
if (schema !== undefined) context.schema = schema;
return context;
}
function requirePluginSchemaMetadataIdentifier(value: unknown, label: string): string {
if (typeof value !== "string") throw new Error(`${label} must be a string`);
const identifier = value.trim();
if (!identifier) throw new Error(`${label} must not be empty`);
if (Array.from(identifier).length > MAX_PLUGIN_SCHEMA_METADATA_NAME_CHARS) {
throw new Error(`${label} must be at most ${MAX_PLUGIN_SCHEMA_METADATA_NAME_CHARS} characters`);
}
return identifier;
}
function optionalPluginSchemaMetadataIdentifier(value: unknown, label: string): string | undefined {
if (value === undefined || value === null) return undefined;
if (typeof value !== "string") throw new Error(`${label} must be a string`);
return value.trim() ? requirePluginSchemaMetadataIdentifier(value, label) : undefined;
}
/**
* Validates one `host.explainPlan` request. The host owns the EXPLAIN text, so
* the only accepted shape is the caller's own SQL plus a connection reference