LegnaSend
开发文档English

API 参数长度与工作区状态核验

修复的不一致

只读 getWorkspaceState 契约允许 8192 字节的 ID 列表,但原生控制台和调试页输入框都截在 4096;HTTP 层又把整个编码后查询串限制为 8192,导致最大 ID 列表连 generation、参数名及逗号转义都容纳不下。

现在集成 API 契约、控制台和查询解析共用有界参数规则:

输入限制
工作区状态 ids最多 8192 个 ASCII 字节,最多 64 个逗号分隔的非空 ID
工作区锚点 anchor最多 8192 个 URL 安全 base64 ASCII 字节;仅指定目录中的一个条目
普通解码参数最多 4096 个 UTF-8 字节
文件清单筛选词最多 256 个 Unicode 码点,同时受字节预算约束
控制台 Range/If-Match最多 1024 字节
集成工作区状态接口的编码后查询串最多 24 KiB
其他集成接口的编码后查询串保留 8 KiB 限制
本地控制台工作区状态 JSON 信封最多 24 KiB,容纳有界字段的 JSON 转义
其他控制台信封保留已有上限,包括工作区发送的独立上限

ID 列表只允许字母、数字、下划线、连字符和分隔逗号,不引入本地路径、任意网址或目标选择。规范 base64url 解码、重复 ID、父目录匹配、来源访问、授权及代次检查仍由原有只读目录处理器执行;POST 仍拒绝。没有增加接口或权限,没有改变原始 LocalSend 字段及握手。

契约与调试页

字符串 Schema 声明按 Unicode 码点计算的 maxLength,并声明 x-legnasend-max-utf8-bytes;操作声明 x-legnasend-max-query-bytes。四种文档语言说明 64 项/8192 字节的边界。调试页读取这些限制,不再统一把所有输入框写死为 4096,并显示 Schema 内的说明。执行前校验最小/最大长度、模式、枚举和数字范围;控制字符与未配对代理字符被拒绝。

编码后查询长度和解码字段长度不同。Dart URI 与 Rust 表单对 ~、* 的编码不同,因此调试页验证草稿时同时检查两种编码,使有效草稿对应的网址示例与控制台请求都满足服务器上限。未填写完整或无效的示例模板仍须修正后再用于外部调用。既有信封、响应及并发预算仍独立生效。

验证

  • 真实鉴权 HTTP 与实际本地 HTTP 控制台都能核验精确 4096/8192 字节列表中的 64 个规范缺失 ID,返回结果一致;8193 字节被拒绝。普通查询上限、路径穿越/绝对路径/网址拒绝,以及只读方法保持验证。
  • 核心控制台 7 项测试通过,包含四语言在线契约、UTF-8/码点、编码后查询边界和精确长度。
  • 参数单元 4 项覆盖 Unicode、Schema 组合、两种查询编码及超限输入。
  • 页面 4 项覆盖英、简中、繁中及香港中文,390 宽、1.6 倍文字;8192 字符草稿完整送到只读控制台,程序设置的超限草稿不会派发。

这是只读接口有界输入的一致性修复,不作为新增文件管理能力或移动真机验收。最终 OpenAPI 导出及离线文档同步由本批主任务统一执行。

目录分页现在共用 24 KiB 编码查询预算,以容纳 8192 字节锚点、UTF-8 相对路径、筛选和代次;其他路由预算不变。