@abtnode/util 1.17.12 → 1.17.13-beta-20260512-004004-69bacba8

package/lib/blocklet-cache.js

@@ -4,22 +4,22 @@ const { BLOCKLET_CACHE_TTL } = require('@abtnode/constant');
 const BLOCKLET_INFO_SHORT_CACHE_TTL = 1000 * 60 * 30; // 30 minutes
 
 /**
- * Blocklet Info 缓存, 用于 blocklet.js 请求，快速返回数据
+ * Blocklet Info cache for blocklet.js requests, allowing fast responses
  *
- * 注意：
- * - Redis Adapter 不使用 LRU cache（Redis 本身已经是内存数据库）
- * - SQLite Adapter 会使用 LRU cache 作为 L1 缓存层
+ * Notes:
+ * - Redis Adapter does not use LRU cache (Redis itself is in-memory)
+ * - SQLite Adapter uses LRU cache as the L1 cache layer
  */
 const blockletInfoShortCache = new DBCache(() => ({
   prefix: 'blocklet-info-short-cache',
   ttl: BLOCKLET_INFO_SHORT_CACHE_TTL, // 30 minutes
-  enableLruCache: true, // 仅对 SQLite 生效
+  enableLruCache: true, // only effective for SQLite
   ...getAbtNodeRedisAndSQLiteUrl(),
 }));
 
 /**
  * @param {string} did: blockletDid
- * @param {string} componentId: componentDid 的格式为 did/children.did
+ * @param {string} componentId: componentDid format is did/children.did
  * @param {string} type: json or js
  * @returns {string}
  */
