原生资源策略与请求计划

本页对应开发 SDK 和动态库源码，ABI 为 1。共享 Rust 核心校验配置并生成请求计划；浏览器主线程和严格 Worker 已实际使用同一规划器。原生动态库提供配置、计划和资源轮询，网络、等待、缓存及取消由宿主执行。桌面自动执行适配和共同脚本配置已接通，移动应用宿主待接入；不能仅配置动态库便假定它会自动联网。

下载完整 C 示例、头文件及版本清单。C 示例使用受控样式响应并读回真实地图像素，无外部网络依赖。另见浏览器资源策略及原生资源回传。

配置与查询

先检查 sqsm_map_runtime_flags() 的 SQSM_MAP_RESOURCE_POLICY（1073741824）或能力 JSON 的 nativeResourcePolicy。在地图创建线程调用 sqsm_map_resource_policy_json，输入 UTF-8 JSON，输出使用 sqsm_map_bytes_free 释放。

{
  "method": "configure",
  "args": [{
    "resourceTimeoutMs": 20000,
    "resourcePolicy": {
      "maxConcurrentRequests": 8,
      "attemptTimeoutMs": 4000,
      "retries": 1,
      "retryDelayMs": 100,
      "cache": "default",
      "fallbacks": [{
        "prefix": "https://primary.example/tiles/",
        "replacements": ["https://backup.example/tiles/"],
        "resourceTypes": ["Tile"],
        "forwardQuery": false
      }]
    }
  }]
}

配置是完整替换，省略字段恢复默认；configure 返回新配置并产生 sqs.resourceschange。校验、事件预留或输出分配失败保留旧配置。getConfiguration 的 args: [] 返回当前快照。只读 plan 以如下查询作为唯一参数，不发 HTTP、不修改配置或地图：

{"method":"plan","args":[{"url":"https://primary.example/tiles/1/2/3?token=private","resourceType":"Tile","maxBytes":8388608,"method":"GET","forceNoStore":false}]}

输入限制 512 KiB，输出限制 1 MiB。配置/查询严格拒绝未知字段、非法类型和范围。配置范围与浏览器策略一致；查询预算 1–64 MiB，方法为 1–32 个 ASCII 字母。资源类型使用 ResourceType 词汇。

非取消、非 WebSocket 的资源轮询项附带 requestPlan，在交付时捕获配置；之后修改配置不会改变已交付请求。计划版本为 1，包含 urls、method、resourceType、maxBytes、maxConcurrentRequests、resourceTimeoutMs、attemptTimeoutMs、retries、retryDelayMs、可选 cache 和 retryOn。HTTP(S) 地址不能含用户凭据。

宿主按顺序尝试 urls，每个地址最多 1 + retries 次。只允许 GET/HEAD 对连接故障、单次超时、HTTP 408/429/5xx 重试或转至备用地址。retryOn 明确给出这些条件；POST 的所有重试条件关闭。读取/解码失败、超预算、取消、永久 4xx 不回退。总期限包含候选、等待与读取，每次期限不得超过剩余总期限；并发名额也包含重试等待。没有指数退避或 Retry-After 处理。

第一条路径/类型匹配规则生效，最多 4 个候选、12 次尝试。备用路径保留编码路径后缀，默认移除查询和片段；仅 forwardQuery: true 转发查询。每个候选独立设置请求头，不能继承上一个地址的授权头；自动令牌只能给精确允许的最终来源。实时 HTTP 强制 no-store。计划不包含令牌、请求头或缓存实现。

C 轮询计划的 maxBytes 同时受核心资源预算和 C 响应接口 8 MiB 限制；通用只读规划器的 64 MiB 上限不扩大响应接口预算。取消项没有执行计划，宿主应取消相应任务及等待；迟到响应仍受地图身份和生成代检查。WebSocket 继续使用独立会话协议。

Rust 与 WASM

Rust 使用 ResourceConfiguration::parse(serde_json::Value) 和 plan_json，模块为 sqs_map::resource_policy；解析后的配置字段不可直接修改。规划不依赖 HTTP、GPU、UI 或 GDAL。

匹配版本的 WASM 提供全局 resourcePolicyPlanJSON(configurationJSON, queryJSON)。先初始化绑定再调用；结果为计划 JSON，错误保留稳定错误码。无需创建地图或 GPU。浏览器 Runtime 使用此规划器；自定义旧绑定没有该函数时仍走既有 TypeScript 规划器，不能据此声称已使用 Rust 规划器。

验证范围

50 组真实 C/WASM 输入结果一致；原生本地 HTTP 宿主与真实软件 Vulkan 验证配置原子性、请求捕获、503 重试/回退、期限、字节预算和取消。主线程及严格 Worker 实际软件 GL 共 68 项检查与两帧影像；执行中已确认调用 Rust 规划器。原生既有 19 项资源/脚本回归仍通过。这些证据不替代公网图源、硬件、Windows/macOS、移动设备或正式二进制发行验收。

共同脚本与宿主能力

原生一次性和持续脚本支持 map.sqs.resources.configure / getConfiguration / plan，配置调用必须 await。持续会话的 sqs.resourceschange 携带 context: resourcePolicy 与深度不可变的 resourceConfiguration；普通资源清理也可能产生同名原生状态事件，处理器应检查 context。历史配置不随下一次替换改变。C JSON 事件中的快照位于 resourcePolicyEvent，持续脚本自动展开为共同字段。

resourcePolicyPlanning 与 resourcePolicyEvents 为 true；原生库的 resourcePolicyExecution 为 false，HTTP仍由外部宿主执行。桌面和浏览器宿主已自动执行同一规划，不改变库的依赖边界。实际配置脚本在原生一次性/持续、桌面、网页主线程/严格Worker各通过30项；持续入口另通过9项不可变快照、身份、once和取消订阅检查。完整共用示例见共同门面，缓存与应用范围见资源策略。

13.6b已接通共同自定义协议规划和瓦片模板，保留真实地址与既有响应身份；边界/宿主注册/预算见协议规划。