feat(storage): support signed read options and local byte ranges

2026-09-30 22:44:54 +08:00
parent 01a03149f9
commit f0c62152d7
29 changed files with 1395 additions and 30 deletions
--- a/reports/signedReadAcceptance.md
+++ b/reports/signedReadAcceptance.md
@@ -0,0 +1,33 @@
+# v0.29.0 通用签名读取验收
+
+范围：Local、S3/R2、OSS 的签名读取选项和本地范围读取。接口不包含业务身份、租户、分享记录、数据库、撤销或固定有效期。旧 Presigner、旧本地链接和默认下载行为兼容。
+
+## 本地回归
+
+2026-09-30，macOS arm64，Go 1.27.1：
+
+- `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -count=1 ./...`：57 个测试包通过，apigen 集成包 123.143 秒。
+- `GOTOOLCHAIN=go1.22.12 GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -count=1 ./...`：57 个测试包通过，apigen 集成包 113.212 秒。
+- `go vet ./...`、`go build ./...`、`git diff --check`：通过。
+- `go run ./examples/signedRead -check`：真实回环 HTTP 预览、中文文件名、下载、HEAD、Range 通过。
+- `python3 scripts/verifyUploads.py --output reports/signedReadMinio.json`：真实隔离 MinIO 的新读取选项、原上传/分片与存储契约通过，见 [报告](signedReadMinio.json)和[日志](signedReadMinio.txt)。独立容器无外部网络、不映射端口，已清理，原有容器保持运行。
+
+首次 MinIO 回归中，原有契约故意发送错误长度触发 SDK 重试退避，耗尽契约的 10 秒预算。测试专用 client 改为 MaxRetries=1，与现有协议测试一致；生产 client 配置未变，修正后通过。
+
+## 覆盖内容
+
+- 默认 attachment、inline、可选 MIME、ASCII/中文/特殊字符文件名，拒绝 CR/LF、控制字符、路径、过长参数、非法 MIME 和 disposition。
+- 本地签名绑定版本、key、有效期、全部响应选项，重复参数、未知参数、签名篡改、版本剥离和旧下载 URL 注入 inline 均拒绝，拒绝前不读存储。
+- 30 分钟实际签名到期时间、TTL 上下限、精确到期边界、取消 context；过期 Range/HEAD/条件请求不得读取文件或返回缓存命中。
+- 本地真实文件 GET/HEAD 内容长度、前缀/后缀/开放区间/截断/多段范围、206/416，Seek 不暴露元数据，按范围读取而非全文件缓冲；顺序读取 Store 回退完整 200。
+- 错误及条件响应保持 private/no-store，HEAD 成功与失败均无响应体。
+- OSS SDK V1/V4 独立重新计算签名，验证响应头在签名前加入，中文文件名、配置域名、到期时间及选项篡改；拒绝未签名配置。S3/R2 验证原生 SDK 查询参数与实际到期时间。
+- MinIO 实际 GET/Range 的响应头、字节和状态正确，篡改 disposition/type/cache/expiry 被服务端拒绝。
+
+## 验证边界
+
+OSS/R2 未使用云账号实测；SDK/MinIO 验证不能代替实际桶和域名验收。OSS 默认域名可能强制下载，其响应头覆盖受平台规则限制，需部署方检查实际 200/206。
+
+浏览器控制工具不可用，隔离 Chrome/Chromium 截图尝试未获得成功渲染证据，因此不计为浏览器预览通过。真实 PDF 的 HTTP 响应已检查，浏览器视觉预览与实际云域名接入仍需项目侧回归。
+
+远程固定版本空缓存验收结果在发布后记录；不移动已发布标签。
--- a/reports/signedReadMinio.json
+++ b/reports/signedReadMinio.json
@@ -0,0 +1,111 @@
+{
+  "status": "passed",
+  "startedAt": "2026-09-30T14:35:32.113432+00:00",
+  "architecture": "arm64",
+  "goVersion": "go version go1.27.1 darwin/arm64",
+  "image": "quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z",
+  "imageId": "sha256:8f08aee614800a237906bd48114d733e5ac5bfac4ccdf731f141b0e880d7a253",
+  "sourceSha256": {
+    "go.mod": "e3877788b18b605a007530f80b684f06a7ae308844c2959a8750ed55ae8037a3",
+    "go.sum": "53c136b153ec7c91731f7c927dfda540fbd683037f3fbd1f3d067b1ec7aabc15",
+    "internal/storagefixture/multipart.go": "da9ec938b3bdb872e10e4f874b6a0224121c14a631dcf4e86d7ebbc1cd34a770",
+    "internal/storagefixture/server.go": "defacc905246a643faf5371e437f9ce458f05461e0a922766034d1f9ffdaf003",
+    "storage/local/local.go": "5d1ca75d0d2ca87981eef84a60bf98d0feefa2a9594940d6bd231877f4f8ec02",
+    "storage/local/local_test.go": "3a2241840968df8e37fd67169c3ef708228449e81f65aff908c8b60d49434dc0",
+    "storage/local/read_test.go": "ef1f7feb0887ea4b1f30304dfaf542fe9788b6e17856c942f1cd98448656194f",
+    "storage/multipart.go": "3b718ebe6da681c89a3f797892c88e7acb15c295df2376d64ac35da0976ed69d",
+    "storage/multipart_test.go": "4053f680f7795db2a6b4aa23590b3669eec7a609dd92c4a1e20891a5299274ee",
+    "storage/oss/oss.go": "4216ce9f3fe3ac5418a5b809db3cef7e99dcca72a25a2a12301f5897cda85dd5",
+    "storage/oss/oss_test.go": "555a954010b1218804dc7951fc75e42eae24eba9a99c0871f5ba787f3fc87d45",
+    "storage/oss/read.go": "429a9a9f6c586a885d7cccb76c9d572d53a79df637ff128caacb2eac35b8d862",
+    "storage/oss/read_test.go": "a1c273cfedd2f3ee31ce407a7ddd6fd5ad02c65ad632a91bc7f3ead3712b5bbd",
+    "storage/oss/upload.go": "556129611f9e5549cac8a36b4026bfb19c112a295b55192579f9ac116e20626f",
+    "storage/oss/upload_test.go": "08eb0ed157f3743288d781f61d4d2b7bfe77852a8259c5e598c719d35889409e",
+    "storage/read.go": "92787c74ae024822f82b5b84bffc9f8a355f1f2565b99ca7fbefe49157ef4851",
+    "storage/read_test.go": "9b11ab9640e98c1c9fa7ce1e2587df217e874e3a6a6e27a0dd0ade6fbf3d5e1a",
+    "storage/s3/config.go": "626ec6a2c0b06c95ee7eb7aa0832b190cfcdeb8a127b6b89e99204040bc3b041",
+    "storage/s3/read.go": "319b57f2ecf435b71085c7cdcafd50a1e30caa5f357f83d4db3cdcef085792b6",
+    "storage/s3/read_test.go": "9b64fda5c83ba41508ec23cf41aeeb9826b677caaa851dcbeb04abe1f43eed65",
+    "storage/s3/s3.go": "016bef5948e97f3d043d2e858716f1c02d9f27c4e02802bdc1be3860116f4b6c",
+    "storage/s3/s3_test.go": "9ef284926ec9936ddfec8c52a9bf04fc7b4be55c43a535f6c5a428d1535f6fec",
+    "storage/s3/upload.go": "3ce0b3626249ffe7a041606d6a9481743af8a0d4868fadea20ed3ed44ee0c765",
+    "storage/s3/upload_test.go": "a41fdbd100d9c79a3606c5942f98017afe26d841b251d96e979df87d0af93867",
+    "storage/signed.go": "ae4b144137627be35718c40743ebc2f063ec667c24b6d8984ccfcca034a73787",
+    "storage/signedUpload.go": "a8d31bcbbad64796f04611e69271e94d917c9bcd5aeabd7a97ea155b0093c814",
+    "storage/signed_test.go": "eaffd40894018814e976477f96cf0fbaecfa1987caad78830d9fc8e96995882f",
+    "storage/storage.go": "cb670872f01cf1d7b4ebf21cec9fc6f52ad93bfdf523b2f28bbb8d9c7fe39a6c",
+    "storage/storagetest/contract.go": "e7ad7242102437882269d4066462059d7974586b36a82d18639eca10fd932be9",
+    "storage/storagetest/uploads.go": "9b66f86dd94ccdf30c7d603d432bc2a55956608898e46c1274fa27d16fa1a969",
+    "storage/upload.go": "9ff2930ba389163acc8063b51107c09a60290609ba384de8004c498ce09f20a1",
+    "storage/upload_test.go": "12b60419807ed64b89e30861674e19abee7b0b7bb0e8ec9ac5b3aa2e0710a1da"
+  },
+  "commands": [
+    [
+      "go",
+      "test",
+      "-p=2",
+      "-c",
+      "-o",
+      "/var/folders/wm/1sg73x8n7879sp3t6m4jpnrr0000gn/T/goOmniUpload3cba6ibp/s3.test",
+      "./storage/s3"
+    ],
+    [
+      "docker",
+      "run",
+      "--rm",
+      "--name",
+      "go-omni-upload-c388755df4ec",
+      "--platform",
+      "linux/arm64",
+      "--cpus",
+      "2",
+      "--memory",
+      "2048m",
+      "--memory-swap",
+      "2048m",
+      "--pids-limit",
+      "256",
+      "--network",
+      "none",
+      "--read-only",
+      "--cap-drop",
+      "ALL",
+      "--security-opt",
+      "no-new-privileges",
+      "--user",
+      "1000:1000",
+      "--tmpfs",
+      "/tmp:rw,nosuid,noexec,size=64m,mode=1777",
+      "--tmpfs",
+      "/data:rw,nosuid,noexec,size=128m,mode=1777",
+      "-v",
+      "/var/folders/wm/1sg73x8n7879sp3t6m4jpnrr0000gn/T/goOmniUpload3cba6ibp:/test:ro",
+      "-e",
+      "GOMAXPROCS=2",
+      "-e",
+      "MINIO_ROOT_USER=goOmniTest",
+      "-e",
+      "MINIO_ROOT_PASSWORD=goOmniTestSecret",
+      "-e",
+      "GO_OMNI_S3_TEST_ADDR=127.0.0.1:9000",
+      "--entrypoint",
+      "sh",
+      "quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z",
+      "-c",
+      "set -eu\nminio --version\nminio server /data --address 127.0.0.1:9000 --console-address 127.0.0.1:9001 >/tmp/minio.log 2>&1 &\nserver=$!\ntrap 'kill \"$server\" 2>/dev/null || true; wait \"$server\" 2>/dev/null || true' EXIT\n/test/s3.test -test.v -test.run '^TestS3Integration$' -test.count=1 -test.timeout=60s || { cat /tmp/minio.log; exit 1; }\n"
+    ]
+  ],
+  "containerLimits": {
+    "cpus": 2,
+    "memoryBytes": 2147483648,
+    "pids": 256,
+    "network": "none"
+  },
+  "notes": [
+    "MinIO verifies S3 signatures; OSS/R2 real cloud accounts are not exercised."
+  ],
+  "preExistingContainersStillRunning": true,
+  "cleanedContainer": "go-omni-upload-c388755df4ec",
+  "finishedAt": "2026-09-30T14:35:34.723540+00:00",
+  "logSha256": "c25db6c44baee149c1e3d6d3b7f81faac9483eb79709bed25f61b03d7b9b3133"
+}
--- a/reports/signedReadMinio.txt
+++ b/reports/signedReadMinio.txt
@@ -0,0 +1,7 @@
+minio version RELEASE.2025-09-07T16-13-09Z (commit-id=07c3a429bfed433e49018cb0f78a52145d4bedeb)
+Runtime: go1.24.6 linux/arm64
+License: GNU AGPLv3 - https://www.gnu.org/licenses/agpl-3.0.html
+Copyright: 2015-2025 MinIO, Inc.
+=== RUN   TestS3Integration
+--- PASS: TestS3Integration (0.63s)
+PASS