@floegence/redevplugin-ui 0.6.17 → 0.6.18

package/dist/surface.d.ts

@@ -1,5 +1,4 @@
 import { PluginBridgeError, type PluginMutationOutcome } from "./errors.js";
-import { pluginUIProtocolVersion } from "./contracts.gen.js";
 import { type FetchLike } from "./http.js";
 import { type PluginSurfaceScope } from "./surface-scope.js";
 import { type PluginUIVNode } from "./ui-reconciler.js";
@@ -10,6 +9,7 @@ export type PluginJSONValue = null | boolean | number | string | PluginJSONValue
 export type PluginJSONObject = {
     [key: string]: PluginJSONValue;
 };
+export type PluginUIProtocolVersion = "plugin-ui-v5" | "plugin-ui-v6";
 export type BridgeLifecycleEvent = {
     type: "ready";
 } | {
@@ -29,7 +29,7 @@ export type TrustedParentBridgeHandshake = {
     asset_session_nonce: string;
     management_revision: number;
     revoke_epoch: number;
-    ui_protocol_version: typeof pluginUIProtocolVersion;
+    ui_protocol_version: PluginUIProtocolVersion;
 };
 export type TrustedParentBridgeTokenRequest = {
     bridge_channel_id: string;
@@ -154,6 +154,35 @@ export type PluginStreamReadResult = {
     terminal_status: PluginStreamTerminalStatus;
     retry_after_ms: 0;
 };
+export type PluginExecutionFailureCode = "adapter_failed" | "contract_invalid" | "platform_failed" | "quota_exceeded" | "runtime_failed";
+type PluginOperationSnapshotActive = {
+    operation_id: string;
+    status: "running" | "cancel_requested";
+    cancelable: boolean;
+    created_at: string;
+    updated_at: string;
+    retry_after_ms: number;
+};
+type PluginOperationSnapshotTerminal = {
+    operation_id: string;
+    status: "completed" | "canceled" | "orphaned_after_disable" | "orphaned_after_uninstall";
+    cancelable: boolean;
+    created_at: string;
+    updated_at: string;
+    retry_after_ms: number;
+    terminal_at: string;
+};
+type PluginOperationSnapshotFailed = {
+    operation_id: string;
+    status: "failed";
+    cancelable: boolean;
+    created_at: string;
+    updated_at: string;
+    retry_after_ms: number;
+    terminal_at: string;
+    failure_code: PluginExecutionFailureCode;
+};
+export type PluginOperationSnapshot = PluginOperationSnapshotActive | PluginOperationSnapshotTerminal | PluginOperationSnapshotFailed;
 export type PluginRiskSeverity = "info" | "low" | "medium" | "high" | "critical";
 export type PluginRiskEffect = "read" | "write" | "execute" | "delete" | "admin";
 export type PluginRiskFlag = {
@@ -237,6 +266,7 @@ export declare class PluginBridgeClient {
     call<T = unknown>(method: string, params?: PluginJSONObject, options?: PluginBridgeRequestOptions): Promise<T>;
     readStream(streamHandle: string, options?: PluginBridgeRequestOptions): Promise<PluginStreamReadResult>;
     cancelOperation(operationID: string, reason?: string, options?: PluginBridgeRequestOptions): Promise<void>;
+    operationSnapshot(operationID: string, options?: PluginBridgeRequestOptions): Promise<PluginOperationSnapshot>;
     render(tree: PluginUIVNode): Promise<void>;
     openCanvas(canvasId: string): Promise<PluginCanvasSurface>;
     updateCanvasAccessibility(canvasId: string, state: PluginCanvasAccessibilityState): Promise<void>;
@@ -333,6 +363,7 @@ export type PluginSurfaceHostBootstrap = {
     pluginId: string;
     pluginInstanceId: string;
     pluginVersion: string;
+    uiProtocolVersion: PluginUIProtocolVersion;
     surfaceId: string;
     surfaceInstanceId: string;
     activeFingerprint: string;
@@ -406,6 +437,7 @@ export type ReDevPluginSurfaceTransportOptions = {
 export declare function createReDevPluginSurfaceTransport(options?: ReDevPluginSurfaceTransportOptions): ReDevPluginSurfaceTransport;
 export type OpaquePluginBootstrapHTMLOptions = {
     scriptNonce?: string;
+    uiProtocolVersion?: PluginUIProtocolVersion;
 };
 export type PluginSurfaceQuiesceResult = {
     outcome: "acknowledged" | "not_ready" | "timed_out";

package/dist/surface.js

@@ -171,6 +171,23 @@ export class PluginBridgeClient {
             reason,
         }), { mutation: true, signal: options.signal });
     }
+    operationSnapshot(operationID, options = {}) {
+        this.#assertActive();
+        if (!validOpaqueHandle(operationID, "operation")) {
+            throw new PluginBridgeError("PLUGIN_INVALID_REQUEST", "Plugin operation handle is invalid");
+        }
+        const id = this.#requestID("operation");
+        return this.#request(id, {
+            type: "redevplugin.bridge.operation.snapshot",
+            id,
+            operation_id: operationID,
+        }, { signal: options.signal }).then((snapshot) => {
+            if (!isPluginOperationSnapshot(snapshot) || snapshot.operation_id !== operationID) {
+                throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin operation snapshot is invalid");
+            }
+            return snapshot;
+        });
+    }
     render(tree) {
         this.#assertActive();
         let validated;
@@ -714,6 +731,10 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     if (!/^[A-Za-z0-9_-]{8,128}$/.test(scriptNonce)) {
         throw new Error("scriptNonce must contain 8-128 URL-safe characters");
     }
+    const uiProtocolVersion = options.uiProtocolVersion ?? pluginUIProtocolVersion;
+    if (uiProtocolVersion !== "plugin-ui-v5" && uiProtocolVersion !== "plugin-ui-v6") {
+        throw new Error("uiProtocolVersion must be plugin-ui-v5 or plugin-ui-v6");
+    }
     const csp = [
         "default-src 'none'",
         `script-src 'nonce-${scriptNonce}'`,
@@ -732,7 +753,7 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     ].join("; ");
     const bootstrapScript = `(() => {
   "use strict";
-  const protocolVersion = ${JSON.stringify(pluginUIProtocolVersion)};
+  const protocolVersion = ${JSON.stringify(uiProtocolVersion)};
   const documentSchema = ${JSON.stringify(opaqueSurfaceDocumentSchemaVersion)};
   const workerGlobalKey = ${JSON.stringify(opaquePluginBridgeGlobalKey)};
   const scriptNonce = ${JSON.stringify(scriptNonce)};
@@ -859,6 +880,13 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
   let pendingQuiesceID;
   const pendingWorkerRequests = new Set();
   const requestSequence = { rpc: 0, stream: 0, stream_ack: 0, render: 0, operation: 0, canvas: 0, asset: 0 };
+  let operationSnapshotSurfaceTokens = 8;
+  let operationSnapshotSurfaceRefillAt = performance.now();
+  const operationSnapshotStateIdleMS = 120000;
+  let operationSnapshotNextPruneAt = performance.now() + 30000;
+  const maxOperationSnapshotStates = 1024;
+  const operationSnapshotStates = new Map();
+  const operationSnapshotRequests = new Map();
   let renderWindowStartedAt = 0;
   let renderCount = 0;
   let uiRevision = 0;
@@ -968,6 +996,8 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     for (const url of blobURLs) URL.revokeObjectURL(url);
     blobURLs.clear();
     pendingWorkerRequests.clear();
+    operationSnapshotStates.clear();
+    operationSnapshotRequests.clear();
     pendingAssets.clear();
     queuedAssets.length = 0;
     activeAssetReads = 0;
@@ -1950,6 +1980,48 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
     return true;
   };
   const completeWorkerRequest = (id) => pendingWorkerRequests.delete(id);
+  const completeOperationSnapshotRequest = (id) => {
+    const operationID = operationSnapshotRequests.get(id);
+    operationSnapshotRequests.delete(id);
+    const state = operationSnapshotStates.get(operationID);
+    if (state) { state.inFlight = false; state.lastSeen = performance.now(); }
+    completeWorkerRequest(id);
+  };
+  const refillSnapshotTokens = (tokens, refillAt, rate, burst, now) => ({
+    tokens: Math.min(burst, tokens + Math.max(0, now - refillAt) * rate / 1000),
+    refillAt: Math.max(refillAt, now),
+  });
+  const operationSnapshotRateLimit = (operationID, requestID) => {
+    const now = performance.now();
+    const surface = refillSnapshotTokens(operationSnapshotSurfaceTokens, operationSnapshotSurfaceRefillAt, 8, 8, now);
+    operationSnapshotSurfaceTokens = surface.tokens;
+    operationSnapshotSurfaceRefillAt = surface.refillAt;
+    if (operationSnapshotSurfaceTokens < 1) return Math.max(500, Math.min(10000, Math.ceil((1 - operationSnapshotSurfaceTokens) / 8 * 1000)));
+    operationSnapshotSurfaceTokens -= 1;
+    let existing = operationSnapshotStates.get(operationID);
+    if (!existing) {
+      if (now >= operationSnapshotNextPruneAt) {
+        for (const [retainedOperationID, state] of operationSnapshotStates) {
+          if (!state.inFlight && now - state.lastSeen >= operationSnapshotStateIdleMS) operationSnapshotStates.delete(retainedOperationID);
+        }
+        operationSnapshotNextPruneAt = now + 30000;
+      }
+      if (operationSnapshotStates.size >= maxOperationSnapshotStates) return 10000;
+      existing = { tokens: 2, refillAt: now, lastSeen: now, inFlight: false };
+      operationSnapshotStates.set(operationID, existing);
+    }
+    const operation = refillSnapshotTokens(existing.tokens, existing.refillAt, 2, 2, now);
+    existing.tokens = operation.tokens;
+    existing.refillAt = operation.refillAt;
+    existing.lastSeen = now;
+    let retryAfterMS = existing.inFlight ? 500 : 0;
+    if (existing.tokens < 1) retryAfterMS = Math.max(retryAfterMS, Math.ceil((1 - existing.tokens) / 2 * 1000));
+    if (retryAfterMS > 0) return Math.max(500, Math.min(10000, retryAfterMS));
+    existing.tokens -= 1;
+    existing.inFlight = true;
+    operationSnapshotRequests.set(requestID, operationID);
+    return 0;
+  };
   const renderRateAllowed = () => {
     const now = performance.now();
     if (now - renderWindowStartedAt >= 1000) { renderWindowStartedAt = now; renderCount = 0; }
@@ -2181,6 +2253,18 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
       sendParent(message);
       return;
     }
+    if (exactKeys(message, ["type", "id", "operation_id"]) && message.type === "redevplugin.bridge.operation.snapshot" &&
+        typeof message.id === "string" && validOpaqueHandle(message.operation_id, "operation")) {
+      if (protocolVersion !== "plugin-ui-v6") return rejectWorkerRequest(message.id, "plugin operation observation requires plugin-ui-v6");
+      if (!acceptWorkerRequest(message.id, "operation")) return rejectWorkerRequest(message.id, "duplicate, replayed, or excessive plugin request");
+      const retryAfterMS = operationSnapshotRateLimit(message.operation_id, message.id);
+      if (retryAfterMS > 0) {
+        completeWorkerRequest(message.id);
+        return sendWorker({ type: "redevplugin.bridge.response", id: message.id, ok: false, error_code: "PLUGIN_OPERATION_RATE_LIMITED", error: "plugin operation snapshot rate limited", error_details: { retry_after_ms: retryAfterMS } });
+      }
+      sendParent(message);
+      return;
+    }
     if (exactKeys(message, ["type", "id", "canvas_id"]) && message.type === "redevplugin.ui.canvas.open" && typeof message.id === "string" && validResourceIdentifier(message.canvas_id)) {
       if (!acceptWorkerRequest(message.id, "canvas")) return rejectWorkerRequest(message.id, "duplicate, replayed, or excessive plugin request");
       openCanvas(message.id, message.canvas_id);
@@ -2234,8 +2318,10 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
         completeWorkerRequest(message.id);
         return;
       }
-      completeWorkerRequest(message.id);
+      if (operationSnapshotRequests.has(message.id)) completeOperationSnapshotRequest(message.id);
+      else completeWorkerRequest(message.id);
       sendParent(message);
+      return;
     }
   };
   const onParentMessage = async (event) => {
@@ -2254,7 +2340,8 @@ export function createOpaquePluginBootstrapHTML(options = {}) {
       return;
     }
     if (message && message.type === "redevplugin.bridge.response" && typeof message.id === "string" && pendingWorkerRequests.has(message.id) && withinLimit(message)) {
-      completeWorkerRequest(message.id);
+	  if (operationSnapshotRequests.has(message.id)) completeOperationSnapshotRequest(message.id);
+	  else completeWorkerRequest(message.id);
       sendWorker(message);
       return;
     }
@@ -2414,7 +2501,7 @@ class PluginSurfaceHostImplementation {
         this.#initialFrameLoad = initialFrameLoad;
         this.#iframe.addEventListener("load", this.#onFrameLoad);
         hardenPluginSurfaceFrame(this.#iframe);
-        this.#iframe.srcdoc = createOpaquePluginBootstrapHTML({ scriptNonce });
+        this.#iframe.srcdoc = createOpaquePluginBootstrapHTML({ scriptNonce, uiProtocolVersion: this.bootstrap.uiProtocolVersion });
         try {
             await withTimeout(this.#completeOpening(signals, initialFrameLoad.promise), this.#loadTimeoutMs, "Plugin surface opening timed out");
         }
@@ -2453,7 +2540,7 @@ class PluginSurfaceHostImplementation {
         iframeWindow.postMessage({
             type: "redevplugin.surface.port",
             frame_generation_id: this.frameGenerationId,
-            ui_protocol_version: pluginUIProtocolVersion,
+            ui_protocol_version: this.bootstrap.uiProtocolVersion,
         }, "*", [channel.port2]);
         await signals.portAcknowledged.promise;
         this.#assertActive();
@@ -2645,6 +2732,10 @@ class PluginSurfaceHostImplementation {
                 await this.#handleOperationCancel(data);
                 return;
             }
+            if (isOperationSnapshotMessage(data)) {
+                await this.#handleOperationSnapshot(data);
+                return;
+            }
             if (isAssetReadMessage(data)) {
                 await this.#handleAssetRead(data);
             }
@@ -2872,6 +2963,30 @@ class PluginSurfaceHostImplementation {
             this.#pendingRequestControllers.delete(message.id);
         }
     }
+    async #handleOperationSnapshot(message) {
+        if (this.bootstrap.uiProtocolVersion !== "plugin-ui-v6") {
+            this.#postError(message.id, "PLUGIN_UI_PROTOCOL_UNSUPPORTED", "Plugin operation observation requires plugin-ui-v6");
+            return;
+        }
+        const controller = this.#registerPendingRequest(message.id);
+        try {
+            const snapshot = await this.#postJSON(`/_redevplugin/api/plugins/surfaces/${encodeURIComponent(this.bootstrap.surfaceInstanceId)}/operations/query`, { operation_id: message.operation_id, bridge_channel_id: this.bridgeChannelId }, controller.signal);
+            if (!isPluginOperationSnapshot(snapshot) || snapshot.operation_id !== message.operation_id) {
+                throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin operation snapshot endpoint returned an invalid response");
+            }
+            if (!controller.signal.aborted && !this.#disposed)
+                this.#postResponse(message.id, snapshot);
+        }
+        catch (error) {
+            if (controller.signal.aborted || this.#disposed)
+                return;
+            const bridgeError = toBridgeError(error, "PLUGIN_OPERATION_NOT_FOUND");
+            this.#postError(message.id, bridgeError.errorCode, bridgeError.message, bridgeError.details, bridgeError.mutationOutcome);
+        }
+        finally {
+            this.#pendingRequestControllers.delete(message.id);
+        }
+    }
     async #handleAssetRead(message) {
         if (this.#activeAssetReads >= maxConcurrentAssetReads) {
             throw new PluginBridgeError("PLUGIN_INVALID_REQUEST", "Plugin asset reads exceed the concurrency limit");
@@ -3017,7 +3132,7 @@ class PluginSurfaceHostImplementation {
             asset_session_nonce: this.bootstrap.assetSessionNonce,
             management_revision: this.bootstrap.managementRevision,
             revoke_epoch: this.bootstrap.revokeEpoch,
-            ui_protocol_version: pluginUIProtocolVersion,
+            ui_protocol_version: this.bootstrap.uiProtocolVersion,
         };
     }
     async #postJSON(path, body, signal) {
@@ -3830,6 +3945,7 @@ function validateHostBootstrap(bootstrap) {
         bootstrap.pluginId,
         bootstrap.pluginInstanceId,
         bootstrap.pluginVersion,
+        bootstrap.uiProtocolVersion,
         bootstrap.surfaceId,
         bootstrap.surfaceInstanceId,
         bootstrap.activeFingerprint,
@@ -3844,6 +3960,9 @@ function validateHostBootstrap(bootstrap) {
             throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin surface bootstrap is incomplete");
         }
     }
+    if (bootstrap.uiProtocolVersion !== "plugin-ui-v5" && bootstrap.uiProtocolVersion !== "plugin-ui-v6") {
+        throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin surface UI protocol is unsupported");
+    }
     if (!Number.isSafeInteger(bootstrap.managementRevision) || bootstrap.managementRevision < 1 ||
         !Number.isSafeInteger(bootstrap.revokeEpoch) || bootstrap.revokeEpoch < 1) {
         throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin surface revision is invalid");
@@ -3965,6 +4084,29 @@ function isOperationCancelMessage(value) {
         validOpaqueHandle(value.operation_id, "operation") &&
         (value.reason === undefined || (typeof value.reason === "string" && value.reason.length <= 256));
 }
+function isOperationSnapshotMessage(value) {
+    return hasExactKeys(value, ["type", "id", "operation_id"]) &&
+        value.type === "redevplugin.bridge.operation.snapshot" &&
+        validBridgeRequestID(value.id, "operation") &&
+        validOpaqueHandle(value.operation_id, "operation");
+}
+function isPluginOperationSnapshot(value) {
+    if (!isRecord(value) || !validOpaqueHandle(value.operation_id, "operation") || typeof value.cancelable !== "boolean" ||
+        !Number.isInteger(value.retry_after_ms) || Number(value.retry_after_ms) < 500 || Number(value.retry_after_ms) > 10000 ||
+        !validDateTime(value.created_at) || !validDateTime(value.updated_at))
+        return false;
+    const common = ["operation_id", "status", "cancelable", "created_at", "updated_at", "retry_after_ms"];
+    if (value.status === "running" || value.status === "cancel_requested")
+        return hasExactKeys(value, common);
+    if (["completed", "canceled", "orphaned_after_disable", "orphaned_after_uninstall"].includes(String(value.status))) {
+        return hasExactKeys(value, [...common, "terminal_at"]) && validDateTime(value.terminal_at);
+    }
+    return value.status === "failed" && hasExactKeys(value, [...common, "terminal_at", "failure_code"]) &&
+        validDateTime(value.terminal_at) && ["adapter_failed", "contract_invalid", "platform_failed", "quota_exceeded", "runtime_failed"].includes(String(value.failure_code));
+}
+function validDateTime(value) {
+    return typeof value === "string" && value.length > 0 && Number.isFinite(Date.parse(value));
+}
 function isBridgeCancelMessage(value) {
     return hasExactKeys(value, ["type", "id"]) &&
         value.type === "redevplugin.bridge.cancel" &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/redevplugin-ui",
-  "version": "0.6.17",
+  "version": "0.6.18",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -32,7 +32,7 @@
     "dist"
   ],
   "dependencies": {
-    "@floegence/redevplugin-contracts": "0.6.17"
+    "@floegence/redevplugin-contracts": "0.6.18"
   },
   "publishConfig": {
     "access": "public"