@microbt/pwa 0.0.0-stage → 0.1.0

package/dist/esm/sw-error-filter.d.ts

@@ -0,0 +1,58 @@
+/** 固定计数项，避免把 URL、错误文案等高基数内容用作监控指标名。 */
+export declare const SW_REJECTION_METRICS: {
+    readonly 'cache-write-network': "SW-CACHE-WRITE-NETWORK";
+    readonly 'cache-entry-exists': "SW-CACHE-ENTRY-EXISTS";
+    readonly 'cache-expiration-cursor': "SW-CACHE-EXPIRATION-CURSOR";
+    readonly 'feedback-media-no-response': "SW-FEEDBACK-MEDIA-NO-RESPONSE";
+};
+export interface SwRejectionDetails {
+    name: string;
+    message: string;
+    stack: string;
+}
+/** 在 SW 内转成纯字符串再 postMessage，保留 DOMException 信息并避免克隆失败。 */
+export declare function serializeSwRejection(reason: unknown): SwRejectionDetails;
+/**
+ * SW unhandledrejection 上报原则：影响不明就保留异常，已知重复故障才减少 error 频率。
+ * 本策略只处理未被业务捕获的 Promise 拒绝；SW 的 error 事件仍走独立的全量上报。
+ *
+ * 哪些上报：
+ * 1. 普通 NetworkError、Failed to fetch、AbortError、非反馈媒体的
+ *    no-response 和所有未知错误：每次报 error。全局事件不能证明主动取消
+ *    或缓存已兜底；网络失败也可能是配置问题，非反馈媒体的 no-response
+ *    （CDN chunk、页面导航）可能是资源最终加载失败（白屏信号），不能
+ *    当成用户断网直接忽略。
+ *    cache-put-with-no-response 是另一种错误，同样每次报，不能用子串混为一类。
+ * 2. getCategory 精确匹配的四类故障：Cache.put 网络写入失败、缓存条目已存在、
+ *    IndexedDB 游标异常、签名反馈媒体 URL 的 no-response（反馈图片/视频
+ *    请求失败，原因未明——日志只有 error:{}，无法区分网络、取消或 CORS；
+ *    此类失败不伤 app 外壳）。每次通知页面记 sum；每类首次及距离上次允许
+ *    上报满 60 秒的下一次故障，同时报 error。其他错误名或文案变体回到第 1 条。
+ *
+ * 哪些不报 error：只有第 2 条中距上次允许上报不足 60 秒的同类重复故障。
+ * 此时仍通知页面记 sum，并非完全丢弃；当前没有仅凭错误名就彻底忽略的类别。
+ * 60 秒是控制重复量的固定窗口，不代表故障已恢复；重复事件不会推迟窗口，
+ * 到期也不会主动补报，必须有下一次故障才再次报 error。
+ *
+ * 限频的本质是故障详情抽样，不是"重复去重、信号不丢"：限频键只有
+ * category，同类中不同 URL 的故障共享窗口——视频 A 首次报错后，视频 B
+ * 在一分钟内首次失败只剩 sum，B 的 URL 和堆栈不会上报。同时 SW 仍向
+ * 所有页面广播，多页面打开时一次故障可能产生多份 error/sum，本策略不
+ * 解决广播重复。接受这两个取舍的理由是此类故障原因未明且不伤外壳，
+ * 保留频次与代表性样本即可，不需要每一次详情。
+ *
+ * 为什么仍保留缓存故障：写入失败影响后续离线使用，游标异常可能中断缓存淘汰。
+ * 即使源于浏览器问题，也需保留频次和代表性堆栈；本策略不负责修复底层故障。
+ * 限频按 SW 实例、按类别独立保存，重启或时钟回拨后重新允许上报。
+ * sum 是页面接收通知的次数，多页面会重复、无客户端会漏收，不是准确的故障总数。
+ * 新旧 SW/页面共存时，旧页面不识别限频字段会继续全量报 error，待页面更新后生效。
+ * 若以后要忽略主动取消或成功兜底的请求，应在掌握请求结果的调用点处理，
+ * 不应在这里扩充关键词黑名单。NetworkFirst 超时只尝试缓存兜底，不会 abort 请求。
+ */
+export declare function createSwRejectionPolicy(): (details: SwRejectionDetails, now?: number) => {
+    reportError: boolean;
+    category?: undefined;
+} | {
+    category: "cache-write-network" | "cache-entry-exists" | "cache-expiration-cursor" | "feedback-media-no-response";
+    reportError: boolean;
+};

