@undefineds.co/xpod 0.4.10 → 0.4.12

package/dist/logging/log-file.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOG_FILE_PATTERN = exports.LOG_FILE_NAME_PATTERN = exports.LOG_DIRECTORY = void 0;
+exports.resolveLogFilePattern = resolveLogFilePattern;
+exports.resolveCurrentLogFile = resolveCurrentLogFile;
+/**
+ * Canonical location of the runtime log file.
+ *
+ * Every writer (main entry, runtime bootstrap, API service) and every reader
+ * (admin diagnostics) resolves the path through this module. When the reader
+ * guessed its own file names instead, the Logs page reported "no log file"
+ * while the runtime kept writing to one.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/** Directory, relative to the runtime working directory. */
+exports.LOG_DIRECTORY = 'logs';
+/** File name template; the rotating transport substitutes `%DATE%`. */
+exports.LOG_FILE_NAME_PATTERN = 'xpod-%DATE%.log';
+/** Both segments, for callers that join them onto a working directory themselves. */
+exports.LOG_FILE_PATTERN = `${exports.LOG_DIRECTORY}/${exports.LOG_FILE_NAME_PATTERN}`;
+/** Concrete files the template produces, including rotated siblings such as `xpod-2026-09-13.log.2`. */
+const CONCRETE_LOG_FILE_NAME = /^xpod-.*\.log(\.\d+)?$/;
+/** Absolute path template handed to the logging transport. */
+function resolveLogFilePattern(cwd = process.cwd()) {
+    return node_path_1.default.join(cwd, exports.LOG_DIRECTORY, exports.LOG_FILE_NAME_PATTERN);
+}
+/**
+ * The log file currently being appended to, or `null` when the runtime has not
+ * written one yet.
+ *
+ * Daily rotation produces one file per date and size rotation keeps older
+ * segments as `.log.N` next to it, so the live file is identified by
+ * modification time rather than by name.
+ */
+function resolveCurrentLogFile(cwd = process.cwd()) {
+    const directory = node_path_1.default.join(cwd, exports.LOG_DIRECTORY);
+    let names;
+    try {
+        names = node_fs_1.default.readdirSync(directory);
+    }
+    catch {
+        return null;
+    }
+    let newest = null;
+    for (const name of names) {
+        if (!CONCRETE_LOG_FILE_NAME.test(name))
+            continue;
+        const file = node_path_1.default.join(directory, name);
+        let mtimeMs;
+        try {
+            const stats = node_fs_1.default.statSync(file);
+            if (!stats.isFile())
+                continue;
+            mtimeMs = stats.mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        if (!newest || mtimeMs > newest.mtimeMs) {
+            newest = { file, mtimeMs };
+        }
+    }
+    return newest?.file ?? null;
+}
+//# sourceMappingURL=log-file.js.map

package/dist/main.js

@@ -17,6 +17,7 @@ const css_process_1 = require("./runtime/css-process");
 const oidc_issuer_1 = require("./runtime/oidc-issuer");
 const AuthMode_1 = require("./authorization/AuthMode");
 const ConfigurableLoggerFactory_1 = require("./logging/ConfigurableLoggerFactory");
+const log_file_1 = require("./logging/log-file");
 const supervisor_1 = require("./supervisor");
 const js_runtime_1 = require("./runtime/js-runtime");
 const database_url_1 = require("./runtime/database-url");
@@ -27,7 +28,7 @@ const EXIT_INTERNAL_ERROR = 50;
 let logger = (0, global_logger_factory_1.getLoggerFor)('Main');
 function initLogger() {
     const loggerFactory = new ConfigurableLoggerFactory_1.ConfigurableLoggerFactory(process.env.CSS_LOGGING_LEVEL || 'info', {
-        fileName: path_1.default.join(process.cwd(), 'logs/xpod-%DATE%.log'),
+        fileName: (0, log_file_1.resolveLogFilePattern)(),
         showLocation: true,
     });
     (0, global_logger_factory_1.setGlobalLoggerFactory)(loggerFactory);

package/dist/notifications/NotificationChannelSweeper.d.ts

@@ -0,0 +1,50 @@
+import type { Finalizable, KeyValueStorage, NotificationChannelStorage, WebSocketMap } from '@solid/community-server';
+import { Initializer } from '@solid/community-server';
+/** 默认清扫间隔（分钟）。同时是“新建但尚未连上 socket”的通道的宽限期。 */
+export declare const NOTIFICATION_CHANNEL_SWEEP_INTERVAL_MINUTES = 5;
+/**
+ * 回收没有活动 socket 的通知通道。
+ *
+ * 背景：CSS 的 `WebSocket2023Storer` 只在 socket 关闭时把它从内存 map 中移除，通道记录留在
+ * `SubscriptionStorage` 里直到 `endAt` 过期（默认 2 周）；客户端 DELETE 失败、页面崩溃、
+ * 进程被强杀等情况都会留下再也无人使用、也无人回收的通道。`ReclaimingWebSocket2023Storer`
+ * 覆盖了正常关闭的路径，本组件负责其余部分：
+ *
+ * 1. 启动时清扫一次：进程刚起来，内存 map 必然为空，任何持久化的通道都不可能还有活动 socket；
+ * 2. 之后每 {@link NOTIFICATION_CHANNEL_SWEEP_INTERVAL_MINUTES} 分钟清扫一次：无 socket 的通道
+ *    需要连续两次被判定为孤儿才删除，避免误删“刚 POST 出来、socket 还在握手”的通道。
+ *
+ * 只回收本实例 `baseUrl` 下的通道：通道 id 由本实例的订阅路由生成，Cloud 集群中共享
+ * `internal_kv` 的其他节点（若存在）的通道由各自实例负责，这里不做跨实例删除。
+ * 与 socket 归属相关的限制（同一个 baseUrl 被多个 CSS 进程共享时无法判断通道是否在别的进程里存活）
+ * 见 `docs/COMPONENTS.md`。
+ */
+export declare class NotificationChannelSweeper extends Initializer implements Finalizable {
+    protected readonly logger: import("global-logger-factory").Logger<unknown>;
+    private readonly channelStorage;
+    private readonly channelIndex;
+    private readonly socketMap;
+    private readonly baseUrl;
+    private readonly intervalMs;
+    /** 见过一次、但当时没有活动 socket 的通道 id；下一次仍是孤儿才回收。 */
+    private readonly awaitingSecondLook;
+    private timer?;
+    private sweeping;
+    constructor(storage: NotificationChannelStorage, channelIndex: KeyValueStorage<string, unknown>, socketMap: WebSocketMap, baseUrl: string, intervalMinutes?: number);
+    /**
+     * CSS 启动序列的一部分（在 HTTP server 开始监听之前执行）：先做一次启动清扫，再挂上有界的周期任务。
+     *
+     * 实测同一次 CSS 启动里本方法会被调用两次（配置图里只出现一次）。这里做成幂等：重复调用既不重复清扫，
+     * 也不重复注册定时器——两个定时器会让“连续两次判定”退化成相隔几百毫秒的两次判定，等于没有宽限期。
+     */
+    handle(): Promise<void>;
+    finalize(): Promise<void>;
+    /**
+     * 执行一次清扫，返回被回收的通道数量。
+     *
+     * @param initial - 启动清扫：内存中还没有任何 socket，因此无 socket 的通道一律视为孤儿。
+     */
+    sweep(initial?: boolean): Promise<number>;
+    /** 枚举本实例 baseUrl 下的通道记录。topic 索引行（值是 id 数组）不是通道，跳过。 */
+    private listOwnedChannels;
+}

package/dist/notifications/NotificationChannelSweeper.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationChannelSweeper = exports.NOTIFICATION_CHANNEL_SWEEP_INTERVAL_MINUTES = void 0;
+const community_server_1 = require("@solid/community-server");
+const global_logger_factory_1 = require("global-logger-factory");
+/** 默认清扫间隔（分钟）。同时是“新建但尚未连上 socket”的通道的宽限期。 */
+exports.NOTIFICATION_CHANNEL_SWEEP_INTERVAL_MINUTES = 5;
+function isNotificationChannel(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate.id === 'string' && typeof candidate.topic === 'string';
+}
+/**
+ * 回收没有活动 socket 的通知通道。
+ *
+ * 背景：CSS 的 `WebSocket2023Storer` 只在 socket 关闭时把它从内存 map 中移除，通道记录留在
+ * `SubscriptionStorage` 里直到 `endAt` 过期（默认 2 周）；客户端 DELETE 失败、页面崩溃、
+ * 进程被强杀等情况都会留下再也无人使用、也无人回收的通道。`ReclaimingWebSocket2023Storer`
+ * 覆盖了正常关闭的路径，本组件负责其余部分：
+ *
+ * 1. 启动时清扫一次：进程刚起来，内存 map 必然为空，任何持久化的通道都不可能还有活动 socket；
+ * 2. 之后每 {@link NOTIFICATION_CHANNEL_SWEEP_INTERVAL_MINUTES} 分钟清扫一次：无 socket 的通道
+ *    需要连续两次被判定为孤儿才删除，避免误删“刚 POST 出来、socket 还在握手”的通道。
+ *
+ * 只回收本实例 `baseUrl` 下的通道：通道 id 由本实例的订阅路由生成，Cloud 集群中共享
+ * `internal_kv` 的其他节点（若存在）的通道由各自实例负责，这里不做跨实例删除。
+ * 与 socket 归属相关的限制（同一个 baseUrl 被多个 CSS 进程共享时无法判断通道是否在别的进程里存活）
+ * 见 `docs/COMPONENTS.md`。
+ */
+class NotificationChannelSweeper extends community_server_1.Initializer {
+    constructor(storage, channelIndex, socketMap, baseUrl, intervalMinutes = exports.NOTIFICATION_CHANNEL_SWEEP_INTERVAL_MINUTES) {
+        super();
+        this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+        /** 见过一次、但当时没有活动 socket 的通道 id；下一次仍是孤儿才回收。 */
+        this.awaitingSecondLook = new Set();
+        this.sweeping = false;
+        this.channelStorage = storage;
+        this.channelIndex = channelIndex;
+        this.socketMap = socketMap;
+        // 通道 id 是 `<baseUrl>/.notifications/...`；补上结尾斜杠，避免 `https://pod.example`
+        // 匹配到 `https://pod.example.evil/...`。
+        this.baseUrl = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+        this.intervalMs = intervalMinutes * 60 * 1000;
+    }
+    /**
+     * CSS 启动序列的一部分（在 HTTP server 开始监听之前执行）：先做一次启动清扫，再挂上有界的周期任务。
+     *
+     * 实测同一次 CSS 启动里本方法会被调用两次（配置图里只出现一次）。这里做成幂等：重复调用既不重复清扫，
+     * 也不重复注册定时器——两个定时器会让“连续两次判定”退化成相隔几百毫秒的两次判定，等于没有宽限期。
+     */
+    async handle() {
+        if (this.timer) {
+            this.logger.debug('Notification channel sweep is already scheduled; ignoring duplicate initializer call');
+            return;
+        }
+        await this.sweep(true);
+        this.timer = (0, community_server_1.setSafeInterval)(this.logger, 'Failed to reclaim orphaned notification channels', async () => {
+            await this.sweep(false);
+        }, this.intervalMs);
+        // 不阻止进程退出：清扫只是运维兜底，不是常驻工作。
+        this.timer.unref();
+        this.logger.info(`Notification channel sweep scheduled every ${this.intervalMs / 60_000} minute(s)`);
+    }
+    async finalize() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    /**
+     * 执行一次清扫，返回被回收的通道数量。
+     *
+     * @param initial - 启动清扫：内存中还没有任何 socket，因此无 socket 的通道一律视为孤儿。
+     */
+    async sweep(initial = false) {
+        if (this.sweeping) {
+            return 0;
+        }
+        this.sweeping = true;
+        try {
+            const channels = await this.listOwnedChannels();
+            const reclaimed = [];
+            for (const channel of channels.values()) {
+                if (this.socketMap.has(channel.id)) {
+                    this.awaitingSecondLook.delete(channel.id);
+                    continue;
+                }
+                if (!initial && !this.awaitingSecondLook.has(channel.id)) {
+                    this.awaitingSecondLook.add(channel.id);
+                    continue;
+                }
+                if (await this.channelStorage.delete(channel.id)) {
+                    reclaimed.push(channel.id);
+                }
+                this.awaitingSecondLook.delete(channel.id);
+            }
+            // 已经被其他路径删除的通道不必再留在这里。
+            for (const id of [...this.awaitingSecondLook]) {
+                if (!channels.has(id)) {
+                    this.awaitingSecondLook.delete(id);
+                }
+            }
+            if (reclaimed.length > 0) {
+                this.logger.info(`Reclaimed ${reclaimed.length} notification channel(s) without a live WebSocket`);
+                this.logger.debug(`Reclaimed notification channels: ${reclaimed.join(', ')}`);
+            }
+            else {
+                this.logger.debug(`Notification channel sweep found no orphan among ${channels.size} channel(s)`);
+            }
+            return reclaimed.length;
+        }
+        finally {
+            this.sweeping = false;
+        }
+    }
+    /** 枚举本实例 baseUrl 下的通道记录。topic 索引行（值是 id 数组）不是通道，跳过。 */
+    async listOwnedChannels() {
+        const channels = new Map();
+        for await (const [, value] of this.channelIndex.entries()) {
+            if (!isNotificationChannel(value) || !value.id.startsWith(this.baseUrl)) {
+                continue;
+            }
+            channels.set(value.id, value);
+        }
+        return channels;
+    }
+}
+exports.NotificationChannelSweeper = NotificationChannelSweeper;
+//# sourceMappingURL=NotificationChannelSweeper.js.map

package/dist/notifications/NotificationChannelSweeper.jsonld

@@ -0,0 +1,136 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld",
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^8.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper",
+      "@type": "Class",
+      "requireElement": "NotificationChannelSweeper",
+      "extends": [
+        "css:dist/init/Initializer.jsonld#Initializer",
+        "css:dist/init/final/Finalizable.jsonld#Finalizable"
+      ],
+      "comment": "回收没有活动 socket 的通知通道。  背景：CSS 的 `WebSocket2023Storer` 只在 socket 关闭时把它从内存 map 中移除，通道记录留在 `SubscriptionStorage` 里直到 `endAt` 过期（默认 2 周）；客户端 DELETE 失败、页面崩溃、 进程被强杀等情况都会留下再也无人使用、也无人回收的通道。`ReclaimingWebSocket2023Storer` 覆盖了正常关闭的路径，本组件负责其余部分：  1. 启动时清扫一次：进程刚起来，内存 map 必然为空，任何持久化的通道都不可能还有活动 socket； 2. 之后每 {@link NOTIFICATION_CHANNEL_SWEEP_INTERVAL_MINUTES} 分钟清扫一次：无 socket 的通道 需要连续两次被判定为孤儿才删除，避免误删“刚 POST 出来、socket 还在握手”的通道。  只回收本实例 `baseUrl` 下的通道：通道 id 由本实例的订阅路由生成，Cloud 集群中共享 `internal_kv` 的其他节点（若存在）的通道由各自实例负责，这里不做跨实例删除。 与 socket 归属相关的限制（同一个 baseUrl 被多个 CSS 进程共享时无法判断通道是否在别的进程里存活） 见 `docs/COMPONENTS.md`。",
+      "parameters": [
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_baseUrl",
+          "range": "xsd:string"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_intervalMinutes",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:number",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          }
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_storage",
+          "range": "css:dist/server/notifications/NotificationChannelStorage.jsonld#NotificationChannelStorage"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_socketMap",
+          "range": "css:dist/server/notifications/WebSocketChannel2023/WebSocketMap.jsonld#WebSocketMap"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_channelIndex",
+          "range": {
+            "@type": "ParameterRangeGenericComponent",
+            "component": "css:dist/storage/keyvalue/KeyValueStorage.jsonld#KeyValueStorage",
+            "genericTypeInstances": [
+              "xsd:string",
+              {
+                "@type": "ParameterRangeWildcard"
+              }
+            ]
+          }
+        }
+      ],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper__member_logger",
+          "memberFieldName": "logger",
+          "range": {
+            "@type": "ParameterRangeWildcard"
+          }
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper__member_channelStorage",
+          "memberFieldName": "channelStorage"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper__member_channelIndex",
+          "memberFieldName": "channelIndex"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper__member_socketMap",
+          "memberFieldName": "socketMap"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper__member_baseUrl",
+          "memberFieldName": "baseUrl"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper__member_intervalMs",
+          "memberFieldName": "intervalMs"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper__member_awaitingSecondLook",
+          "memberFieldName": "awaitingSecondLook"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper__member_timer",
+          "memberFieldName": "timer"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper__member_sweeping",
+          "memberFieldName": "sweeping"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper__member_constructor",
+          "memberFieldName": "constructor"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper__member_handle",
+          "memberFieldName": "handle"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper__member_finalize",
+          "memberFieldName": "finalize"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper__member_sweep",
+          "memberFieldName": "sweep"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper__member_listOwnedChannels",
+          "memberFieldName": "listOwnedChannels"
+        }
+      ],
+      "constructorArguments": [
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_storage"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_channelIndex"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_socketMap"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_baseUrl"
+        },
+        {
+          "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_intervalMinutes"
+        }
+      ]
+    }
+  ]
+}

