Skip to content

feat: S3 public CDN host like OSS (AI生成) - #104

Merged
pluveto merged 2 commits into
mainfrom
feat/issue-100-s3-cdn-host
Sep 1, 2026
Merged

pluveto merged 2 commits into
mainfrom
feat/issue-100-s3-cdn-host

Conversation

@pluveto

@pluveto pluveto commented Sep 1, 2026

Copy link
Copy Markdown
Owner

Closes #100

S3 now has the same optional public CDN host as Aliyun OSS. Printed locators use that prefix; PUT and SigV4 still target endpoint. Empty/absent host keeps the current url_format behavior. public_base is accepted as an install-time alias.

Field name

  • Canonical: host (matches [uploaders.aliyunoss])
  • Alias at install: public_base (same idea as Qiniu; not a second field on S3Config)
  • Empty / missing → locator_for interpolates url_format as before
[uploaders.s3]
endpoint = "https://s3.us-west-2.amazonaws.com"
url_format = "{endpoint}/{bucket}/{path}"
host = "https://cdn.example.com"

How to verify

cargo test --workspace --locked
cargo clippy --workspace --locked --all-targets -- -D warnings
  • locator_without_host_uses_url_format — default {endpoint}/{bucket}/{path}
  • locator_with_host_uses_cdn_not_endpoint — CDN prefix wins; endpoint/bucket stay out of the public URL
  • sigv4_matches_independent_get_object_vector — signing unchanged (host: String::new())

Manual: set [uploaders.s3] host = "https://cdn.example.com", upload a file, confirm the printed URL is https://cdn.example.com/<key> while the PUT still goes to endpoint.

Three giants (deliberate)

Eric Evans:
The domain fact is two addresses for one object: the API write target and the public read locator. OSS already says this as endpoint vs host. S3 today folds the public URL into url_format interpolating {endpoint}, so the API address leaks into the locator. The issue asks for OSS language, so the field is host, not cdn_domain. Callers must not assemble CDN URLs; that stays inside the S3 context. public_base is Qiniu’s word for the same idea — translate it at install, do not put a second name on S3Config. Empty host is the current model, not a new required concept. No Go 0.2 forward-compat.

John Ousterhout:
Design twice. (1) Teach people url_format = "https://cdn.example.com/{path}" and/or add a {host} placeholder. (2) Optional host that short-circuits locator_for the way OSS does. (1) is a shallow module: the config still composes URLs, and it is easy to sign against the CDN by mistake. (2) hides the split; PUT stays on endpoint. Two knobs (host + url_format) is real complexity — accept it only with strict precedence: non-empty host wins, empty falls back. Done means locator tests with and without host, the existing SigV4 vector still passes, and put_url / sign_request never read host.

Alan Kay:
S3Uploader is the object. locator_for is the message “what public URL is this key?”. upload / sign_request / put_url must not see the CDN host. Do not leak CDN assembly to app, history, or a template the caller has to get right. State: host is the public prefix, endpoint is the API address. Empty host means the object still answers via url_format. Late binding: optional host so existing S3 objects keep working.

三个人的讨论

Ousterhout: two public-URL mechanisms is over-loose. Users can already set url_format to a CDN. Why add host?

Evans: that is not the OSS language the issue asked for. url_format still exposes {endpoint} and {bucket}. Domain experts say host.

Kay: url_format as the only path turns the object into a template engine. The object should answer locator_for. Host is the better message.

Ousterhout: then host is acceptable only if PUT is untouched and empty host is a no-op. Reject adding {host} as a third path. Reject making host required.

Evans: a second field public_base on S3Config would split the language. Alias only at s3_from_profile.

Kay agrees: install translates; the object’s vocabulary is host.

收敛结论

已收敛. Optional host: String on S3Config (empty = absent). locator_for uses join_host_path(host, key) when host is non-empty; otherwise url_format. PUT/SigV4 use endpoint only. public_base alias in s3_from_profile. Samples document the field. README skipped (S3 fields are not listed there).

Rejected:

  • {host} placeholder in url_format — shallow; callers still assemble
  • Required host like OSS — breaks existing S3 configs
  • Using CDN as the SigV4 Host header — signatures would fail; PUT must stay on endpoint
  • Go 0.2 field names / forward-compat — out of scope
  • public_base as a first-class S3Config field — splits ubiquitous language

决策与后续

Decided:

  • Field: host; install alias: public_base
  • Precedence: non-empty host over url_format
  • Locator message stays on S3Uploader; no caller-side CDN join
  • Signing/PUT unchanged

Residual risk: a host without scheme yields a scheme-less locator (same as OSS). Documented with https://cdn.example.com.

S3Uploader.locator_for uses host when set; PUT still signs against endpoint.
Empty host keeps url_format. public_base is accepted as an install alias.
Comment thread crates/upgit-uploaders/tests/s3.rs Outdated
"got {auth}"
);
}

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

两个都是低价值测试

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in SHA: 4aff904

Comment thread config.sample.zh-CN.toml Outdated
# S3 API 端点(AWS 区域 URL 或兼容端点)。
endpoint = "https://s3.us-west-2.amazonaws.com"
# 公开 URL 模板。占位符:{endpoint} {bucket} {path}。
# 公开 URL 模板。占位符:{endpoint} {bucket} {path}。host 为空时使用。

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

“host 为空时使用。”这种措辞令人费解,不如附带一个例子

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in SHA: 4aff904

Remove the low-value locator tests. Document url_format vs host with
concrete printed-URL examples instead of "used when host is empty".
@pluveto
pluveto merged commit 09b6642 into main Sep 1, 2026
3 checks passed
@pluveto
pluveto deleted the feat/issue-100-s3-cdn-host branch September 1, 2026 14:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

S3兼容配置支持CDN域名

1 participant