package/dist/esm/sw-error-filter.js

@@ -0,0 +1,87 @@
+// src/sw-error-filter.ts
+var SW_REJECTION_METRICS = {
+  "cache-write-network": "SW-CACHE-WRITE-NETWORK",
+  "cache-entry-exists": "SW-CACHE-ENTRY-EXISTS",
+  "cache-expiration-cursor": "SW-CACHE-EXPIRATION-CURSOR",
+  "feedback-media-no-response": "SW-FEEDBACK-MEDIA-NO-RESPONSE"
+};
+function serializeSwRejection(reason) {
+  try {
+    if (reason !== null && typeof reason === "object") {
+      const error = reason;
+      return {
+        name: typeof error.name === "string" ? error.name : "",
+        message: typeof error.message === "string" ? error.message : JSON.stringify(reason) || String(reason),
+        stack: typeof error.stack === "string" ? error.stack : ""
+      };
+    }
+    return { name: "", message: String(reason), stack: "" };
+  } catch {
+    return {
+      name: "",
+      message: "[Unserializable rejection reason]",
+      stack: ""
+    };
+  }
+}
+var NO_RESPONSE_MESSAGE_PREFIX = "no-response :: ";
+var FEEDBACK_MEDIA_HOST = "super-acme-online.oss-cn-hangzhou.aliyuncs.com";
+var FEEDBACK_MEDIA_PATH_PREFIXES = ["/saas/feedbackVideo/", "/user-center/feedback/"];
+function isSignedFeedbackMediaNoResponse(message) {
+  var _a;
+  if (!message.startsWith(NO_RESPONSE_MESSAGE_PREFIX)) {
+    return false;
+  }
+  try {
+    const details = JSON.parse(message.slice(NO_RESPONSE_MESSAGE_PREFIX.length));
+    const url = Array.isArray(details) ? (_a = details[0]) == null ? void 0 : _a.url : void 0;
+    if (typeof url !== "string") {
+      return false;
+    }
+    const parsed = new URL(url);
+    if (parsed.hostname !== FEEDBACK_MEDIA_HOST) {
+      return false;
+    }
+    if (!FEEDBACK_MEDIA_PATH_PREFIXES.some((prefix) => parsed.pathname.startsWith(prefix))) {
+      return false;
+    }
+    return parsed.searchParams.has("Expires") && parsed.searchParams.has("Signature");
+  } catch {
+    return false;
+  }
+}
+function getCategory({ name, message }) {
+  if (name === "NetworkError" && message === "Failed to execute 'put' on 'Cache': Cache.put() encountered a network error") {
+    return "cache-write-network";
+  }
+  if (name === "InvalidAccessError" && message === "Failed to execute 'put' on 'Cache': Entry already exists.") {
+    return "cache-entry-exists";
+  }
+  if (name === "UnknownError" && message === "Attempt to iterate a cursor that doesn't exist") {
+    return "cache-expiration-cursor";
+  }
+  if (name === "no-response" && isSignedFeedbackMediaNoResponse(message)) {
+    return "feedback-media-no-response";
+  }
+  return void 0;
+}
+function createSwRejectionPolicy() {
+  const lastReported = /* @__PURE__ */ new Map();
+  return (details, now = Date.now()) => {
+    const category = getCategory(details);
+    if (!category) {
+      return { reportError: true };
+    }
+    const previous = lastReported.get(category);
+    const reportError = previous === void 0 || now < previous || now - previous >= 6e4;
+    if (reportError) {
+      lastReported.set(category, now);
+    }
+    return { category, reportError };
+  };
+}
+export {
+  SW_REJECTION_METRICS,
+  createSwRejectionPolicy,
+  serializeSwRejection
+};