package/dist/notifications/ReclaimingWebSocket2023Storer.d.ts

@@ -0,0 +1,25 @@
+import type { NotificationChannelStorage, WebSocket2023HandlerInput, WebSocketMap } from '@solid/community-server';
+import { WebSocket2023Storer } from '@solid/community-server';
+/**
+ * WebSocket2023Storer 的等位替换：保留 CSS 原有行为（把 socket 存进 map、socket 关闭时从 map 移除、
+ * 定期关掉已过期通道的 socket），并补上缺失的一环——最后一个 socket 关闭或出错时回收通道记录。
+ *
+ * CSS 默认实现只在 `close`/`error` 时调用 `socketMap.deleteEntry(...)`，通道记录会一直留在
+ * `SubscriptionStorage` 里直到 `endAt` 过期（`NotificationSubscriber` 默认把它压到 2 周后），
+ * 因此每次页面刷新、HMR、崩溃都会留下一个再也不会被使用的通道。
+ *
+ * 只有当该通道名下的 socket 全部消失时才删除：同一个通道允许多个 socket（例如两个标签页共用一次订阅），
+ * 只要还有 socket 存活就必须保留通道，否则会静默掐断仍在监听的客户端。
+ */
+export declare class ReclaimingWebSocket2023Storer extends WebSocket2023Storer {
+    private readonly channelStorage;
+    private readonly liveSockets;
+    /**
+     * 一次 socket 终止可能先 `error` 再 `close`，这里保证同一个通道只回收一次。
+     * 通道 id 由 `randomUUID()` 生成且永不复用，因此不需要清理已回收的 id。
+     */
+    private readonly reclaiming;
+    constructor(storage: NotificationChannelStorage, socketMap: WebSocketMap, cleanupTimer?: number);
+    handle(input: WebSocket2023HandlerInput): Promise<void>;
+    private reclaim;
+}

