@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/extensions/lifecycle.js

@@ -1,18 +1,23 @@
-import { PLUGIN_DEPLOYMENT_CONFIG_TOPIC } from "./deployment-config.js";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { LockedInterval } from "../infra/schedule/locked-interval.js";
+import { KERNEL_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
+import { ExtensionHost } from "./host.js";
+import { ExtensionInstalls } from "./installs.js";
+import { PLUGIN_DEPLOYMENT_CONFIG_TOPIC, PLUGINS_CHANGED_TOPIC, PLUGINS_RECONCILE_JOB, PLUGINS_RECONCILE_TOPIC, STALE_RECONCILE_PERIODS, } from "./lifecycle-topics.js";
 import { PLUGINS_MIGRATED_TOPIC } from "./migrate-lock.js";
-/**
- * 插件期望状态 / 快照变了（kernel bus 主题，频道 `cap:kernel:plugins.changed`，payload `{ plugin }`）。
- * 后台、CLI 写完 PG 后发布；各副本据此 reconcile，并作废路由闸门的名字缓存。
- */
-export const PLUGINS_CHANGED_TOPIC = "plugins.changed";
-/** 周期兜底（kernel bus 主题 `plugins.reconcile`，payload `{}`）：维护任务 `plugins-reconcile` 发布。 */
-export const PLUGINS_RECONCILE_TOPIC = "plugins.reconcile";
-export { PLUGINS_MIGRATED_TOPIC };
-/** 维护任务：每 `extensionHost.reconcileIntervalSeconds` 秒发布一次 `plugins.reconcile`（任务名与 scheduler id 不含 `:`）。 */
-export const PLUGINS_RECONCILE_JOB = "plugins-reconcile";
-export const PLUGINS_RECONCILE_SCHEDULER_ID = "plugins-reconcile-every";
-/** 副本行心跳超过这么多个 reconcile 周期的副本不计入（C16；读状态的一方据此筛选）。 */
-export const STALE_RECONCILE_PERIODS = 3;
+import { ReplicaStatusStore } from "./sources.js";
+export { PLUGINS_CHANGED_TOPIC, PLUGINS_MIGRATED_TOPIC, PLUGINS_RECONCILE_JOB, PLUGINS_RECONCILE_TOPIC, STALE_RECONCILE_PERIODS, };
 /** 心跳超过这么多个周期的行直接删除（副本早已退出；读的一方本来就不计入）。 */
 const PRUNE_RECONCILE_PERIODS = 10;
 /**
@@ -23,34 +28,49 @@ const PRUNE_RECONCILE_PERIODS = 10;
  * 每次 reconcile 开始与结束时都刷新本副本状态行的心跳，并清理已卸载插件的行与早已退出的副本的行。
  * 进程内只有排队用的 Promise（不是跨副本状态）。
  */
-export class ExtensionLifecycle {
-    d;
+let ExtensionLifecycle = class ExtensionLifecycle {
+    host;
+    bus;
+    status;
+    installs;
+    config;
+    log;
     running;
     queued;
     unsubs = [];
+    /** {@link start} was called (the kernel's start sequence; never in the CLI, which loads nothing). */
+    started = false;
     stopped = false;
-    constructor(d) {
-        this.d = d;
+    constructor(host, bus, status, 
+    /** Every install record's name (any desired state): prunes status rows this replica no longer knows. */
+    installs, config, log) {
+        this.host = host;
+        this.bus = bus;
+        this.status = status;
+        this.installs = installs;
+        this.config = config;
+        this.log = log;
     }
     /** 订阅三个主题（订阅失败只记 error：周期任务的消息同样收不到时，下次启动再来）。 */
     async start() {
+        this.started = true;
         const on = async (topic, handler) => {
             try {
-                this.unsubs.push(await this.d.bus.subscribe(topic, handler));
+                this.unsubs.push(await this.bus.subscribe(topic, handler));
             }
             catch (err) {
-                this.d.log.error("cannot subscribe to plugin lifecycle topic", { topic, err });
+                this.log.error("cannot subscribe to plugin lifecycle topic", { topic, err });
             }
         };
         await on(PLUGINS_CHANGED_TOPIC, (p) => {
             // 安装 / 卸载改变了「部署已知」的插件名：路由闸门不等 TTL
-            this.d.host.invalidateKnownNames();
+            this.host.invalidateKnownNames();
             this.trigger(`changed:${pluginOf(p)}`);
         });
         await on(PLUGINS_RECONCILE_TOPIC, () => this.trigger("periodic"));
         await on(PLUGINS_MIGRATED_TOPIC, (p) => this.trigger(`migrated:${pluginOf(p)}`));
         await on(PLUGIN_DEPLOYMENT_CONFIG_TOPIC, (p) => {
-            this.applyConfig(pluginOf(p)).catch((err) => this.d.log.error("applying a plugin deployment config change failed", {
+            this.applyConfig(pluginOf(p)).catch((err) => this.log.error("applying a plugin deployment config change failed", {
                 plugin: pluginOf(p),
                 err,
             }));
@@ -63,7 +83,7 @@ export class ExtensionLifecycle {
     async applyConfig(plugin) {
         if (this.stopped)
             return;
-        const r = await this.d.host.applyDeploymentConfig(plugin);
+        const r = await this.host.applyDeploymentConfig(plugin);
         if (r === "not_loaded")
             await this.reconcile(`config:${plugin}`);
     }
@@ -79,7 +99,9 @@ export class ExtensionLifecycle {
      * 宿主那一步失败只记 error（下一个周期再来）；之后照常刷新心跳。
      */
     reconcile(reason) {
-        if (this.stopped)
+        // Before start (the bootstrap step, the CLI) there is nothing loaded to converge: the host
+        // loads the desired state as it is when it starts
+        if (this.stopped || !this.started)
             return Promise.resolve();
         if (this.queued)
             return this.queued;
@@ -98,38 +120,38 @@ export class ExtensionLifecycle {
     }
     /** 用同一个包重新 setup（配置的非 hot 改动、依赖方联动；与 reconcile 一样在宿主的串行队列里）。 */
     async reload(name) {
-        await this.d.host.reload(name);
+        await this.host.reload(name);
     }
     trigger(reason) {
-        this.reconcile(reason).catch((err) => this.d.log.error("plugin reconcile failed", { reason, err }));
+        this.reconcile(reason).catch((err) => this.log.error("plugin reconcile failed", { reason, err }));
     }
     async run(reason) {
         // 开始时也刷新心跳：converge 可能很久（排空在途调用、迁移），不能因此被读状态的一方当成退出的副本
-        await this.d.status.heartbeat().catch((err) => {
-            this.d.log.warn("cannot refresh plugin replica status heartbeats", { err });
+        await this.status.heartbeat().catch((err) => {
+            this.log.warn("cannot refresh plugin replica status heartbeats", { err });
         });
         try {
-            await this.d.host.converge();
+            await this.host.converge();
         }
         catch (err) {
             if (this.stopped)
                 return;
-            this.d.log.error("plugin reconcile failed; retrying on the next cycle", { reason, err });
+            this.log.error("plugin reconcile failed; retrying on the next cycle", { reason, err });
         }
         if (this.stopped)
             return;
         if (reason === "periodic") {
             // 丢了 plugin-deployment-config 消息时：周期兜底重读生效插件的部署配置（没变时什么都不做）
-            for (const name of this.d.host.configurablePlugins()) {
+            for (const name of this.host.configurablePlugins()) {
                 if (this.stopped)
                     return;
                 try {
-                    await this.d.host.applyDeploymentConfig(name);
+                    await this.host.applyDeploymentConfig(name);
                 }
                 catch (err) {
                     if (this.stopped)
                         return;
-                    this.d.log.error("applying a plugin deployment config change failed", {
+                    this.log.error("applying a plugin deployment config change failed", {
                         plugin: name,
                         err,
                     });
@@ -137,16 +159,58 @@ export class ExtensionLifecycle {
             }
         }
         try {
-            await this.d.status.heartbeat();
-            const keep = [...this.d.host.declared().keys(), ...(await this.d.installedNames())];
-            const period = this.d.reconcileIntervalSeconds();
-            await this.d.status.prune(keep, PRUNE_RECONCILE_PERIODS * period);
+            await this.status.heartbeat();
+            const keep = [...this.host.declared().keys(), ...(await this.installs.installedNames())];
+            const period = this.config.get().extensionHost.reconcileIntervalSeconds;
+            await this.status.prune(keep, PRUNE_RECONCILE_PERIODS * period);
         }
         catch (err) {
-            this.d.log.warn("cannot refresh plugin replica status heartbeats", { err });
+            this.log.warn("cannot refresh plugin replica status heartbeats", { err });
         }
     }
-}
+};
+ExtensionLifecycle = __decorate([
+    Injectable(),
+    __param(0, Inject(ExtensionHost)),
+    __param(1, Inject(KERNEL_BUS)),
+    __param(2, Inject(ReplicaStatusStore)),
+    __param(3, Inject(ExtensionInstalls)),
+    __param(4, Inject(KernelConfigService)),
+    __param(5, Inject(KERNEL_LOGGER))
+], ExtensionLifecycle);
+export { ExtensionLifecycle };
 const pluginOf = (p) => typeof p === "object" && p !== null && typeof p.plugin === "string"
     ? p.plugin
     : "?";
+/**
+ * The periodic reconcile fallback (job `plugins-reconcile`, once per
+ * `extensionHost.reconcileIntervalSeconds` across replicas): publishes `kernel.plugins.reconcile`,
+ * so every replica converges even when it lost a message. A worker-role job (`WorkerModule`); every
+ * replica's {@link ExtensionLifecycle} subscribes to the topic.
+ */
+let PluginsReconcileJob = class PluginsReconcileJob {
+    bus;
+    config;
+    lockService;
+    log;
+    constructor(bus, config, lockService, log) {
+        this.bus = bus;
+        this.config = config;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    async run() {
+        await this.bus.publish(PLUGINS_RECONCILE_TOPIC, {});
+    }
+};
+__decorate([
+    LockedInterval(PLUGINS_RECONCILE_JOB, (c) => c.extensionHost.reconcileIntervalSeconds * 1000)
+], PluginsReconcileJob.prototype, "run", null);
+PluginsReconcileJob = __decorate([
+    Injectable(),
+    __param(0, Inject(KERNEL_BUS)),
+    __param(1, Inject(KernelConfigService)),
+    __param(2, Inject(LockService)),
+    __param(3, Inject(KERNEL_LOGGER))
+], PluginsReconcileJob);
+export { PluginsReconcileJob };

package/dist/extensions/locks.d.ts

@@ -0,0 +1,45 @@
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { XactLock } from "../infra/database/xact-lock.js";
+/**
+ * Serializes the install record writes of one extension name (install, enable, disable, uninstall),
+ * including a first install that has no row to lock yet. Joins the caller's transaction
+ * (`mandatory`), which holds the lock until it ends.
+ */
+export declare class PluginInstallLock {
+    private readonly xactLock;
+    readonly txHost: TransactionHost;
+    constructor(xactLock: XactLock, txHost: TransactionHost);
+    lock(name: string): Promise<void>;
+}
+/**
+ * Serializes the permission snapshot writes of one extension (web approval, the bootstrap step's
+ * approval of a stored package). Joins the caller's transaction (`mandatory`).
+ */
+export declare class PluginApproveLock {
+    private readonly xactLock;
+    readonly txHost: TransactionHost;
+    constructor(xactLock: XactLock, txHost: TransactionHost);
+    lock(name: string): Promise<void>;
+}
+/**
+ * Serializes the deployment config writes of one extension. Joins the caller's transaction
+ * (`mandatory`).
+ */
+export declare class PluginDeploymentConfigLock {
+    private readonly xactLock;
+    readonly txHost: TransactionHost;
+    constructor(xactLock: XactLock, txHost: TransactionHost);
+    lock(name: string): Promise<void>;
+}
+/**
+ * Serializes the enables of the providers of one single-provider extension point (`sandbox@2`, …):
+ * two concurrent enables of different providers cannot both see the point free. Joins the
+ * caller's transaction (`mandatory`); taken after the install lock of the extension's name, the
+ * points in sorted order.
+ */
+export declare class SingleProviderLock {
+    private readonly xactLock;
+    readonly txHost: TransactionHost;
+    constructor(xactLock: XactLock, txHost: TransactionHost);
+    lock(extensionPoint: string): Promise<void>;
+}

package/dist/extensions/locks.js

@@ -0,0 +1,112 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { XactLock } from "../infra/database/xact-lock.js";
+/**
+ * Serializes the install record writes of one extension name (install, enable, disable, uninstall),
+ * including a first install that has no row to lock yet. Joins the caller's transaction
+ * (`mandatory`), which holds the lock until it ends.
+ */
+let PluginInstallLock = class PluginInstallLock {
+    xactLock;
+    txHost;
+    constructor(xactLock, txHost) {
+        this.xactLock = xactLock;
+        this.txHost = txHost;
+    }
+    async lock(name) {
+        await this.xactLock.lock(`capybara.plugin-install:${name}`);
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], PluginInstallLock.prototype, "lock", null);
+PluginInstallLock = __decorate([
+    Injectable(),
+    __param(0, Inject(XactLock)),
+    __param(1, Inject(TransactionHost))
+], PluginInstallLock);
+export { PluginInstallLock };
+/**
+ * Serializes the permission snapshot writes of one extension (web approval, the bootstrap step's
+ * approval of a stored package). Joins the caller's transaction (`mandatory`).
+ */
+let PluginApproveLock = class PluginApproveLock {
+    xactLock;
+    txHost;
+    constructor(xactLock, txHost) {
+        this.xactLock = xactLock;
+        this.txHost = txHost;
+    }
+    async lock(name) {
+        await this.xactLock.lock(`capybara.plugin-approve:${name}`);
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], PluginApproveLock.prototype, "lock", null);
+PluginApproveLock = __decorate([
+    Injectable(),
+    __param(0, Inject(XactLock)),
+    __param(1, Inject(TransactionHost))
+], PluginApproveLock);
+export { PluginApproveLock };
+/**
+ * Serializes the deployment config writes of one extension. Joins the caller's transaction
+ * (`mandatory`).
+ */
+let PluginDeploymentConfigLock = class PluginDeploymentConfigLock {
+    xactLock;
+    txHost;
+    constructor(xactLock, txHost) {
+        this.xactLock = xactLock;
+        this.txHost = txHost;
+    }
+    async lock(name) {
+        await this.xactLock.lock(`capybara.plugin-deployment-config:${name}`);
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], PluginDeploymentConfigLock.prototype, "lock", null);
+PluginDeploymentConfigLock = __decorate([
+    Injectable(),
+    __param(0, Inject(XactLock)),
+    __param(1, Inject(TransactionHost))
+], PluginDeploymentConfigLock);
+export { PluginDeploymentConfigLock };
+/**
+ * Serializes the enables of the providers of one single-provider extension point (`sandbox@2`, …):
+ * two concurrent enables of different providers cannot both see the point free. Joins the
+ * caller's transaction (`mandatory`); taken after the install lock of the extension's name, the
+ * points in sorted order.
+ */
+let SingleProviderLock = class SingleProviderLock {
+    xactLock;
+    txHost;
+    constructor(xactLock, txHost) {
+        this.xactLock = xactLock;
+        this.txHost = txHost;
+    }
+    async lock(extensionPoint) {
+        await this.xactLock.lock(`capybara.single-provider:${extensionPoint}`);
+    }
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], SingleProviderLock.prototype, "lock", null);
+SingleProviderLock = __decorate([
+    Injectable(),
+    __param(0, Inject(XactLock)),
+    __param(1, Inject(TransactionHost))
+], SingleProviderLock);
+export { SingleProviderLock };

package/dist/extensions/migrate-lock.d.ts

@@ -1,12 +1,11 @@
-import { type Transaction } from "kysely";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
 /** 插件迁移完成（kernel bus 主题，频道 `cap:kernel:plugins.migrated`，payload `{ plugin, sha256 }`）。 */
 export declare const PLUGINS_MIGRATED_TOPIC = "plugins.migrated";
 /** 插件迁移咨询锁的键前缀（`hashtext(<前缀><插件名>)`）。 */
 export declare const MIGRATE_LOCK_PREFIX = "capybara.plugin-migrate:";
 /** {@link ensureMigrated} 的依赖。 */
 export interface MigrateLockDeps {
-    db: KernelDb;
+    db: KernelSchemaDb;
     /** 迁移用独立连接（不走连接池）。 */
     dbUrl: string;
     connectTimeoutMs?: number | undefined;
@@ -45,7 +44,7 @@ export declare function ensureMigrated(d: MigrateLockDeps, name: string, sha256:
  * 按插件 schema 的 `_migrations` 表比对文件名与 checksum（与迁移器相同的 sha256）；改过内容的也算未执行。
  * 插件从没迁移过时返回全部文件。
  */
-export declare function unrunMigrations(db: KernelDb | Transaction<KernelDatabase>, name: string, files: {
+export declare function unrunMigrations(db: KernelSchemaDb, name: string, files: {
     file: string;
     sql: string;
 }[]): Promise<string[]>;