yeow-api 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "yeow-api",
-    "version": "0.5.0",
+    "version": "0.6.0",
     "description": "Yeow API",
     "type": "module",
     "main": "./src/index.ts",

package/src/core.ts

@@ -80,8 +80,8 @@ export { get as pdcGet, set as pdcSet, has as pdcHas, remove as pdcRemove, keys
 export { add as addRecipe, remove as removeRecipe, getForItem as getRecipesForItem } from './recipe.js';
 export { Material, getMaterials, getBlocks, getItems } from './material.js';
 export type { MaterialInfo } from './material.js';
-export { registerService, registerNativeService, request as serviceRequest, subscribe as serviceSubscribe, publish as servicePublish } from './service.js';
-export type { ServiceResult, NativeServiceResult } from './service.js';
+export { Service, PluginService, NativeService, ServiceReply, registerService, registerNativeService, getService, hasService } from './service.js';
+export type { ServiceKind, ServiceRequestOptions, ServiceResponse, NativeTerminateInfo, NativePlatforms } from './service.js';
 export { log, Logger } from './log.js';
 export type { Message } from './message.js';
 export { getEnv } from './env.js';

package/src/global.d.ts

@@ -50,13 +50,22 @@ declare global {
 
   interface TextDecoder {
     readonly encoding: string;
-    decode(input?: Uint8Array): string;
+    decode(input?: ArrayBuffer | ArrayBufferView): string;
   }
   const TextDecoder: {
     new (encoding?: string): TextDecoder;
     prototype: TextDecoder;
   };
 
+  // ── performance（高精度单调时间）──
+  interface Performance {
+    /** 相对上下文起点的毫秒数（单调、亚毫秒精度）。 */
+    now(): number;
+    /** 上下文创建时的 epoch 毫秒。 */
+    readonly timeOrigin: number;
+  }
+  var performance: Performance;
+
   function setTimeout(handler: (...args: any[]) => void, timeout?: number, ...args: any[]): string;
   function clearTimeout(id: string): void;
   function setInterval(handler: (...args: any[]) => void, timeout?: number, ...args: any[]): string;

package/src/service.ts

@@ -1,8 +1,32 @@
-import { post } from './task.js';
+export type ServiceKind = 'plugin' | 'native';
 
-export interface ServiceResult {
-  serviceId: string;
-  token: string;
+export interface ServiceRequestOptions {
+  /** 请求头（app 级键值对；`content-type` 为典型项）。 */
+  headers?: Record<string, string>;
+  /** 便捷别名：等价于 `headers['content-type']`。 */
+  contentType?: string;
+  /** 请求体：JSON 值，或 `Uint8Array`（原始二进制，运行时解码后原样转发）。 */
+  body?: any;
+  /** 超时（毫秒）；缺省用运行时配置（默认 30000）。 */
+  timeout?: number;
+}
+
+/**
+ * 服务响应（fetch 风格）。响应体始终以字节承载：`json()` / `text()` 在 JS 侧解码，
+ * `bytes()` / `arrayBuffer()` 直接取原始字节。`body` 为未来的可读流预留。
+ */
+export interface ServiceResponse {
+  readonly ok: boolean;
+  readonly status: number;
+  readonly contentType: string;
+  readonly headers: Record<string, string>;
+  /** 预留：未来的可读流（当前为 undefined）。 */
+  readonly body?: unknown;
+  base64(): Promise<string>;
+  bytes(): Promise<Uint8Array>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  text(): Promise<string>;
+  json(): Promise<any>;
 }
 
 export interface NativeTerminateInfo {
@@ -12,40 +36,87 @@ export interface NativeTerminateInfo {
   output?: string;
 }
 
-export interface NativeServiceResult {
-  serviceId: string;
-  ready: () => Promise<void>;
-  onTerminate: (handler: (info: NativeTerminateInfo) => void) => void;
+/** 服务回复：服务方 `onRequest` 返回它以携带响应头；返回普通值等价于 JSON body。 */
+export class ServiceReply {
+  constructor(public readonly body: any, public readonly headers?: Record<string, string>) {}
 }
 
-// ── Register Plugin Service ──
+type NativePlatform = string | { file: string };
+export type NativePlatforms = Record<string, NativePlatform>;
+
+// ── 内部实现 ──────────────────────────────────────────────────────
 
-export async function registerService(refName: string, onRequest: (path: string, body: any) => any, isPublic = true): Promise<ServiceResult> {
-  const svcCbId = _registerCallback((payload: any) => {
-    if (payload?._svc === 'request') {
-      let body: any = null;
-      try { body = JSON.parse(payload.body); } catch { body = {}; }
-      const result = onRequest(payload.path, body);
-      $send('service', { t: 'response', requestId: payload.requestId, body: result });
+function _response(r: { headers?: Record<string, string>; contentType?: string; base64?: string; status?: number }): ServiceResponse {
+  const b64 = r.base64 ?? '';
+  const headers: Record<string, string> = {};
+  const raw = r.headers || {};
+  for (const k of Object.keys(raw)) headers[k.toLowerCase()] = raw[k];
+  const ct = r.contentType || headers['content-type'] || 'application/octet-stream';
+  headers['content-type'] = ct;
+  const decode = () => new TextDecoder().decode(Uint8Array.fromBase64(b64));
+  return {
+    ok: true,
+    status: r.status ?? 200,
+    contentType: ct,
+    headers,
+    base64: () => Promise.resolve(b64),
+    bytes: () => Promise.resolve(Uint8Array.fromBase64(b64)),
+    arrayBuffer: () => {
+      const u8 = Uint8Array.fromBase64(b64);
+      return Promise.resolve(u8.byteOffset === 0 && u8.byteLength === u8.buffer.byteLength ? u8.buffer : u8.slice().buffer);
+    },
+    text: () => Promise.resolve(decode()),
+    json: () => Promise.resolve().then(() => { const t = decode(); return t === '' ? null : JSON.parse(t); }),
+  };
+}
+
+function _request(serviceId: string, path: string, options: ServiceRequestOptions): Promise<ServiceResponse> {
+  return new Promise((resolve, reject) => {
+    const cbId = _registerCallback((result: any) => {
+      if (result?.err) { reject(new Error(result.err)); return; }
+      resolve(_response(result));
+    });
+    const headers: Record<string, string> = { ...(options.headers || {}) };
+    if (options.contentType && !headers['content-type']) headers['content-type'] = options.contentType;
+    const body = options.body;
+    if (body instanceof Uint8Array) {
+      if (!headers['content-type']) headers['content-type'] = 'application/octet-stream';
+    } else if (body !== undefined && body !== null) {
+      if (!headers['content-type']) headers['content-type'] = 'application/json';
+    } else if (!headers['content-type']) {
+      headers['content-type'] = 'application/json';
     }
-  }, { persistent: true });
-
-  const r = $send('service', { t: 'register', refName, onRequest: svcCbId, public: isPublic }) as ServiceResult & { err?: string; serviceId?: string };
-  if (r?.err) {
-    _unregisterCallback(svcCbId);
-    const e: any = new Error(r.err);
-    if (r.serviceId) e.serviceId = r.serviceId;
-    throw e;
-  }
-  return r;
+    const p: Record<string, unknown> = { t: 'request', serviceId, path, requestId: cbId, headers, contentType: headers['content-type'] };
+    if (options.timeout !== undefined && options.timeout !== null) p.timeout = options.timeout;
+    if (body instanceof Uint8Array) {
+      p.body = body.toBase64();
+      p.bodyEncoding = 'base64';
+    } else if (body !== undefined && body !== null) {
+      p.body = body;
+    }
+    $send('service', p);
+  });
 }
 
-// ── Register Native Service ──
+function _subscribe(serviceId: string, eventPath: string, handler: (body: any, eventPath: string) => void): () => void {
+  const cbId = _registerCallback((payload: any) => { handler(payload.body, payload.eventPath); }, { persistent: true });
+  $send('service', { t: 'subscribe', serviceId, eventPath, cb: cbId });
+  return () => {
+    $send('service', { t: 'unsubscribe', serviceId, eventPath });
+    _unregisterCallback(cbId);
+  };
+}
 
-type NativePlatform = string | { file: string } | { dir: string; entry: string };
-type NativePlatforms = Record<string, NativePlatform>;
+function _unregister(serviceId: string, token?: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const p: Record<string, unknown> = { t: 'unregister', serviceId };
+    if (token) p.token = token;
+    const r = $send('service', p) as any;
+    if (r?.err) reject(new Error(r.err)); else resolve();
+  });
+}
 
-function _serviceReady(serviceId: string): Promise<void> {
+function _awaitReady(serviceId: string): Promise<void> {
   return new Promise((resolve, reject) => {
     const cbId = _registerCallback((result: any) => {
       if (result?.err) {
@@ -64,51 +135,138 @@ function _serviceReady(serviceId: string): Promise<void> {
   });
 }
 
-export async function registerNativeService(refName: string, platforms: NativePlatforms, isPublic = true): Promise<NativeServiceResult> {
-  const r = $send('service', { t: 'registerNative', refName, platforms, public: isPublic }) as { serviceId: string; err?: string };
-  if (r.err) {
-    const e: any = new Error(r.err);
-    if ((r as any).serviceId) e.serviceId = (r as any).serviceId;
-    throw e;
+function _info(serviceId: string): Promise<{ exists: boolean; kind: ServiceKind | null }> {
+  return new Promise((resolve, reject) => {
+    const r = $send('service', { t: 'info', serviceId }) as any;
+    if (r?.err) { reject(new Error(r.err)); return; }
+    resolve({ exists: !!r.exists, kind: (r.kind ?? null) as ServiceKind | null });
+  });
+}
+
+// ── Service 对象（OOP）────────────────────────────────────────────
+
+/** 服务句柄基类（插件服务 / 原生服务通用能力）。 */
+export abstract class Service {
+  abstract readonly kind: ServiceKind;
+  constructor(readonly id: string) {}
+
+  /** 请求服务（fetch 风格）。失败 / 超时 / 服务卸载时 Promise reject。 */
+  request(path: string, options: ServiceRequestOptions = {}): Promise<ServiceResponse> {
+    return _request(this.id, path, options);
+  }
+
+  /** 订阅服务事件；返回取消函数。插件 unload / hot-reload 时运行时自动清理。 */
+  subscribe(eventPath: string, handler: (body: any, eventPath: string) => void): () => void {
+    return _subscribe(this.id, eventPath, handler);
+  }
+
+  /** 卸载服务。Plugin Service 需属主 token，Native Service 需调用方为属主。 */
+  unregister(): Promise<void> {
+    return _unregister(this.id);
   }
-  let terminateCb: string | null = null;
-  return {
-    serviceId: r.serviceId,
-    ready: () => _serviceReady(r.serviceId),
-    onTerminate(handler) {
-      if (terminateCb) _unregisterCallback(terminateCb);
-      terminateCb = _registerCallback((info: unknown) => handler(info as NativeTerminateInfo), { persistent: true });
-      $send('service', { t: 'registerNativeTerminate', serviceId: r.serviceId, cb: terminateCb });
-    },
-  };
 }
 
-// ── Request ──
+/** 插件服务（JS 服务）。属主句柄（registerService）持有 token；消费者句柄（getService）无 token。 */
+export class PluginService extends Service {
+  readonly kind = 'plugin' as const;
+  readonly token?: string;
+  constructor(id: string, token?: string) {
+    super(id);
+    this.token = token;
+  }
 
-export function request(serviceId: string, path: string, body?: any): Promise<any> {
+  /** 发布事件（仅属主：需 token）。 */
+  publish(eventPath: string, body?: any): void {
+    if (!this.token) throw new Error('publish requires the owner token of plugin service ' + this.id);
+    $send('service', { t: 'publish', token: this.token, eventPath, body: body ?? {} });
+  }
+
+  override unregister(): Promise<void> {
+    if (!this.token) return Promise.reject(new Error('unregister requires the owner token of plugin service ' + this.id));
+    return _unregister(this.id, this.token);
+  }
+}
+
+/** 原生服务（子进程）。 */
+export class NativeService extends Service {
+  readonly kind = 'native' as const;
+  private _terminateCb: string | null = null;
+  constructor(id: string) { super(id); }
+
+  /** 等待原生服务就绪（进程 TCP 就绪消息已收到时 resolve）。 */
+  ready(): Promise<void> { return _awaitReady(this.id); }
+
+  /** 注册服务终止钩子（仅属主有效；重复调用替换旧回调）。 */
+  onTerminate(handler: (info: NativeTerminateInfo) => void): void {
+    if (this._terminateCb) _unregisterCallback(this._terminateCb);
+    this._terminateCb = _registerCallback((info: unknown) => handler(info as NativeTerminateInfo), { persistent: true });
+    $send('service', { t: 'registerNativeTerminate', serviceId: this.id, cb: this._terminateCb });
+  }
+}
+
+// ── 注册 / 获取 ───────────────────────────────────────────────────
+
+/**
+ * 注册 Plugin Service。成功返回 {@link PluginService}（属主句柄，含 token）；
+ * 失败（权限 / 已存在）抛错——已存在时 `error.serviceId` 指向既有服务，应以其降级接入。
+ */
+export function registerService(refName: string, onRequest: (path: string, body: any) => any, isPublic = true): Promise<PluginService> {
   return new Promise((resolve, reject) => {
-    const cbId = _registerCallback((result: any) => {
-      if (result?.err) { reject(new Error(result.err)); } else resolve(result);
-    });
-    $send('service', { t: 'request', serviceId, path, body: body || {}, requestId: cbId });
+    const svcCbId = _registerCallback((payload: any) => {
+      if (payload?._svc === 'request') {
+        const result = onRequest(payload.path, payload.body ?? null);
+        if (result instanceof ServiceReply) {
+          $send('service', { t: 'response', requestId: payload.requestId, headers: result.headers, body: result.body });
+        } else {
+          $send('service', { t: 'response', requestId: payload.requestId, body: result });
+        }
+      }
+    }, { persistent: true });
+    const r = $send('service', { t: 'register', refName, onRequest: svcCbId, public: isPublic }) as any;
+    if (r?.err) {
+      _unregisterCallback(svcCbId);
+      const e: any = new Error(r.err);
+      if (r.serviceId) e.serviceId = r.serviceId;
+      reject(e);
+      return;
+    }
+    resolve(new PluginService(r.serviceId, r.token));
   });
 }
 
-// ── Subscribe ──
-
-export function subscribe(serviceId: string, eventPath: string, handler: (body: any, eventPath: string) => void): () => void {
-  const cbId = _registerCallback((payload: any) => {
-    handler(payload.body, payload.eventPath);
-  }, { persistent: true });
-  $send('service', { t: 'subscribe', serviceId, eventPath, cb: cbId });
-  return () => {
-    $send('service', { t: 'unsubscribe', serviceId, eventPath });
-    _unregisterCallback(cbId);
-  };
+/** 注册 Native Service。成功返回 {@link NativeService}；失败抛错。 */
+export function registerNativeService(refName: string, platforms: NativePlatforms, isPublic = true): Promise<NativeService> {
+  return new Promise((resolve, reject) => {
+    const r = $send('service', { t: 'registerNative', refName, platforms, public: isPublic }) as any;
+    if (r?.err) {
+      const e: any = new Error(r.err);
+      if (r.serviceId) e.serviceId = r.serviceId;
+      reject(e);
+      return;
+    }
+    resolve(new NativeService(r.serviceId));
+  });
 }
 
-// ── Publish ──
+/** 按 id 获取服务句柄；不存在时抛错。返回的消费者句柄无 token（不能 publish / unregister 插件服务）。 */
+export function getService(serviceId: string): Promise<Service> {
+  return _info(serviceId).then(i => {
+    if (!i.exists) {
+      const e: any = new Error('Service not found: ' + serviceId);
+      e.serviceId = serviceId;
+      throw e;
+    }
+    return i.kind === 'native' ? new NativeService(serviceId) : new PluginService(serviceId);
+  });
+}
 
-export function publish(token: string, eventPath: string, body?: any): void {
-  $send('service', { t: 'publish', token, eventPath, body: body || {} });
+/**
+ * 检查服务是否存在。
+ *
+ * > **不要用它判断后再注册**：检查与注册**不是原子操作**，并发下会竞态——两个插件可能同时检查到
+ * > 不存在，随后一个注册成功、另一个被拒绝。注册必须用 `try-catch` 包裹，并在捕获到「已存在」时用
+ * > `error.serviceId` 降级接入既有服务。此方法仅用于展示 / 诊断。
+ */
+export function hasService(serviceId: string): Promise<boolean> {
+  return _info(serviceId).then(i => i.exists);
 }

package/src/worker.ts

@@ -5,6 +5,19 @@ export interface WorkerOptions {
   entry?: string;
   /** 代码字符串；与 `entry` 互斥。 */
   code?: string;
+  /**
+   * 权限覆盖（可选）。默认继承主插件全部权限。
+   * - `allow`：白名单——只有命中的节点允许（未声明时继承主插件权限）
+   * - `deny`：黑名单——优先级最高（先于 allow 与继承）
+   *
+   * 节点格式 `channel:op`（如 `fs:server.readFile`、`http:*`、`task:player.*`、`*`）。
+   * **不能提权**：主插件未声明的权限，`allow` 无效（仍按默认拒绝）。
+   * 例：`deny: ['*']` 只允许标准 ES 代码；`deny: ['fs:*', 'http:*']` 仅禁用这两类。
+   */
+  permissions?: {
+    allow?: string[];
+    deny?: string[];
+  };
 }
 
 let _seq = 0;
@@ -35,9 +48,10 @@ function _sendWorkerAsync(t: string, p: Record<string, unknown>): Promise<void>
  * Worker —— 虚拟插件（独立 QuickJS 上下文 + 线程）。
  *
  * - 事件/命令/服务以独立实体注册；调度器任务独立统计
- * - 共享主插件的**数据目录**与**权限**
+ * - 共享主插件的**数据目录**；权限默认继承主插件，可按需用 `allow`/`deny` 收紧（不可提权）
  * - 不能创建新的 Worker（嵌套被拒绝）
- * - **创建后无法销毁，只能卸载**（卸载物理销毁 JS 上下文，句柄保留——可重新 load）
+ * - `unload()` 卸载（物理销毁 JS 上下文，句柄保留——可重新 load）；
+ *   `destroy()` **彻底销毁**（移除注册，句柄作废，同名可重建）
  * - 主插件卸载时连带卸载；/yeow 管理命令不覆盖 Worker；profiler 会统计（标记 created by 主插件）
  * - Worker 的 JS 错误与主插件同样回传（dev 模式经 source-map 定位）
  */
@@ -46,15 +60,18 @@ export class Worker {
   private readonly entry?: string;
   private readonly code?: string;
   private readonly key: string;
+  private readonly permissions?: { allow?: string[]; deny?: string[] };
   private _loaded = false;
+  private _destroyed = false;
   private _onMessage: ((msg: any) => void) | null = null;
   /** 内部 workerId（主插件 JS 侧分配；跨主插件可重复）。 */
   readonly id: string;
 
-  constructor(name: string, entry: string | undefined, code: string | undefined) {
+  constructor(name: string, entry: string | undefined, code: string | undefined, permissions?: { allow?: string[]; deny?: string[] }) {
     this.name = name;
     this.entry = entry;
     this.code = code;
+    this.permissions = permissions;
     this.id = 'worker_' + (++_seq);
     this.key = (__plugin?.name || 'unknown') + ':' + name;
     // 主插件侧 onMessage 回调（worker → main 时 Java 投递到这里）
@@ -71,6 +88,7 @@ export class Worker {
 
   /** 启动 Worker：执行 init.js → worker-inject.js → Worker 代码 → INIT → LOAD（已加载为 no-op）。 */
   load(): Promise<void> {
+    if (this._destroyed) return Promise.reject(new Error('worker has been destroyed'));
     if (this._loaded) return Promise.resolve();
     this._loaded = true;
     return _sendWorkerAsync('load', { name: this.name });
@@ -78,22 +96,40 @@ export class Worker {
 
   /** 卸载 Worker（物理销毁 JS 上下文并清理其事件/命令/服务/任务；句柄保留，可重新 load）。 */
   unload(): Promise<void> {
+    if (this._destroyed) return Promise.reject(new Error('worker has been destroyed'));
     this._loaded = false;
     return _sendWorkerAsync('unload', { name: this.name });
   }
 
   /** 向 Worker 发送消息（其 onMessage 回调接收；未 load 时抛错）。 */
   postMessage(msg: Record<string, unknown>): Promise<void> {
+    if (this._destroyed) return Promise.reject(new Error('worker has been destroyed'));
     return _sendWorkerAsync('post', { name: this.name, msg });
   }
 
   /** 重载 Worker 代码（需已 load；旧上下文销毁、新代码重新加载）。 */
   reload(): Promise<void> {
+    if (this._destroyed) return Promise.reject(new Error('worker has been destroyed'));
     const p: Record<string, unknown> = { name: this.name };
     if (this.entry) p.entry = this.entry;
     else p.code = this.code;
     return _sendWorkerAsync('reload', p);
   }
+
+  /**
+   * **彻底销毁** Worker：卸载并移除注册（清理事件/命令/服务/任务），句柄作废——
+   * 之后 load/post/reload 均 reject；同名 Worker 可重新 `createWorker`。
+   */
+  destroy(): Promise<void> {
+    if (this._destroyed) return Promise.resolve();
+    return _sendWorkerAsync('destroy', { name: this.name }).then(() => {
+      this._destroyed = true;
+      this._loaded = false;
+      const cb = _msgCbs[this.id];
+      if (cb) { _unregisterCallback(cb); delete _msgCbs[this.id]; }
+      delete _created[this.key];
+    });
+  }
 }
 
 /**
@@ -122,11 +158,12 @@ export function createWorker(options: WorkerOptions): Worker {
     throw new Error('createWorker: duplicate worker name "' + name + '" in plugin ' + (__plugin?.name || 'unknown'));
   }
   _created[key] = true;
-  const w = new Worker(name, options.entry, options.code);
+  const w = new Worker(name, options.entry, options.code, options.permissions);
   // 注册到运行时注册表（同步；重复/非法名抛错）
   const p: Record<string, unknown> = { name, msgCb: _msgCbs[w.id] };
   if (options.entry) p.entry = options.entry;
   else p.code = options.code;
+  if (options.permissions) p.permissions = options.permissions;
   _sendWorker({ t: 'create', p });
   return w;
 }