HTTP

理解 HTTP 插件的 HTTPS 下载、虚拟目标、重定向、超时、取消和资源上限。

模块边界

HTTP 插件当前只提供下载。它不提供通用请求、上传、进度事件、公开 AbortSignal、请求头定制或响应缓存。下载内容必须写入可写虚拟文件系统，不返回真实文件路径。

层级	入口	责任
前端 API	`frontend/src/api/http.ts`	URL、路径、布尔值和 120 秒超时
协议清单	`protocol/plugins.json`	`http` 插件和 `http.download` 归属
Windows 插件	`windows/src/plugins/ksm_http_plugin.cpp`	请求分发和取消
Windows 传输	`windows/src/platform/ksm_windows_host_services.cpp`	WinHTTP、重定向和临时文件
Android 传输	`KSMAndroidHostServices.kt`	`HttpsURLConnection` 和生命周期取消

平台与权限

命令	Windows	Android	权限	返回
`http.download`	支持	支持	`http.download`	`{ path, bytes }`

参数与固定行为

参数	类型	必填	说明
`url`	string	是	绝对 `https://` URL
`path`	string	是	`app://data`、`app://cache` 或 `app://tmp` 下的文件路径
`overwrite`	boolean	否	默认 `false`

固定语义：

只允许 HTTPS；拒绝非 HTTPS、用户名密码、空主机和超长 URL。
目标不能是目录、只读根、app://picked 或真实文件路径。
最多跟随 5 次重定向，每一跳仍必须是 HTTPS。
总超时 120 秒，最大下载体积 100 MiB。
先写目标同目录 .part 文件，成功后提交；失败、超时或取消时删除临时文件。
overwrite: false 时目标已存在返回 IO_ERROR。
不提供进度事件。前端超时或页面重载会通过现有 cancel 链路中止请求。

示例

TypeScript

try {
  const result = await KSM.http.download({
    url: 'https://example.com/releases/kasumi.zip',
    path: 'app://cache/releases/kasumi.zip',
    overwrite: false
  });

  console.info(result.path, result.bytes);
} catch (error) {
  if (error instanceof Error && error.name === 'IO_ERROR') {
    console.warn('目标已存在或下载提交失败');
  }
}

平台差异

Windows 使用 WinHTTP 并关闭自动重定向，取消时关闭活动句柄。Android 使用 HttpsURLConnection，取消时 disconnect() 活动连接。Android 在低内存或 Activity 销毁时只取消当前窗口下载；两端都逐跳校验 HTTPS。

错误行为

错误码	场景
`INVALID_ARGS`	URL、路径或 `overwrite` 类型非法
`PERMISSION_DENIED`	未授予 `http.download` 或路径越界
`BUSY`	同一请求 ID 已有下载
`IO_ERROR`	目标存在、重定向超限、体积超限、网络或提交失败
`TIMEOUT`	前端请求超时或宿主总下载超时
`CANCELLED`	页面重载、窗口销毁或显式取消
`NOT_SUPPORTED`	宿主未配置下载服务

排查路径

确认 URL 是绝对 HTTPS，且没有凭据。
确认目标是可写沙箱中的文件，不是目录或 picked 句柄。
目标已存在时显式设置 overwrite: true，或改用新路径。
检查重定向是否超过 5 次，每一跳是否仍为 HTTPS。
检查响应声明长度和实际写入是否超过 100 MiB。
失败后检查目录是否残留 .part 文件。
页面重载后不要复用旧请求 ID 或错误地重试已完成下载。

模块边界

层级	入口	责任
前端 API	`frontend/src/api/http.ts`	URL、路径、布尔值和 120 秒超时
协议清单	`protocol/plugins.json`	`http` 插件和 `http.download` 归属
Windows 插件	`windows/src/plugins/ksm_http_plugin.cpp`	请求分发和取消
Windows 传输	`windows/src/platform/ksm_windows_host_services.cpp`	WinHTTP、重定向和临时文件
Android 传输	`KSMAndroidHostServices.kt`	`HttpsURLConnection` 和生命周期取消

命令

Windows

Android

权限

http.download

支持

http.download

{ path, bytes }

参数与固定行为

参数	类型	必填	说明
`url`	string	是	绝对 `https://` URL
`path`	string	是	`app://data`、`app://cache` 或 `app://tmp` 下的文件路径
`overwrite`	boolean	否	默认 `false`

固定语义：

只允许 HTTPS；拒绝非 HTTPS、用户名密码、空主机和超长 URL。

目标不能是目录、只读根、app://picked 或真实文件路径。

最多跟随 5 次重定向，每一跳仍必须是 HTTPS。

总超时 120 秒，最大下载体积 100 MiB。

先写目标同目录 .part 文件，成功后提交；失败、超时或取消时删除临时文件。

overwrite: false 时目标已存在返回 IO_ERROR。

不提供进度事件。前端超时或页面重载会通过现有 cancel 链路中止请求。

示例

TypeScript

try {
  const result = await KSM.http.download({
    url: 'https://example.com/releases/kasumi.zip',
    path: 'app://cache/releases/kasumi.zip',
    overwrite: false
  });

  console.info(result.path, result.bytes);
} catch (error) {
  if (error instanceof Error && error.name === 'IO_ERROR') {
    console.warn('目标已存在或下载提交失败');
  }
}

错误行为

错误码	场景
`INVALID_ARGS`	URL、路径或 `overwrite` 类型非法
`PERMISSION_DENIED`	未授予 `http.download` 或路径越界
`BUSY`	同一请求 ID 已有下载
`IO_ERROR`	目标存在、重定向超限、体积超限、网络或提交失败
`TIMEOUT`	前端请求超时或宿主总下载超时
`CANCELLED`	页面重载、窗口销毁或显式取消
`NOT_SUPPORTED`	宿主未配置下载服务

排查路径

确认 URL 是绝对 HTTPS，且没有凭据。

确认目标是可写沙箱中的文件，不是目录或 picked 句柄。

目标已存在时显式设置 overwrite: true，或改用新路径。

检查重定向是否超过 5 次，每一跳是否仍为 HTTPS。

检查响应声明长度和实际写入是否超过 100 MiB。

失败后检查目录是否残留 .part 文件。

页面重载后不要复用旧请求 ID 或错误地重试已完成下载。

模块边界

平台与权限

参数与固定行为

示例

平台差异

错误行为

排查路径

评论

On this page

模块边界

平台与权限

参数与固定行为

示例

平台差异

错误行为

排查路径