package/dist/notifications/ReclaimingWebSocket2023Storer.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReclaimingWebSocket2023Storer = void 0;
+const community_server_1 = require("@solid/community-server");
+/**
+ * WebSocket2023Storer 的等位替换：保留 CSS 原有行为（把 socket 存进 map、socket 关闭时从 map 移除、
+ * 定期关掉已过期通道的 socket），并补上缺失的一环——最后一个 socket 关闭或出错时回收通道记录。
+ *
+ * CSS 默认实现只在 `close`/`error` 时调用 `socketMap.deleteEntry(...)`，通道记录会一直留在
+ * `SubscriptionStorage` 里直到 `endAt` 过期（`NotificationSubscriber` 默认把它压到 2 周后），
+ * 因此每次页面刷新、HMR、崩溃都会留下一个再也不会被使用的通道。
+ *
+ * 只有当该通道名下的 socket 全部消失时才删除：同一个通道允许多个 socket（例如两个标签页共用一次订阅），
+ * 只要还有 socket 存活就必须保留通道，否则会静默掐断仍在监听的客户端。
+ */
+class ReclaimingWebSocket2023Storer extends community_server_1.WebSocket2023Storer {
+    constructor(storage, socketMap, cleanupTimer) {
+        super(storage, socketMap, cleanupTimer);
+        /**
+         * 一次 socket 终止可能先 `error` 再 `close`，这里保证同一个通道只回收一次。
+         * 通道 id 由 `randomUUID()` 生成且永不复用，因此不需要清理已回收的 id。
+         */
+        this.reclaiming = new Set();
+        this.channelStorage = storage;
+        this.liveSockets = socketMap;
+    }
+    async handle(input) {
+        await super.handle(input);
+        const { channel, webSocket } = input;
+        // 基类的监听器先注册，所以这里运行时 map 已经反映了本次关闭后的真实状态。
+        // socket 事件回调不能把 rejection 抛回事件循环：删除失败只记日志，交给清扫器和 endAt 兜底。
+        const reclaim = () => {
+            this.reclaim(channel.id).catch((error) => {
+                this.logger.error(`Failed to reclaim notification channel ${channel.id}: ${(0, community_server_1.createErrorMessage)(error)}`);
+            });
+        };
+        webSocket.on('close', reclaim);
+        webSocket.on('error', reclaim);
+    }
+    async reclaim(id) {
+        if (this.liveSockets.has(id) || this.reclaiming.has(id)) {
+            return;
+        }
+        this.reclaiming.add(id);
+        try {
+            if (await this.channelStorage.delete(id)) {
+                this.logger.info(`Reclaimed notification channel ${id}: its last WebSocket closed`);
+            }
+        }
+        finally {
+            this.reclaiming.delete(id);
+        }
+    }
+}
+exports.ReclaimingWebSocket2023Storer = ReclaimingWebSocket2023Storer;
+//# sourceMappingURL=ReclaimingWebSocket2023Storer.js.map