package/dist/esm/sw-polyfills.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/sw-polyfills.js

@@ -0,0 +1,14 @@
+// src/sw-polyfills.ts
+if (typeof Promise.allSettled !== "function") {
+  Promise.allSettled = function(values) {
+    return Promise.all(
+      Array.from(
+        values,
+        (item) => Promise.resolve(item).then(
+          (value) => ({ status: "fulfilled", value }),
+          (reason) => ({ status: "rejected", reason })
+        )
+      )
+    );
+  };
+}

package/dist/esm/sw-request-filter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SW 缓存路由的协议守卫：仅 http(s) 请求允许进入 workbox 缓存路由。
+ *
+ * 注：workbox-routing 已在路由匹配前排除非 http(s) 请求——
+ * Router.handleRequest 中 `!url.protocol.startsWith('http')` 直接 return，
+ * blob:/data: 不会 respondWith，由浏览器本地解析。本守卫与框架行为等价，
+ * 属防御性加固：防止未来改用自定义 fetch 监听或路由重构时，blob:/data:
+ * 被误引入缓存语义。
+ *
+ * 线上 blob: 图片加载失败（SLS 202609，Android WebView ×3）与本守卫无关，
+ * 根因未定位，需单独排查。
+ */
+export declare function isHttpOrHttpsRequest(url: string): boolean;

package/dist/esm/sw-request-filter.js

@@ -0,0 +1,7 @@
+// src/sw-request-filter.ts
+function isHttpOrHttpsRequest(url) {
+  return url.startsWith("https://") || url.startsWith("http://");
+}
+export {
+  isHttpOrHttpsRequest
+};

package/dist/esm/sw.d.ts

@@ -0,0 +1,4 @@
+import './sw-polyfills';
+export declare function setupServiceWorker(options: {
+    release: string;
+}): void;

package/dist/esm/sw.js

