dsh-mobile 0.6.15 → 0.6.17

package/docs/SLOW_CONNECTIONS.md

@@ -32,6 +32,8 @@
 
 `http failure` 日志按网关区分 `parser`、`target`、`upstream` 三类：分别表示 HTTP 解析／接收失败、非法请求目标、已认证的 `POST /api/session/prompt` 被上游拒绝。每类首条立即记录，后续 30 秒内聚合，下一条的 `suppressed` 是此前被抑制的同类数量。日志不保留原始报错、请求正文、原始包、Cookie、Token、查询参数或任意 URL；不记录某条也不能证明它成功。
 
+`slow api` 日志采样已认证并转发、耗时至少 3 秒的 `/api/` 请求：固定方法、`/api/session` 等固定路由类别（未知类别归为 `/api/other`）、状态和 `durationMs`。耗时从进入上游代理转发算到响应关闭，包含客户端中途放弃的响应；它是代理等待时间，不是上游处理耗时，也不能单凭该数字确定哪一层慢。日志不保留会话 ID 等路径后缀、查询参数、请求正文或任意原始路径，每个网关首条立即记录、后续采样在 30 秒窗口内聚合。不改变超时、重试或缓存策略。
+
 `upstreamTimeoutMs` 既用于上游传输等待，也配置了入站完整请求的接收期限；持续上传不保证避开这个总期限，Node 的定期检查会影响实际触发时刻。不要仅凭 HTTP 400 就删除配对、清空 App 数据或自动重发。先区分拒绝来源，并查看实际响应正文、Content-Type、准确版本和脱敏的代理上游状态；消息或工具是否已执行不明时，先核对会话结果。
 
 ## 不同事件流不能混为一谈
@@ -108,7 +110,15 @@ websocketCompression:
 
 ## 静态资源缓存与重复下载
 
-网关自身生成的资源使用带引号的 ETag，并在设备鉴权和资源检查之后处理 GET/HEAD 的条件请求。网关对上游静态资源做流式 gzip 时，可保留合法上游 ETag 的弱校验形式，并维护 `Vary: Accept-Encoding`；不会把原始内容的长度或范围元信息当作压缩内容的元信息，也不会缓存失败响应或为 API 请求新增缓存。
+网关自有静态资源（`/mobile-access/compat.js`、`mobile-layout.js`、自定义 CSS/JS）使用带引号的内容 ETag 和 `Cache-Control: private, no-cache`。浏览器可保存正文，但每次复用前必须重新校验；网关先检查设备授权和当前资源，再处理 GET/HEAD 条件请求，内容未变时返回 `304`，文件改动后返回新正文。实际缓存复用仍取决于浏览器行为。
+
+移动启动 HTML 包含绑定当前认证 Session 的页面标识，保持 `no-store`，不复用其他页面或 Session 的启动文档；配对页和 API 响应也保持 `no-store`。网关对上游静态资源做流式 gzip 时，可保留合法上游 ETag 的弱校验形式，并维护 `Vary: Accept-Encoding`；不会把原始内容的长度或范围元信息当作压缩内容的元信息，也不会缓存失败响应或为 API 请求新增缓存。
+
+可压缩的文本响应都走这条流式管道：静态资源、HTML 文档和 `/api/` 的 JSON 都会在手机声明 `Accept-Encoding: gzip` 时压缩，并维护 `Vary`。`/plugins/`、`/assets/` 下的静态资源**沿用原有判定，行为不变**（包括上游原本就会压缩的路径）。静态路径之外，`text/event-stream` 保持不压缩，否则逐帧事件会被 gzip 块缓冲；声明长度小于 1KB 或没有声明长度的响应也保持原样，压缩开销大于收益或可能被逐段消费。范围请求、已编码响应和 304 仍按原规则处理，不带 `Accept-Encoding` 的客户端收到的字节与以前一致。
+
+移动端启动页由网关拼装，不经过上面的代理压缩流程；正文至少 1KiB 且请求接受 gzip 时会压缩，压缩和未压缩响应都维护 `Vary: Accept-Encoding`。页面仍使用 `no-store`，不复用旧启动文档；它包含当前会话与模块选择对应的启动信息。
+
+网关把上游应用模块组合为启动批（`/mobile-access/mobile-boot/<hash>.js`），按 3MiB 源码目标大小切分，最多保留 16 个合并批，始终保留移动布局替换；超出数量的模块改用其原有独立资源地址，不因这项优化拒绝整个启动图。大于目标大小的单个模块不会拆开，原有单模块和组装大小限制不变。较小的响应和缓存复用可减少重复传输，但不能保证总启动时间或修复所有自动重连原因。合并批使用带引号 ETag 和 `private, max-age=30, must-revalidate`：短时间内重载可复用本地副本；布局文件改动后，已缓存的旧批最多可继续使用 30 秒，随后重新校验。ETag 与正文绑定，内容改变后返回新正文而不是 304。
 
 上游未提供校验标识的资源不会因此自动得到一个可靠标识。检查重复下载时，比较同一完整资源 URL 在普通打开、重新加载和 App 冷启动中的 `200`/`304`、缓存命中、`If-None-Match`、编码与实际传输量；不要先清除站点数据再把结果当作正常缓存行为。HTTP 校验语义改善不保证每个 WebView 都会复用缓存，也不能仅凭这些响应头认定 [#107](https://github.com/saya-ch/dsh-mobile/issues/107) 已完全解决。