@zhin.js/isolate 1.0.7 → 1.0.10

package/README.md

@@ -2,8 +2,6 @@
 
 下一代 Zhin Runtime 的可选 Node 隔离适配器。它为每个 `runtime: isolated` Plugin generation 创建独立 Worker 或 child process，并只通过 structured-clone RPC 与 Host 通信。
 
-> 当前包属于 `feature/next` 绿地实现，版本仍为 `0.0.0` 且未作为稳定 API 发布。
-
 ## 为什么独立成包
 
 `@zhin.js/runtime` 只定义 `IsolatedPluginRuntimePort`，不强制默认 IM 安装携带隔离实现。需要故障或并发隔离的 Root 显式安装本包；trusted Plugin 的启动路径和生产闭包不变。
@@ -71,13 +69,12 @@ Host 从对应 owner 的 Resource snapshot 取得 `isolatedPluginToken`，再调
 
 ## 代际切换
 
-适配器参与 Runtime generation handoff：
+隔离进程参与 Runtime generation readiness：
 
 1. `prepare` 创建候选 isolate、import entry 并校验 definition，但不执行 setup。
-2. `quiescePrevious` 停止旧 handle 接收新调用，并等待所有已接收 RPC 完成。
-3. `activateNext` 在候选 isolate 内执行 setup；失败会清理候选并恢复旧 handle。
-4. Runtime 原子提交 snapshot 后，`openNext` 才开放新 handle。
-5. 旧 generation 的最后一个 lease 释放后，Scope disposer 终止旧 isolate。
+2. `activateNext(signal)` 在候选 isolate 内执行 setup；失败会清理候选，旧代从未被触碰。
+3. Runtime 原子提交 snapshot 后，新请求才能从新 snapshot 取得 handle。
+4. 旧 generation 的在途请求继续持有旧 lease；最后一个 lease 释放后，Scope disposer 终止旧 isolate。
 
 RPC 超时会把整个实例标记为 failed 并终止 transport，因为远端工作可能仍在运行，不能把超时伪装成安全 drain。Worker/进程意外退出会拒绝全部 pending RPC，并通过 `onCrash` 上报；当前 generation 内不静默重启。
 

package/lib/contracts.d.ts

@@ -1,5 +1,5 @@
 import { type Dispose, type PluginId } from '@zhin.js/plugin-runtime';
