webloom-framework 0.1.0

package/dist/index.js

@@ -0,0 +1,583 @@
+import { createRemoteServiceMessageCodec, UpgradeGateRejectedError } from './chunk-KGNF36DZ.js';
+export { LIFECYCLE_ERROR_TEXT, LifecycleScopeRevokedError, PermissionDeniedError, PermissionLeaseRevokedError, PluginGraphValidationError, RESOURCE_OWNER, RESOURCE_REGISTRY_CAPABILITY, RUNTIME_MESSAGE_BUS, RemoteServiceUnavailableError, SCOPED_TASK_SCHEDULER_CAPABILITY, StartupCapabilityError, StartupPluginError, UpgradeGateRejectedError, buildPluginGraph, createCapabilityRegistry, createInMemoryPluginConfigStore, createLifecycleScope, createMessageBus, createMessagePortServiceTransport, createPermissionLease, createPluginHost, createPluginIntentController, createRemoteServiceBridge, createRemoteServiceMessageCodec, createResourceRegistry, createResourceScope, createResourceStore, createRuntimeUnitImplementationRegistry, createScopedMessageBus, createScopedTaskScheduler, createServiceBridge, dependenciesOfManifest, lifecycleErrorText, providesOfManifest, registerOwnedResource, reverseDependentsOf, validatePluginGraph, validateRuntimeUnitDependencyContracts } from './chunk-KGNF36DZ.js';
+
+// src/contracts/plugin.ts
+function runtimeCapabilityContractVersion(capability) {
+  return `${capability}.v1`;
+}
+function defineRuntimeUnitDependencies(dependencies, defaults = {}) {
+  return dependencies.map((dependency) => ({
+    capability: dependency.capability,
+    contractVersion: runtimeCapabilityContractVersion(dependency.capability),
+    sourceExecution: defaults.sourceExecution ?? "default",
+    scope: defaults.scope ?? "root",
+    ...dependency.reason !== void 0 ? { reason: dependency.reason } : {},
+    ...dependency.optional !== void 0 ? { optional: dependency.optional } : {}
+  }));
+}
+function defineRuntimeUnitProvidedContracts(capabilities) {
+  return Object.fromEntries(
+    capabilities.map((capability) => [capability, runtimeCapabilityContractVersion(capability)])
+  );
+}
+
+// src/lifecycle/permissionVerifier.ts
+function verifyPermissionLease(options) {
+  options.lease.assert(options.permission);
+  if (options.binding) options.lease.assertBinding(options.binding);
+}
+
+// src/lifecycle/scopedRegistry.ts
+function definitionId(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const id = value.id;
+  return typeof id === "string" && id.length > 0 ? id : void 0;
+}
+function defaultRegistrationRules() {
+  return [{ method: "register", idArgument: 0, unregisterMethod: "unregister" }];
+}
+function createScopedRegistryFacade(target, scope, options) {
+  const rules = options.registrations ?? defaultRegistrationRules();
+  const byMethod = new Map(rules.map((rule) => [rule.method, rule]));
+  const unregisterMethods = new Set(
+    rules.map((rule) => rule.unregisterMethod).filter((method) => Boolean(method))
+  );
+  const ownedRegistrations = /* @__PURE__ */ new Set();
+  const objectTarget = target;
+  const remember = (rule, id, result, args) => {
+    const unregisterMethod = rule.unregisterMethod;
+    if (typeof result !== "function" && (!unregisterMethod || id === void 0)) return result;
+    const key = rule.method + ":" + (id ?? "returned");
+    let active = true;
+    let removeScopeRevoke = () => void 0;
+    let removeScopeCleanup = () => void 0;
+    const entry = {};
+    const clearOwnership = (removeDispose = true) => {
+      if (!active) return false;
+      active = false;
+      ownedRegistrations.delete(entry);
+      removeScopeRevoke();
+      if (removeDispose) removeScopeCleanup();
+      return true;
+    };
+    const invokeUnregister = (...offArgs) => {
+      if (typeof result === "function") {
+        return result.apply(target, offArgs);
+      }
+      const unregister = objectTarget[unregisterMethod];
+      if (typeof unregister !== "function") return void 0;
+      const unregisterArgument = rule.unregisterArgument ?? rule.idArgument ?? 0;
+      const unregisterArgs = [...args];
+      unregisterArgs[unregisterArgument] = id;
+      return unregister.apply(target, unregisterArgs);
+    };
+    const cleanup = async (_reason) => {
+      if (!active) {
+        if (entry.revokedCleanup) await entry.revokedCleanup;
+        return;
+      }
+      if (!clearOwnership()) return;
+      await invokeUnregister();
+    };
+    const revokeNow = (_reason) => {
+      if (!clearOwnership(false)) return;
+      try {
+        const pending = invokeUnregister();
+        if (pending && typeof pending.then === "function") {
+          const revokedCleanup = Promise.resolve(pending).then(() => void 0);
+          entry.revokedCleanup = revokedCleanup;
+          revokedCleanup.catch(() => void 0);
+        }
+      } catch (error) {
+        entry.revokedCleanup = Promise.reject(error);
+        entry.revokedCleanup.catch(() => void 0);
+      }
+    };
+    entry.id = id;
+    entry.unregisterMethod = unregisterMethod;
+    entry.revokeNow = revokeNow;
+    Object.defineProperty(entry, "active", {
+      enumerable: true,
+      configurable: false,
+      get: () => active,
+      set: (value) => {
+        active = value;
+      }
+    });
+    entry.removeScopeCleanup = removeScopeCleanup;
+    ownedRegistrations.add(entry);
+    removeScopeCleanup = scope.onDispose(
+      cleanup,
+      options.name + ":" + key,
+      "after-teardown"
+    );
+    entry.removeScopeCleanup = removeScopeCleanup;
+    removeScopeRevoke = scope.onRevoke(revokeNow);
+    if (typeof result === "function") {
+      return (...offArgs) => {
+        if (!clearOwnership()) return void 0;
+        return result.apply(target, offArgs);
+      };
+    }
+    return result;
+  };
+  return new Proxy(target, {
+    get(current, property, receiver) {
+      const value = Reflect.get(current, property, receiver);
+      if (typeof value !== "function") return value;
+      const rule = typeof property === "string" ? byMethod.get(property) : void 0;
+      if (rule) {
+        return (...args) => {
+          scope.assertActive();
+          const callArgs = [...args];
+          if (rule.bindPluginIdArgument !== void 0 && scope.identity.pluginId) {
+            const claimedPluginId = callArgs[rule.bindPluginIdArgument];
+            if (claimedPluginId !== void 0 && claimedPluginId !== scope.identity.pluginId) {
+              throw new Error(
+                'Registry owner "' + String(claimedPluginId) + '" does not match plugin instance "' + scope.identity.pluginId + '"'
+              );
+            }
+            callArgs[rule.bindPluginIdArgument] = scope.identity.pluginId;
+          }
+          if (rule.ownerPluginIdProperty && scope.identity.pluginId) {
+            const definition = callArgs[rule.idArgument ?? 0];
+            if (definition && typeof definition === "object") {
+              const claimedPluginId = definition[rule.ownerPluginIdProperty];
+              if (claimedPluginId !== void 0 && claimedPluginId !== scope.identity.pluginId) {
+                throw new Error(
+                  'Registry owner "' + String(claimedPluginId) + '" does not match plugin instance "' + scope.identity.pluginId + '"'
+                );
+              }
+            }
+          }
+          const result = value.apply(target, callArgs);
+          const id = rule.idArgument === void 0 ? void 0 : definitionId(callArgs[rule.idArgument]);
+          return remember(rule, id, result, callArgs);
+        };
+      }
+      if (typeof property === "string" && unregisterMethods.has(property)) {
+        return (...args) => {
+          scope.assertActive();
+          const id = definitionId(args[0]) ?? (typeof args[0] === "string" ? args[0] : void 0);
+          const owned = [...ownedRegistrations].find(
+            (entry) => entry.active && entry.id === id && entry.unregisterMethod === property
+          );
+          if (!owned) {
+            throw new Error(
+              'Registry resource "' + (id ?? "unknown") + '" is not owned by this plugin instance'
+            );
+          }
+          const result = value.apply(target, args);
+          owned.active = false;
+          ownedRegistrations.delete(owned);
+          owned.removeScopeCleanup();
+          return result;
+        };
+      }
+      return value.bind(target);
+    }
+  });
+}
+
+// src/lifecycle/upgradeGate.ts
+function validGeneration(value) {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === "string" && value.length > 0))];
+}
+function makeSessionId() {
+  try {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+      return `upgrade-session:${crypto.randomUUID()}`;
+    }
+  } catch {
+  }
+  return `upgrade-session:${Date.now().toString(36)}:${Math.random().toString(36).slice(2)}`;
+}
+function buildIsCompatible(options, buildId) {
+  try {
+    if (options.isBuildCompatible) return options.isBuildCompatible(buildId);
+  } catch {
+    return false;
+  }
+  return buildId === options.buildId || options.compatibleBuildIds?.has(buildId) === true;
+}
+function createUpgradeGate(options) {
+  if (!options.protocolVersion || !options.buildId || !options.authorityInstanceId) {
+    throw new Error("\u5347\u7EA7\u95E8\u7981\u7684 protocolVersion\u3001buildId \u548C authorityInstanceId \u5FC5\u987B\u6709\u6548");
+  }
+  if (!validGeneration(options.handoverGeneration)) {
+    throw new Error("\u5347\u7EA7\u95E8\u7981\u7684 handoverGeneration \u5FC5\u987B\u662F\u975E\u8D1F\u5B89\u5168\u6574\u6570");
+  }
+  const contractVersions = uniqueStrings(options.supportedContractVersions);
+  if (contractVersions.length === 0) {
+    throw new Error("\u5347\u7EA7\u95E8\u7981\u81F3\u5C11\u9700\u8981\u4E00\u4E2A supportedContractVersions");
+  }
+  let currentState = "active";
+  let closeReason = "upgrade gate closed";
+  const leases = /* @__PURE__ */ new Set();
+  const sessions = /* @__PURE__ */ new Set();
+  const sessionByObject = /* @__PURE__ */ new WeakMap();
+  const emptyWaiters = /* @__PURE__ */ new Set();
+  const notifyEmpty = () => {
+    if (leases.size !== 0) return;
+    for (const resolve of [...emptyWaiters]) {
+      emptyWaiters.delete(resolve);
+      resolve();
+    }
+  };
+  const removeLease = (record) => {
+    if (!leases.delete(record)) return;
+    record.session.leases.delete(record);
+    record.removeExternalAbort?.();
+    record.removeExternalAbort = void 0;
+    notifyEmpty();
+  };
+  const revokeSession = (record, reason) => {
+    if (record.revoked) return;
+    record.revoked = true;
+    record.reason = reason;
+    try {
+      record.controller.abort(new UpgradeGateRejectedError(reason));
+    } catch {
+      record.controller.abort();
+    }
+    for (const lease of [...record.leases]) revokeLease(lease, reason);
+    sessions.delete(record);
+  };
+  const revokeLease = (record, reason) => {
+    if (record.revoked) return;
+    record.revoked = true;
+    record.reason = reason;
+    try {
+      record.controller.abort(new UpgradeGateRejectedError(reason));
+    } catch {
+      record.controller.abort();
+    }
+    removeLease(record);
+  };
+  const assertAccepting = () => {
+    if (currentState === "active") return;
+    throw new UpgradeGateRejectedError(currentState === "draining" ? "draining" : "closed", closeReason);
+  };
+  const handshake = (input) => {
+    if (currentState !== "active") {
+      return { accepted: false, reason: currentState === "draining" ? "draining" : "closed" };
+    }
+    if (typeof input.connectionId !== "string" || input.connectionId.length === 0 || input.protocolVersion !== options.protocolVersion || typeof input.protocolVersion !== "string" || typeof input.buildId !== "string" || typeof input.authorityInstanceId !== "string" || input.authorityInstanceId.length === 0) {
+      return { accepted: false, reason: "protocol-mismatch" };
+    }
+    if (!buildIsCompatible(options, input.buildId)) {
+      return { accepted: false, reason: "build-incompatible" };
+    }
+    if (!validGeneration(input.handoverGeneration)) {
+      return { accepted: false, reason: "stale-generation" };
+    }
+    if (input.handoverGeneration < options.handoverGeneration) {
+      return { accepted: false, reason: "stale-generation" };
+    }
+    if (input.handoverGeneration > options.handoverGeneration) {
+      return { accepted: false, reason: "future-generation" };
+    }
+    const contractVersion = contractVersions.find((version) => input.supportedContractVersions.includes(version));
+    if (!contractVersion) return { accepted: false, reason: "contract-mismatch" };
+    const sessionRecord = {
+      sessionId: makeSessionId(),
+      connectionId: input.connectionId,
+      contractVersion,
+      controller: new AbortController(),
+      revoked: false,
+      reason: "upgrade session closed",
+      leases: /* @__PURE__ */ new Set()
+    };
+    const session = {
+      connectionId: sessionRecord.connectionId,
+      sessionId: sessionRecord.sessionId,
+      authorityInstanceId: options.authorityInstanceId,
+      handoverGeneration: options.handoverGeneration,
+      contractVersion,
+      get revoked() {
+        return sessionRecord.revoked || !sessions.has(sessionRecord);
+      },
+      signal: sessionRecord.controller.signal,
+      assertActive() {
+        if (sessionRecord.revoked || !sessions.has(sessionRecord)) {
+          throw new UpgradeGateRejectedError(sessionRecord.reason, "\u5347\u7EA7\u63E1\u624B\u4F1A\u8BDD\u5DF2\u5931\u6548");
+        }
+        if (currentState === "closed") {
+          throw new UpgradeGateRejectedError("closed", closeReason);
+        }
+      },
+      admit(input2) {
+        return admitForSession(sessionRecord, input2);
+      },
+      close(reason = "upgrade session closed") {
+        revokeSession(sessionRecord, reason);
+      }
+    };
+    sessionRecord.session = session;
+    sessions.add(sessionRecord);
+    sessionByObject.set(session, sessionRecord);
+    return {
+      accepted: true,
+      mode: options.mode ?? "cold-switch",
+      handoverGeneration: options.handoverGeneration,
+      contractVersion,
+      connectionId: sessionRecord.connectionId,
+      sessionId: sessionRecord.sessionId,
+      session
+    };
+  };
+  const admitForSession = (sessionRecord, input) => {
+    if (sessionRecord.revoked || !sessions.has(sessionRecord)) {
+      throw new UpgradeGateRejectedError(sessionRecord.reason, "\u5347\u7EA7\u63E1\u624B\u4F1A\u8BDD\u5DF2\u5931\u6548");
+    }
+    assertAccepting();
+    if (input.signal?.aborted) {
+      throw new UpgradeGateRejectedError("caller-aborted", "I/O \u5728\u53D6\u5F97\u63A5\u7BA1\u79DF\u7EA6\u524D\u5DF2\u53D6\u6D88");
+    }
+    const record = {
+      session: sessionRecord,
+      operation: input.operation,
+      controller: new AbortController(),
+      revoked: false,
+      reason: "upgrade I/O lease released"
+    };
+    leases.add(record);
+    sessionRecord.leases.add(record);
+    if (input.signal) {
+      const onAbort = () => revokeLease(record, "caller-aborted");
+      input.signal.addEventListener("abort", onAbort, { once: true });
+      record.removeExternalAbort = () => input.signal?.removeEventListener("abort", onAbort);
+    }
+    const lease = {
+      connectionId: sessionRecord.connectionId,
+      sessionId: sessionRecord.sessionId,
+      authorityInstanceId: options.authorityInstanceId,
+      handoverGeneration: options.handoverGeneration,
+      contractVersion: sessionRecord.contractVersion,
+      operation: record.operation,
+      get revoked() {
+        return record.revoked || !leases.has(record);
+      },
+      signal: record.controller.signal,
+      assertActive() {
+        if (record.revoked || !leases.has(record)) {
+          throw new UpgradeGateRejectedError(record.reason, "\u5347\u7EA7 I/O \u79DF\u7EA6\u5DF2\u5931\u6548");
+        }
+        if (currentState === "closed") {
+          throw new UpgradeGateRejectedError("closed", closeReason);
+        }
+      },
+      release() {
+        if (record.revoked) return;
+        record.revoked = true;
+        record.reason = "upgrade I/O lease released";
+        removeLease(record);
+      }
+    };
+    return lease;
+  };
+  const admit = (input) => {
+    const sessionRecord = sessionByObject.get(input.session);
+    if (!sessionRecord) {
+      throw new UpgradeGateRejectedError("invalid-session", "I/O \u5FC5\u987B\u4F7F\u7528\u5F53\u524D\u95E8\u7981\u63E1\u624B\u8FD4\u56DE\u7684\u4F1A\u8BDD");
+    }
+    return admitForSession(sessionRecord, input);
+  };
+  const beginDrain = (reason = "upgrade handover draining") => {
+    if (currentState !== "active") return;
+    closeReason = reason;
+    currentState = "draining";
+  };
+  const drain = async (timeoutMs) => {
+    beginDrain();
+    if (leases.size === 0) return { state: currentState, drained: true, pending: 0 };
+    if (timeoutMs !== void 0 && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) {
+      throw new Error("\u5347\u7EA7\u6392\u7A7A timeoutMs \u5FC5\u987B\u662F\u975E\u8D1F\u6709\u9650\u6570");
+    }
+    let timeout;
+    let timerResolve;
+    const empty = new Promise((resolve) => {
+      emptyWaiters.add(resolve);
+      timerResolve = resolve;
+    });
+    const timeoutPromise = timeoutMs === void 0 ? void 0 : new Promise((resolve) => {
+      timeout = setTimeout(resolve, timeoutMs);
+    });
+    if (timeoutPromise) await Promise.race([empty, timeoutPromise]);
+    else await empty;
+    if (timeout !== void 0) clearTimeout(timeout);
+    if (timerResolve) emptyWaiters.delete(timerResolve);
+    const pending = leases.size;
+    return { state: currentState, drained: pending === 0, pending };
+  };
+  const close = (reason = "upgrade gate closed") => {
+    if (currentState === "closed") return;
+    closeReason = reason;
+    currentState = "closed";
+    for (const session of [...sessions]) revokeSession(session, reason);
+    for (const lease of [...leases]) revokeLease(lease, reason);
+    notifyEmpty();
+  };
+  return {
+    get state() {
+      return currentState;
+    },
+    mode: options.mode ?? "cold-switch",
+    authorityInstanceId: options.authorityInstanceId,
+    handoverGeneration: options.handoverGeneration,
+    handshake,
+    assertAccepting,
+    admit,
+    beginDrain,
+    drain,
+    close,
+    activeIo: () => leases.size
+  };
+}
+
+// src/transport/messagePortServiceProvider.ts
+function isCallMessage(input, codec) {
+  if (!input || typeof input !== "object") return false;
+  const message = input;
+  return message.type === codec.type("call") && typeof message.callId === "string" && message.callId.length > 0 && typeof message.connectionId === "string" && typeof message.providerInstanceId === "string" && Boolean(message.reference);
+}
+function isCancelMessage(input, codec) {
+  if (!input || typeof input !== "object") return false;
+  const message = input;
+  return message.type === codec.type("cancel") && typeof message.callId === "string" && typeof message.connectionId === "string" && typeof message.providerInstanceId === "string";
+}
+function errorMessage(error) {
+  const candidate = error && typeof error === "object" ? error : void 0;
+  return {
+    ...typeof candidate?.name === "string" ? { name: candidate.name } : {},
+    message: typeof candidate?.message === "string" ? candidate.message : String(error),
+    ...typeof candidate?.code === "string" ? { code: candidate.code } : {}
+  };
+}
+function post(port, message) {
+  try {
+    port.postMessage(message);
+  } catch {
+  }
+}
+function createMessagePortServiceProvider(options) {
+  const pending = /* @__PURE__ */ new Map();
+  const codec = options.codec ?? createRemoteServiceMessageCodec();
+  let activeProviderInstanceIds = new Set(
+    options.snapshot.services.map((service) => service.providerInstanceId)
+  );
+  let disposed = false;
+  const sendError = (message, error) => {
+    const response = {
+      type: codec.type("error"),
+      callId: message.callId,
+      connectionId: message.connectionId,
+      providerInstanceId: message.providerInstanceId,
+      error: errorMessage(error)
+    };
+    post(options.port, codec.encode(response));
+  };
+  const onMessage = (event) => {
+    if (disposed) return;
+    const decoded = codec.decode(event.data);
+    if (isCancelMessage(decoded, codec)) {
+      if (decoded.connectionId !== options.handshake.connectionId) return;
+      const call = pending.get(decoded.callId);
+      if (call?.providerInstanceId === decoded.providerInstanceId) {
+        call.controller.abort(new Error("Remote service request cancelled"));
+      }
+      return;
+    }
+    if (!isCallMessage(decoded, codec)) return;
+    const message = decoded;
+    if (message.connectionId !== options.handshake.connectionId) {
+      sendError(message, Object.assign(new Error("Remote service connection mismatch"), { code: "service.connection_mismatch" }));
+      return;
+    }
+    if (!activeProviderInstanceIds.has(message.providerInstanceId)) {
+      sendError(message, Object.assign(new Error("Remote service provider mismatch"), { code: "service.provider_mismatch" }));
+      return;
+    }
+    if (pending.has(message.callId)) {
+      sendError(message, Object.assign(new Error("Remote service callId is duplicated"), { code: "service.duplicate_call" }));
+      return;
+    }
+    const controller = new AbortController();
+    pending.set(message.callId, { controller, providerInstanceId: message.providerInstanceId });
+    void (async () => {
+      try {
+        const result = await options.handleCall({ message, signal: controller.signal });
+        if (controller.signal.aborted || disposed) return;
+        const response = {
+          type: codec.type("result"),
+          callId: message.callId,
+          connectionId: message.connectionId,
+          providerInstanceId: message.providerInstanceId,
+          result
+        };
+        post(options.port, codec.encode(response));
+      } catch (error) {
+        if (disposed) return;
+        sendError(message, error);
+      } finally {
+        pending.delete(message.callId);
+      }
+    })();
+  };
+  options.port.addEventListener("message", onMessage);
+  options.port.start();
+  post(options.port, codec.encode({
+    type: codec.type("handshake"),
+    handshake: options.handshake
+  }));
+  post(options.port, codec.encode({
+    type: codec.type("snapshot"),
+    snapshot: options.snapshot
+  }));
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    options.port.removeEventListener("message", onMessage);
+    for (const { controller } of pending.values()) controller.abort(new Error("Remote service provider disposed"));
+    pending.clear();
+    if (options.closeOnDispose !== false) options.port.close();
+  };
+  const provider = {
+    publishSnapshot(snapshot) {
+      if (disposed) return;
+      activeProviderInstanceIds = new Set(
+        snapshot.services.map((service) => service.providerInstanceId)
+      );
+      post(options.port, codec.encode({
+        type: codec.type("snapshot"),
+        snapshot
+      }));
+    },
+    invalidate(reason = "Remote service invalidated") {
+      if (disposed) return;
+      activeProviderInstanceIds = /* @__PURE__ */ new Set();
+      for (const { controller } of pending.values()) controller.abort(new Error(reason));
+      post(options.port, codec.encode({
+        type: codec.type("invalidate"),
+        reason
+      }));
+    },
+    disconnect(reason = "Remote service disconnected") {
+      if (disposed) return;
+      post(options.port, codec.encode({
+        type: codec.type("disconnect"),
+        reason
+      }));
+      dispose();
+    },
+    dispose
+  };
+  return provider;
+}
+
+export { createMessagePortServiceProvider, createScopedRegistryFacade, createUpgradeGate, defineRuntimeUnitDependencies, defineRuntimeUnitProvidedContracts, runtimeCapabilityContractVersion, verifyPermissionLease };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map