package/dist/notifications/ReclaimingWebSocket2023Storer.jsonld

@@ -0,0 +1,77 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld",
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^8.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer",
+      "@type": "Class",
+      "requireElement": "ReclaimingWebSocket2023Storer",
+      "extends": [
+        "css:dist/server/notifications/WebSocketChannel2023/WebSocket2023Storer.jsonld#WebSocket2023Storer"
+      ],
+      "comment": "WebSocket2023Storer 的等位替换：保留 CSS 原有行为（把 socket 存进 map、socket 关闭时从 map 移除、 定期关掉已过期通道的 socket），并补上缺失的一环——最后一个 socket 关闭或出错时回收通道记录。  CSS 默认实现只在 `close`/`error` 时调用 `socketMap.deleteEntry(...)`，通道记录会一直留在 `SubscriptionStorage` 里直到 `endAt` 过期（`NotificationSubscriber` 默认把它压到 2 周后）， 因此每次页面刷新、HMR、崩溃都会留下一个再也不会被使用的通道。  只有当该通道名下的 socket 全部消失时才删除：同一个通道允许多个 socket（例如两个标签页共用一次订阅）， 只要还有 socket 存活就必须保留通道，否则会静默掐断仍在监听的客户端。",
+      "parameters": [
+        {
+          "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer_cleanupTimer",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:number",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          }
+        },
+        {
+          "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer_storage",
+          "range": "css:dist/server/notifications/NotificationChannelStorage.jsonld#NotificationChannelStorage"
+        },
+        {
+          "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer_socketMap",
+          "range": "css:dist/server/notifications/WebSocketChannel2023/WebSocketMap.jsonld#WebSocketMap"
+        }
+      ],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer__member_channelStorage",
+          "memberFieldName": "channelStorage"
+        },
+        {
+          "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer__member_liveSockets",
+          "memberFieldName": "liveSockets"
+        },
+        {
+          "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer__member_reclaiming",
+          "memberFieldName": "reclaiming"
+        },
+        {
+          "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer__member_constructor",
+          "memberFieldName": "constructor"
+        },
+        {
+          "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer__member_handle",
+          "memberFieldName": "handle"
+        },
+        {
+          "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer__member_reclaim",
+          "memberFieldName": "reclaim"
+        }
+      ],
+      "constructorArguments": [
+        {
+          "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer_storage"
+        },
+        {
+          "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer_socketMap"
+        },
+        {
+          "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer_cleanupTimer"
+        }
+      ]
+    }
+  ]
+}

