@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.3

package/dist/kernel.module.d.ts

@@ -0,0 +1,17 @@
+import { type DynamicModule } from "@nestjs/common";
+import type { KernelAppOptions } from "./app.js";
+import type { KernelConfig } from "./config/schema.js";
+/**
+ * The kernel application's root module (nest kernel spec §2): the global infra (config, logging,
+ * the shutdown state, database, Redis, locks, cache, queues, throttler), the application options,
+ * the domain modules `KernelLifecycle` uses, the role modules by `roles` (`ApiModule`: the
+ * controllers; `WorkerModule`: every cron and queue consumer; `GatewayModule`: the channel
+ * supervisor and the webhook inbound), the health endpoints and the global error filter on every
+ * role, and {@link KernelLifecycle}, which owns the start order and the stop phases (it drives the
+ * worker and gateway roles' parts, `WorkerRole` / `GatewayRole`). `KernelLifecycle` sits in the
+ * root module on purpose: Nest runs shutdown hooks from the root outwards, so its stop phases
+ * finish before the global infra closes Redis and the pool.
+ */
+export declare class KernelModule {
+    static forRoot(config: KernelConfig, options?: KernelAppOptions): DynamicModule;
+}

package/dist/kernel.module.js

@@ -0,0 +1,136 @@
+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 KernelAppOptionsModule_1, KernelModule_1;
+import { Global, Module } from "@nestjs/common";
+import { APP_INTERCEPTOR } from "@nestjs/core";
+import { CatalogModule } from "./catalog/catalog.module.js";
+import { ChannelsModule } from "./channels/channels.module.js";
+import { TitlesModule } from "./conversations/titles.js";
+import { ExtensionsModule } from "./extensions/extensions.module.js";
+import { ApiModule } from "./http/api.module.js";
+import { ErrorFilterModule } from "./http/error-filter.module.js";
+import { IdentityModule } from "./identity/identity.module.js";
+import { CacheModule } from "./infra/cache/cache.module.js";
+import { ConfigModule } from "./infra/config/config.module.js";
+import { DatabaseModule } from "./infra/database/database.module.js";
+import { KernelEventsModule } from "./infra/events/kernel-events.js";
+import { HealthController } from "./infra/health/health.controller.js";
+import { HealthModule } from "./infra/health/health.module.js";
+import { databaseCheck, HEALTH_CHECKS, redisCheck } from "./infra/health/health.options.js";
+import { GracefulShutdownModule } from "./infra/lifecycle/graceful-shutdown.module.js";
+import { LockModule } from "./infra/lock/lock.module.js";
+import { LoggingModule } from "./infra/logging/logging.module.js";
+import { QueueModule } from "./infra/queue/queue.module.js";
+import { RedisModule } from "./infra/redis/redis.module.js";
+import { KernelThrottlerModule } from "./infra/throttler/throttler.module.js";
+import { KERNEL_POOL, REDIS } from "./infra/tokens.js";
+import { ValidationModule } from "./infra/validation/validation.module.js";
+import { KernelLifecycle } from "./lifecycle/kernel-lifecycle.js";
+import { KERNEL_APP_OPTIONS } from "./lifecycle/tokens.js";
+import { createConfiguredLogger } from "./log-config.js";
+import { KERNEL_OVERRIDE_TOKENS } from "./overrides.js";
+import { GatewayModule } from "./roles/gateway.module.js";
+import { WorkerModule } from "./roles/worker.module.js";
+import { UsageReportModule } from "./runtime/usage-report.js";
+/**
+ * Global: the options the application was built with (`KERNEL_APP_OPTIONS`) and its `overrides`,
+ * the test seams (`KernelOverride`: values for the named seam tokens the domain modules
+ * resolve as optional providers). A token outside {@link KERNEL_OVERRIDE_TOKENS} is refused, so no
+ * domain class can be replaced this way.
+ */
+let KernelAppOptionsModule = KernelAppOptionsModule_1 = class KernelAppOptionsModule {
+    static forRoot(options) {
+        const overrides = options.overrides ?? [];
+        for (const o of overrides) {
+            if (!KERNEL_OVERRIDE_TOKENS.has(o.provide)) {
+                const token = o.provide;
+                const name = typeof token === "function" ? token.name : String(token);
+                throw new Error(`overrides: ${name} is not a kernel test seam`);
+            }
+        }
+        return {
+            module: KernelAppOptionsModule_1,
+            global: true,
+            providers: [{ provide: KERNEL_APP_OPTIONS, useValue: options }, ...overrides],
+            // an application enhancer (`APP_INTERCEPTOR`) applies globally from any module and is never
+            // exported (Nest gives it a unique token)
+            exports: [
+                KERNEL_APP_OPTIONS,
+                ...overrides.map((o) => o.provide).filter((t) => t !== APP_INTERCEPTOR),
+            ],
+        };
+    }
+};
+KernelAppOptionsModule = KernelAppOptionsModule_1 = __decorate([
+    Global(),
+    Module({})
+], KernelAppOptionsModule);
+/**
+ * The kernel application's root module (nest kernel spec §2): the global infra (config, logging,
+ * the shutdown state, database, Redis, locks, cache, queues, throttler), the application options,
+ * the domain modules `KernelLifecycle` uses, the role modules by `roles` (`ApiModule`: the
+ * controllers; `WorkerModule`: every cron and queue consumer; `GatewayModule`: the channel
+ * supervisor and the webhook inbound), the health endpoints and the global error filter on every
+ * role, and {@link KernelLifecycle}, which owns the start order and the stop phases (it drives the
+ * worker and gateway roles' parts, `WorkerRole` / `GatewayRole`). `KernelLifecycle` sits in the
+ * root module on purpose: Nest runs shutdown hooks from the root outwards, so its stop phases
+ * finish before the global infra closes Redis and the pool.
+ */
+let KernelModule = KernelModule_1 = class KernelModule {
+    static forRoot(config, options = {}) {
+        const logger = options.logger ?? createConfiguredLogger(config);
+        return {
+            module: KernelModule_1,
+            imports: [
+                LoggingModule.forRoot(config, { logger }),
+                ConfigModule.forRoot(config, options.env !== undefined ? { env: options.env } : {}),
+                GracefulShutdownModule,
+                DatabaseModule.forRoot(),
+                RedisModule,
+                LockModule,
+                CacheModule,
+                KernelEventsModule,
+                QueueModule.forRoot(),
+                KernelThrottlerModule,
+                HealthModule,
+                ValidationModule,
+                ErrorFilterModule,
+                KernelAppOptionsModule.forRoot({ ...options, logger }),
+                // KernelLifecycle's setup check, the extension host it drives, the catalog it syncs and
+                // the producers its stop closes on every role (titles, usage.report, channel deliveries)
+                IdentityModule,
+                ExtensionsModule,
+                CatalogModule,
+                TitlesModule,
+                UsageReportModule,
+                ChannelsModule,
+                // the role modules, by `roles` (nest kernel spec §2)
+                ...(config.roles.includes("api") ? [ApiModule] : []),
+                ...(config.roles.includes("worker") ? [WorkerModule.forRoot(config)] : []),
+                ...(config.roles.includes("gateway") ? [GatewayModule] : []),
+            ],
+            controllers: [HealthController],
+            providers: [
+                {
+                    provide: HEALTH_CHECKS,
+                    inject: [KERNEL_POOL, REDIS],
+                    // biome-ignore lint/suspicious/noExplicitAny: the pool carries no schema types
+                    useFactory: (pool, redis) => ({
+                        pg: databaseCheck(pool),
+                        redis: redisCheck(redis),
+                    }),
+                },
+                KernelLifecycle,
+            ],
+        };
+    }
+};
+KernelModule = KernelModule_1 = __decorate([
+    Module({})
+    // biome-ignore lint/complexity/noStaticOnlyClass: a Nest dynamic module
+], KernelModule);
+export { KernelModule };