-export type IsolatedPluginStatus = 'prepared' | 'active' | 'quiesced' | 'failed' | 'closed';
+export type IsolatedPluginStatus = 'prepared' | 'active' | 'failed' | 'closed';
 export interface IsolatedPluginEvent {
     readonly name: string;
     readonly payload: unknown;

package/lib/runtime.d.ts

@@ -1,4 +1,4 @@
-import type { PluginId } from '@zhin.js/plugin-runtime';
+import { type PluginId } from '@zhin.js/plugin-runtime';
 import type { IsolatedPluginPrepareRequest, IsolatedPluginRuntimePort, PreparedIsolatedPlugin } from '@zhin.js/runtime';
 import { type IsolateMode } from './transport.js';
 export interface IsolatedHostCallContext {
@@ -15,5 +15,5 @@ export interface NodeIsolatedPluginRuntimeOptions {
 export declare class NodeIsolatedPluginRuntime implements IsolatedPluginRuntimePort {
     #private;
     constructor(options?: NodeIsolatedPluginRuntimeOptions);
-    prepare(request: IsolatedPluginPrepareRequest): Promise<PreparedIsolatedPlugin>;
+    prepare(request: IsolatedPluginPrepareRequest, signal: AbortSignal): Promise<PreparedIsolatedPlugin>;
 }

package/lib/runtime.js

@@ -1,4 +1,5 @@
 import { pathToFileURL } from 'node:url';
+import { createGenerationAdmissionGate, generationAdmissionSource, } from '@zhin.js/plugin-runtime';
 import { isolatedPluginToken, } from './contracts.js';
 import { deserializeError, serializeError, } from './protocol.js';
 import { createTransport } from './transport.js';
@@ -8,43 +9,28 @@ export class NodeIsolatedPluginRuntime {
     #requestTimeoutMs;
     #hostMethods;
     #onCrash;
-    #quiescedPrevious = new Map();
     constructor(options = {}) {
         this.#mode = options.mode ?? 'worker';
         this.#requestTimeoutMs = options.requestTimeoutMs ?? 10_000;
         this.#hostMethods = Object.freeze({ ...options.hostMethods });
         this.#onCrash = options.onCrash;
     }
-    async prepare(request) {
+    async prepare(request, signal) {
+        signal.throwIfAborted();
         assertCloneable(request.config, `Config for ${request.owner}`);
-        const instance = new IsolatedInstance(request.owner, createTransport(this.#mode), this.#requestTimeoutMs, this.#hostMethods, this.#onCrash);
+        const admission = createGenerationAdmissionGate();
+        const instance = new IsolatedInstance(request.owner, createTransport(this.#mode), this.#requestTimeoutMs, this.#hostMethods, this.#onCrash, admission);
         try {
-            const descriptor = await instance.request('prepare', {
+            const descriptor = await instance.requestAbortable('prepare', {
                 ...request,
                 entry: pathToFileURL(request.entry).href,
-            });
+            }, signal);
             return {
                 descriptor,
                 resources: [{ token: isolatedPluginToken, value: instance }],
                 handoff: {
-                    quiescePrevious: async (previous) => {
-                        const handle = previous.resources.get(request.owner)?.get(isolatedPluginToken.id);
-                        if (!(handle instanceof IsolatedInstance))
-                            return;
-                        await handle.quiesce();
-                        this.#quiescedPrevious.set(request.owner, handle);
-                    },
-                    activateNext: () => instance.activate(),
+                    activateNext: (activationSignal) => instance.activate(activationSignal),
                     deactivateNext: () => instance.deactivate(),
-                    resumePrevious: () => {
-                        const previous = this.#quiescedPrevious.get(request.owner);
-                        this.#quiescedPrevious.delete(request.owner);
-                        previous?.resume();
-                    },
-                    openNext: () => {
-                        instance.open();
-                        this.#quiescedPrevious.delete(request.owner);
-                    },
                 },
                 dispose: () => instance.close(),
             };
@@ -61,25 +47,28 @@ class IsolatedInstance {
     timeoutMs;
     hostMethods;
     onCrash;
+    admission;
+    [generationAdmissionSource];
     #status = 'prepared';
     #nextRequest = 1;
-    #inFlight = 0;
-    #drainWaiters = [];
     #closed = false;
     #pending = new Map();
     #listeners = new Set();
-    constructor(owner, transport, timeoutMs, hostMethods, onCrash) {
+    constructor(owner, transport, timeoutMs, hostMethods, onCrash, admission = createGenerationAdmissionGate()) {
         this.owner = owner;
         this.transport = transport;
         this.timeoutMs = timeoutMs;
         this.hostMethods = hostMethods;
         this.onCrash = onCrash;
+        this.admission = admission;
+        this[generationAdmissionSource] = Object.freeze([admission]);
         transport.onMessage((message) => this.#onMessage(message));
         transport.onExit((error) => this.#fail(error));
     }
     get status() { return this.#status; }
-    async activate() {
-        await this.request('activate');
+    async activate(signal) {
+        await this.requestAbortable('activate', undefined, signal);
+        this.#status = 'active';
     }
     async deactivate() {
         if (this.#closed || this.#status === 'failed')
@@ -87,40 +76,14 @@ class IsolatedInstance {
         await this.request('deactivate');
         this.#status = 'prepared';
     }
-    open() {
-        if (this.#closed || this.#status === 'failed')
-            throw new Error(`Cannot open ${this.owner}`);
-        this.#status = 'active';
-    }
-    async quiesce() {
-        if (this.#status !== 'active')
-            return;
-        this.#status = 'quiesced';
-        if (this.#inFlight === 0)
-            return;
-        await new Promise((resolve) => this.#drainWaiters.push(resolve));
-    }
-    resume() {
-        if (this.#status === 'quiesced')
-            this.#status = 'active';
-    }
     async call(method, input) {
         if (this.#status !== 'active') {
             throw new Error(`Isolated Plugin ${this.owner} is not accepting calls: ${this.#status}`);
         }
         assertMethod(method);
         assertCloneable(input, `Input for ${method}`);
-        this.#inFlight += 1;
-        try {
-            return await this.request('call', { method, input });
-        }
-        finally {
-            this.#inFlight -= 1;
-            if (this.#inFlight === 0) {
-                for (const resolve of this.#drainWaiters.splice(0))
-                    resolve();
-            }
-        }
+        return this.admission.enter(() => this.request('call', { method, input }))
+            ?? Promise.reject(new Error(`Isolated Plugin ${this.owner} generation is not admitted`));
     }
     onEvent(listener) {
         this.#listeners.add(listener);
@@ -148,6 +111,26 @@ class IsolatedInstance {
             this.transport.send({ type: 'request', id, method, payload });
         });
     }
+    async requestAbortable(method, payload, signal) {
+        signal.throwIfAborted();
+        let abort;
+        const aborted = new Promise((_resolve, reject) => {
+            abort = () => {
+                const reason = signal.reason instanceof Error
+                    ? signal.reason
+                    : new Error(`Isolated request aborted: ${method}`);
+                this.#fail(reason);
+                void this.transport.close().then(() => reject(reason), (closeError) => reject(new AggregateError([reason, closeError], `Isolated request cancellation failed: ${method}`)));
+            };
+        });
+        signal.addEventListener('abort', abort, { once: true });
+        try {
+            return await Promise.race([this.request(method, payload), aborted]);
+        }
+        finally {
+            signal.removeEventListener('abort', abort);
+        }
+    }
     async close() {
         if (this.#closed)
             return;
@@ -176,21 +159,29 @@ class IsolatedInstance {
             return;
         }
         if (message.type === 'event') {
-            const event = Object.freeze({ name: message.name, payload: message.payload });
-            for (const listener of this.#listeners)
-                listener(event);
+            this.admission.enter(() => {
+                const event = Object.freeze({ name: message.name, payload: message.payload });
+                for (const listener of this.#listeners)
+                    listener(event);
+            });
             return;
         }
         void this.#handleHostCall(message);
     }
     async #handleHostCall(message) {
-        const method = this.hostMethods[message.method];
         try {
-            if (!method)
-                throw new Error(`Host RPC method is not allowed: ${message.method}`);
-            const value = await method(message.input, { owner: this.owner });
-            assertCloneable(value, `Host RPC result for ${message.method}`);
-            this.transport.send({ type: 'host-result', id: message.id, ok: true, value });
+            const handled = this.admission.enter(async () => {
+                const method = this.hostMethods[message.method];
+                if (!method)
+                    throw new Error(`Host RPC method is not allowed: ${message.method}`);
+                const value = await method(message.input, { owner: this.owner });
+                assertCloneable(value, `Host RPC result for ${message.method}`);
+                this.transport.send({ type: 'host-result', id: message.id, ok: true, value });
+            });
+            if (!handled) {
+                throw new Error(`Isolated Plugin ${this.owner} generation is not admitted`);
+            }
+            await handled;
         }
         catch (error) {
             this.transport.send({
@@ -206,8 +197,6 @@ class IsolatedInstance {
             return;
         this.#status = 'failed';
         this.#rejectPending(error);
-        for (const resolve of this.#drainWaiters.splice(0))
-            resolve();
         this.onCrash?.(this.owner, error);
     }
     #rejectPending(error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/isolate",
-  "version": "1.0.7",
+  "version": "1.0.10",
   "description": "Worker and child-process isolation adapter for the Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -16,8 +16,8 @@
     "lib"
   ],
   "dependencies": {
-    "@zhin.js/plugin-runtime": "1.1.3",
-    "@zhin.js/runtime": "1.0.7"
+    "@zhin.js/plugin-runtime": "1.1.6",
+    "@zhin.js/runtime": "1.0.10"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",