package/dist/notifications/index.d.ts

@@ -1,3 +1,5 @@
 export * from './device-notification-protocol';
 export * from './DeviceNotificationHub';
 export * from './DeviceNotificationResourceListener';
+export * from './NotificationChannelSweeper';
+export * from './ReclaimingWebSocket2023Storer';

package/dist/notifications/index.js

@@ -17,4 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./device-notification-protocol"), exports);
 __exportStar(require("./DeviceNotificationHub"), exports);
 __exportStar(require("./DeviceNotificationResourceListener"), exports);
+__exportStar(require("./NotificationChannelSweeper"), exports);
+__exportStar(require("./ReclaimingWebSocket2023Storer"), exports);
 //# sourceMappingURL=index.js.map

package/dist/runtime/Proxy.d.ts

@@ -14,13 +14,44 @@ export declare class GatewayProxy {
     private readonly baseUrl?;
     private readonly internalAdminAuthSecret?;
     private readonly clientRemoteAddressResolver?;
+    /**
+     * Upgrade relay for runtimes whose HTTP server cannot expose the raw upgraded
+     * socket (Bun). `undefined` keeps the byte-level `http-proxy` relay.
+     */
+    private readonly nativeUpgradeRelay?;
+    /** Sockets created by `upgrade` events, dropped on shutdown. */
+    private readonly upgradeSockets;
     constructor(port: number | undefined, supervisor: Supervisor, bindHost?: string, options?: GatewayProxyOptions);
+    /**
+     * Upgraded sockets outlive the HTTP request that created them; they are
+     * tracked so shutdown can drop them instead of waiting for a long lived
+     * notification channel to end on its own.
+     */
+    private trackUpgradeSocket;
+    /**
+     * Picks the internal service that owns an upgrade path.
+     *
+     * `/ws/*` and the device notification multiplex live on the API server; every
+     * other upgrade (Solid notification channels, edge node tunnels) goes to CSS.
+     */
+    private resolveUpgradeTarget;
+    private relayUpgradeWithHttpProxy;
     setTargets(targets: {
         css?: string | GatewayProxyTarget;
         api?: string | GatewayProxyTarget;
     }): void;
     start(): Promise<void>;
     stop(): Promise<void>;
+    /**
+     * Closes the listener with a bounded wait.
+     *
+     * The listening socket stops accepting as soon as `close()` is called, but
+     * the callback waits for every connection to end. Node keeps upgraded sockets
+     * counted until they are destroyed (done above); Bun additionally never calls
+     * back once a WebSocket was closed from the server side
+     * (oven-sh/bun#28396), so waiting forever would block gateway restarts.
+     */
+    private closeServer;
     private handleRequest;
     private isApiWebProductPath;
     private shouldRouteToApi;
@@ -65,4 +96,10 @@ export interface GatewayProxyOptions {
     baseUrl?: string;
     internalAdminAuthSecret?: string;
     clientRemoteAddressResolver?: (req: http.IncomingMessage) => string | undefined;
+    /**
+     * Forces the native (message level) upgrade relay on or off.
+     * Defaults to `true` on Bun, where the `http-proxy` relay cannot reach the
+     * client socket at all.
+     */
+    nativeUpgradeRelay?: boolean;
 }