package/dist/lifecycle/kernel-lifecycle.d.ts

@@ -0,0 +1,140 @@
+import { type ExtensionContext } from "@capybara-hq/plugin-sdk";
+import { type BeforeApplicationShutdown, type OnApplicationBootstrap, type OnApplicationShutdown } from "@nestjs/common";
+import type { Redis } from "ioredis";
+import { type Kysely } from "kysely";
+import type { KernelAppOptions } from "../app.js";
+import { MarketplacesService } from "../catalog/marketplaces.service.js";
+import { PluginImport } from "../catalog/plugin-import.js";
+import { ChannelJobs } from "../channels/jobs.js";
+import { ChannelOutbound } from "../channels/outbound.js";
+import { TitleQueue } from "../conversations/titles.js";
+import { ExtensionBlobs } from "../extensions/blobs.js";
+import { BootstrapService } from "../extensions/bootstrap.js";
+import { ExtensionHost } from "../extensions/host.js";
+import { ExtensionInstalls } from "../extensions/installs.js";
+import { ExtensionLifecycle } from "../extensions/lifecycle.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { ReplicaStatusStore } from "../extensions/sources.js";
+import type { KernelHttpApp } from "../http/app.js";
+import type { GatewayRoutes } from "../http/gateway-routes.js";
+import { AccountsService } from "../identity/accounts.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { GracefulShutdown } from "../infra/lifecycle/graceful-shutdown.service.js";
+import type { KernelLogger } from "../log.js";
+import { GatewayRole } from "../roles/gateway-role.js";
+import { WorkerRole } from "../roles/worker-role.js";
+import { UsageReporter } from "../runtime/usage-report.js";
+/**
+ * The stop phase budgets. Each phase waits `min(its budget, what is left of the total)`, where the
+ * total is `STOP_TIMEOUT_MS` (30 s, `GracefulShutdown`) counted from the moment the shutdown
+ * began, in this order: migrate 2 s (the start's in-flight kernel migration, aborted, until its
+ * session ended) → http 10 s → runs 10 s → plugins 5 s, 27 s in all. The bus subscriber, Redis and
+ * the pool are closed after the phases by the infra modules (`onApplicationShutdown`) within what
+ * is left of the same 30 s, so the whole stop never takes longer than 30 s.
+ * The http phase is one deadline: first the listen in progress finishes (closing while listening
+ * would leave the port open), then HTTP closes, both within these 10 s; whatever is still open at
+ * the deadline is disconnected.
+ * The runs phase: this process's runs get the stop signal, stop at their next step boundary and
+ * their jobs go back to the queue; runs over the budget are left to BullMQ's stalled-job handling
+ * on another worker (spec 8.5). So when an earlier phase hangs, the extension queues still get at
+ * least 5 s to drain.
+ */
+export declare const STOP_BUDGET_MS: {
+    readonly migrate: 2000;
+    readonly http: 10000;
+    readonly runs: 10000;
+    readonly plugins: 5000;
+};
+/**
+ * The kernel's start order and stop phases on Nest's hooks (nest kernel spec §4).
+ *
+ * Start (`onApplicationBootstrap`, run by `app.init()`): Redis ready → kernel migrations → official
+ * marketplace sync → bootstrap → extension host load → role parts (workers, schedules, gateway) →
+ * mount extension routes → extension lifecycle reconcile → (second bootstrap pass) → config watch.
+ * {@link listen} runs only after that resolved, so nothing is served before the extensions are
+ * loaded. A stop requested meanwhile makes the sequence throw at its next checkpoint.
+ *
+ * Stop (`beforeApplicationShutdown`, or {@link stop} directly): readiness answers 503, the start is
+ * aborted, then today's phases with {@link STOP_BUDGET_MS} (HTTP, runs, channels, queues, the
+ * extension host). Redis and the pool are closed after this by the infra modules
+ * (`onApplicationShutdown`, global modules run last).
+ */
+export declare class KernelLifecycle implements OnApplicationBootstrap, BeforeApplicationShutdown, OnApplicationShutdown {
+    private readonly accounts;
+    private readonly configService;
+    readonly log: KernelLogger;
+    private readonly options;
+    private readonly pool;
+    private readonly redis;
+    private readonly kdb;
+    private readonly shutdown;
+    private readonly host;
+    private readonly registry;
+    private readonly installs;
+    private readonly blobs;
+    private readonly extensionLifecycle;
+    private readonly replicaStatus;
+    private readonly bootstrap;
+    private readonly marketplaces;
+    private readonly pluginImport;
+    private readonly bus;
+    private readonly usageReport;
+    private readonly titles;
+    private readonly channelJobs;
+    private readonly channelOutbound;
+    private readonly worker?;
+    private readonly gateway?;
+    /** The startup config (hot fields are read through the config service). */
+    private readonly config;
+    /** Set when the application was never set up completely: shutdown only releases connections. */
+    private onlyRelease;
+    private stopPromise;
+    /** {@link listen} was called: the start work in flight is the listen, not the start sequence. */
+    private listenStarted;
+    private listening;
+    private httpApp;
+    private unwatchConfig;
+    /** What the first bootstrap pass did, carried into the second one. */
+    private bootstrapCarry;
+    constructor(accounts: AccountsService, configService: KernelConfigService, log: KernelLogger, options: KernelAppOptions, pool: Kysely<any>, redis: Redis, kdb: KernelDb, shutdown: GracefulShutdown, host: ExtensionHost, registry: ExtensionRegistry, installs: ExtensionInstalls, blobs: ExtensionBlobs, extensionLifecycle: ExtensionLifecycle, replicaStatus: ReplicaStatusStore, bootstrap: BootstrapService, marketplaces: MarketplacesService, pluginImport: PluginImport, bus: Pick<ExtensionContext["bus"], "publish" | "subscribe">, usageReport: UsageReporter, titles: TitleQueue, channelJobs: ChannelJobs, channelOutbound: ChannelOutbound, worker?: WorkerRole | undefined, gateway?: GatewayRole | undefined);
+    /** The kernel HTTP application (set up by `buildKernelApp` before `init()`). */
+    get http(): KernelHttpApp;
+    attachHttp(http: KernelHttpApp): void;
+    /** The gateway role's HTTP routes (the channel webhook), when the roles include `gateway`. */
+    gatewayRoutes(): GatewayRoutes | undefined;
+    /** The port listened on; undefined before {@link listen} resolves and after the stop. */
+    get port(): number | undefined;
+    /** The application was not set up completely: its shutdown only releases connections. */
+    releaseOnly(): void;
+    private checkpoint;
+    onApplicationBootstrap(): Promise<void>;
+    /**
+     * Listens on `port` (0.0.0.0; every role listens: worker-only serves only `/healthz` and
+     * `/readyz`) after the start sequence; returns the actual port.
+     */
+    listen(port: number): Promise<number>;
+    /**
+     * Runs the bootstrap step unless it is done for the manifest. A required entry that cannot be
+     * completed (or a missing / tampered package: then nothing was installed) stops the start, so the
+     * kernel never serves without a required plugin. A failed optional entry is logged and returns
+     * true: the start runs the step once more after the extensions loaded (a declarative entry's
+     * catalog files need the object store, which on a fresh deployment is itself a bootstrap plugin),
+     * and the next start tries again while it stays incomplete.
+     */
+    private runBootstrap;
+    /** 部署尚无活跃企业管理员时提示去初始化；查询失败只记日志，不影响启动。 */
+    private warnIfSetupPending;
+    beforeApplicationShutdown(): Promise<void>;
+    /** Logs the end of the stop phases (Redis and the pool close right after, in the infra modules). */
+    onApplicationShutdown(): void;
+    /**
+     * Runs the stop phases once (idempotent): the shutdown begins at once (`GracefulShutdown.begin`:
+     * readiness answers 503, the start is aborted, the SSE streams close). Closing the application
+     * calls this from `beforeApplicationShutdown`; `closeKernelApp` (the tests, the signal handlers
+     * of `startKernelApp`) calls it directly next to `app.close()`, so the shutdown
+     * begins before any module's `onModuleDestroy` runs (Nest runs those first).
+     */
+    stop(): Promise<void>;
+    private runStopPhases;
+}