@@ -0,0 +1,194 @@
+// src/sw.ts
+import { CacheableResponsePlugin } from "workbox-cacheable-response";
+import { clientsClaim, skipWaiting } from "workbox-core";
+import { ExpirationPlugin } from "workbox-expiration";
+import { registerRoute, setDefaultHandler } from "workbox-routing";
+import { CacheFirst, NetworkFirst, NetworkOnly, StaleWhileRevalidate } from "workbox-strategies";
+import "./sw-polyfills";
+import {
+  JS_CSS_CACHE_NAME_PREFIX,
+  purgeMismatchedCacheEntries,
+  STATIC_ASSETS_CACHE_NAME_PREFIX,
+  ValidateResponsePlugin
+} from "./sw-cache-validation";
+import { ChunkDiagnosticsPlugin } from "./sw-chunk-diagnostics";
+import { createSwRejectionPolicy, serializeSwRejection } from "./sw-error-filter";
+import { isHttpOrHttpsRequest } from "./sw-request-filter";
+function setupServiceWorker(options) {
+  clientsClaim();
+  skipWaiting();
+  setDefaultHandler(new NetworkOnly());
+  registerRoute(
+    ({ request }) => request.mode === "navigate" && isHttpOrHttpsRequest(request.url),
+    new NetworkFirst({
+      cacheName: `cache-pages-${self.location.origin}`,
+      networkTimeoutSeconds: 3,
+      plugins: [
+        new CacheableResponsePlugin({
+          statuses: [0, 200]
+        }),
+        new ExpirationPlugin({
+          maxEntries: 10,
+          maxAgeSeconds: 60 * 60 * 24 * 3,
+          // 3 天，须短于 chunk 的 7 天
+          purgeOnQuotaError: true
+        })
+      ]
+    })
+  );
+  class CORSPlugin {
+    async requestWillFetch({ request }) {
+      return new Request(request, {
+        mode: "cors",
+        credentials: "same-origin"
+      });
+    }
+  }
+  function shouldNotCacheImage(url) {
+    try {
+      const urlObj = new URL(url);
+      const authParams = [
+        "Signature",
+        "OSSAccessKeyId",
+        "Expires",
+        "token",
+        "auth",
+        "key",
+        "apikey",
+        "api_key",
+        "access_token",
+        "x-oss-signature"
+      ];
+      for (const param of authParams) {
+        if (urlObj.searchParams.has(param)) {
+          console.log(`图片URL包含授权参数 ${param}，不进行缓存: ${url}`);
+          return true;
+        }
+      }
+      if (urlObj.search && urlObj.search.length > 20) {
+        console.log(`图片URL包含较长查询参数，可能是授权URL，不进行缓存: ${url}`);
+        return true;
+      }
+      return false;
+    } catch (error) {
+      console.error(`URL解析错误，不进行缓存: ${url}`, error);
+      return true;
+    }
+  }
+  registerRoute(
+    ({ request }) => {
+      if (!isHttpOrHttpsRequest(request.url)) {
+        return false;
+      }
+      if (request.destination === "image") {
+        return !shouldNotCacheImage(request.url);
+      }
+      return request.destination === "font";
+    },
+    new CacheFirst({
+      cacheName: `${STATIC_ASSETS_CACHE_NAME_PREFIX}${self.location.origin}`,
+      plugins: [
+        // new CORSPlugin(),
+        new CacheableResponsePlugin({
+          statuses: [0, 200]
+        }),
+        new ValidateResponsePlugin(),
+        new ExpirationPlugin({
+          maxEntries: 50,
+          // 减少最大缓存条目数量
+          maxAgeSeconds: 60 * 60 * 24 * 7,
+          // 减少缓存时间为7天
+          purgeOnQuotaError: true
+        })
+      ]
+    })
+  );
+  registerRoute(
+    ({ request }) => {
+      if (!isHttpOrHttpsRequest(request.url)) {
+        return false;
+      }
+      return request.destination === "script" || request.destination === "style";
+    },
+    new StaleWhileRevalidate({
+      cacheName: `${JS_CSS_CACHE_NAME_PREFIX}${self.location.origin}`,
+      plugins: [
+        new CORSPlugin(),
+        new CacheableResponsePlugin({
+          statuses: [0, 200]
+        }),
+        new ValidateResponsePlugin(),
+        new ExpirationPlugin({
+          // 单版本构建实测 43 个 js/css 文件，30 上限必然误逐当前版本 chunk
+          // （LRU 逐出后弱网/旧版本清理场景直接白屏），须大于单版本全量
+          maxEntries: 60,
+          maxAgeSeconds: 60 * 60 * 24 * 7,
+          // 减少缓存时间为7天
+          purgeOnQuotaError: true
+        }),
+        // 放在 CORS 改写和缓存过滤之后，只观察最终请求/缓存结果。
+        new ChunkDiagnosticsPlugin({ release: options.release })
+      ]
+    })
+  );
+  self.addEventListener("error", (event) => {
+    var _a;
+    const errorInfo = {
+      type: "error",
+      message: event.message,
+      filename: event.filename,
+      line: event.lineno,
+      column: event.colno,
+      error: event.error,
+      stack: ((_a = event.error) == null ? void 0 : _a.stack) || new Error().stack
+    };
+    console.error("[ServiceWorker Error]", errorInfo);
+    self.clients.matchAll().then((clients) => {
+      clients.forEach((client) => {
+        client.postMessage({
+          type: "SW_ERROR",
+          payload: errorInfo
+        });
+      });
+    }).catch((err) => {
+      console.error("[ServiceWorker] Error posting error to clients:", err);
+    });
+  });
+  const classifyRejection = createSwRejectionPolicy();
+  self.addEventListener("unhandledrejection", (event) => {
+    const details = serializeSwRejection(event.reason);
+    const rejectionInfo = {
+      // 保持 reason 为可读文本，旧页面也能消费新 SW 消息。
+      reason: details.name ? `${details.name}: ${details.message}` : details.message,
+      stack: details.stack || new Error().stack,
+      ...classifyRejection(details)
+    };
+    if (rejectionInfo.reportError) {
+      console.error("[ServiceWorker Unhandled Rejection]", rejectionInfo);
+    }
+    self.clients.matchAll().then((clients) => {
+      clients.forEach((client) => {
+        client.postMessage({
+          type: "SW_UNHANDLED_REJECTION",
+          payload: rejectionInfo
+        });
+      });
+    }).catch((err) => {
+      console.error("[ServiceWorker] Error posting unhandled rejection to clients:", err);
+    });
+  });
+  self.addEventListener("activate", (event) => {
+    event.waitUntil(
+      Promise.all([
+        purgeMismatchedCacheEntries(),
+        // 清理 pageCache recipe 时代的遗留 HTML 缓存：无过期机制，且新 HTML
+        // 路由已改用带 ExpirationPlugin 的 cache-pages-（旧条目若无时间戳
+        // 会被 ExpirationPlugin 视为永不过期，不能改名复用）
+        caches.delete("pages")
+      ])
+    );
+  });
+}
+export {
+  setupServiceWorker
+};

