feat(plugins): expose read-only estimated plan host api
This commit is contained in:
1 parent
ea16af7f28
commit
f909f85075
23 files changed
+2059
-17
No files matched your search
@@ -1,5 +1,6 @@
|
||||
import type { InstalledPlugin, PluginBinaryEvent, PluginEvent, PluginUiAssetPayload, PluginUiContribution } from "@/types/database";
|
||||
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";
|
||||
|
||||
const PLUGIN_MESSAGE_SOURCE = "dbx-plugin";
|
||||
const HOST_MESSAGE_SOURCE = "dbx-host";
|
||||
@@ -9,6 +10,8 @@ const MAX_BRIDGE_BINARY_BYTES = 8 * 1024 * 1024;
|
||||
// Distinct from the sidecar binary cap: saved files go straight from the
|
||||
// plugin iframe to disk and never traverse plugin frames.
|
||||
const MAX_BRIDGE_SAVE_BYTES = 512 * 1024 * 1024;
|
||||
// Mirrors MAX_PLUGIN_PLAN_NAME_CHARS in crates/dbx-core/src/query/plugin_plan.rs.
|
||||
const MAX_PLUGIN_PLAN_IDENTIFIER_CHARS = 256;
|
||||
|
||||
/** Structured editor appearance: SQL editor settings that have no CSS-token
|
||||
* carrier (font size is a number, the syntax theme an id). Font families are
|
||||
@@ -58,6 +61,17 @@ export interface PluginHostBridgeApi {
|
||||
openFilesystem?(pluginId: string, providerId: string, context?: PluginWorkbenchContext): Promise<void> | void;
|
||||
/** Explicit user-triggered reconnect of an owned plugin connection (full flow, interactive password prompt allowed). */
|
||||
reopenConnection?(pluginId: string, connectionId: string): Promise<void>;
|
||||
/**
|
||||
* Estimated plan capability metadata for one connection. Requires the plugin
|
||||
* to declare `host.plans:read`. The host only reads the stored connection
|
||||
* config; it never connects or probes the server.
|
||||
*/
|
||||
getPlanCapabilities?(connectionId: string): Promise<PluginPlanCapabilities>;
|
||||
/**
|
||||
* Read-only estimated plan acquisition. Requires `host.plans:read`. The host
|
||||
* generates and owns the EXPLAIN statement; the plugin cannot pass one.
|
||||
*/
|
||||
explainPlan?(request: PluginPlanRequest): Promise<PluginPlanResult>;
|
||||
closeTab?(): Promise<void> | void;
|
||||
/** Persist plugin bytes through the host's native save dialog. Resolves null when the user cancels. */
|
||||
saveFile?(pluginId: string, request: PluginSaveFileRequest, data: Uint8Array): Promise<PluginSaveFileResult | null>;
|
||||
@@ -177,7 +191,9 @@ export class PluginHostBridge {
|
||||
locale: this.locale,
|
||||
theme: this.theme ? clonePluginData(this.theme) : undefined,
|
||||
permissions: [...(this.plugin.manifest.permissions || [])],
|
||||
capabilities: { downloadFile: !!this.api.downloadFile },
|
||||
// Additive capability advertisement: an older host omits `planApi`, and a
|
||||
// plugin must treat the absence as "unsupported" rather than probing.
|
||||
capabilities: { downloadFile: !!this.api.downloadFile, planApi: !!this.api.getPlanCapabilities && !!this.api.explainPlan },
|
||||
context: snapshotPluginWorkbenchContext(this.context),
|
||||
});
|
||||
}
|
||||
@@ -297,6 +313,17 @@ export class PluginHostBridge {
|
||||
await this.api.openFilesystem(this.plugin.manifest.id, requireProtocolName(input.providerId, "filesystem provider"), isRecord(input.context) ? input.context : undefined);
|
||||
return null;
|
||||
}
|
||||
if (method === "host.getPlanCapabilities") {
|
||||
this.requirePermission(PLUGIN_PLAN_PERMISSION);
|
||||
if (!this.api.getPlanCapabilities) throw new Error("Host plan API is unavailable");
|
||||
const input = requireRecord(params, "host.getPlanCapabilities params");
|
||||
return this.api.getPlanCapabilities(requirePluginPlanIdentifier(input.connectionId, "connectionId"));
|
||||
}
|
||||
if (method === "host.explainPlan") {
|
||||
this.requirePermission(PLUGIN_PLAN_PERMISSION);
|
||||
if (!this.api.explainPlan) throw new Error("Host plan API is unavailable");
|
||||
return this.api.explainPlan(requirePluginPlanRequest(requireRecord(params, "host.explainPlan params")));
|
||||
}
|
||||
if (method === "host.saveFile") {
|
||||
const input = isRecord(params) ? params : {};
|
||||
// The sandboxed iframe cannot trigger downloads (WKWebView cancels blob
|
||||
@@ -606,6 +633,10 @@ export function pluginSdkSource(initialTheme?: PluginBridgeTheme): string {
|
||||
openWorkbench: (contributionId, childContext, options) => request('host.openWorkbench', { contributionId, context: childContext, forceNew: !!(options && options.forceNew) }),
|
||||
openFilesystem: (providerId, childContext) => request('host.openFilesystem', { providerId, context: childContext }),
|
||||
reopenConnection: (connectionId) => request('host.reopenConnection', { connectionId }),
|
||||
// Estimated plans only: mode must be sent explicitly so a plugin states
|
||||
// its intent, and the host refuses anything other than "estimated".
|
||||
getPlanCapabilities: (connectionId) => request('host.getPlanCapabilities', { connectionId }),
|
||||
explainPlan: (planRequest) => request('host.explainPlan', planRequest),
|
||||
saveFile: (options = {}, data) => {
|
||||
if (data === undefined) return request('host.saveFile', options);
|
||||
if (typeof data === 'string') return request('host.saveFile', { ...(options || {}), dataBase64: data });
|
||||
@@ -687,6 +718,59 @@ function requireTimeout(value: unknown): number {
|
||||
return Math.min(120_000, Math.max(1, Math.round(value)));
|
||||
}
|
||||
|
||||
/** A connection id, database, or schema name: bounded, trimmed, never empty. */
|
||||
function requirePluginPlanIdentifier(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 (identifier.length > MAX_PLUGIN_PLAN_IDENTIFIER_CHARS) {
|
||||
throw new Error(`${label} must be at most ${MAX_PLUGIN_PLAN_IDENTIFIER_CHARS} characters`);
|
||||
}
|
||||
return identifier;
|
||||
}
|
||||
|
||||
function optionalPluginPlanScope(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() ? requirePluginPlanIdentifier(value, label) : undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates one `host.explainPlan` request. The host owns the EXPLAIN text, so
|
||||
* the only accepted shape is the caller's own SQL plus a connection reference
|
||||
* and an explicit `estimated` mode; anything else is refused here rather than
|
||||
* forwarded and downgraded. The backend re-checks every one of these bounds.
|
||||
*/
|
||||
function requirePluginPlanRequest(input: Record<string, unknown>): PluginPlanRequest {
|
||||
if (input.mode !== "estimated") throw new Error('host.explainPlan serves mode "estimated" only');
|
||||
if (typeof input.sql !== "string") throw new Error("host.explainPlan requires sql");
|
||||
const sql = input.sql.trim();
|
||||
if (!sql) throw new Error("host.explainPlan requires a non-empty sql");
|
||||
if (sql.length > MAX_PLUGIN_PLAN_SQL_CHARS) {
|
||||
throw new Error(`sql must be at most ${MAX_PLUGIN_PLAN_SQL_CHARS} characters`);
|
||||
}
|
||||
|
||||
const request: PluginPlanRequest = {
|
||||
connectionId: requirePluginPlanIdentifier(input.connectionId, "connectionId"),
|
||||
sql,
|
||||
mode: "estimated",
|
||||
};
|
||||
const database = optionalPluginPlanScope(input.database, "database");
|
||||
if (database !== undefined) request.database = database;
|
||||
const schema = optionalPluginPlanScope(input.schema, "schema");
|
||||
if (schema !== undefined) request.schema = schema;
|
||||
if (input.timeoutMs !== undefined && input.timeoutMs !== null) {
|
||||
request.timeoutMs = clampPluginPlanTimeout(input.timeoutMs);
|
||||
}
|
||||
return request;
|
||||
}
|
||||
|
||||
/** Pre-clamps to the host ceiling; the backend additionally clamps to the connection's own timeout. */
|
||||
function clampPluginPlanTimeout(value: unknown): number {
|
||||
if (typeof value !== "number" || !Number.isFinite(value)) throw new Error("timeoutMs must be a number");
|
||||
return Math.min(MAX_PLUGIN_PLAN_TIMEOUT_MS, Math.max(1, Math.round(value)));
|
||||
}
|
||||
|
||||
function base64ToBytes(value: string): ArrayBuffer {
|
||||
const binary = atob(value);
|
||||
const bytes = new Uint8Array(binary.length);
|
||||
|
||||
Reference in new issue
Block a user