@@ -28,7 +28,7 @@ const getBlockletInfoCachePrefixKey = (did) => {
 };
 
 /**
- * 删除 Blocklet Info 缓存 (包括内存缓存和 DBCache)
+ * Delete Blocklet Info cache (including memory cache and DBCache)
  *
  * CLUSTER MODE NOTE:
  * - Memory cache: Cleared via delByPrefix with cluster sync.
@@ -38,10 +38,10 @@ const getBlockletInfoCachePrefixKey = (did) => {
  */
 const clearBlockletInfoCache = async (did, logger = console) => {
   try {
-    // 由于 cacheKey 包含动态参数（pathPrefix 等），无法枚举所有可能的 key
-    // 所以使用前缀匹配删除所有与该 DID 相关的缓存
+    // cacheKey contains dynamic parameters (pathPrefix, etc.), so all possible keys cannot be enumerated
+    // use prefix matching to delete all cache entries related to this DID
     const prefix = getBlockletInfoCachePrefixKey(did);
-    // DBCache 也使用前缀删除（del 方法会删除该 key 及其 group 下的所有 key）
+    // DBCache also uses prefix deletion (del removes this key and all keys in its group)
     await blockletInfoShortCache.del(prefix);
     logger.info('Cleared blocklet info cache', { did, prefix });
   } catch (error) {
@@ -50,17 +50,17 @@ const clearBlockletInfoCache = async (did, logger = console) => {
 };
 
 /**
- * Blocklet state 缓存, 用于内部数据获取，避免重复查询数据库
+ * Blocklet state cache for internal data retrieval to avoid repeated database queries
  */
 const blockletCache = new DBCache(() => ({
   prefix: 'blocklet-state',
   ttl: BLOCKLET_CACHE_TTL,
-  enableLruCache: false, // 明确禁用 LRU cache
+  enableLruCache: false, // explicitly disable LRU cache
   ...getAbtNodeRedisAndSQLiteUrl(),
 }));
 
 /**
- * 删除 Blocklet state 缓存
+ * Delete Blocklet state cache
  * @param {string} did: blockletDid
  */
 const deleteBlockletCache = async (did, logger = console) => {

package/lib/deep-clone.js

@@ -3,8 +3,7 @@ function deepClone(o) {
     return undefined;
   }
 
-  // 优先使用 structuredClone（性能更好，支持更多类型）
-  // structuredClone（Node.js 17+ / 现代浏览器）
+  // prefer structuredClone (better perf, more type support; Node.js 17+ / modern browsers)
   try {
     return structuredClone(o);
   } catch {

package/lib/did-document.js

@@ -216,7 +216,7 @@ const getBlockletServices = ({
       rr: encodeBase32(slpDid),
       value: daemonDidDomain,
       domain: slpDomain,
-      derivedFrom: serverDid, // 用于验证 slpDid 的所有权是否合法
+      derivedFrom: serverDid, // used to verify that the ownership of slpDid is legitimate
     });
   }
 

package/lib/download-file.js

@@ -119,7 +119,7 @@ const downloadFile = async (
         let current = 0;
         response.data.on('data', (chunk) => {
           current += chunk.length;
-          // 每 2 秒检查一次, db-cache 里是否标记了取消, 如果有, 则取消下载
+          // check every 2 seconds whether cancellation has been flagged in db-cache; if so, cancel the download
           if (Date.now() - t > 2000) {
             t = Date.now();
             checkCanceled().then((cancelled) => {

package/lib/ensure-docker-endpoint-healthy.js

@@ -4,14 +4,14 @@ async function ensureDockerEndpointHealthy({ host, port, timeout = 10 * 1000 })
   const checkWget = await promiseSpawn(`docker exec ${host} sh -c "command -v wget || echo 'no-wget'"`, timeout);
 
   if (checkWget.trim() === 'no-wget') {
-    // 检测容器类型并安装 wget
+    // detect the container OS type and install wget
     await promiseSpawn(
       `docker exec ${host} sh -c "if [ -f /etc/os-release ]; then . /etc/os-release && (echo $ID | grep -q 'alpine' && apk add --no-cache wget || (echo $ID | grep -q 'debian' && apt-get update && apt-get install -y wget) || (echo $ID | grep -q 'centos' && yum install -y wget)); else echo 'Unsupported OS'; fi"`,
       timeout
     );
   }
 
-  // 使用 wget 检查端口健康状态
+  // use wget to check port health status
   const res = await promiseSpawn(`docker exec ${host} wget --spider http://${host}:${port}`, timeout);
   if (!res.includes('connected') && !res.includes('200 OK')) {
     throw new Error(`Docker endpoint ${host}:${port} is not healthy`);

package/lib/ensure-endpoint-healthy.js

@@ -36,7 +36,7 @@ const dialHttp = (host, port, timeout = 3 * 1000) => {
     const socket = net.connect({ host, port });
     let dataBuffer = '';
 
-    // 设定一个整体超时定时器，确保整个 socket 生命期最多 3 秒
+    // Set an overall timeout to keep the socket lifetime under 3 seconds
     const overallTimeout = setTimeout(() => {
       socket.destroy();
       reject(new Error(`Socket existed for more than ${timeout}ms`));
@@ -61,17 +61,17 @@ const dialHttp = (host, port, timeout = 3 * 1000) => {
       }
     });
 
-    // 处理连接结束时的数据情况：如果首行未完整结束，也视为无效响应
+    // Handle data on connection end: if the first line is incomplete, treat it as an invalid response
     socket.on('end', () => {
       clearTimeout(overallTimeout);
       socket.destroy();
       if (!dataBuffer) {
         reject(new Error('No data received'));
       } else if (dataBuffer.indexOf('\r\n') === -1) {
-        // 没有完整的首行
+        // No complete first line
         reject(new Error(`Response did not complete the first line: "${dataBuffer}"`));
       } else {
-        // 如果数据有首行但没走到 data 回调中结束后的逻辑（比如数据中断），则进行最终判断
+        // If data has a first line but did not reach the data callback completion logic (for example interrupted data), do a final check
         const firstLine = dataBuffer.substring(0, dataBuffer.indexOf('\r\n'));
         if (firstLine.startsWith('HTTP')) {
           resolve(firstLine);
@@ -104,7 +104,7 @@ const ensureStarted = async ({
       await dialHttp(host, port, minConsecutiveTime);
     } else {
       await dial(host, port);
-      // 如果是 TCP 协议, 标注需要等待 TCP 的，则需要等待 3 秒，确保服务已经启动，例如 MySQL 这种
+      // For TCP protocols marked as requiring TCP wait, wait 3 seconds to ensure the service has started, such as MySQL
       if (waitTCP) {
         await sleep(WAIT_TCP_TIME);
       }

package/lib/format-context.js

@@ -34,7 +34,7 @@ module.exports = (ctx = {}) => {
     timezone: safeGet('x-timezone'),
   };
 
-  // 警告，尽量不要在这里传递整个 headers 对象，因为可能会影响后续流程
+  // WARNING: avoid passing the entire headers object here as it may interfere with downstream processing
 
   return result;
 };

package/lib/fs.js

@@ -4,7 +4,7 @@ const path = require('path');
 const canReadAndWriteDir = (dir) => {
   const root = '/';
 
-  // 向父级找到一个存在且有读写权限的目录，否则返回false，即该目录不可读写
+  // walk up to the nearest ancestor directory that exists and has read/write permission; if none found, return false
   const tmpArray = dir.split(path.sep).filter(Boolean);
   do {
     const tmpDir = path.join(root, tmpArray.join(path.sep));

package/lib/gcp.js

@@ -61,7 +61,7 @@ const getExternalIpv4 = async () => {
 };
 
 const getInternalIpv6 = async () => {
-  // TODO: 没有支持 ipv6 的机器，这个接口没有在实际的机器上测试
+  // TODO: no IPv6-capable machine is available; this interface has not been tested on a real machine
   const internalIp = await getMeta('instance/network-interfaces/0/ipv6s');
 
   debug('getLocalIpv6', { internalIp });
@@ -69,7 +69,7 @@ const getInternalIpv6 = async () => {
 };
 
 const getExternalIpv6 = async () => {
-  // TODO: 没有支持 ipv6 的机器，这个接口没有在实际的机器上测试
+  // TODO: no IPv6-capable machine is available; this interface has not been tested on a real machine
   const externalIp = await getMeta('instance/network-interfaces/0/access-configs/0/external-ipv6');
   debug('getPublicIpv6', { externalIp });
 

package/lib/get-pm2-process-info.js

@@ -4,7 +4,7 @@ const pm2 = require('./pm2/async-pm2');
 
 const noop = () => {};
 
-// 新增 10_000 ms 的超时时间，避免 pm2 遇到什么问题一直不返回
+// add 10,000 ms timeout to avoid pm2 hanging indefinitely on errors
 const getPm2ProcessInfo = (processId, { printError = noop, throwOnNotExist = true, timeout = 10_000 } = {}) => {
   return new Promise((resolve, reject) => {
     let settled = false;

package/lib/get-token-from-req.js

@@ -47,8 +47,7 @@ function getTokenFromReq(req, opts) {
   if (tokenList.length > 1) {
     _duplicate = true;
   } else if (tokenList.length === 1) {
-    // HACK: 在统一登录的切换账户场景中，会同时携带 cookie 和 header bearerToken，但这两个值是不一样的
-    // 如果出现了这种情况，则应该判断为不重复，并最终以 headerToken 的值为准
+    // HACK: in federated-login account-switch flow, both cookie and header bearerToken may be present with different values; treat as non-duplicate and prefer headerToken
     if (headerToken === (cookieToken || bodyToken || queryToken)) {
       _duplicate = true;
     }

package/lib/logo-middleware.js

@@ -157,7 +157,7 @@ const ensureCustomOgImage = (req, res, next) => {
 const ensureBundleLogo = (req, res, next) => {
   /**
    * @type {{
-   *  blocklet: import('@blocklet/server-js').BlockletState, // 目前肯定是不准确的，但是有些属性是通用的，无伤大雅
+   *  blocklet: import('@blocklet/server-js').BlockletState, // currently not fully accurate, but some properties are generic and this is acceptable
    *  sendOptions: any
    * }}
    * */
@@ -201,7 +201,7 @@ const cacheError = (err, req, res, next) => {
 const ensureDefaultLogo = (req, res, next) => {
   /**
    * @type {{
-   *  blocklet: import('@blocklet/server-js').BlockletState, // 目前肯定是不准确的，但是有些属性是通用的，无伤大雅
+   *  blocklet: import('@blocklet/server-js').BlockletState, // currently not fully accurate, but some properties are generic and this is acceptable
    *  sendOptions: any
    * }}
    * */
@@ -233,7 +233,7 @@ const ensureDefaultLogo = (req, res, next) => {
 const ensureCustomFavicon = (req, res, next) => {
   /**
    * @type {{
-   *  blocklet: import('@blocklet/server-js').BlockletState, // 目前肯定是不准确的，但是有些属性是通用的，无伤大雅
+   *  blocklet: import('@blocklet/server-js').BlockletState, // currently not fully accurate, but some properties are generic and this is acceptable
    *  sendOptions: any
    * }}
    * */

package/lib/middlewares/ensure-locale.js

@@ -19,7 +19,7 @@ function ensureLocale({ methods = ['body', 'query', 'cookies'], force = false }
       }
     }
 
-    // 将 cookie 中的语言设置转换为标准语言
+    // normalize the language setting from the cookie into a standard locale code
     const localeMap = {
       'zh-CN': 'zh',
       'en-US': 'en',

package/lib/notification-preview/highlight.js

@@ -14,11 +14,11 @@ const toTextList = (str) => {
   const arr = [];
   try {
     let startPoint = 0;
-    const pattern = /<(.+?)\(?[tx|nft|token|stake|did|dapp|link]+[:](.+?)\)?>/gi; // 匹配 <asdad(did:abt:xxx)>
+    const pattern = /<(.+?)\(?[tx|nft|token|stake|did|dapp|link]+[:](.+?)\)?>/gi; // matches <asdad(did:abt:xxx)>
     const matches = str.matchAll(pattern);
 
     for (const match of matches) {
-      const didPattern = /\([tx|nft|token|stake|did|dapp|link]+[:](.+?)\)/gi; // 匹配 (did:abt:xxx)
+      const didPattern = /\([tx|nft|token|stake|did|dapp|link]+[:](.+?)\)/gi; // matches (did:abt:xxx)
 
       const oriHit = match[0];
       const matchIndex = match.index || startPoint;
@@ -98,7 +98,7 @@ const toClickableSpan = (str, isHighLight = true) => {
           const url = getLink(item);
           const { type, chainId, did } = item;
 
-          // HACK: 邮件中无法支持 dapp 的展示，缺少 dapp 链接，只能作为加粗展示
+          // HACK: dapp display is not supported in email (no dapp link available), so render as bold only
           if (isSameAddr(type, 'dapp')) {
             return `<em style="font-weight:bold;" data-type="${type}" data-chain-id="${chainId}" data-did="${did}">${item.text}</em>`;
           }
@@ -106,7 +106,7 @@ const toClickableSpan = (str, isHighLight = true) => {
             return `<a target="_blank" rel="noopener noreferrer" style="color:#4598fa;font-weight:bold;" href="${url}">${item.text}</a>`;
           }
 
-          // 默认展示为加粗
+          // default: render as bold
           return `<em style="font-weight:bold;" data-type="${type}" data-chain-id="${chainId}" data-did="${did}">${item.text}</em>`;
         }
         return item.text;
@@ -118,7 +118,7 @@ const toClickableSpan = (str, isHighLight = true) => {
 };
 
 /**
- * 用于 slack 渲染带有连接的消息内容
+ * Render message content with links for Slack
  * @param {*} str
  * @returns
  */
@@ -129,7 +129,7 @@ const toSlackLink = (str) => {
       if (item instanceof Link) {
         return `<${getLink(item)}|${item.text}>`;
       }
-      // HACK: 移除字符串中 :\n 的换行符
+      // HACK: remove :\n newlines from string content
       return item.replace(/:\n/g, ': ');
     })
     .join('');

package/lib/notification-preview/util.js

@@ -20,7 +20,7 @@ const getExplorerUrl = (chainId) => {
 };
 
 /**
- * notifications 持久化列表
+ * persistent notifications list key
  */
 const generateKey = () => {
   const did = window?.env?.appId;
@@ -63,23 +63,23 @@ const getImagePath = (url) => {
 };
 
 /**
- * 判断通知是否包含activity
- * @param {Object} notification - 通知对象
- * @returns {boolean} - 是否包含activity
+ * Check whether the notification includes an activity
+ * @param {Object} notification - the notification object
+ * @returns {boolean} - whether the notification includes an activity
  */
 const isActivityIncluded = (notification) => {
   return !isEmpty(notification.activity) && !!notification.activity.type && !!notification.activity.actor;
 };
 
 /**
- * 判断 actor 是否是用户的 DID
- *  actor 的类型有两种 1) 用户 2) 组件
+ * Check whether the actor is a user DID
+ * actor can be one of two types: 1) user 2) component
  * @param {*} notification
  * @returns
  */
 const isUserActor = (notification) => {
-  // 1. 如果是 isActivityIncluded 并且 notification 中有 actorInfo 则认为是用户
-  // 2. 如果是 isActivityIncluded 并且 actorInfo 没有查询到用户，则认为是 component
+  // 1. if isActivityIncluded and the notification has actorInfo, treat as a user
+  // 2. if isActivityIncluded but actorInfo does not resolve to a user, treat as a component
   return isActivityIncluded(notification) && !!notification.actorInfo && !!notification.actorInfo.did;
 };
 
@@ -124,7 +124,6 @@ const ACTIVITY_DESCRIPTIONS = {
   [ACTIVITY_TYPES.UN_ASSIGN]: () => 'has revoked your task assignment: ',
 };
 
-// 导出所有函数
 module.exports = {
   isEVMChain,
   getExplorerUrl,

package/lib/pm2/pm2-start-or-reload.js

@@ -38,7 +38,7 @@ function loadReloadEnv() {
   }
 }
 
-// 等单个 pm_id online
+// wait for a single pm_id to come online
 function waitProcOnlineById(id, timeout = 20_000) {
   const start = Date.now();
   return new Promise((resolve, reject) => {
@@ -61,16 +61,16 @@ async function rollingRestartWithEnv(config) {
     pm2.list((err, list) => (err ? reject(err) : resolve(list)));
   });
 
-  // 固定顺序
+  // ensure a fixed order
   const targets = procs.filter((p) => p.name === name).sort((a, b) => a.pm_id - b.pm_id);
 
   for (const p of targets) {
     await new Promise((resolve, reject) => {
       pm2.reload(p.pm_id, {}, (err) => (err ? reject(err) : resolve()));
     });
-    // 等这个 pm_id 回到 online（而不是 name 级别）
+    // wait for this specific pm_id to come back online (not at the name level)
     await waitProcOnlineById(p.pm_id, listen_timeout);
-    // 给切换一点冗余，避免瞬时影响
+    // add a small buffer after the switch to avoid transient disruption
     await new Promise((r) => setTimeout(r, 500));
   }
 }

package/lib/pm2/setup-graceful-shutdown.js

@@ -7,21 +7,21 @@ function setupGracefulShutdown(server, opts = {}) {
   server[INSTALLED] = true;
 
   const {
-    killTimeout = 10000, // 总体兜底退出时间（ms）
-    socketEndTimeout = 5000, // 等待所有 TCP 连接优雅结束的最大时间（ms）
-    wsServers = [], // 可传入 ws 或 socket.io 实例，用于优雅关闭
-    logger = console, // 日志对象
-    setConnectionCloseOnShutdown = true, // h1 关停时设置 Connection: close / shouldKeepAlive=false
-    tuneKeepAlive = true, // 关停时温和缩短 keepAliveTimeout
-    http503OnShutdown = false, // 关停窗口是否对新请求/新流立即 503（默认 false：保持 200）
-    http503DelayMs = 2000, // 503 生效延迟（ms），给新进程接管留时间
-    quietEndDelay = 250, // 关停后延迟一小段再 end 空闲 socket（降低竞态）
-    // ---- HTTP/2 相关可选项 ----
-    enableHttp2Support = false, // 若服务包含 HTTP/2，建议保持 true
-    http2RefuseNewStreamsOnShutdown = true, // 关停窗口拒绝“新建流”（用 503 响应）
-    // ---- KA 调优参数（温和缩短）----
-    kaGentleMs = 600, // 关停期将 keepAliveTimeout 降到该值（建议 300–800ms）
-    kaPhaseDelayMs = 500, // 进入关停后，延迟一小段时间再缩短 KA
+    killTimeout = 10000, // overall fallback exit timeout (ms)
+    socketEndTimeout = 5000, // max time to wait for all TCP connections to close gracefully (ms)
+    wsServers = [], // ws or socket.io instances to close gracefully
+    logger = console, // logger instance
+    setConnectionCloseOnShutdown = true, // set Connection: close / shouldKeepAlive=false during h1 shutdown
+    tuneKeepAlive = true, // gently shorten keepAliveTimeout during shutdown
+    http503OnShutdown = false, // whether to immediately 503 new requests/streams during shutdown window (default false: keep 200)
+    http503DelayMs = 2000, // delay (ms) before 503 takes effect, giving the new process time to take over
+    quietEndDelay = 250, // delay slightly after shutdown before ending idle sockets (reduces race conditions)
+    // ---- HTTP/2 optional settings ----
+    enableHttp2Support = false, // set to true if the server uses HTTP/2
+    http2RefuseNewStreamsOnShutdown = true, // refuse new streams during the shutdown window (respond with 503)
+    // ---- Keep-Alive tuning parameters (gentle reduction) ----
+    kaGentleMs = 600, // reduce keepAliveTimeout to this value during shutdown (recommended 300–800ms)
+    kaPhaseDelayMs = 500, // delay slightly after entering shutdown before shortening KA
   } = opts;
 
   let isShuttingDown = false;
@@ -42,7 +42,7 @@ function setupGracefulShutdown(server, opts = {}) {
     server.on('listening', sendReadyOnce);
   }
 
-  // --------- HTTP/1.1 连接与请求跟踪 ----------
+  // --------- HTTP/1.1 connection and request tracking ----------
   const sockets = new Set();
   const metaMap = new WeakMap(); // socket -> { active: number, _ended?: boolean }
 
@@ -60,11 +60,11 @@ function setupGracefulShutdown(server, opts = {}) {
     const isH2 = req.httpVersionMajor >= 2;
 
     if (isShuttingDown) {
-      // HTTP/1.x：仅设置 shouldKeepAlive=false（Node 会自动输出 Connection: close）
+      // HTTP/1.x: only set shouldKeepAlive=false (Node will automatically emit Connection: close)
       if (!isH2 && setConnectionCloseOnShutdown && !res.headersSent) {
         try {
           res.shouldKeepAlive = false;
-          // 下面这句可选；shouldKeepAlive=false 已足够，保留以兼容旧栈
+          // the line below is optional; shouldKeepAlive=false is sufficient, kept for compatibility with older stacks
           res.setHeader?.('Connection', 'close');
         } catch {
           //
@@ -88,7 +88,7 @@ function setupGracefulShutdown(server, opts = {}) {
       if (!m) return;
       m.active = Math.max(0, m.active - 1);
 
-      // 关停期且该 socket 已无在途请求 → 优雅收尾
+      // during shutdown, if this socket has no in-flight requests -> graceful teardown
       if (isShuttingDown && m.active === 0 && !m._ended) {
         m._ended = true;
         try {
@@ -99,11 +99,11 @@ function setupGracefulShutdown(server, opts = {}) {
       }
     };
 
-    res.on('finish', done); // 正常完成
-    res.on('close', done); // 客户端提前断开
+    res.on('finish', done); // normal completion
+    res.on('close', done); // client disconnected early
   });
 
-  // --------- WebSocket / Socket.IO 关闭 ----------
+  // --------- WebSocket / Socket.IO shutdown ----------
   function closeWebSockets() {
     for (const s of wsServers) {
       if (s && s.clients && typeof s.clients.forEach === 'function') {
@@ -146,7 +146,7 @@ function setupGracefulShutdown(server, opts = {}) {
               }
             }
           }
-          s.close(); // 停止接受新连接并关闭现有
+          s.close(); // stop accepting new connections and close existing ones
         } catch (e) {
           logger.error('[shutdown] close socket.io failed:', e);
         }
@@ -162,7 +162,7 @@ function setupGracefulShutdown(server, opts = {}) {
     }
   }
 
-  // --------- HTTP/2 会话与流管理 ----------
+  // --------- HTTP/2 session and stream management ----------
   const h2Sessions = new Set();
   const h2Meta = new WeakMap(); // session -> { active: number, closed?: boolean }
 
@@ -173,27 +173,27 @@ function setupGracefulShutdown(server, opts = {}) {
       const http2 = require('http2');
       NGHTTP2_NO_ERROR = http2.constants.NGHTTP2_NO_ERROR;
 
-      // 仅 http2 服务器会触发
+      // only triggered on http2 servers
       server.on?.('session', (session) => {
         h2Sessions.add(session);
         h2Meta.set(session, { active: 0 });
 
         session.on('close', () => h2Sessions.delete(session));
 
-        // 统计活跃流, Http2Stream
+        // count active streams (Http2Stream)
         session.on('stream', (stream) => {
           const meta = h2Meta.get(session);
           if (meta) meta.active++;
 
-          // 关停窗口内：可选择拒绝“新建流”
+          // within the shutdown window: optionally refuse new stream creation
           if (isShuttingDown && http2RefuseNewStreamsOnShutdown) {
             const should503 =
               http503OnShutdown && (http503DelayMs <= 0 || Date.now() - shutdownStartedAt >= http503DelayMs);
             try {
-              // 用 503 语义清晰，Node 没有直接暴露 REFUSED_STREAM 常量
+              // 503 is semantically clear; Node does not directly expose the REFUSED_STREAM constant
               stream.respond({ ':status': should503 ? 503 : 200 });
               if (should503) stream.end('server reloading');
-              else stream.end(); // 若不打 503，可立即结束，以促使客户端重建到新实例
+              else stream.end(); // if not sending 503, end immediately to prompt the client to reconnect to the new instance
               return;
             } catch {
               //
@@ -221,11 +221,11 @@ function setupGracefulShutdown(server, opts = {}) {
       });
     }
   } catch (e) {
-    // 环境不支持 http2，忽略
+    // environment does not support http2, ignore
     NGHTTP2_NO_ERROR = undefined;
   }
 
-  // --------- h1 TCP socket 收尾 ----------
+  // --------- h1 TCP socket teardown ----------
   function drainTcpSockets() {
     sockets.forEach((socket) => {
       const meta = metaMap.get(socket) || { active: 0 };
@@ -239,7 +239,7 @@ function setupGracefulShutdown(server, opts = {}) {
       }
     });
 
-    // 兜底：到点仍未关闭的强制 destroy（避免泄露）
+    // fallback: force-destroy any sockets still open at deadline (prevents leaks)
     const hardKillAfter = Math.min(socketEndTimeout, Math.max(0, killTimeout - 200));
     setTimeout(() => {
       sockets.forEach((socket) => {
@@ -258,15 +258,15 @@ function setupGracefulShutdown(server, opts = {}) {
     shutdownStartedAt = Date.now();
     logger.info('[shutdown] starting graceful shutdown');
 
-    // (A) HTTP/1.x：温和缩短 keep-alive（可选）
+    // (A) HTTP/1.x: gently reduce keep-alive timeout (optional)
     if (tuneKeepAlive) {
       setTimeout(
         () => {
           try {
-            const ka = Math.max(50, Number(kaGentleMs) || 600); // 安全下限 50ms
+            const ka = Math.max(50, Number(kaGentleMs) || 600); // safety lower bound: 50ms
             if ('keepAliveTimeout' in server) server.keepAliveTimeout = ka;
             if ('headersTimeout' in server) server.headersTimeout = Math.max(server.headersTimeout || 0, ka + 1000);
-            // 不设置 requestTimeout（保持 0 / 无限），避免掐在途
+            // do not set requestTimeout (keep 0 / unlimited) to avoid cutting off in-flight requests
           } catch {
             //
           }
@@ -275,7 +275,7 @@ function setupGracefulShutdown(server, opts = {}) {
       ).unref?.();
     }
 
-    // (B) HTTP/2：向现有会话发 GOAWAY，阻止新流（让已有流跑完）
+    // (B) HTTP/2: send GOAWAY to existing sessions to block new streams (let existing streams finish)
     if (enableHttp2Support && NGHTTP2_NO_ERROR != null) {
       for (const session of h2Sessions) {
         try {
@@ -286,10 +286,10 @@ function setupGracefulShutdown(server, opts = {}) {
       }
     }
 
-    // 1) 先优雅关闭 WS/Socket.IO
+    // 1) gracefully close WS/Socket.IO first
     closeWebSockets();
 
-    // 2) 停止接收新的 TCP 连接/HTTP 请求/HTTP2 会话
+    // 2) stop accepting new TCP connections / HTTP requests / HTTP2 sessions
     if (typeof server.close === 'function') {
       server.close(() => {
         logger.log('[shutdown] http server closed, exiting 0');
@@ -297,11 +297,11 @@ function setupGracefulShutdown(server, opts = {}) {
       });
     }
 
-    // 3) 稍等一会儿再去收尾（减少与在途请求竞争）
+    // 3) wait briefly before teardown (reduces race with in-flight requests)
     setTimeout(() => {
       drainTcpSockets(); // h1
 
-      // h2：对“已无活跃流”的会话关闭
+      // h2: close sessions with no active streams
       if (enableHttp2Support) {
         for (const session of h2Sessions) {
           const meta = h2Meta.get(session) || { active: 0 };
@@ -317,7 +317,7 @@ function setupGracefulShutdown(server, opts = {}) {
       }
     }, quietEndDelay).unref?.();
 
-    // 4) h2 兜底：到点仍未关闭的会话直接 destroy，避免泄露
+    // 4) h2 fallback: destroy any sessions still open at deadline to prevent leaks
     const hardKillAfter = Math.min(socketEndTimeout, Math.max(0, killTimeout - 200));
     setTimeout(() => {
       if (enableHttp2Support) {
@@ -331,7 +331,7 @@ function setupGracefulShutdown(server, opts = {}) {
       }
     }, hardKillAfter).unref?.();
 
-    // 5) 最终兜底：进程仍未退出则强退
+    // 5) final fallback: force-exit if the process has not exited yet
     setTimeout(() => {
       logger.error('[shutdown] timeout reached, forcing exit 1');
       process.exit(1);

package/lib/port.js

@@ -51,7 +51,7 @@ const isPortTaken = async (port) => {
       .once('listening', () => {
         tester.once('close', () => resolve(false)).close();
       })
-      .listen(port, '::'); // 这里需要注意: 如果不加 host, 在某些时候端口占用了, 还是会返回 false
+      .listen(port, '::'); // Note: without host, this may still return false even when the port is occupied
   });
 };