package/package.json

@@ -1,6 +1,92 @@
 {
   "name": "@microbt/pwa",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "microbt service worker runtime and page-side registration for web apps",
+  "keywords": [
+    "microbt",
+    "pwa",
+    "service-worker",
+    "workbox"
+  ],
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/esm/protocol.d.ts",
+      "import": "./dist/esm/protocol.js"
+    },
+    "./sw": {
+      "types": "./dist/esm/sw.d.ts",
+      "import": "./dist/esm/sw.js"
+    },
+    "./recovery": {
+      "types": "./dist/esm/recovery.d.ts",
+      "import": "./dist/esm/recovery.js"
+    }
+  },
+  "main": "dist/esm/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "father build",
+    "build:deps": "father prebundle",
+    "dev": "father dev",
+    "format": "prettier --cache --write .",
+    "lint": "eslint . --fix ",
+    "prepare": "husky install",
+    "prepublishOnly": "father doctor && npm run build",
+    "postpublish": "cnpm sync @microbt/pwa",
+    "test": "vitest run"
+  },
+  "lint-staged": {
+    "*.{md,json}": [
+      "prettier --cache --write"
+    ],
+    "*.{js,jsx}": [
+      "eslint --fix",
+      "prettier --cache --write"
+    ],
+    "*.ts?(x)": [
+      "eslint --fix",
+      "prettier --cache --parser=typescript --write"
+    ]
+  },
+  "dependencies": {
+    "workbox-cacheable-response": "^7.0.0",
+    "workbox-core": "^7.0.0",
+    "workbox-expiration": "^7.0.0",
+    "workbox-routing": "^7.0.0",
+    "workbox-strategies": "^7.0.0",
+    "workbox-window": "^7.0.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^17.4.4",
+    "@commitlint/config-conventional": "^17.4.4",
+    "@microbt/environment": "^1.2.14",
+    "@types/node": "^22.13.4",
+    "@typescript-eslint/eslint-plugin": "^5.54.1",
+    "@typescript-eslint/parser": "^5.54.1",
+    "eslint": "^8.36.0",
+    "father": "^4.1.0",
+    "husky": "^8.0.3",
+    "lint-staged": "^13.2.0",
+    "prettier": "^2.8.4",
+    "prettier-plugin-organize-imports": "^3.2.2",
+    "prettier-plugin-packagejson": "^2.4.3",
+    "typescript": "^5.4.2",
+    "vitest": "^1.6.1"
+  },
+  "peerDependencies": {
+    "@microbt/environment": "^1.2.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}