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

@@ -9,6 +9,7 @@ import QueryLoadingState from "@/components/common/QueryLoadingState.vue";
import JsonTree from "@/components/common/JsonTree.vue"; import JsonTree from "@/components/common/JsonTree.vue";
import RedisJsonEditor from "@/components/redis/RedisJsonEditor.vue"; import RedisJsonEditor from "@/components/redis/RedisJsonEditor.vue";
import * as api from "@/lib/backend/api"; import * as api from "@/lib/backend/api";
import type { MeilisearchIndexSettings } from "@/lib/backend/tauri";
import { useToast } from "@/composables/useToast"; import { useToast } from "@/composables/useToast";
import { useConnectionStore } from "@/stores/connectionStore"; import { useConnectionStore } from "@/stores/connectionStore";
import { useQueryStore } from "@/stores/queryStore"; import { useQueryStore } from "@/stores/queryStore";
@@ -28,7 +29,7 @@ const connectionStore = useConnectionStore();
const queryStore = useQueryStore(); const queryStore = useQueryStore();
const settingsText = ref(""); const settingsText = ref("");
const settingsValue = ref<Record<string, any>>({}); const settingsValue = ref<MeilisearchIndexSettings>({});
const loading = ref(false); const loading = ref(false);
const error = ref(""); const error = ref("");
const editMode = ref(false); const editMode = ref(false);
@@ -82,9 +83,9 @@ async function saveSettings() {
isSaving.value = true; isSaving.value = true;
saveError.value = ""; saveError.value = "";
try { try {
await api.meilisearchUpdateIndexSettings(props.connectionId, props.index, parsed as Record<string, any>); await api.meilisearchUpdateIndexSettings(props.connectionId, props.index, parsed as Record<string, unknown>);
toast(t("meilisearch.settingsSaved")); toast(t("meilisearch.settingsSaved"));
settingsValue.value = parsed as Record<string, any>; settingsValue.value = parsed as MeilisearchIndexSettings;
settingsText.value = JSON.stringify(parsed, null, 2); settingsText.value = JSON.stringify(parsed, null, 2);
editMode.value = false; editMode.value = false;
} catch (e: any) { } catch (e: any) {
@@ -383,6 +383,7 @@ function createBridge() {
// bridge; the backend owns EXPLAIN generation, the timeout, and the plan cap. // bridge; the backend owns EXPLAIN generation, the timeout, and the plan cap.
getPlanCapabilities: (connectionId) => api.getPluginPlanCapabilities(connectionId), getPlanCapabilities: (connectionId) => api.getPluginPlanCapabilities(connectionId),
explainPlan: (request) => api.getPluginEstimatedPlan(request), explainPlan: (request) => api.getPluginEstimatedPlan(request),
getTableMetadata: (context) => api.getPluginTableMetadata(context),
closeTab: () => emit("closeTab"), closeTab: () => emit("closeTab"),
saveFile: (_pluginId, request, data) => savePluginFile(request, data), saveFile: (_pluginId, request, data) => savePluginFile(request, data),
downloadFile: isTauriRuntime() ? downloadPluginFile : undefined, downloadFile: isTauriRuntime() ? downloadPluginFile : undefined,
+1
View File
@@ -214,6 +214,7 @@ export const getObjectSource = forward("getObjectSource");
export const getEventInfo = forward("getEventInfo"); export const getEventInfo = forward("getEventInfo");
export const getCustomTypeDetails = forward("getCustomTypeDetails"); export const getCustomTypeDetails = forward("getCustomTypeDetails");
export const getColumns = forward("getColumns"); export const getColumns = forward("getColumns");
export const getPluginTableMetadata = forward("getPluginTableMetadata");
export const getAllColumns = forward("getAllColumns"); export const getAllColumns = forward("getAllColumns");
export const getSqlServerColumnMetadata = forward("getSqlServerColumnMetadata"); export const getSqlServerColumnMetadata = forward("getSqlServerColumnMetadata");
export const listDataTypes = forward("listDataTypes"); export const listDataTypes = forward("listDataTypes");
+9 -3
View File
@@ -190,10 +190,12 @@ import type {
PromptTemplate, PromptTemplate,
SshPromptResolution, SshPromptResolution,
MeilisearchIndexOverview, MeilisearchIndexOverview,
MeilisearchIndexSettings,
ElasticsearchIndexMetadataKind, ElasticsearchIndexMetadataKind,
ElasticsearchDeleteByQueryResult, ElasticsearchDeleteByQueryResult,
} from "@/lib/backend/tauri"; } from "@/lib/backend/tauri";
import type { QueryEditability } from "@/lib/sql/sqlAnalysis"; import type { QueryEditability } from "@/lib/sql/sqlAnalysis";
import type { PluginTableMetadata, PluginTableMetadataRequest } from "@/types/pluginSchemaMetadata";
import type { CsvQuoteMode } from "@/lib/export/csvQuoteMode"; import type { CsvQuoteMode } from "@/lib/export/csvQuoteMode";
import type { MigrationPreflight, MigrationReport } from "./migration"; import type { MigrationPreflight, MigrationReport } from "./migration";
export type { MigrationPreflight, MigrationReport } from "./migration"; export type { MigrationPreflight, MigrationReport } from "./migration";
@@ -1166,6 +1168,10 @@ export async function getColumns(connectionId: string, database: string, schema:
return get(`/api/schema/columns?${qs({ connection_id: connectionId, database, schema, table, catalog, client_session_id: clientSessionId })}`); return get(`/api/schema/columns?${qs({ connection_id: connectionId, database, schema, table, catalog, client_session_id: clientSessionId })}`);
} }
export async function getPluginTableMetadata(request: PluginTableMetadataRequest): Promise<PluginTableMetadata> {
return post("/api/plugin/table-metadata", request);
}
export async function getSqlServerColumnMetadata(connectionId: string, database: string, schema: string, table: string): Promise<SqlServerColumnMetadata[]> { export async function getSqlServerColumnMetadata(connectionId: string, database: string, schema: string, table: string): Promise<SqlServerColumnMetadata[]> {
return get(`/api/schema/sqlserver/column-metadata?${qs({ connection_id: connectionId, database, schema, table })}`); return get(`/api/schema/sqlserver/column-metadata?${qs({ connection_id: connectionId, database, schema, table })}`);
} }
@@ -4928,14 +4934,14 @@ export async function meilisearchGetDocument(connectionId: string, index: string
}); });
} }
export async function meilisearchGetIndexSettings(connectionId: string, index: string): Promise<Record<string, any>> { export async function meilisearchGetIndexSettings(connectionId: string, index: string): Promise<MeilisearchIndexSettings> {
return post("/api/document-store/meilisearch/settings/get", { return post("/api/document-store/meilisearch/settings/get", {
connectionId, connectionId,
index, index,
}); });
} }
export async function meilisearchUpdateIndexSettings(connectionId: string, index: string, settings: Record<string, any>): Promise<void> { export async function meilisearchUpdateIndexSettings(connectionId: string, index: string, settings: Record<string, unknown>): Promise<void> {
return post("/api/document-store/meilisearch/settings/update", { return post("/api/document-store/meilisearch/settings/update", {
connectionId, connectionId,
index, index,
@@ -4943,7 +4949,7 @@ export async function meilisearchUpdateIndexSettings(connectionId: string, index
}); });
} }
export async function meilisearchGetIndexStats(connectionId: string, index: string): Promise<{ numberOfDocuments: number; isIndexing: boolean; fieldDistribution: Record<string, number> } & Record<string, any>> { export async function meilisearchGetIndexStats(connectionId: string, index: string): Promise<{ numberOfDocuments: number; isIndexing: boolean; fieldDistribution: Record<string, number> } & Record<string, unknown>> {
return post("/api/document-store/meilisearch/stats", { return post("/api/document-store/meilisearch/stats", {
connectionId, connectionId,
index, index,
+16 -3
View File
@@ -24,6 +24,7 @@ import { collectBrowserSupportInfo } from "@/lib/app/supportInfo";
// Re-exported below so the HTTP transport shares one definition; imported here // Re-exported below so the HTTP transport shares one definition; imported here
// for this module's own signatures (a re-export does not bind local names). // for this module's own signatures (a re-export does not bind local names).
import type { PluginPlanCapabilities, PluginPlanRequest, PluginPlanResult } from "@/types/pluginPlan"; import type { PluginPlanCapabilities, PluginPlanRequest, PluginPlanResult } from "@/types/pluginPlan";
import type { PluginTableMetadata, PluginTableMetadataRequest } from "@/types/pluginSchemaMetadata";
function invoke<T>(command: string, args?: Record<string, unknown>): Promise<T> { function invoke<T>(command: string, args?: Record<string, unknown>): Promise<T> {
assertUpdateAllowsCommand(command); assertUpdateAllowsCommand(command);
@@ -832,6 +833,7 @@ export async function saveMaxRetries(maxRetries: number): Promise<void> {
export type { OpenTabsStatePayload, PersistedEditorGroup } from "@/lib/app/openTabsPersistence"; export type { OpenTabsStatePayload, PersistedEditorGroup } from "@/lib/app/openTabsPersistence";
/** Shared with `@/lib/plugins/pluginHostBridge`; re-exported so the HTTP transport reuses one definition. */ /** Shared with `@/lib/plugins/pluginHostBridge`; re-exported so the HTTP transport reuses one definition. */
export type { PluginPlanCapabilities, PluginPlanRequest, PluginPlanResult } from "@/types/pluginPlan"; export type { PluginPlanCapabilities, PluginPlanRequest, PluginPlanResult } from "@/types/pluginPlan";
export type { PluginColumnMetadata, PluginMetadataFieldAvailability, PluginMetadataFieldCapabilities, PluginTableMetadata, PluginTableMetadataRequest } from "@/types/pluginSchemaMetadata";
import type { OpenTabsStatePayload } from "@/lib/app/openTabsPersistence"; import type { OpenTabsStatePayload } from "@/lib/app/openTabsPersistence";
import { uuid } from "@/lib/common/utils"; import { uuid } from "@/lib/common/utils";
@@ -1540,6 +1542,10 @@ export async function getColumns(connectionId: string, database: string, schema:
}); });
} }
export async function getPluginTableMetadata(request: PluginTableMetadataRequest): Promise<PluginTableMetadata> {
return invoke("get_plugin_table_metadata", { request });
}
export async function getSqlServerColumnMetadata(connectionId: string, database: string, schema: string, table: string): Promise<SqlServerColumnMetadata[]> { export async function getSqlServerColumnMetadata(connectionId: string, database: string, schema: string, table: string): Promise<SqlServerColumnMetadata[]> {
return invoke("get_sqlserver_column_metadata", { return invoke("get_sqlserver_column_metadata", {
connectionId, connectionId,
@@ -4765,14 +4771,14 @@ export async function meilisearchGetDocument(connectionId: string, index: string
}); });
} }
export async function meilisearchGetIndexSettings(connectionId: string, index: string): Promise<Record<string, any>> { export async function meilisearchGetIndexSettings(connectionId: string, index: string): Promise<MeilisearchIndexSettings> {
return invoke("meilisearch_get_index_settings", { return invoke("meilisearch_get_index_settings", {
connectionId, connectionId,
index, index,
}); });
} }
export async function meilisearchUpdateIndexSettings(connectionId: string, index: string, settings: Record<string, any>): Promise<void> { export async function meilisearchUpdateIndexSettings(connectionId: string, index: string, settings: Record<string, unknown>): Promise<void> {
return invoke("meilisearch_update_index_settings", { return invoke("meilisearch_update_index_settings", {
connectionId, connectionId,
index, index,
@@ -4780,13 +4786,20 @@ export async function meilisearchUpdateIndexSettings(connectionId: string, index
}); });
} }
export async function meilisearchGetIndexStats(connectionId: string, index: string): Promise<{ numberOfDocuments: number; isIndexing: boolean; fieldDistribution: Record<string, number> } & Record<string, any>> { export async function meilisearchGetIndexStats(connectionId: string, index: string): Promise<{ numberOfDocuments: number; isIndexing: boolean; fieldDistribution: Record<string, number> } & Record<string, unknown>> {
return invoke("meilisearch_get_index_stats", { return invoke("meilisearch_get_index_stats", {
connectionId, connectionId,
index, index,
}); });
} }
export interface MeilisearchIndexSettings {
[key: string]: unknown;
pagination?: {
maxTotalHits?: number;
};
}
export interface MeilisearchIndexOverview { export interface MeilisearchIndexOverview {
uid: string; uid: string;
primaryKey: string | null; primaryKey: string | null;
+101
View File
@@ -567,6 +567,95 @@ describe("PluginHostBridge", () => {
expect(messages[2]).toMatchObject({ id: "legacy", error: "Host plan API is unavailable" }); expect(messages[2]).toMatchObject({ id: "legacy", error: "Host plan API is unavailable" });
}); });
it("requires host.schema:read, normalizes table identity, and serves narrow metadata", async () => {
const messages: unknown[] = [];
const target = { postMessage: (message: unknown) => messages.push(message) } as unknown as Window;
const getTableMetadata = vi.fn().mockResolvedValue({
columns: [{ name: "id", dataType: "integer", nullable: false }],
fieldCapabilities: { length: "unknown", precision: "unknown", scale: "unknown", default: "unknown" },
});
const base = { invoke: vi.fn(), notify: vi.fn(), sendBinary: vi.fn(), readAsset: vi.fn(), getTableMetadata };
const denied = new PluginHostBridge(plugin(), workbench, {}, () => target, base);
planCall(denied, target, "host.getTableMetadata", { connectionId: "c1", table: "users" }, "denied");
await vi.waitFor(() => expect(messages).toHaveLength(1));
expect(messages[0]).toMatchObject({ id: "denied", error: "Plugin has not declared permission 'host.schema:read'" });
expect(getTableMetadata).not.toHaveBeenCalled();
const allowed = new PluginHostBridge(plugin(["host.schema:read"]), workbench, {}, () => target, base);
allowed.sendInit();
planCall(allowed, target, "host.getTableMetadata", { connectionId: " c1 ", database: " app ", schema: " ", table: " users " }, "metadata");
await vi.waitFor(() => expect(messages).toHaveLength(3));
expect(getTableMetadata).toHaveBeenCalledWith({ connectionId: "c1", database: "app", table: "users" });
expect(messages[2]).toMatchObject({ id: "metadata", result: expect.objectContaining({ columns: expect.any(Array) }) });
});
it("rejects malformed table metadata contexts and advertises the adapter capability", async () => {
const messages: any[] = [];
const target = { postMessage: (message: unknown) => messages.push(message) } as unknown as Window;
const getTableMetadata = vi.fn();
const bridge = new PluginHostBridge(plugin(["host.schema:read"]), workbench, {}, () => target, {
invoke: vi.fn(),
notify: vi.fn(),
sendBinary: vi.fn(),
readAsset: vi.fn(),
getTableMetadata,
});
bridge.sendInit();
expect(messages[0].capabilities).toMatchObject({ schemaMetadataApi: true });
const cases: [string, unknown, string][] = [
["missing-connection", { table: "users" }, "connectionId"],
["blank-connection", { connectionId: " ", table: "users" }, "connectionId"],
["missing-table", { connectionId: "c1" }, "table"],
["table-type", { connectionId: "c1", table: 7 }, "table"],
["identifier-long", { connectionId: "c1", table: "x".repeat(257) }, "table"],
["scope-type", { connectionId: "c1", table: "users", schema: 1 }, "schema"],
];
for (const [id, params] of cases) planCall(bridge, target, "host.getTableMetadata", params, id);
planCall(bridge, target, "host.getTableMetadata", "not an object", "params-object");
await vi.waitFor(() => expect(messages).toHaveLength(cases.length + 2));
cases.forEach(([id, , expected], index) => {
expect(messages[index + 1]).toMatchObject({ id });
expect(messages[index + 1].error).toContain(expected);
});
expect(messages[messages.length - 1]).toMatchObject({ id: "params-object", error: "host.getTableMetadata params must be an object" });
expect(getTableMetadata).not.toHaveBeenCalled();
const legacyMessages: any[] = [];
const legacyTarget = { postMessage: (message: unknown) => legacyMessages.push(message) } as unknown as Window;
const legacy = new PluginHostBridge(plugin(["host.schema:read"]), workbench, {}, () => legacyTarget, {
invoke: vi.fn(),
notify: vi.fn(),
sendBinary: vi.fn(),
readAsset: vi.fn(),
});
legacy.sendInit();
expect(legacyMessages[0].capabilities).toMatchObject({ schemaMetadataApi: false });
planCall(legacy, legacyTarget, "host.getTableMetadata", { connectionId: "c1", table: "users" }, "legacy");
await vi.waitFor(() => expect(legacyMessages).toHaveLength(2));
expect(legacyMessages[1]).toMatchObject({ id: "legacy", error: "Host schema metadata API is unavailable" });
});
it.each(["Connection session is not open for the requested database", "Query canceled", "metadata provider denied", "DBX metadata pool is busy; please retry"])("forwards schema metadata failures without retrying: %s", async (error) => {
const messages: unknown[] = [];
const target = { postMessage: (message: unknown) => messages.push(message) } as unknown as Window;
const getTableMetadata = vi.fn().mockRejectedValue(new Error(error));
const bridge = new PluginHostBridge(plugin(["host.schema:read"]), workbench, {}, () => target, {
invoke: vi.fn(),
notify: vi.fn(),
sendBinary: vi.fn(),
readAsset: vi.fn(),
getTableMetadata,
});
planCall(bridge, target, "host.getTableMetadata", { connectionId: "c1", table: "users" }, "failure");
await vi.waitFor(() => expect(messages).toHaveLength(1));
expect(messages[0]).toMatchObject({ id: "failure", error });
expect(getTableMetadata).toHaveBeenCalledTimes(1);
});
it("opens only the owning plugin filesystem with explicit permission", async () => { it("opens only the owning plugin filesystem with explicit permission", async () => {
const messages: unknown[] = []; const messages: unknown[] = [];
const target = { postMessage: (message: unknown) => messages.push(message) } as unknown as Window; const target = { postMessage: (message: unknown) => messages.push(message) } as unknown as Window;
@@ -1036,6 +1125,7 @@ describe("plugin SDK source", () => {
invoke: (method: string, params?: unknown, options?: { timeoutMs?: number }) => Promise<unknown>; invoke: (method: string, params?: unknown, options?: { timeoutMs?: number }) => Promise<unknown>;
getPlanCapabilities: (connectionId: string) => Promise<unknown>; getPlanCapabilities: (connectionId: string) => Promise<unknown>;
explainPlan: (request: unknown) => Promise<unknown>; explainPlan: (request: unknown) => Promise<unknown>;
getTableMetadata: (context: unknown) => Promise<unknown>;
}; };
} }
@@ -1123,6 +1213,17 @@ describe("plugin SDK source", () => {
expect(requests[1].params).toEqual({ connectionId: "c1", sql: "SELECT 1", mode: "estimated" }); expect(requests[1].params).toEqual({ connectionId: "c1", sql: "SELECT 1", mode: "estimated" });
}); });
it("exposes read-only table metadata through the SDK request surface", () => {
const posted: unknown[] = [];
const { dbxPlugin } = loadSdk(posted);
void dbxPlugin!.getTableMetadata({ connectionId: "c1", database: "app", table: "users" });
const request = firstRequest(posted);
expect(request.method).toBe("host.getTableMetadata");
expect(request.params).toEqual({ connectionId: "c1", database: "app", table: "users" });
});
it("forwards fileTransfer requests to the host api", async () => { it("forwards fileTransfer requests to the host api", async () => {
const messages: unknown[] = []; const messages: unknown[] = [];
const target = { postMessage: (message: unknown) => messages.push(message) } as unknown as Window; const target = { postMessage: (message: unknown) => messages.push(message) } as unknown as Window;
@@ -2,6 +2,7 @@ import type { InstalledPlugin, PluginBinaryEvent, PluginEvent, PluginUiAssetPayl
import { clonePluginData, snapshotPluginWorkbenchContext } from "./pluginData"; 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 { 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 { 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 PLUGIN_MESSAGE_SOURCE = "dbx-plugin";
const HOST_MESSAGE_SOURCE = "dbx-host"; const HOST_MESSAGE_SOURCE = "dbx-host";
@@ -109,6 +110,8 @@ export interface PluginHostBridgeApi {
* generates and owns the EXPLAIN statement; the plugin cannot pass one. * generates and owns the EXPLAIN statement; the plugin cannot pass one.
*/ */
explainPlan?(request: PluginPlanRequest): Promise<PluginPlanResult>; 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; closeTab?(): Promise<void> | void;
/** Persist plugin bytes through the host's native save dialog. Resolves null when the user cancels. */ /** 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>; saveFile?(pluginId: string, request: PluginSaveFileRequest, data: Uint8Array): Promise<PluginSaveFileResult | null>;
@@ -249,6 +252,7 @@ export class PluginHostBridge {
capabilities: { capabilities: {
downloadFile: !!this.api.downloadFile, downloadFile: !!this.api.downloadFile,
planApi: !!this.api.getPlanCapabilities && !!this.api.explainPlan, planApi: !!this.api.getPlanCapabilities && !!this.api.explainPlan,
[PLUGIN_SCHEMA_METADATA_CAPABILITY]: !!this.api.getTableMetadata,
storage: !!this.api.storageGet && !!this.api.storageSet && !!this.api.storageDelete, storage: !!this.api.storageGet && !!this.api.storageSet && !!this.api.storageDelete,
ai: !!this.api.openAiConversation, ai: !!this.api.openAiConversation,
}, },
@@ -399,6 +403,11 @@ export class PluginHostBridge {
if (!this.api.explainPlan) throw new Error("Host plan API is unavailable"); if (!this.api.explainPlan) throw new Error("Host plan API is unavailable");
return this.api.explainPlan(requirePluginPlanRequest(requireRecord(params, "host.explainPlan params"))); 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") { if (method === "host.saveFile") {
const input = isRecord(params) ? params : {}; const input = isRecord(params) ? params : {};
// The sandboxed iframe cannot trigger downloads (WKWebView cancels blob // 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". // its intent, and the host refuses anything other than "estimated".
getPlanCapabilities: (connectionId) => request('host.getPlanCapabilities', { connectionId }), getPlanCapabilities: (connectionId) => request('host.getPlanCapabilities', { connectionId }),
explainPlan: (planRequest) => request('host.explainPlan', planRequest), 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) => { saveFile: (options = {}, data) => {
if (data === undefined) return request('host.saveFile', options); if (data === undefined) return request('host.saveFile', options);
if (typeof data === 'string') return request('host.saveFile', { ...(options || {}), dataBase64: data }); 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; 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 * 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 * the only accepted shape is the caller's own SQL plus a connection reference
@@ -0,0 +1,47 @@
/**
* Read-only Plugin Host schema metadata contract (#9917).
*
* The request reuses the canonical `PluginTableContext` from the table tree;
* this file only defines the narrow response returned by the host. It does not
* expose DBX's internal `ColumnInfo`, comments, keys, credentials or SQL.
*/
import type { PluginTableContext } from "@/types/database";
export type { PluginTableContext } from "@/types/database";
/** Permission required by `host.getTableMetadata`. */
export const PLUGIN_SCHEMA_METADATA_PERMISSION = "host.schema:read";
/** Capability advertised by the bridge when the backend adapter is present. */
export const PLUGIN_SCHEMA_METADATA_CAPABILITY = "schemaMetadataApi";
/** Mirrors the Rust-side identifier bound for the plugin metadata request. */
export const MAX_PLUGIN_SCHEMA_METADATA_NAME_CHARS = 256;
export type PluginMetadataFieldAvailability = "supported" | "unsupported" | "unknown";
export interface PluginTableMetadata {
columns: PluginColumnMetadata[];
/** Conservative provider provenance for optional structured fields. */
fieldCapabilities: PluginMetadataFieldCapabilities;
}
export interface PluginColumnMetadata {
name: string;
dataType: string;
nullable: boolean;
length?: number | null;
precision?: number | null;
scale?: number | null;
default?: string | null;
}
export interface PluginMetadataFieldCapabilities {
length: PluginMetadataFieldAvailability;
precision: PluginMetadataFieldAvailability;
scale: PluginMetadataFieldAvailability;
default: PluginMetadataFieldAvailability;
}
export type PluginTableMetadataRequest = PluginTableContext;
+27
View File
@@ -139,6 +139,33 @@ pub async fn run_agent_loop(
max_tokens: Option<u32>, max_tokens: Option<u32>,
task_contract: Option<&AiTaskContract>, task_contract: Option<&AiTaskContract>,
is_agent_mode: bool, is_agent_mode: bool,
) -> Result<String, String> {
run_agent_loop_inner(
config,
system_prompt,
messages,
agent_ctx,
on_event,
cancelled,
max_tokens,
task_contract,
is_agent_mode,
)
.boxed()
.await
}
#[allow(clippy::too_many_arguments)]
async fn run_agent_loop_inner(
config: &AiConfig,
system_prompt: &str,
messages: &[AiMessage],
agent_ctx: &AgentLoopContext,
on_event: impl Fn(AgentEvent) + Send + Sync + Clone + 'static,
cancelled: &Notify,
max_tokens: Option<u32>,
task_contract: Option<&AiTaskContract>,
is_agent_mode: bool,
) -> Result<String, String> { ) -> Result<String, String> {
let contract_system_prompt = augment_system_prompt_with_task_contract(system_prompt, task_contract, is_agent_mode); let contract_system_prompt = augment_system_prompt_with_task_contract(system_prompt, task_contract, is_agent_mode);
let system_prompt = contract_system_prompt.as_str(); let system_prompt = contract_system_prompt.as_str();
+49
View File
@@ -1406,6 +1406,55 @@ impl AppState {
self.connections.read().await.keys().any(|key| pool_key_belongs_to_connection(key, connection_id)) self.connections.read().await.keys().any(|key| pool_key_belongs_to_connection(key, connection_id))
} }
/// Find an already-registered metadata/workload pool for a metadata read.
/// Unlike `get_or_create_metadata_pool_for_session`, this is a pure lookup:
/// it never validates credentials, starts an agent, or opens a transport.
pub(crate) async fn existing_metadata_pool_key_for_session(
&self,
connection_id: &str,
database: Option<&str>,
client_session_id: Option<&str>,
) -> Option<String> {
let config = {
let configs = self.configs.read().await;
configs.get(connection_id).cloned()
}?;
let pool_database = metadata_pool_database(Some(&config), database);
let mut base_pool_keys =
vec![base_pool_key_for_with_catalog(Some(config.db_type), connection_id, pool_database, None, false)];
// MongoDB document operations use a connection-level pool and send the
// requested database in the command. A host connection can therefore
// legitimately be registered either under the selected database or
// under the connection-level key; probe both without creating either.
if config.db_type == DatabaseType::MongoDb {
let connection_pool_key =
base_pool_key_for_with_catalog(Some(config.db_type), connection_id, None, None, false);
if !base_pool_keys.contains(&connection_pool_key) {
base_pool_keys.push(connection_pool_key);
}
}
let connections = self.connections.read().await;
base_pool_keys
.into_iter()
.flat_map(|base_pool_key| {
[
pool_key_for_session_role(
Some(&config),
base_pool_key.clone(),
client_session_id,
AgentSessionRole::Metadata,
),
pool_key_for_session_role(
Some(&config),
base_pool_key,
client_session_id,
AgentSessionRole::Workload,
),
]
})
.find(|pool_key| connections.pools.contains_key(pool_key))
}
/// Mutate the registry atomically. The callback is deliberately /// Mutate the registry atomically. The callback is deliberately
/// synchronous; asynchronous cleanup must use values returned from it. /// synchronous; asynchronous cleanup must use values returned from it.
pub async fn update_connection_pools<R>(&self, update: impl FnOnce(&mut ConnectionPoolRegistry) -> R) -> R { pub async fn update_connection_pools<R>(&self, update: impl FnOnce(&mut ConnectionPoolRegistry) -> R) -> R {
@@ -1446,6 +1446,7 @@ mod tests {
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
metadata_capabilities: None,
} }
} }
@@ -2399,6 +2400,7 @@ mod tests {
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
metadata_capabilities: None,
}), }),
target: Some(ColumnInfo { target: Some(ColumnInfo {
name: "large_val".to_string(), name: "large_val".to_string(),
@@ -2416,6 +2418,7 @@ mod tests {
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
metadata_capabilities: None,
}), }),
changes: vec!["data_type BIGINT → INT".to_string()], changes: vec!["data_type BIGINT → INT".to_string()],
add_position: None, add_position: None,
+14 -6
View File
@@ -232,15 +232,12 @@ pub async fn mongo_server_version_core(
} }
} }
pub async fn mongo_run_command_core( pub(crate) async fn mongo_run_command_with_existing_pool(
state: &AppState, pool: &PoolKind,
connection_id: &str,
database: &str, database: &str,
command_json: &str, command_json: &str,
) -> Result<MongoDocumentResult, String> { ) -> Result<MongoDocumentResult, String> {
ensure_document_pool(state, connection_id).await?; match pool {
let pool = state.pool_handle(connection_id).await.ok_or("Not found")?;
match &pool {
PoolKind::MongoDb(client) => mongo_driver::run_command(client, database, command_json).await, PoolKind::MongoDb(client) => mongo_driver::run_command(client, database, command_json).await,
PoolKind::Agent(client) => { PoolKind::Agent(client) => {
let mut client = client.lock().await; let mut client = client.lock().await;
@@ -261,6 +258,17 @@ pub async fn mongo_run_command_core(
} }
} }
pub async fn mongo_run_command_core(
state: &AppState,
connection_id: &str,
database: &str,
command_json: &str,
) -> Result<MongoDocumentResult, String> {
ensure_document_pool(state, connection_id).await?;
let pool = state.pool_handle(connection_id).await.ok_or("Not found")?;
mongo_run_command_with_existing_pool(&pool, database, command_json).await
}
pub async fn mongo_show_databases_core(state: &AppState, connection_id: &str) -> Result<MongoDocumentResult, String> { pub async fn mongo_show_databases_core(state: &AppState, connection_id: &str) -> Result<MongoDocumentResult, String> {
mongo_run_command_core(state, connection_id, MONGO_SHOW_DATABASES_DATABASE, MONGO_SHOW_DATABASES_COMMAND_JSON).await mongo_run_command_core(state, connection_id, MONGO_SHOW_DATABASES_DATABASE, MONGO_SHOW_DATABASES_COMMAND_JSON).await
} }
+121 -24
View File
@@ -19,6 +19,9 @@ use std::time::{Duration, Instant};
mod kingbase; mod kingbase;
mod mongodb_columns; mod mongodb_columns;
pub mod plugin_metadata;
#[cfg(test)]
mod plugin_metadata_tests;
macro_rules! extract_pool { macro_rules! extract_pool {
($pool:expr, $variant:ident) => { ($pool:expr, $variant:ident) => {
@@ -6859,6 +6862,22 @@ async fn retry_metadata_connection_for_session<T, F, Fut>(
connection_id: &str, connection_id: &str,
database: Option<&str>, database: Option<&str>,
client_session_id: Option<&str>, client_session_id: Option<&str>,
operation: F,
) -> Result<T, String>
where
F: FnMut() -> Fut,
Fut: Future<Output = Result<T, String>>,
{
Box::pin(run_metadata_connection_for_session(state, connection_id, database, client_session_id, true, operation))
.await
}
async fn run_metadata_connection_for_session<T, F, Fut>(
state: &AppState,
connection_id: &str,
database: Option<&str>,
client_session_id: Option<&str>,
allow_recovery: bool,
mut operation: F, mut operation: F,
) -> Result<T, String> ) -> Result<T, String>
where where
@@ -6875,6 +6894,9 @@ where
} }
None => None, None => None,
}; };
if !allow_recovery {
return operation().await;
}
let mut retried = false; let mut retried = false;
let mut missing_pool_retry = false; let mut missing_pool_retry = false;
loop { loop {
@@ -7083,21 +7105,77 @@ async fn get_columns_core_for_session_inner(
table: &str, table: &str,
client_session_id: Option<&str>, client_session_id: Option<&str>,
use_client_session_context: bool, use_client_session_context: bool,
) -> Result<Vec<db::ColumnInfo>, String> {
get_columns_core_for_session_inner_with_pool(
state,
connection_id,
database,
schema,
table,
client_session_id,
use_client_session_context,
None,
true,
)
.await
}
async fn get_columns_core_for_existing_pool(
state: &AppState,
connection_id: &str,
database: &str,
schema: &str,
table: &str,
pool_key: &str,
) -> Result<Vec<db::ColumnInfo>, String> {
get_columns_core_for_session_inner_with_pool(
state,
connection_id,
database,
schema,
table,
None,
true,
Some(pool_key),
false,
)
.await
}
async fn get_columns_core_for_session_inner_with_pool(
state: &AppState,
connection_id: &str,
database: &str,
schema: &str,
table: &str,
client_session_id: Option<&str>,
use_client_session_context: bool,
existing_pool_key: Option<&str>,
allow_recovery: bool,
) -> Result<Vec<db::ColumnInfo>, String> { ) -> Result<Vec<db::ColumnInfo>, String> {
let context_session_id = if use_client_session_context { client_session_id } else { None }; let context_session_id = if use_client_session_context { client_session_id } else { None };
retry_metadata_connection_for_session(state, connection_id, Some(database), client_session_id, || async { let existing_pool_key = existing_pool_key.map(str::to_owned);
let pool_key = state let operation = || async {
.get_or_create_metadata_pool_for_session(connection_id, Some(database), client_session_id) let pool_key = if let Some(pool_key) = existing_pool_key.as_deref() {
.await?; pool_key.to_string()
} else {
state.get_or_create_metadata_pool_for_session(connection_id, Some(database), client_session_id).await?
};
let db_config = connection_config(state, connection_id).await; let db_config = connection_config(state, connection_id).await;
if db_config.as_ref().is_some_and(|config| config.db_type == DatabaseType::MongoDb) {
let pool_handle = state.pool_handle(&pool_key).await.ok_or("Pool not found")?;
return mongodb_columns::get_columns_from_existing_pool(&pool_handle, database, table).await;
}
{ {
let pool_handle = state.pool_handle(&pool_key).await; let pool_handle = state.pool_handle(&pool_key).await;
if let Some(PoolKind::ExternalDriver { config, session, .. }) = pool_handle.as_ref() { if let Some(PoolKind::ExternalDriver { config, session, .. }) = pool_handle.as_ref() {
let config = config.clone(); let config = config.clone();
let session = session.clone(); let session = session.clone();
if uses_presto_like_information_schema_tables(&config.db_type) { if uses_presto_like_information_schema_tables(&config.db_type) {
return external_driver_presto_like_columns(session, config.as_ref(), database, schema, table).await; return external_driver_presto_like_columns(session, config.as_ref(), database, schema, table)
.await;
} }
let query_oracle_columns_first = let query_oracle_columns_first =
should_query_oracle_columns_via_sql_first(&config.db_type, context_session_id); should_query_oracle_columns_via_sql_first(&config.db_type, context_session_id);
@@ -7168,25 +7246,29 @@ async fn get_columns_core_for_session_inner(
let database = database.to_string(); let database = database.to_string();
let schema = schema.to_string(); let schema = schema.to_string();
let table = table.to_string(); let table = table.to_string();
return client.list_columns(database, schema, table).await; return client.list_columns(database, schema, table).await;
} }
if let Some(client) = extract_pool!(pool_handle.as_ref(), ClickHouse) { if let Some(client) = extract_pool!(pool_handle.as_ref(), ClickHouse) {
return db::clickhouse_driver::get_columns(&client, clickhouse_metadata_database(database, schema), table) return db::clickhouse_driver::get_columns(
.await &client,
.map(deduplicate_column_infos); clickhouse_metadata_database(database, schema),
table,
)
.await
.map(deduplicate_column_infos);
} }
if let Some(client) = extract_pool!(pool_handle.as_ref(), InfluxDb) { if let Some(client) = extract_pool!(pool_handle.as_ref(), InfluxDb) {
return db::influxdb_driver::get_columns(&client, database, table).await.map(deduplicate_column_infos); return db::influxdb_driver::get_columns(&client, database, table).await.map(deduplicate_column_infos);
} }
if let Some(client) = extract_pool!(pool_handle.as_ref(), InfluxDb3) { if let Some(client) = extract_pool!(pool_handle.as_ref(), InfluxDb3) {
return db::influxdb3_driver::get_columns(&client, database, table).await.map(deduplicate_column_infos); return db::influxdb3_driver::get_columns(&client, database, table).await.map(deduplicate_column_infos);
} }
if let Some(client) = extract_pool!(pool_handle.as_ref(), VictoriaMetrics) { if let Some(client) = extract_pool!(pool_handle.as_ref(), VictoriaMetrics) {
return db::victoriametrics_driver::get_columns(&client, table).await.map(deduplicate_column_infos); return db::victoriametrics_driver::get_columns(&client, table).await.map(deduplicate_column_infos);
} }
if let Some(linked) = crate::sql_dialect::parse_sqlserver_linked_schema_ref(schema) { if let Some(linked) = crate::sql_dialect::parse_sqlserver_linked_schema_ref(schema) {
if let Some(client) = extract_pool!(pool_handle.as_ref(), SqlServer) { if let Some(client) = extract_pool!(pool_handle.as_ref(), SqlServer) {
let mut client = lock_sqlserver_metadata_client(&client).await?; let mut client = lock_sqlserver_metadata_client(&client).await?;
return db::sqlserver::get_linked_server_columns( return db::sqlserver::get_linked_server_columns(
&mut client, &mut client,
&linked.server, &linked.server,
@@ -7201,10 +7283,10 @@ async fn get_columns_core_for_session_inner(
try_sqlserver!(pool_handle, get_columns, schema, table); try_sqlserver!(pool_handle, get_columns, schema, table);
if let Some(client) = extract_pool!(pool_handle.as_ref(), Agent) { if let Some(client) = extract_pool!(pool_handle.as_ref(), Agent) {
let fallback_config = db_config.clone(); let fallback_config = db_config.clone();
let mut client = client.lock().await; let mut client = client.lock().await;
let oracle_sql_config = fallback_config.as_ref().filter(|config| { let oracle_sql_config = fallback_config
should_query_oracle_columns_via_sql_first(&config.db_type, context_session_id) .as_ref()
}); .filter(|config| should_query_oracle_columns_via_sql_first(&config.db_type, context_session_id));
let query_oracle_columns_first = oracle_sql_config.is_some(); let query_oracle_columns_first = oracle_sql_config.is_some();
if let Some(config) = oracle_sql_config { if let Some(config) = oracle_sql_config {
match oracle_columns_via_sql( match oracle_columns_via_sql(
@@ -7252,7 +7334,9 @@ async fn get_columns_core_for_session_inner(
) )
.await .await
{ {
Ok(fallback_columns) if !fallback_columns.is_empty() => return Ok(fallback_columns), Ok(fallback_columns) if !fallback_columns.is_empty() => {
return Ok(fallback_columns)
}
Ok(_) => {} Ok(_) => {}
Err(error) => { Err(error) => {
log::warn!( log::warn!(
@@ -7266,6 +7350,8 @@ async fn get_columns_core_for_session_inner(
} }
} }
} }
}
if let Some(config) = fallback_config.as_ref().filter(|_| existing_pool_key.is_none()) {
match native_postgres_metadata_pool(state, connection_id, database, config).await { match native_postgres_metadata_pool(state, connection_id, database, config).await {
Ok(Some(pool)) => { Ok(Some(pool)) => {
return db::postgres::get_columns(&pool, schema, table) return db::postgres::get_columns(&pool, schema, table)
@@ -7288,7 +7374,7 @@ async fn get_columns_core_for_session_inner(
return Ok(deduplicate_column_infos(columns)); return Ok(deduplicate_column_infos(columns));
} }
Err(agent_error) => { Err(agent_error) => {
if let Some(config) = fallback_config.as_ref() { if let Some(config) = fallback_config.as_ref().filter(|_| existing_pool_key.is_none()) {
if let Some(pool) = if let Some(pool) =
native_postgres_metadata_pool(state, connection_id, database, config).await? native_postgres_metadata_pool(state, connection_id, database, config).await?
{ {
@@ -7354,9 +7440,9 @@ async fn get_columns_core_for_session_inner(
PoolKind::Turso(client) => { PoolKind::Turso(client) => {
db::turso_driver::get_columns(client, schema, table).await.map(deduplicate_column_infos) db::turso_driver::get_columns(client, schema, table).await.map(deduplicate_column_infos)
} }
PoolKind::CloudflareD1(client) => db::cloudflare_d1_driver::get_columns(client, schema, table) PoolKind::CloudflareD1(client) => {
.await db::cloudflare_d1_driver::get_columns(client, schema, table).await.map(deduplicate_column_infos)
.map(deduplicate_column_infos), }
PoolKind::Elasticsearch(client) => { PoolKind::Elasticsearch(client) => {
db::elasticsearch_driver::get_columns(client, table).await.map(deduplicate_column_infos) db::elasticsearch_driver::get_columns(client, table).await.map(deduplicate_column_infos)
} }
@@ -7371,7 +7457,15 @@ async fn get_columns_core_for_session_inner(
} }
_ => Ok(vec![]), _ => Ok(vec![]),
} }
}) };
Box::pin(run_metadata_connection_for_session(
state,
connection_id,
Some(database),
client_session_id,
allow_recovery,
operation,
))
.await .await
} }
@@ -7413,6 +7507,9 @@ fn deduplicate_column_infos(columns: Vec<db::ColumnInfo>) -> Vec<db::ColumnInfo>
if existing.data_type.trim().is_empty() && !column.data_type.trim().is_empty() { if existing.data_type.trim().is_empty() && !column.data_type.trim().is_empty() {
existing.data_type = column.data_type; existing.data_type = column.data_type;
} }
if existing.metadata_capabilities != column.metadata_capabilities {
existing.metadata_capabilities = None;
}
} else { } else {
result.push(column); result.push(column);
} }
+31 -10
View File
@@ -3,28 +3,48 @@ use std::collections::{BTreeMap, BTreeSet};
use mongodb::bson::Bson; use mongodb::bson::Bson;
use serde_json::{json, Value}; use serde_json::{json, Value};
use crate::connection::AppState; use crate::connection::{AppState, PoolKind};
use crate::db::mongo_driver::MongoDocumentResult; use crate::db::mongo_driver::MongoDocumentResult;
use crate::db::ColumnInfo; use crate::db::ColumnInfo;
const SAMPLE_SIZE: usize = 100; const SAMPLE_SIZE: usize = 100;
const MAX_FIELDS: usize = 512; const MAX_FIELDS: usize = 512;
fn sample_command(collection: &str) -> Value {
json!({
"find": collection,
"filter": {},
"limit": SAMPLE_SIZE,
"batchSize": SAMPLE_SIZE,
"singleBatch": true,
"maxTimeMS": 5000,
})
}
pub(super) async fn get_columns( pub(super) async fn get_columns(
state: &AppState, state: &AppState,
connection_id: &str, connection_id: &str,
database: &str, database: &str,
collection: &str, collection: &str,
) -> Result<Vec<ColumnInfo>, String> { ) -> Result<Vec<ColumnInfo>, String> {
let command = json!({ let result = crate::mongo_ops::mongo_run_command_core(
"find": collection, state,
"filter": {}, connection_id,
"limit": SAMPLE_SIZE, database,
"batchSize": SAMPLE_SIZE, &sample_command(collection).to_string(),
"singleBatch": true, )
"maxTimeMS": 5000, .await?;
}); columns_from_sample(&result)
let result = crate::mongo_ops::mongo_run_command_core(state, connection_id, database, &command.to_string()).await?; }
pub(super) async fn get_columns_from_existing_pool(
pool: &PoolKind,
database: &str,
collection: &str,
) -> Result<Vec<ColumnInfo>, String> {
let result =
crate::mongo_ops::mongo_run_command_with_existing_pool(pool, database, &sample_command(collection).to_string())
.await?;
columns_from_sample(&result) columns_from_sample(&result)
} }
@@ -68,6 +88,7 @@ fn columns_from_sample(result: &MongoDocumentResult) -> Result<Vec<ColumnInfo>,
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
metadata_capabilities: None,
}) })
.collect()) .collect())
} }
@@ -0,0 +1,287 @@
//! Narrow, read-only schema metadata exposed through the plugin Host API.
//!
//! The request is the wire representation of the desktop `PluginTableContext`:
//! it carries table identity only, never a connection config or credential. The
//! implementation deliberately enters the existing schema abstraction instead
//! of issuing driver-specific metadata SQL from the plugin layer.
use serde::{Deserialize, Serialize};
use crate::connection::AppState;
use crate::db;
use crate::types::ColumnMetadataCapabilities;
pub const MAX_PLUGIN_SCHEMA_METADATA_NAME_CHARS: usize = 256;
pub const CONNECTION_NOT_OPEN_ERROR: &str = "Connection is not open";
pub const TABLE_METADATA_SESSION_NOT_OPEN_ERROR: &str = "Connection session is not open for the requested database";
/// The Rust wire DTO intentionally mirrors the public TypeScript
/// `PluginTableContext` field-for-field. It is not a second table identity
/// model; it is the camelCase JSON boundary used by Tauri and Web transports.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PluginTableContext {
pub connection_id: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub database: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub schema: Option<String>,
pub table: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PluginTableMetadata {
pub columns: Vec<PluginColumnMetadata>,
/// Reports whether structured optional fields are exposed by the provider
/// path. `unknown` is deliberate when an external provider gives DBX no
/// provenance; the host never guesses from a database type.
pub field_capabilities: PluginMetadataFieldCapabilities,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PluginColumnMetadata {
pub name: String,
pub data_type: String,
pub nullable: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub length: Option<i32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub precision: Option<i32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub scale: Option<i32>,
#[serde(rename = "default", default, skip_serializing_if = "Option::is_none")]
pub default_value: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct PluginMetadataFieldCapabilities {
pub length: PluginMetadataFieldAvailability,
pub precision: PluginMetadataFieldAvailability,
pub scale: PluginMetadataFieldAvailability,
#[serde(rename = "default")]
pub default_value: PluginMetadataFieldAvailability,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum PluginMetadataFieldAvailability {
Supported,
Unsupported,
Unknown,
}
/// Resolve one table's columns through DBX's existing metadata subsystem.
///
/// The open-connection check is intentionally before `get_columns_core`: that
/// ordinary DBX path is allowed to create metadata pools for the application,
/// but a plugin request must not turn a saved configuration into an implicit
/// connection. A closed request returns without touching the pool registry.
pub async fn get_table_metadata(state: &AppState, context: PluginTableContext) -> Result<PluginTableMetadata, String> {
let context = validate_plugin_table_context(context)?;
let config = {
let configs = state.configs.read().await;
configs.get(&context.connection_id).cloned()
}
.ok_or_else(|| "Connection config not found".to_string())?;
if !state.is_connection_open(&context.connection_id).await {
return Err(CONNECTION_NOT_OPEN_ERROR.to_string());
}
// A table contribution may omit a scope when the selected database does
// not expose one. When the host already knows a saved/default scope, use
// that existing identity; otherwise the schema subsystem receives the
// same empty scope used by its normal metadata path.
let database = context.database.as_deref().or_else(|| config.effective_database()).unwrap_or_default();
let schema = context.schema.as_deref().or(config.default_schema.as_deref()).unwrap_or_default();
let pool_key = state
.existing_metadata_pool_key_for_session(&context.connection_id, Some(database), None)
.await
.ok_or_else(|| TABLE_METADATA_SESSION_NOT_OPEN_ERROR.to_string())?;
let columns = super::get_columns_core_for_existing_pool(
state,
&context.connection_id,
database,
schema,
&context.table,
&pool_key,
)
.await?;
if columns.is_empty() {
return Err("Table metadata provider returned no columns".to_string());
}
let field_capabilities = field_capabilities(&columns);
Ok(PluginTableMetadata { columns: columns.into_iter().map(map_column).collect(), field_capabilities })
}
fn validate_plugin_table_context(mut context: PluginTableContext) -> Result<PluginTableContext, String> {
context.connection_id = required_identifier(context.connection_id, "connectionId")?;
context.table = required_identifier(context.table, "table")?;
context.database = optional_identifier(context.database, "database")?;
context.schema = optional_identifier(context.schema, "schema")?;
Ok(context)
}
fn required_identifier(value: String, name: &str) -> Result<String, String> {
let value = value.trim();
if value.is_empty() {
return Err(format!("{name} must not be empty"));
}
if value.chars().count() > MAX_PLUGIN_SCHEMA_METADATA_NAME_CHARS {
return Err(format!("{name} must be at most {MAX_PLUGIN_SCHEMA_METADATA_NAME_CHARS} characters"));
}
Ok(value.to_string())
}
fn optional_identifier(value: Option<String>, name: &str) -> Result<Option<String>, String> {
let Some(value) = value else {
return Ok(None);
};
let value = value.trim();
if value.is_empty() {
return Ok(None);
}
if value.chars().count() > MAX_PLUGIN_SCHEMA_METADATA_NAME_CHARS {
return Err(format!("{name} must be at most {MAX_PLUGIN_SCHEMA_METADATA_NAME_CHARS} characters"));
}
Ok(Some(value.to_string()))
}
fn map_column(column: db::ColumnInfo) -> PluginColumnMetadata {
PluginColumnMetadata {
name: column.name,
data_type: column.data_type,
nullable: column.is_nullable,
length: column.character_maximum_length,
precision: column.numeric_precision,
scale: column.numeric_scale,
default_value: column.column_default,
}
}
fn field_capabilities(columns: &[db::ColumnInfo]) -> PluginMetadataFieldCapabilities {
PluginMetadataFieldCapabilities {
length: field_capability(columns, |capabilities| capabilities.length),
precision: field_capability(columns, |capabilities| capabilities.precision),
scale: field_capability(columns, |capabilities| capabilities.scale),
default_value: field_capability(columns, |capabilities| capabilities.default),
}
}
fn field_capability(
columns: &[db::ColumnInfo],
field: impl Fn(ColumnMetadataCapabilities) -> bool,
) -> PluginMetadataFieldAvailability {
let Some(first) = columns.first().and_then(|column| column.metadata_capabilities) else {
return PluginMetadataFieldAvailability::Unknown;
};
if columns.iter().all(|column| column.metadata_capabilities.is_some_and(|capabilities| capabilities == first)) {
if field(first) {
PluginMetadataFieldAvailability::Supported
} else {
PluginMetadataFieldAvailability::Unsupported
}
} else {
PluginMetadataFieldAvailability::Unknown
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::storage::Storage;
fn config() -> crate::models::connection::ConnectionConfig {
serde_json::from_value(serde_json::json!({
"id": "conn-1",
"name": "Connection",
"db_type": "postgres",
"host": "127.0.0.1",
"port": 5432,
"username": "user",
"password": "secret"
}))
.unwrap()
}
fn column(name: &str) -> db::ColumnInfo {
db::ColumnInfo {
name: name.to_string(),
data_type: "character varying".to_string(),
is_nullable: true,
column_default: None,
numeric_precision: None,
numeric_scale: None,
character_maximum_length: Some(64),
metadata_capabilities: Some(ColumnMetadataCapabilities::all_supported()),
..Default::default()
}
}
#[test]
fn maps_column_info_to_the_narrow_public_contract() {
let metadata = PluginTableMetadata {
columns: vec![map_column(column("name"))],
field_capabilities: field_capabilities(&[column("name")]),
};
let value = serde_json::to_value(metadata).unwrap();
assert_eq!(value["columns"][0]["name"], "name");
assert_eq!(value["columns"][0]["dataType"], "character varying");
assert_eq!(value["columns"][0]["nullable"], true);
assert_eq!(value["columns"][0]["length"], 64);
assert!(value["columns"][0].get("default").is_none());
assert!(value["columns"][0].get("comment").is_none());
assert_eq!(value["fieldCapabilities"]["length"], "supported");
}
#[test]
fn does_not_guess_capabilities_without_provider_provenance() {
let column = db::ColumnInfo { name: "id".to_string(), data_type: "integer".to_string(), ..Default::default() };
let capabilities = field_capabilities(&[column]);
assert_eq!(capabilities.length, PluginMetadataFieldAvailability::Unknown);
assert_eq!(capabilities.precision, PluginMetadataFieldAvailability::Unknown);
}
#[test]
fn preserves_unsupported_structured_fields_without_fabricating_values() {
let mut column_info = column("id");
column_info.character_maximum_length = None;
column_info.numeric_precision = None;
column_info.numeric_scale = None;
column_info.metadata_capabilities = Some(ColumnMetadataCapabilities::default_only());
let metadata = PluginTableMetadata {
columns: vec![map_column(column_info)],
field_capabilities: field_capabilities(&[db::ColumnInfo {
metadata_capabilities: Some(ColumnMetadataCapabilities::default_only()),
..column("id")
}]),
};
let value = serde_json::to_value(metadata).unwrap();
assert!(value["columns"][0].get("length").is_none());
assert_eq!(value["fieldCapabilities"]["length"], "unsupported");
assert_eq!(value["fieldCapabilities"]["default"], "supported");
}
#[tokio::test]
async fn saved_but_disconnected_context_is_rejected_without_creating_a_pool() {
let dir = tempfile::tempdir().unwrap();
let storage = Storage::open(&dir.path().join("storage.db")).await.unwrap();
let state = AppState::new_with_plugin_dir(storage, dir.path().join("plugins"));
let config = config();
state.configs.write().await.insert(config.id.clone(), config);
let context = PluginTableContext {
connection_id: "conn-1".to_string(),
database: Some("app".to_string()),
schema: Some("public".to_string()),
table: "users".to_string(),
};
let error = get_table_metadata(&state, context).await.unwrap_err();
assert_eq!(error, CONNECTION_NOT_OPEN_ERROR);
assert!(state.with_connection_pools(|pools| pools.is_empty()).await);
}
}
@@ -0,0 +1,276 @@
use super::plugin_metadata::{get_table_metadata, PluginTableContext, TABLE_METADATA_SESSION_NOT_OPEN_ERROR};
use super::{
get_columns_core_for_existing_pool, get_columns_core_for_session_inner, run_metadata_connection_for_session,
};
use crate::connection::{AppState, PoolKind, METADATA_POOL_ACQUIRE_TIMEOUT};
use crate::db::agent_driver::{AgentDriverClient, AgentLaunchSpec, AgentRuntimeClient};
use crate::models::connection::{ConnectionConfig, DatabaseType};
use crate::storage::Storage;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Arc;
use std::time::Duration;
async fn state(db_type: DatabaseType) -> (tempfile::TempDir, AppState) {
let dir = tempfile::tempdir().unwrap();
let storage = Storage::open(&dir.path().join("storage.db")).await.unwrap();
let state = AppState::new_with_plugin_and_agent_dir_and_app_version(
storage,
dir.path().join("plugins"),
dir.path().join("agents"),
"test",
);
let config: ConnectionConfig = serde_json::from_value(serde_json::json!({
"id": "conn",
"name": "Metadata test",
"db_type": db_type,
"host": "127.0.0.1",
"port": 5432,
"username": "user",
"password": "secret",
"database": "app",
"connect_timeout_secs": 1
}))
.unwrap();
state.configs.write().await.insert(config.id.clone(), config);
(dir, state)
}
fn context() -> PluginTableContext {
PluginTableContext {
connection_id: "conn".to_string(),
database: Some("app".to_string()),
schema: Some("public".to_string()),
table: "users".to_string(),
}
}
struct ScriptedAgent(Arc<AgentRuntimeClient>);
impl Drop for ScriptedAgent {
fn drop(&mut self) {
self.0.kill();
}
}
async fn scripted_agent(dir: &std::path::Path, response: serde_json::Value) -> ScriptedAgent {
let script = dir.join("metadata-agent.py");
std::fs::write(
&script,
r#"import json, pathlib, sys
response = json.loads(sys.argv[1])
calls = pathlib.Path(sys.argv[2])
print(json.dumps({'ready': True}), flush=True)
for line in sys.stdin:
request = json.loads(line)
method = request['method']
if method == 'handshake':
body = {'result': {'protocolVersion': 2, 'agentProtocolVersion': 2, 'capabilities': ['multi_session']}}
elif method == 'get_columns':
with calls.open('a') as output:
output.write(method + '\n')
body = response
else:
body = {'result': {}}
print(json.dumps({'jsonrpc': '2.0', 'id': request['id'], **body}), flush=True)
"#,
)
.unwrap();
let python = if cfg!(windows) { "python" } else { "python3" };
let runtime = AgentRuntimeClient::spawn(
AgentLaunchSpec::new(python).with_args([
script.to_string_lossy().to_string(),
response.to_string(),
dir.join("calls").to_string_lossy().to_string(),
]),
"test",
)
.await
.unwrap();
ScriptedAgent(runtime)
}
#[tokio::test]
async fn existing_pool_never_connects_on_empty_or_error_but_default_app_keeps_fallback() {
for db_type in [DatabaseType::Highgo, DatabaseType::Vastbase] {
for provider_error in [false, true] {
let (dir, state) = state(db_type).await;
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
state.configs.write().await.get_mut("conn").unwrap().port = listener.local_addr().unwrap().port();
let response = if provider_error {
serde_json::json!({"error": {"code": -1, "message": "metadata denied", "data": {
"category": "sql", "sessionDisposition": "keep"
}}})
} else {
serde_json::json!({"result": []})
};
let agent = scripted_agent(dir.path(), response).await;
agent.0.increment_session_count();
let client = AgentDriverClient::shared_session(agent.0.clone(), "metadata-session".to_string());
let pool_key = "conn:app:role:metadata";
state.update_connection_pools(|pools| pools.insert(pool_key.to_string(), PoolKind::agent(client))).await;
let error = tokio::time::timeout(Duration::from_secs(3), async {
tokio::select! {
biased;
_ = listener.accept() => panic!("plugin metadata attempted a native connection"),
result = get_table_metadata(&state, context()) => result.unwrap_err(),
}
})
.await
.expect("plugin metadata must not wait for a native fallback");
if provider_error {
assert!(error.contains("metadata denied"), "{error}");
assert_eq!(
crate::db::agent_driver::try_agent_error_from_legacy(&error).and_then(|error| error.category()),
Some(crate::db::agent_driver::AgentErrorCategory::Sql)
);
} else {
assert_eq!(error, "Table metadata provider returned no columns");
}
assert_eq!(std::fs::read_to_string(dir.path().join("calls")).unwrap().lines().count(), 1);
assert!(state.pool_handle(pool_key).await.is_some());
assert_eq!(state.with_connection_pools(|pools| pools.len()).await, 1);
tokio::time::timeout(Duration::from_secs(3), async {
tokio::select! {
accepted = listener.accept() => { accepted.unwrap(); }
result = get_columns_core_for_session_inner(&state, "conn", "app", "public", "users", None, true) => {
panic!("ordinary app skipped its native fallback: {result:?}");
}
}
})
.await
.expect("ordinary app fallback must still connect");
assert_eq!(std::fs::read_to_string(dir.path().join("calls")).unwrap().lines().count(), 2);
agent.0.kill();
let stale_error = tokio::time::timeout(Duration::from_secs(3), async {
tokio::select! {
biased;
_ = listener.accept() => panic!("stale plugin pool triggered a native connection"),
result = get_table_metadata(&state, context()) => result.unwrap_err(),
}
})
.await
.expect("cancelled metadata must release the agent lock");
assert!(stale_error.contains("unavailable"), "{stale_error}");
assert!(state.pool_handle(pool_key).await.is_some());
assert_eq!(state.with_connection_pools(|pools| pools.len()).await, 1);
}
}
}
#[tokio::test]
async fn existing_pool_shares_app_concurrency_limit_and_queue_timeout() {
for db_type in [DatabaseType::Mysql, DatabaseType::Postgres] {
let (_dir, state) = state(db_type).await;
tokio::time::pause();
let entered = AtomicUsize::new(0);
let mut operations = Vec::new();
for index in 0..6 {
let operation = run_metadata_connection_for_session(&state, "conn", Some("app"), None, index < 3, || {
entered.fetch_add(1, Ordering::SeqCst);
std::future::pending::<Result<(), String>>()
});
let mut operation = Box::pin(operation);
assert!(futures::poll!(operation.as_mut()).is_pending());
operations.push(operation);
}
assert_eq!(entered.load(Ordering::SeqCst), 6);
let mut queued =
Box::pin(run_metadata_connection_for_session(&state, "conn", Some("app"), None, false, || {
entered.fetch_add(1, Ordering::SeqCst);
async { Ok(()) }
}));
assert!(futures::poll!(queued.as_mut()).is_pending());
tokio::time::advance(METADATA_POOL_ACQUIRE_TIMEOUT).await;
assert_eq!(queued.await.unwrap_err(), crate::query::METADATA_POOL_BUSY_ERROR);
assert_eq!(entered.load(Ordering::SeqCst), 6);
drop(operations);
for _ in 0..6 {
run_metadata_connection_for_session(&state, "conn", Some("app"), None, false, || async { Ok(()) })
.await
.unwrap();
}
tokio::time::resume();
}
}
#[tokio::test]
async fn existing_pool_entrypoint_waits_for_the_shared_budget_before_provider_lookup() {
let (_dir, state) = state(DatabaseType::Postgres).await;
let mut held = Vec::new();
for _ in 0..6 {
held.push(state.acquire_metadata_permit("conn", Some("app"), DatabaseType::Postgres, None).await.unwrap());
}
let mut lookup = Box::pin(get_columns_core_for_existing_pool(&state, "conn", "app", "public", "users", "conn:app"));
assert!(futures::poll!(lookup.as_mut()).is_pending());
drop(held.pop());
assert_eq!(lookup.await.unwrap_err(), "Pool not found");
let mut next = Box::pin(state.acquire_metadata_permit("conn", Some("app"), DatabaseType::Postgres, None));
assert!(matches!(futures::poll!(next.as_mut()), std::task::Poll::Ready(Ok(_))));
}
#[tokio::test]
async fn existing_pool_releases_permits_on_success_error_and_cancellation_without_retry() {
let (_dir, state) = state(DatabaseType::Postgres).await;
let mut held = Vec::new();
for _ in 0..5 {
held.push(state.acquire_metadata_permit("conn", Some("app"), DatabaseType::Postgres, None).await.unwrap());
}
for result in [Ok(()), Err("Pool not found"), Err("connection reset by peer"), Err("Query canceled")] {
let mut attempts = 0;
let actual = run_metadata_connection_for_session(&state, "conn", Some("app"), None, false, || {
attempts += 1;
async { result.map_err(str::to_string) }
})
.await;
assert_eq!(actual, result.map_err(str::to_string));
assert_eq!(attempts, 1);
}
let mut running = Box::pin(run_metadata_connection_for_session(&state, "conn", Some("app"), None, false, || {
std::future::pending::<Result<(), String>>()
}));
assert!(futures::poll!(running.as_mut()).is_pending());
let queued_calls = AtomicUsize::new(0);
let mut queued = Box::pin(run_metadata_connection_for_session(&state, "conn", Some("app"), None, false, || {
queued_calls.fetch_add(1, Ordering::SeqCst);
async { Ok(()) }
}));
assert!(futures::poll!(queued.as_mut()).is_pending());
drop(queued);
drop(running);
assert_eq!(queued_calls.load(Ordering::SeqCst), 0);
let mut next = Box::pin(state.acquire_metadata_permit("conn", Some("app"), DatabaseType::Postgres, None));
assert!(matches!(futures::poll!(next.as_mut()), std::task::Poll::Ready(Ok(_))));
}
#[tokio::test]
async fn invalid_scope_and_removed_pool_do_not_create_or_reconnect() {
let (_dir, state) = state(DatabaseType::Postgres).await;
let mut invalid = context();
invalid.table = " ".to_string();
assert_eq!(get_table_metadata(&state, invalid).await.unwrap_err(), "table must not be empty");
let mut unknown = context();
unknown.connection_id = "unknown".to_string();
assert_eq!(get_table_metadata(&state, unknown).await.unwrap_err(), "Connection config not found");
state
.update_connection_pools(|pools| {
pools.insert("conn:other".to_string(), PoolKind::agent(AgentDriverClient::test_stub()));
})
.await;
assert_eq!(get_table_metadata(&state, context()).await.unwrap_err(), TABLE_METADATA_SESSION_NOT_OPEN_ERROR);
state
.update_connection_pools(|pools| {
pools.remove("conn:other");
pools.insert("conn:app".to_string(), PoolKind::agent(AgentDriverClient::test_stub()));
})
.await;
let key = state.existing_metadata_pool_key_for_session("conn", Some("app"), None).await.unwrap();
state.update_connection_pools(|pools| pools.remove(&key)).await;
assert_eq!(
get_columns_core_for_existing_pool(&state, "conn", "app", "public", "users", &key).await.unwrap_err(),
"Pool not found"
);
assert!(state.with_connection_pools(|pools| pools.is_empty()).await);
}
@@ -293,6 +293,7 @@ fn column_info_serialization_roundtrip() {
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
metadata_capabilities: None,
}; };
let json = serde_json::to_value(&col).unwrap(); let json = serde_json::to_value(&col).unwrap();
assert_eq!(json.get("is_unique"), Some(&serde_json::json!(true))); assert_eq!(json.get("is_unique"), Some(&serde_json::json!(true)));
@@ -340,6 +341,7 @@ fn table_columns_result_serialization_contract() {
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
metadata_capabilities: None,
}], }],
error: Some("partial".to_string()), error: Some("partial".to_string()),
}; };
@@ -27,6 +27,7 @@ fn col(name: &str, data_type: &str) -> ColumnInfo {
numeric_precision: None, numeric_precision: None,
numeric_scale: None, numeric_scale: None,
character_maximum_length: None, character_maximum_length: None,
metadata_capabilities: None,
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
@@ -30,6 +30,7 @@ fn col(name: &str, data_type: &str) -> ColumnInfo {
numeric_precision: None, numeric_precision: None,
numeric_scale: None, numeric_scale: None,
character_maximum_length: None, character_maximum_length: None,
metadata_capabilities: None,
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
@@ -48,6 +48,7 @@ fn generate_details(tables: &[TableInfo], columns_per_table: usize) -> Vec<Table
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
metadata_capabilities: None,
}) })
.collect(), .collect(),
indexes: vec![], indexes: vec![],
@@ -36,6 +36,7 @@ fn col(name: &str, data_type: &str) -> ColumnInfo {
numeric_precision: None, numeric_precision: None,
numeric_scale: None, numeric_scale: None,
character_maximum_length: None, character_maximum_length: None,
metadata_capabilities: None,
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
@@ -29,6 +29,7 @@ fn column(name: &str, data_type: &str) -> ColumnInfo {
numeric_precision: None, numeric_precision: None,
numeric_scale: None, numeric_scale: None,
character_maximum_length: None, character_maximum_length: None,
metadata_capabilities: None,
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
@@ -395,6 +395,7 @@ pub async fn get_columns(client: &MeilisearchClient, index: &str) -> Result<Vec<
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
metadata_capabilities: None,
}) })
.collect()) .collect())
} }
+6 -4
View File
@@ -24,10 +24,10 @@ use crate::models::connection::{
}; };
use crate::sql::{starts_with_executable_sql_keyword, starts_with_executable_sql_keyword_for_database}; use crate::sql::{starts_with_executable_sql_keyword, starts_with_executable_sql_keyword_for_database};
use crate::types::{ use crate::types::{
ColumnInfo, CompletionAssistantCandidate, CompletionAssistantCandidateKind, CompletionAssistantMatchMode, ColumnInfo, ColumnMetadataCapabilities, CompletionAssistantCandidate, CompletionAssistantCandidateKind,
CompletionAssistantObjectKind, CompletionAssistantRequest, CompletionAssistantResponse, DatabaseInfo, CompletionAssistantMatchMode, CompletionAssistantObjectKind, CompletionAssistantRequest,
ForeignKeyInfo, IndexInfo, LargeValueCell, ObjectInfo, ObjectStatistics, QueryMessage, QueryResult, CompletionAssistantResponse, DatabaseInfo, ForeignKeyInfo, IndexInfo, LargeValueCell, ObjectInfo, ObjectStatistics,
SpatialColumnBuilder, TableInfo, TriggerInfo, QueryMessage, QueryResult, SpatialColumnBuilder, TableInfo, TriggerInfo,
}; };
use dbx_types::metadata_filter::{table_name_filter_matches, TableNameFilter}; use dbx_types::metadata_filter::{table_name_filter_matches, TableNameFilter};
@@ -4238,6 +4238,7 @@ where
enum_values, enum_values,
character_set: get_opt_str(row, "CHARACTER_SET_NAME").filter(|s| !s.is_empty()), character_set: get_opt_str(row, "CHARACTER_SET_NAME").filter(|s| !s.is_empty()),
collation: get_opt_str(row, "COLLATION_NAME").filter(|s| !s.is_empty()), collation: get_opt_str(row, "COLLATION_NAME").filter(|s| !s.is_empty()),
metadata_capabilities: Some(ColumnMetadataCapabilities::all_supported()),
}) })
}) })
.collect(); .collect();
@@ -4294,6 +4295,7 @@ where
.and_then(|c| c.split_once('_').map(|(charset, _)| charset.to_string())) .and_then(|c| c.split_once('_').map(|(charset, _)| charset.to_string()))
.filter(|s| !s.is_empty()), .filter(|s| !s.is_empty()),
collation, collation,
metadata_capabilities: Some(ColumnMetadataCapabilities::default_only()),
}) })
}) })
.collect(); .collect();
@@ -218,6 +218,7 @@ pub async fn get_columns_show_from(
.and_then(|c| c.split_once('_').map(|(charset, _)| charset.to_string())) .and_then(|c| c.split_once('_').map(|(charset, _)| charset.to_string()))
.filter(|s| !s.is_empty()), .filter(|s| !s.is_empty()),
collation, collation,
metadata_capabilities: None,
}) })
}) })
.collect()) .collect())
+9 -6
View File
@@ -33,12 +33,13 @@ use crate::execution::{await_stream_with_progress_timeout, DbOperationBudget, St
use crate::models::connection::DatabaseType; use crate::models::connection::DatabaseType;
use crate::sql::starts_with_executable_sql_keyword; use crate::sql::starts_with_executable_sql_keyword;
use crate::types::{ use crate::types::{
ColumnInfo, CompletionAssistantCandidate, CompletionAssistantCandidateKind, CompletionAssistantMatchMode, ColumnInfo, ColumnMetadataCapabilities, CompletionAssistantCandidate, CompletionAssistantCandidateKind,
CompletionAssistantObjectKind, CompletionAssistantRequest, CompletionAssistantResponse, ConstraintInfo, CompletionAssistantMatchMode, CompletionAssistantObjectKind, CompletionAssistantRequest,
CustomTypeDdl, CustomTypeDetails, CustomTypeDomainConstraint, CustomTypeKind, CustomTypeMember, CompletionAssistantResponse, ConstraintInfo, CustomTypeDdl, CustomTypeDetails, CustomTypeDomainConstraint,
CustomTypeProperties, DatabaseInfo, DatabaseStorageInfo, ExtensionInfo, ForeignKeyInfo, FunctionInfo, IndexInfo, CustomTypeKind, CustomTypeMember, CustomTypeProperties, DatabaseInfo, DatabaseStorageInfo, ExtensionInfo,
ObjectInfo, ObjectStatistics, OwnerInfo, PgPartitionBound, PgPartitionKind, PgPartitionNode, PgTablePartitioning, ForeignKeyInfo, FunctionInfo, IndexInfo, ObjectInfo, ObjectStatistics, OwnerInfo, PgPartitionBound,
QueryMessage, QueryResult, RuleInfo, SchemaInfo, SequenceInfo, SpatialColumnBuilder, TableInfo, TriggerInfo, PgPartitionKind, PgPartitionNode, PgTablePartitioning, QueryMessage, QueryResult, RuleInfo, SchemaInfo,
SequenceInfo, SpatialColumnBuilder, TableInfo, TriggerInfo,
}; };
pub const GAUSSDB_COMPATIBILITY_SQL: &str = pub const GAUSSDB_COMPATIBILITY_SQL: &str =
@@ -4711,6 +4712,7 @@ fn column_info_from_row_offset(row: &Row, offset: usize) -> ColumnInfo {
numeric_scale: row.try_get::<_, Option<i32>>(offset + 8).ok().flatten(), numeric_scale: row.try_get::<_, Option<i32>>(offset + 8).ok().flatten(),
character_maximum_length: row.try_get::<_, Option<i32>>(offset + 9).ok().flatten(), character_maximum_length: row.try_get::<_, Option<i32>>(offset + 9).ok().flatten(),
enum_values: parse_enum_values_from_row(row, offset + 10), enum_values: parse_enum_values_from_row(row, offset + 10),
metadata_capabilities: Some(ColumnMetadataCapabilities::all_supported()),
..Default::default() ..Default::default()
} }
} }
@@ -7622,6 +7624,7 @@ fn redshift_columns_from_query_result(result: QueryResult) -> Vec<ColumnInfo> {
numeric_scale: query_result_i32(&row, 5), numeric_scale: query_result_i32(&row, 5),
character_maximum_length: query_result_i32(&row, 6), character_maximum_length: query_result_i32(&row, 6),
enum_values: None, enum_values: None,
metadata_capabilities: Some(ColumnMetadataCapabilities::all_supported()),
..Default::default() ..Default::default()
}) })
}) })
+5 -3
View File
@@ -18,9 +18,9 @@ extern crate libsqlite3_hotbundle;
use super::file_validator::validate_file_path; use super::file_validator::validate_file_path;
use crate::sql::starts_with_executable_sql_keyword; use crate::sql::starts_with_executable_sql_keyword;
use crate::types::{ use crate::types::{
ColumnInfo, CompletionAssistantCandidate, CompletionAssistantCandidateKind, CompletionAssistantMatchMode, ColumnInfo, ColumnMetadataCapabilities, CompletionAssistantCandidate, CompletionAssistantCandidateKind,
CompletionAssistantObjectKind, CompletionAssistantRequest, CompletionAssistantResponse, DatabaseInfo, CompletionAssistantMatchMode, CompletionAssistantObjectKind, CompletionAssistantRequest,
ForeignKeyInfo, IndexInfo, QueryResult, TableInfo, TriggerInfo, CompletionAssistantResponse, DatabaseInfo, ForeignKeyInfo, IndexInfo, QueryResult, TableInfo, TriggerInfo,
}; };
const SQLITE_DATABASE_HEADER: &[u8; 16] = b"SQLite format 3\0"; const SQLITE_DATABASE_HEADER: &[u8; 16] = b"SQLite format 3\0";
@@ -1588,6 +1588,7 @@ pub async fn get_columns(pool: &SqliteHandle, schema: &str, table: &str) -> Resu
numeric_scale: None, numeric_scale: None,
character_maximum_length: None, character_maximum_length: None,
enum_values: None, enum_values: None,
metadata_capabilities: Some(ColumnMetadataCapabilities::default_only()),
..Default::default() ..Default::default()
} }
}) })
@@ -1623,6 +1624,7 @@ pub async fn get_columns(pool: &SqliteHandle, schema: &str, table: &str) -> Resu
numeric_scale: None, numeric_scale: None,
character_maximum_length: None, character_maximum_length: None,
enum_values: None, enum_values: None,
metadata_capabilities: Some(ColumnMetadataCapabilities::default_only()),
..Default::default() ..Default::default()
}) })
}) })
+1
View File
@@ -2570,6 +2570,7 @@ fn infer_document_columns(documents: &[Value]) -> Vec<ColumnInfo> {
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
metadata_capabilities: None,
}) })
.collect() .collect()
} }
@@ -9,11 +9,12 @@ pub const SUPPORTED_PLUGIN_MANIFEST_VERSION: u32 = 1;
/// ///
/// 1.1 adds the plugin-initiated `host/requestUserInput` method (see /// 1.1 adds the plugin-initiated `host/requestUserInput` method (see
/// `plugins/runtime.rs`). 1.2 adds the plugin-initiated plan Host API /// `plugins/runtime.rs`). 1.2 adds the plugin-initiated plan Host API
/// (`host.getPlanCapabilities` / `host.explainPlan`). Both are additive: older /// (`host.getPlanCapabilities` / `host.explainPlan`). 1.3 adds read-only table
/// plugins keep working, and a plugin that wants either capability must check /// schema metadata (`host.getTableMetadata`). All are additive: older plugins
/// the advertised version (or the matching `capabilities` / `host.features` /// keep working, and a plugin that wants either capability must check the
/// advertised version (or the matching `capabilities` / `host.features`
/// entry) before calling it. /// entry) before calling it.
pub const SUPPORTED_PLUGIN_HOST_API_VERSION: &str = "1.2.0"; pub const SUPPORTED_PLUGIN_HOST_API_VERSION: &str = "1.3.0";
/// Capabilities the host advertises to a plugin backend at `plugin/initialize`. /// Capabilities the host advertises to a plugin backend at `plugin/initialize`.
pub const SUPPORTED_PLUGIN_HOST_FEATURES: &[&str] = &["host.requestUserInput"]; pub const SUPPORTED_PLUGIN_HOST_FEATURES: &[&str] = &["host.requestUserInput"];
pub const SUPPORTED_PLUGIN_PROTOCOL_VERSION: u32 = 1; pub const SUPPORTED_PLUGIN_PROTOCOL_VERSION: u32 = 1;
@@ -21,8 +22,16 @@ pub const PLUGIN_CONNECTION_TEST_METHOD: &str = "connection/test";
pub const PLUGIN_CONNECTION_CONNECT_METHOD: &str = "connection/connect"; pub const PLUGIN_CONNECTION_CONNECT_METHOD: &str = "connection/connect";
pub const PLUGIN_CONNECTION_DISCONNECT_METHOD: &str = "connection/disconnect"; pub const PLUGIN_CONNECTION_DISCONNECT_METHOD: &str = "connection/disconnect";
pub const PLUGIN_CONNECTION_ACTION_METHOD: &str = "connection/action"; pub const PLUGIN_CONNECTION_ACTION_METHOD: &str = "connection/action";
pub const SUPPORTED_PLUGIN_PERMISSIONS: &[&str] = pub const SUPPORTED_PLUGIN_PERMISSIONS: &[&str] = &[
&["host.events", "host.binary", "host.workbench", "host.filesystem", "host.plans:read", "host.storage", "host.ai"]; "host.events",
"host.binary",
"host.workbench",
"host.filesystem",
"host.plans:read",
"host.schema:read",
"host.storage",
"host.ai",
];
/// Cap the number of `host.network:<origin>` entries so a manifest cannot bloat /// Cap the number of `host.network:<origin>` entries so a manifest cannot bloat
/// the sandbox CSP or enumerate large origin lists. /// the sandbox CSP or enumerate large origin lists.
@@ -1572,7 +1581,7 @@ mod tests {
} }
#[test] #[test]
fn accepts_host_plans_read_and_still_rejects_unknown_permissions() { fn accepts_read_only_host_permissions_and_still_rejects_unknown_permissions() {
let dir = tempfile::tempdir().unwrap(); let dir = tempfile::tempdir().unwrap();
std::fs::create_dir_all(dir.path().join("ui")).unwrap(); std::fs::create_dir_all(dir.path().join("ui")).unwrap();
std::fs::write(dir.path().join("ui").join("index.html"), "<!doctype html>").unwrap(); std::fs::write(dir.path().join("ui").join("index.html"), "<!doctype html>").unwrap();
@@ -1585,14 +1594,22 @@ mod tests {
"publisher": "example", "publisher": "example",
"engines": { "dbx": ">=0.1.0", "host_api": "^1.0" }, "engines": { "dbx": ">=0.1.0", "host_api": "^1.0" },
"entrypoints": { "ui": { "root": "ui", "entry": "ui/index.html" } }, "entrypoints": { "ui": { "root": "ui", "entry": "ui/index.html" } },
"permissions": ["host.plans:read"] "permissions": ["host.plans:read", "host.schema:read"]
})) }))
.unwrap(); .unwrap();
let compatibility = manifest.compatibility(dir.path(), "0.1.0"); let compatibility = manifest.compatibility(dir.path(), "0.1.0");
assert!(compatibility.compatible, "{:?}", compatibility.errors); assert!(compatibility.compatible, "{:?}", compatibility.errors);
// The plan API is read-only: an execute-scoped scope must not be declared. // Both the plan and schema metadata APIs are read-only; execute/write
for permission in ["host.plans:execute", "host.plans", "host.plans:read:all", "host.plan:read"] { // scopes must not be declared as substitutes.
for permission in [
"host.plans:execute",
"host.plans",
"host.plans:read:all",
"host.plan:read",
"host.schema:write",
"host.schema",
] {
let manifest: PluginManifest = serde_json::from_value(serde_json::json!({ let manifest: PluginManifest = serde_json::from_value(serde_json::json!({
"manifest_version": 1, "manifest_version": 1,
"id": "io.dbx.example", "id": "io.dbx.example",
@@ -1635,22 +1652,22 @@ mod tests {
assert_eq!(declared, SUPPORTED_PLUGIN_PERMISSIONS.iter().map(|value| value.to_string()).collect::<Vec<_>>()); assert_eq!(declared, SUPPORTED_PLUGIN_PERMISSIONS.iter().map(|value| value.to_string()).collect::<Vec<_>>());
} }
/// The reason for the 1.2.0 bump: `engines.host_api` is how a plugin states /// The reason for the 1.3.0 bump: `engines.host_api` is how a plugin states
/// "I need the plan API", so the advertised version has to satisfy `^1.2` /// "I need the schema metadata API", so the advertised version has to
/// while a floor this host cannot meet stays rejected. /// satisfy `^1.3` while a floor this host cannot meet stays rejected.
#[test] #[test]
fn host_api_advertises_the_floor_a_plan_api_plugin_declares() { fn host_api_advertises_the_floor_a_schema_metadata_plugin_declares() {
let advertised = semver::Version::parse(SUPPORTED_PLUGIN_HOST_API_VERSION) let advertised = semver::Version::parse(SUPPORTED_PLUGIN_HOST_API_VERSION)
.expect("the advertised Host API version must be semver"); .expect("the advertised Host API version must be semver");
assert!( assert!(
semver::VersionReq::parse("^1.2").unwrap().matches(&advertised), semver::VersionReq::parse("^1.3").unwrap().matches(&advertised),
"the host must satisfy the plan API floor it asks plugins to declare" "the host must satisfy the schema metadata API floor it asks plugins to declare"
); );
for requirement in ["^1.0", "^1.1", "^1.2", ">=1.1.0, <2.0.0"] { for requirement in ["^1.0", "^1.1", "^1.2", "^1.3", ">=1.1.0, <2.0.0"] {
assert!(host_api_requirement_errors(requirement).is_empty(), "{requirement} must be satisfiable"); assert!(host_api_requirement_errors(requirement).is_empty(), "{requirement} must be satisfiable");
} }
for requirement in [">=1.3.0", "^2.0"] { for requirement in [">=1.4.0", "^2.0"] {
assert!(!host_api_requirement_errors(requirement).is_empty(), "{requirement} must be rejected"); assert!(!host_api_requirement_errors(requirement).is_empty(), "{requirement} must be rejected");
} }
} }
+4
View File
@@ -6374,6 +6374,7 @@ mod tests {
numeric_precision: None, numeric_precision: None,
numeric_scale: None, numeric_scale: None,
character_maximum_length: None, character_maximum_length: None,
metadata_capabilities: None,
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
@@ -9214,6 +9215,7 @@ mod tests {
numeric_precision: None, numeric_precision: None,
numeric_scale: None, numeric_scale: None,
character_maximum_length: None, character_maximum_length: None,
metadata_capabilities: None,
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
@@ -12410,6 +12412,7 @@ mod tests {
numeric_precision: None, numeric_precision: None,
numeric_scale: None, numeric_scale: None,
character_maximum_length: None, character_maximum_length: None,
metadata_capabilities: None,
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
@@ -12427,6 +12430,7 @@ mod tests {
numeric_precision: None, numeric_precision: None,
numeric_scale: None, numeric_scale: None,
character_maximum_length: None, character_maximum_length: None,
metadata_capabilities: None,
enum_values: None, enum_values: None,
character_set: None, character_set: None,
collation: None, collation: None,
+22
View File
@@ -181,6 +181,26 @@ pub struct ObjectSource {
pub editable: Option<bool>, pub editable: Option<bool>,
} }
/// Provenance for structured metadata fields that are optional in [`ColumnInfo`].
/// This stays internal to the metadata mapping path and is not serialized.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ColumnMetadataCapabilities {
pub default: bool,
pub length: bool,
pub precision: bool,
pub scale: bool,
}
impl ColumnMetadataCapabilities {
pub const fn all_supported() -> Self {
Self { default: true, length: true, precision: true, scale: true }
}
pub const fn default_only() -> Self {
Self { default: true, length: false, precision: false, scale: false }
}
}
#[derive(Debug, Clone, Serialize, Deserialize, Default)] #[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct ColumnInfo { pub struct ColumnInfo {
pub name: String, pub name: String,
@@ -203,6 +223,8 @@ pub struct ColumnInfo {
pub character_set: Option<String>, pub character_set: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")] #[serde(default, skip_serializing_if = "Option::is_none")]
pub collation: Option<String>, pub collation: Option<String>,
#[serde(skip)]
pub metadata_capabilities: Option<ColumnMetadataCapabilities>,
} }
#[derive(Debug, Clone, Serialize, Deserialize)] #[derive(Debug, Clone, Serialize, Deserialize)]
+1
View File
@@ -566,6 +566,7 @@ async fn serve() {
.route("/schema/event-info", get(routes::schema::get_event_info)) .route("/schema/event-info", get(routes::schema::get_event_info))
.route("/schema/custom-type-details", get(routes::schema::get_custom_type_details)) .route("/schema/custom-type-details", get(routes::schema::get_custom_type_details))
.route("/schema/columns", get(routes::schema::list_columns)) .route("/schema/columns", get(routes::schema::list_columns))
.route("/plugin/table-metadata", post(routes::schema::get_plugin_table_metadata))
.route("/schema/all-columns", get(routes::schema::get_all_columns)) .route("/schema/all-columns", get(routes::schema::get_all_columns))
.route("/schema/data-types", get(routes::schema::list_data_types)) .route("/schema/data-types", get(routes::schema::list_data_types))
.route("/schema/indexes", get(routes::schema::list_indexes)) .route("/schema/indexes", get(routes::schema::list_indexes))
+9
View File
@@ -462,6 +462,15 @@ fn should_cache_columns(client_session_id: Option<&str>) -> bool {
client_session_id.is_none() client_session_id.is_none()
} }
pub async fn get_plugin_table_metadata(
State(state): State<Arc<WebState>>,
Json(request): Json<dbx_core::schema::plugin_metadata::PluginTableContext>,
) -> Result<Json<dbx_core::schema::plugin_metadata::PluginTableMetadata>, AppError> {
let result =
dbx_core::schema::plugin_metadata::get_table_metadata(&state.app, request).await.map_err(AppError::from)?;
Ok(Json(result))
}
pub async fn list_columns( pub async fn list_columns(
State(state): State<Arc<WebState>>, State(state): State<Arc<WebState>>,
Query(q): Query<SchemaQuery>, Query(q): Query<SchemaQuery>,
+58 -2
View File
@@ -103,6 +103,7 @@ Manifest 中的路径相对于包根目录,不能以 `/` 开头、不能包含
"host.filesystem", "host.filesystem",
"host.binary", "host.binary",
"host.plans:read", "host.plans:read",
"host.schema:read",
"host.storage", "host.storage",
"host.network:https://s3.example.com:443" "host.network:https://s3.example.com:443"
], ],
@@ -120,7 +121,8 @@ Manifest 中的路径相对于包根目录,不能以 `/` 开头、不能包含
- `engines.dbx` 是可选的 DBX 版本范围;`engines.host_api` 是必需的 Host API 版本声明。 - `engines.dbx` 是可选的 DBX 版本范围;`engines.host_api` 是必需的 Host API 版本声明。
- `host.workbench` 允许打开另一个工作台,`host.events` 接收宿主事件,`host.binary` 使用二进制通道,`host.filesystem` 使用文件系统入口。 - `host.workbench` 允许打开另一个工作台,`host.events` 接收宿主事件,`host.binary` 使用二进制通道,`host.filesystem` 使用文件系统入口。
- `host.plans:read` 允许针对 DBX 自己的连接读取估算执行计划(见 [估算执行计划](#估算执行计划))。它是只读权限:不授予普通 SQL 执行、写操作、DDL 或真实执行计划,且这是唯一存在的计划类权限。 - `host.plans:read` 允许针对 DBX 自己的连接读取估算执行计划(见 [估算执行计划](#估算执行计划))。它是只读权限:不授予普通 SQL 执行、写操作、DDL 或真实执行计划,且这是唯一存在的计划类权限。
- `host.storage` 为工作台 UI 提供本插件独享的持久化键值存储(见 [持久化 UI 状态](#持久化-ui-状态));数据只落在插件自己的数据目录里。 - `host.schema:read` 允许通过 `host.getTableMetadata` 读取已打开连接的窄化 table schema metadata;它不会授予任意 SQL、写入或隐式重连(见 [Table Schema Metadata](#table-schema-metadata))。
- `host.storage` 为工作台 UI 提供本插件独享的持久化键值存储(见 [持久化 UI 状态](#持久化-ui-状态));数据只落在插件自己的插件数据目录里。
- `host.ai` 允许插件在 DBX 内置 AI 面板中新建带数据快照的对话,沿用宿主的模型选择、历史、追问、停止和导出功能。旧版 DBX 会在安装时因未知权限而失败,需要兼容旧宿主的插件应把 `host.ai` 作为可选能力。 - `host.ai` 允许插件在 DBX 内置 AI 面板中新建带数据快照的对话,沿用宿主的模型选择、历史、追问、停止和导出功能。旧版 DBX 会在安装时因未知权限而失败,需要兼容旧宿主的插件应把 `host.ai` 作为可选能力。
- `host.network:https://host[:port]` 声明浏览器可访问的 HTTPS origin,DBX 将它加入 CSP 的 `connect-src`;最多 8 个,不允许路径、通配符或 Token。仍受目标服务 CORS 规则约束。该权限不是原生 Sidecar 的网络防火墙。 - `host.network:https://host[:port]` 声明浏览器可访问的 HTTPS origin,DBX 将它加入 CSP 的 `connect-src`;最多 8 个,不允许路径、通配符或 Token。仍受目标服务 CORS 规则约束。该权限不是原生 Sidecar 的网络防火墙。
- `backend.transport` 默认是 `stdio-jsonl`;需要二进制帧时使用 `stdio-framed`,并同时声明 `host.binary`。 - `backend.transport` 默认是 `stdio-jsonl`;需要二进制帧时使用 `stdio-framed`,并同时声明 `host.binary`。
@@ -313,7 +315,8 @@ const assetUrl = await window.dbxPlugin.readAssetUrl("assets/empty-state.svg");
| `openFilesystem(id, context)` | 打开本插件的文件系统入口;需要 `host.filesystem`。 | | `openFilesystem(id, context)` | 打开本插件的文件系统入口;需要 `host.filesystem`。 |
| `getPlanCapabilities(connectionId)` | 读取宿主与该连接能提供什么计划能力;需要 `host.plans:read`。 | | `getPlanCapabilities(connectionId)` | 读取宿主与该连接能提供什么计划能力;需要 `host.plans:read`。 |
| `explainPlan({ connectionId, database?, schema?, sql, mode, timeoutMs? })` | 返回 `sql` 的估算执行计划;需要 `host.plans:read`。 | | `explainPlan({ connectionId, database?, schema?, sql, mode, timeoutMs? })` | 返回 `sql` 的估算执行计划;需要 `host.plans:read`。 |
| `capabilities` | 来自 init 消息的 `{ downloadFile, planApi, storage, ai }`。字段缺失或为 `false` 表示当前宿主不支持该组 Host API,应据此关闭功能而不是用真实请求试探。 | | `getTableMetadata({ connectionId, database?, schema?, table })` | 读取已打开连接的窄化 table schema metadata;需要 `host.schema:read`。 |
| `capabilities` | 来自 init 消息的 `{ downloadFile, planApi, schemaMetadataApi, storage, ai }`。字段缺失或为 `false` 表示当前宿主不支持该组 Host API,应据此关闭功能而不是用真实请求试探。 |
| `ai.openConversation({ title, prompt, context, send? })` | 在内置 AI 面板新建插件对话;`send` 默认 `false`,为 `true` 时立即分析;需要 `host.ai`,并以 `capabilities.ai` 广播——旧宿主不带该字段,请按能力位关闭而不是用真实请求试探。 | | `ai.openConversation({ title, prompt, context, send? })` | 在内置 AI 面板新建插件对话;`send` 默认 `false`,为 `true` 时立即分析;需要 `host.ai`,并以 `capabilities.ai` 广播——旧宿主不带该字段,请按能力位关闭而不是用真实请求试探。 |
| `onInit(fn)` / `onEvent(fn)` | 监听初始化、环境变化或后端事件;转发后端事件需要 `host.events`。 | | `onInit(fn)` / `onEvent(fn)` | 监听初始化、环境变化或后端事件;转发后端事件需要 `host.events`。 |
| `storage` | 本插件独享的持久化键值状态;需要 `host.storage`;见下文。 | | `storage` | 本插件独享的持久化键值状态;需要 `host.storage`;见下文。 |
@@ -367,6 +370,59 @@ if (window.dbxPlugin.capabilities.planApi) {
计划 API 属于 Host API 1.2。无法离开它工作的插件应在 manifest 里声明下限:`"engines": { "host_api": "^1.2" }`。manifest 里的版本范围是兼容下限,`capabilities.planApi` 是运行期探测,两者都保留。 计划 API 属于 Host API 1.2。无法离开它工作的插件应在 manifest 里声明下限:`"engines": { "host_api": "^1.2" }`。manifest 里的版本范围是兼容下限,`capabilities.planApi` 是运行期探测,两者都保留。
### Table Schema Metadata(表结构元数据)
插件可以读取当前 DBX 已打开连接中某个 table 的窄化 schema metadata,而不需要拥有驱动、连接池、凭据或自己拼 SQL。请求复用现有的 `PluginTableContext`,只允许 table identity:
```json
{
"permissions": ["host.schema:read"]
}
```
```js
if (window.dbxPlugin.capabilities.schemaMetadataApi) {
const metadata = await window.dbxPlugin.getTableMetadata({
connectionId,
database,
schema,
table: "users"
});
for (const column of metadata.columns) {
renderColumn(column.name, column.dataType, column.nullable);
}
}
```
`getTableMetadata({ connectionId, database?, schema?, table })` 返回:
```json
{
"columns": [
{
"name": "id",
"dataType": "integer",
"nullable": false,
"precision": 32,
"default": "nextval('users_id_seq'::regclass)"
}
],
"fieldCapabilities": {
"length": "supported",
"precision": "supported",
"scale": "supported",
"default": "supported"
}
}
```
- `columns` 只包含 `name`、`dataType`、`nullable`、可选的 `length`、`precision`、`scale` 和 `default`。不会返回 comment、key/index、credential、连接串、驱动内部对象或任意 SQL 结果。
- 可选值在没有值时保持 `null` 或直接省略,绝不会被伪造为 `0` 或空字符串。`fieldCapabilities` 用 `supported`、`unsupported`、`unknown` 区分提供方支持、明确不支持和宿主没有可靠 provenance 的情况;`unknown` 不应被插件当成支持。
- `database` 和 `schema` 可选;不可用时省略,不要把空字符串当作 public identity。`connectionId` 和 `table` 必须是非空且不超过 256 个字符的 identity 值。
- 这是只读 API。DBX 只复用已打开的 Host connection/session,禁止插件隐式重连、创建连接池或执行任意 SQL。已保存但当前断开的连接会以 `Connection is not open` 拒绝;请求的 database 没有对应已打开 session 时也会拒绝,而不是切换到别的连接。
该 API 属于 Host API 1.3。无法离开它工作的插件应声明:`"engines": { "host_api": "^1.3" }`;同时仍应读取 `capabilities.schemaMetadataApi`,因为旧宿主不会提供该字段。没有 `host.schema:read` 时,宿主会在请求到达 backend 前拒绝调用。
### 文件传输与系统拖放 ### 文件传输与系统拖放
桌面端宿主通过 `window.dbxPlugin.fileTransfer` 把本地文件流式接入插件沙箱。句柄只在用户明确同意后打开:原生打开/保存对话框(`pick` / `beginSave`),或从系统拖放到本插件工作台区域内的文件(`onDrop`)。传输按分块进行,多 GB 文件也不会整体载入内存。 桌面端宿主通过 `window.dbxPlugin.fileTransfer` 把本地文件流式接入插件沙箱。句柄只在用户明确同意后打开:原生打开/保存对话框(`pick` / `beginSave`),或从系统拖放到本插件工作台区域内的文件(`onDrop`)。传输按分块进行,多 GB 文件也不会整体载入内存。
+57 -1
View File
@@ -103,6 +103,7 @@ Manifest paths are relative to the package root. They cannot start with `/`, con
"host.filesystem", "host.filesystem",
"host.binary", "host.binary",
"host.plans:read", "host.plans:read",
"host.schema:read",
"host.storage", "host.storage",
"host.network:https://s3.example.com:443" "host.network:https://s3.example.com:443"
], ],
@@ -120,6 +121,7 @@ Manifest paths are relative to the package root. They cannot start with `/`, con
- `engines.dbx` is an optional DBX version range; `engines.host_api` is required. - `engines.dbx` is an optional DBX version range; `engines.host_api` is required.
- `host.workbench` opens another workbench, `host.events` receives host events, `host.binary` enables binary channels, and `host.filesystem` enables filesystem entrypoints. - `host.workbench` opens another workbench, `host.events` receives host events, `host.binary` enables binary channels, and `host.filesystem` enables filesystem entrypoints.
- `host.plans:read` allows reading estimated execution plans for DBX's own connections (see [Estimated Execution Plans](#estimated-execution-plans)). It is read-only: it never grants SQL execution, writes, DDL, or actual plans, and it is the only plan scope that exists. - `host.plans:read` allows reading estimated execution plans for DBX's own connections (see [Estimated Execution Plans](#estimated-execution-plans)). It is read-only: it never grants SQL execution, writes, DDL, or actual plans, and it is the only plan scope that exists.
- `host.schema:read` allows `host.getTableMetadata` to read narrow table schema metadata from an already-open connection; it grants no arbitrary SQL, writes, or implicit reconnect (see [Table Schema Metadata](#table-schema-metadata)).
- `host.storage` gives the workbench UI a persistent key-value store scoped to this plugin (see [Persistent UI State](#persistent-ui-state)). Values never leave the plugin's own data directory. - `host.storage` gives the workbench UI a persistent key-value store scoped to this plugin (see [Persistent UI State](#persistent-ui-state)). Values never leave the plugin's own data directory.
- `host.ai` lets the plugin open a conversation with a data snapshot in the built-in DBX AI panel, using its model selector, history, follow-up messages, cancellation and export. Older DBX builds reject the unknown permission at install time, so plugins that must install everywhere should treat `host.ai` as optional. - `host.ai` lets the plugin open a conversation with a data snapshot in the built-in DBX AI panel, using its model selector, history, follow-up messages, cancellation and export. Older DBX builds reject the unknown permission at install time, so plugins that must install everywhere should treat `host.ai` as optional.
- `host.network:https://host[:port]` declares a browser-accessible HTTPS origin added to CSP `connect-src`; at most eight origins are allowed, with no paths, wildcards, or tokens. The service's CORS rules still apply. This permission is not a native Sidecar network firewall. - `host.network:https://host[:port]` declares a browser-accessible HTTPS origin added to CSP `connect-src`; at most eight origins are allowed, with no paths, wildcards, or tokens. The service's CORS rules still apply. This permission is not a native Sidecar network firewall.
@@ -313,7 +315,8 @@ const assetUrl = await window.dbxPlugin.readAssetUrl("assets/empty-state.svg");
| `openFilesystem(id, context)` | Opens a filesystem entry; requires `host.filesystem`. | | `openFilesystem(id, context)` | Opens a filesystem entry; requires `host.filesystem`. |
| `getPlanCapabilities(connectionId)` | Reads what the host and this connection can plan; requires `host.plans:read`. | | `getPlanCapabilities(connectionId)` | Reads what the host and this connection can plan; requires `host.plans:read`. |
| `explainPlan({ connectionId, database?, schema?, sql, mode, timeoutMs? })` | Returns the estimated plan for `sql`; requires `host.plans:read`. | | `explainPlan({ connectionId, database?, schema?, sql, mode, timeoutMs? })` | Returns the estimated plan for `sql`; requires `host.plans:read`. |
| `capabilities` | `{ downloadFile, planApi, storage, ai }` from the init message. A missing or `false` entry means that Host API group is unavailable here, so gate the matching call on it instead of probing with a request. | | `getTableMetadata({ connectionId, database?, schema?, table })` | Reads narrow table schema metadata from an already-open connection; requires `host.schema:read`. |
| `capabilities` | `{ downloadFile, planApi, schemaMetadataApi, storage, ai }` from the init message. A missing or `false` entry means that Host API group is unavailable here, so gate the matching call on it instead of probing with a request. |
| `ai.openConversation({ title, prompt, context, send? })` | Opens a new plugin conversation in the built-in AI panel; `send` defaults to `false`, or starts analysis when `true`; requires `host.ai` and is advertised as `capabilities.ai` — gate on it instead of probing, since older hosts omit it. | | `ai.openConversation({ title, prompt, context, send? })` | Opens a new plugin conversation in the built-in AI panel; `send` defaults to `false`, or starts analysis when `true`; requires `host.ai` and is advertised as `capabilities.ai` — gate on it instead of probing, since older hosts omit it. |
| `onInit(fn)` / `onEvent(fn)` | Observes initialization, environment changes, or backend events; forwarding backend events requires `host.events`. | | `onInit(fn)` / `onEvent(fn)` | Observes initialization, environment changes, or backend events; forwarding backend events requires `host.events`. |
| `storage` | Persistent per-plugin key-value state; requires `host.storage`; see below. | | `storage` | Persistent per-plugin key-value state; requires `host.storage`; see below. |
@@ -367,6 +370,59 @@ Gate on capability rather than probing: read `dbxPlugin.capabilities.planApi` fr
The plan API is Host API 1.2. A plugin that cannot work without it declares the floor in its manifest with `"engines": { "host_api": "^1.2" }`. The manifest range is a compatibility floor and `capabilities.planApi` is the runtime check; keep both. The plan API is Host API 1.2. A plugin that cannot work without it declares the floor in its manifest with `"engines": { "host_api": "^1.2" }`. The manifest range is a compatibility floor and `capabilities.planApi` is the runtime check; keep both.
### Table Schema Metadata
A plugin can read narrow schema metadata for one table on a DBX connection that is already open, without owning a driver, connection pool, credential, or SQL string. The request reuses the canonical `PluginTableContext` and contains table identity only:
```json
{
"permissions": ["host.schema:read"]
}
```
```js
if (window.dbxPlugin.capabilities.schemaMetadataApi) {
const metadata = await window.dbxPlugin.getTableMetadata({
connectionId,
database,
schema,
table: "users"
});
for (const column of metadata.columns) {
renderColumn(column.name, column.dataType, column.nullable);
}
}
```
`getTableMetadata({ connectionId, database?, schema?, table })` returns:
```json
{
"columns": [
{
"name": "id",
"dataType": "integer",
"nullable": false,
"precision": 32,
"default": "nextval('users_id_seq'::regclass)"
}
],
"fieldCapabilities": {
"length": "supported",
"precision": "supported",
"scale": "supported",
"default": "supported"
}
}
```
- `columns` contains only `name`, `dataType`, `nullable`, and optional `length`, `precision`, `scale`, and `default`. It never returns comments, keys/indexes, credentials, connection strings, driver objects, or arbitrary SQL results.
- Optional values remain `null` or are omitted when no value exists; they are never fabricated as `0` or an empty string. `fieldCapabilities` uses `supported`, `unsupported`, and `unknown` to distinguish provider support, an explicitly unavailable field, and missing reliable provenance; plugins must not treat `unknown` as supported.
- `database` and `schema` are optional and omitted when unavailable; do not use empty strings as public identity. `connectionId` and `table` must be non-empty identity values no longer than 256 characters.
- This API is read-only. DBX reuses only an already-open Host connection/session; a plugin cannot trigger an implicit reconnect, create a pool, or execute arbitrary SQL. A saved-but-disconnected connection is rejected with `Connection is not open`; a requested database without a matching open session is also rejected instead of being routed to another connection.
This API is part of Host API 1.3. A plugin that cannot work without it should declare `"engines": { "host_api": "^1.3" }` and still read `capabilities.schemaMetadataApi`, because older hosts omit that field. Without `host.schema:read`, the host rejects the request before it reaches the backend.
### File Transfer and OS Drops ### File Transfer and OS Drops
Desktop hosts stream local files into plugin sandboxes through `window.dbxPlugin.fileTransfer`. Handles are opened only after explicit user consent: a native open/save dialog (`pick` / `beginSave`) or a file dropped from the OS onto this plugin's workbench area (`onDrop`). Transfers are chunked, so multi-gigabyte files never load into memory. Desktop hosts stream local files into plugin sandboxes through `window.dbxPlugin.fileTransfer`. Handles are opened only after explicit user consent: a native open/save dialog (`pick` / `beginSave`) or a file dropped from the OS onto this plugin's workbench area (`onDrop`). Transfers are chunked, so multi-gigabyte files never load into memory.
+130
View File
@@ -0,0 +1,130 @@
import { strict as assert } from "node:assert";
import { readFileSync } from "node:fs";
import { test } from "vitest";
import { PluginHostBridge } from "../../apps/desktop/src/lib/plugins/pluginHostBridge.ts";
import {
MAX_PLUGIN_SCHEMA_METADATA_NAME_CHARS,
PLUGIN_SCHEMA_METADATA_PERMISSION,
} from "../../apps/desktop/src/types/pluginSchemaMetadata.ts";
import type { PluginTableContext, PluginTableMetadata } from "../../apps/desktop/src/types/pluginSchemaMetadata.ts";
import type { InstalledPlugin, PluginWorkbenchContribution } from "../../apps/desktop/src/types/database.ts";
const coreSource = readFileSync("crates/dbx-core/src/schema/plugin_metadata.rs", "utf8");
const manifestSource = readFileSync("crates/dbx-plugin-runtime/src/plugins/manifest.rs", "utf8");
const manifestSchema = JSON.parse(readFileSync("plugins/manifest.schema.json", "utf8"));
function rustStructFields(source: string, name: string): string[] {
const marker = `pub struct ${name} {`;
const start = source.indexOf(marker);
assert.notEqual(start, -1, `Could not find struct ${name}`);
let depth = 0;
let end = start;
for (let index = source.indexOf("{", start); index < source.length; index += 1) {
if (source[index] === "{") depth += 1;
else if (source[index] === "}") {
depth -= 1;
if (depth === 0) {
end = index;
break;
}
}
}
return source
.slice(start, end)
.split("\n")
.map((line) => /^\s*pub\s+([a-z0-9_]+)\s*:/.exec(line)?.[1])
.filter((field): field is string => field !== undefined);
}
function camelCase(value: string): string {
return value.replace(/_([a-z])/g, (_match, letter: string) => letter.toUpperCase());
}
function plugin(permissions: string[]): InstalledPlugin {
return {
manifest: { id: "sample", name: "Sample", version: "1.0.0", permissions, drivers: [], contributions: [] },
compatibility: { compatible: true },
} as InstalledPlugin;
}
const workbench = { type: "workbench", id: "sample.main", label: "Sample" } as PluginWorkbenchContribution;
function sandbox() {
const messages: Record<string, unknown>[] = [];
const target = { postMessage: (message: unknown) => messages.push(message as Record<string, unknown>) } as unknown as Window;
return { messages, target };
}
function send(bridge: PluginHostBridge, target: Window, params: unknown, id = "1"): void {
bridge.handleWindowMessage({
source: target,
data: { source: "dbx-plugin", version: 1, type: "request", id, method: "host.getTableMetadata", params },
} as MessageEvent);
}
async function until(check: () => boolean, what: string): Promise<void> {
for (let attempt = 0; attempt < 200; attempt += 1) {
if (check()) return;
await new Promise((resolve) => setTimeout(resolve, 5));
}
throw new Error(`Timed out waiting for ${what}`);
}
test("schema metadata request and response fields match the Rust/TS contract", () => {
assert.deepEqual(rustStructFields(coreSource, "PluginTableContext").map(camelCase), ["connectionId", "database", "schema", "table"]);
assert.deepEqual(rustStructFields(coreSource, "PluginColumnMetadata").map((field) => (field === "default_value" ? "default" : camelCase(field))), [
"name",
"dataType",
"nullable",
"length",
"precision",
"scale",
"default",
]);
assert.deepEqual(rustStructFields(coreSource, "PluginTableMetadata").map(camelCase), ["columns", "fieldCapabilities"]);
assert.ok(manifestSource.includes(`"${PLUGIN_SCHEMA_METADATA_PERMISSION}"`));
assert.ok(manifestSchema.properties.permissions.items.anyOf[0].enum.includes(PLUGIN_SCHEMA_METADATA_PERMISSION));
assert.equal(MAX_PLUGIN_SCHEMA_METADATA_NAME_CHARS, 256);
});
test("the bridge sends only the canonical table context and never reaches an undeclared plugin adapter", async () => {
const { messages, target } = sandbox();
const sent: PluginTableContext[] = [];
const result: PluginTableMetadata = {
columns: [{ name: "id", dataType: "integer", nullable: false }],
fieldCapabilities: { length: "unknown", precision: "unknown", scale: "unknown", default: "unknown" },
};
const bridge = new PluginHostBridge(plugin([PLUGIN_SCHEMA_METADATA_PERMISSION]), workbench, {}, () => target, {
invoke: async <T>() => undefined as T,
notify: async () => undefined,
sendBinary: async () => undefined,
readAsset: async () => ({ dataBase64: "", contentType: "" }),
getTableMetadata: async (context) => {
sent.push(context);
return result;
},
});
send(bridge, target, { connectionId: " c1 ", database: "app", schema: " ", table: " users " });
await until(() => sent.length === 1, "the metadata request");
assert.deepEqual(sent[0], { connectionId: "c1", database: "app", table: "users" });
await until(() => messages.some((message) => message.id === "1"), "the metadata response");
assert.deepEqual(messages.find((message) => message.id === "1")?.result, result);
const denied = sandbox();
let called = false;
const deniedBridge = new PluginHostBridge(plugin([]), workbench, {}, () => denied.target, {
invoke: async <T>() => undefined as T,
notify: async () => undefined,
sendBinary: async () => undefined,
readAsset: async () => ({ dataBase64: "", contentType: "" }),
getTableMetadata: async () => {
called = true;
return result;
},
});
send(deniedBridge, denied.target, { connectionId: "c1", table: "users" }, "denied");
await until(() => denied.messages.length === 1, "the permission rejection");
assert.match(String(denied.messages[0].error), /host\.schema:read/);
assert.equal(called, false);
});
+61 -2
View File
@@ -371,9 +371,10 @@ A workbench opens in a normal persistent DBX tab. The iframe is loaded with `san
- `openWorkbench(contributionId, context)` — requires `host.workbench` - `openWorkbench(contributionId, context)` — requires `host.workbench`
- `openFilesystem(providerId, context)` — requires `host.filesystem` - `openFilesystem(providerId, context)` — requires `host.filesystem`
- `getPlanCapabilities(connectionId)` / `explainPlan(request)` — reads an estimated execution plan for one connection; requires `host.plans:read`, see [Estimated execution plans](#estimated-execution-plans) - `getPlanCapabilities(connectionId)` / `explainPlan(request)` — reads an estimated execution plan for one connection; requires `host.plans:read`, see [Estimated execution plans](#estimated-execution-plans)
- `getTableMetadata({ connectionId, database?, schema?, table })` — reads narrow schema metadata for one table on an already-open connection; requires `host.schema:read`, see [Table Schema Metadata](#table-schema-metadata)
- `storage` — `storage.get(key)` / `storage.set(key, value)` / `storage.delete(key)` persist small JSON state per plugin in `plugin-data/<id>`; requires `host.storage`; values cap at 256 KiB and the whole store at 1 MiB, bulk data belongs in the sidecar's `DBX_PLUGIN_DATA_DIR` - `storage` — `storage.get(key)` / `storage.set(key, value)` / `storage.delete(key)` persist small JSON state per plugin in `plugin-data/<id>`; requires `host.storage`; values cap at 256 KiB and the whole store at 1 MiB, bulk data belongs in the sidecar's `DBX_PLUGIN_DATA_DIR`
- `ai.openConversation({ title, prompt, context, send? })` — opens a plugin conversation in the built-in DBX AI panel from a snapshot the plugin supplies; requires `host.ai`; `title` caps at 200 characters, `prompt` at 32000, and `context` at 2 MiB, and `send` defaults to `false` so pass `true` to start the analysis immediately. The host copies the snapshot into the conversation as history data and never hands model output or model configuration back to the plugin - `ai.openConversation({ title, prompt, context, send? })` — opens a plugin conversation in the built-in DBX AI panel from a snapshot the plugin supplies; requires `host.ai`; `title` caps at 200 characters, `prompt` at 32000, and `context` at 2 MiB, and `send` defaults to `false` so pass `true` to start the analysis immediately. The host copies the snapshot into the conversation as history data and never hands model output or model configuration back to the plugin
- `capabilities` — `{ downloadFile, planApi, storage, ai }` advertised in the init message; a missing or `false` entry means that Host API group is unavailable on this host, so gate the matching call on it instead of probing with a request - `capabilities` — `{ downloadFile, planApi, schemaMetadataApi, storage, ai }` advertised in the init message; a missing or `false` entry means that Host API group is unavailable on this host, so gate the matching call on it instead of probing with a request
- `onEvent(listener)` — events are forwarded only with `host.events` - `onEvent(listener)` — events are forwarded only with `host.events`
- `onBinary(listener)` — binary frames are forwarded only with `host.binary`; listeners receive `{ channel, data: Uint8Array }` - `onBinary(listener)` — binary frames are forwarded only with `host.binary`; listeners receive `{ channel, data: Uint8Array }`
@@ -500,6 +501,64 @@ Every entry has `name`, canonical `uri`, `kind` (`file`, `directory`, `symlink`,
Mutation methods return `{ success, message?, entry? }` and are rejected unless the provider declares the matching capability. Inline read/write payloads are capped at 4 MiB. The built-in file manager currently owns directory navigation, pagination, and bounded file preview. Large upload/download and PTY/SFTP streams use `stdio-framed` binary channels with plugin-defined transfer methods, chunk acknowledgements, cancellation, and progress events; they must not be encoded as one large JSON value. Mutation methods return `{ success, message?, entry? }` and are rejected unless the provider declares the matching capability. Inline read/write payloads are capped at 4 MiB. The built-in file manager currently owns directory navigation, pagination, and bounded file preview. Large upload/download and PTY/SFTP streams use `stdio-framed` binary channels with plugin-defined transfer methods, chunk acknowledgements, cancellation, and progress events; they must not be encoded as one large JSON value.
### Table Schema Metadata
A plugin can read narrow, read-only schema metadata for one table without owning a driver, connection pool, credential, or SQL string. It reuses the canonical `PluginTableContext` identity used by table contributions:
```json
{
"permissions": ["host.schema:read"]
}
```
```js
if (window.dbxPlugin.capabilities.schemaMetadataApi) {
const metadata = await window.dbxPlugin.getTableMetadata({
connectionId,
database,
schema,
table: "users"
});
renderColumns(metadata.columns);
}
```
The result is deliberately narrower than DBX's internal `ColumnInfo`:
```json
{
"columns": [
{
"name": "id",
"dataType": "integer",
"nullable": false,
"precision": 32,
"default": "nextval('users_id_seq'::regclass)"
}
],
"fieldCapabilities": {
"length": "supported",
"precision": "supported",
"scale": "supported",
"default": "supported"
}
}
```
`columns` exposes only `name`, `dataType`, `nullable`, and optional `length`, `precision`, `scale`, and `default`. Comments, keys/indexes, credentials, connection strings, driver objects, and arbitrary SQL results never cross the boundary. Optional values remain omitted or `null`; the host never turns missing metadata into `0` or an empty string. `fieldCapabilities` reports `supported`, `unsupported`, or `unknown` for each structured optional field. `unknown` means DBX lacks reliable provider provenance and must not be treated as support.
`database` and `schema` are optional and omitted when unavailable. `connectionId` and `table` are non-empty, trimmed identity values capped at 256 characters. The host must already hold the matching connection/session: a saved-but-disconnected connection is rejected with `Connection is not open`, and a database without an open matching session is rejected instead of creating a pool or switching connections. The permission grants no arbitrary SQL and no write access.
This is Host API 1.3. A plugin that requires it declares:
```json
{
"engines": { "host_api": "^1.3" }
}
```
The `schemaMetadataApi` capability is runtime detection for older hosts; a plugin should gate the call on it rather than probing the request. Without `host.schema:read`, the bridge rejects the call before the backend adapter runs.
### Estimated execution plans ### Estimated execution plans
A plugin can read the **estimated** execution plan of a query without touching a database driver, a credential, or a connection string. The host builds the `EXPLAIN` statement with its own `build_explain_sql`, applies the same read-only safety gate DBX uses for its own plan view, and executes it on the connection the plugin names. The plugin receives only the raw plan. A plugin can read the **estimated** execution plan of a query without touching a database driver, a credential, or a connection string. The host builds the `EXPLAIN` statement with its own `build_explain_sql`, applies the same read-only safety gate DBX uses for its own plan view, and executes it on the connection the plugin names. The plugin receives only the raw plan.
@@ -692,7 +751,7 @@ Sidecars are shared per plugin process, not spawned per tab. Plugins own their i
- **UI isolation:** sandboxed iframe, restrictive CSP, bounded bridge payloads, safe asset paths, plugin identity binding. - **UI isolation:** sandboxed iframe, restrictive CSP, bounded bridge payloads, safe asset paths, plugin identity binding.
- **Secret persistence:** plugin secrets are removed from connection JSON and stored through DBX's secret-store path. Ordinary cloud-sync snapshots always contain redacted placeholders. Secrets enter sync data only inside the encrypted payload when the user has configured a sync passphrase; without one, plugin secrets remain local and are not synchronized. - **Secret persistence:** plugin secrets are removed from connection JSON and stored through DBX's secret-store path. Ordinary cloud-sync snapshots always contain redacted placeholders. Secrets enter sync data only inside the encrypted payload when the user has configured a sync passphrase; without one, plugin secrets remain local and are not synchronized.
- **Native backend trust:** a native sidecar runs with the current OS user's privileges. A signature identifies the repository that approved and published the package; it is not an OS sandbox or proof that the author is harmless. Install only plugins whose backend code you trust. - **Native backend trust:** a native sidecar runs with the current OS user's privileges. A signature identifies the repository that approved and published the package; it is not an OS sandbox or proof that the author is harmless. Install only plugins whose backend code you trust.
- **Permission declarations:** privileged host bridge operations require declared permissions. Plugin UI network egress is fully blocked except for explicitly declared `host.network:` origins. Native process filesystem/network access cannot currently be completely mediated by DBX. `host.plans:read` grants reading host-generated estimated execution plans only; it never grants SQL execution, writes, DDL, or actual plans. `host.storage` confines the workbench UI to a small JSON store inside its own `plugin-data/<id>` directory; it grants no other filesystem reach. `host.ai` lets a workbench open a built-in AI conversation seeded with a snapshot the plugin supplies; the plugin gets no model output, no model configuration, and no SQL execution out of it. - **Permission declarations:** privileged host bridge operations require declared permissions. Plugin UI network egress is fully blocked except for explicitly declared `host.network:` origins. Native process filesystem/network access cannot currently be completely mediated by DBX. `host.plans:read` grants reading host-generated estimated execution plans only; it never grants SQL execution, writes, DDL, or actual plans. `host.schema:read` grants only narrow metadata for a table on an already-open host connection; it never grants arbitrary SQL, writes, or reconnects. `host.storage` confines the workbench UI to a small JSON store inside its own `plugin-data/<id>` directory; it grants no other filesystem reach. `host.ai` lets a workbench open a built-in AI conversation seeded with a snapshot the plugin supplies; the plugin gets no model output, no model configuration, and no SQL execution out of it.
Custom repository public keys can be added or removed in Plugin Center. Obtain them through a channel independent from the downloaded package. Custom repository public keys can be added or removed in Plugin Center. Obtain them through a channel independent from the downloaded package.
+1 -1
View File
@@ -30,7 +30,7 @@
"uniqueItems": true, "uniqueItems": true,
"items": { "items": {
"anyOf": [ "anyOf": [
{ "enum": ["host.events", "host.binary", "host.workbench", "host.filesystem", "host.plans:read", "host.storage", "host.ai"] }, { "enum": ["host.events", "host.binary", "host.workbench", "host.filesystem", "host.plans:read", "host.schema:read", "host.storage", "host.ai"] },
{ "type": "string", "pattern": "^host\\.network:https://[A-Za-z0-9._-]+(:[0-9]+)?$" } { "type": "string", "pattern": "^host\\.network:https://[A-Za-z0-9._-]+(:[0-9]+)?$" }
] ]
} }
+10
View File
@@ -388,6 +388,16 @@ pub async fn get_columns(
.await .await
} }
/// Read-only Plugin Host API over the existing connection. The core function
/// performs the open-connection gate before entering the ordinary metadata path.
#[tauri::command]
pub async fn get_plugin_table_metadata(
state: State<'_, Arc<AppState>>,
request: dbx_core::schema::plugin_metadata::PluginTableContext,
) -> Result<dbx_core::schema::plugin_metadata::PluginTableMetadata, String> {
dbx_core::schema::plugin_metadata::get_table_metadata(&state, request).await
}
#[tauri::command] #[tauri::command]
pub async fn get_all_columns( pub async fn get_all_columns(
state: State<'_, Arc<AppState>>, state: State<'_, Arc<AppState>>,
+1
View File
@@ -1984,6 +1984,7 @@ pub fn run() {
commands::schema::list_schema_infos, commands::schema::list_schema_infos,
commands::schema::list_data_types, commands::schema::list_data_types,
commands::schema::get_columns, commands::schema::get_columns,
commands::schema::get_plugin_table_metadata,
commands::schema::get_all_columns, commands::schema::get_all_columns,
commands::schema::get_sqlserver_column_metadata, commands::schema::get_sqlserver_column_metadata,
commands::schema::list_indexes, commands::schema::list_indexes,