Skip to content

feat(services/cos): support cosn scheme and STS security token#7418

Open
WangXiaoBao1222 wants to merge 1 commit intoapache:mainfrom
WangXiaoBao1222:feat/cos-security-token-and-cosn-scheme
Open

feat(services/cos): support cosn scheme and STS security token#7418
WangXiaoBao1222 wants to merge 1 commit intoapache:mainfrom
WangXiaoBao1222:feat/cos-security-token-and-cosn-scheme

Conversation

@WangXiaoBao1222
Copy link
Copy Markdown

Which issue does this PR close?

Closes #7417.

Rationale for this change

This PR adds two related improvements to the Tencent Cloud COS (services/cos) backend:

  1. cosn:// scheme alias — In the Hadoop / Spark ecosystem, Tencent COS is
    commonly accessed via the cosn:// protocol (see the official
    hadoop-cos document). Users migrating Lance / Spark workloads to
    OpenDAL expect the same URI style to work out of the box, so we register
    cosn as an alias of cos at the service layer.

  2. STS temporary-credential (security_token) support — Production
    deployments frequently use Tencent Cloud STS (GetFederationToken /
    AssumeRole) to issue short-lived credentials consisting of a
    secret_id, secret_key, and a security_token. Previously, only
    the first two could be passed via config; the third one had to be
    injected via environment variables, which is awkward in embedded or
    multi-tenant scenarios.

What changes are included in this PR?

  • Register cosn as an alias of cos in services/cos/src/lib.rs.

  • Add CosConfig::security_token config field.

  • Add CosBuilder::security_token(...) setter with doc comments describing
    the precedence rules.

  • In CosBuilder::build, when both secret_id and secret_key are
    provided, resolve the session token with this precedence:

    1. explicit config.security_token set by the user;
    2. environment variables (TENCENTCLOUD_TOKEN,
      TENCENTCLOUD_SECURITY_TOKEN, QCLOUD_SECRET_TOKEN), only when
      disable_config_load is not set.

    The resolved token is then forwarded to
    StaticCredentialProvider::with_security_token so the
    x-cos-security-token header is attached automatically when signing.

  • Redact security_token in the Debug impl of CosConfig to avoid
    leaking secrets into logs.

  • Add unit tests covering:

    • CosConfig::from_uri correctly parses both cos:// and cosn://
      URIs, including bucket, root, and security_token;
    • security_token is redacted in Debug output.

Verified locally:

  • cargo fmt --all -- --check
  • cargo clippy -p opendal-service-cos --all-targets -- -D warnings
  • cargo test -p opendal-service-cos
  • Manual end-to-end test against a real Tencent COS bucket using STS
    temporary credentials from sts.tencentcloudapi.com — read / write /
    list / delete all succeeded via both cos:// and cosn:// schemes.

Are there any user-facing changes?

Yes, but fully backward-compatible:

  • New optional builder method CosBuilder::security_token(...).
  • New optional config field CosConfig::security_token.
  • cosn:// is now accepted wherever cos:// was previously accepted.

No existing behavior is removed or changed for users who do not set
security_token or use cosn://, so no breaking-changes label is
required.

AI Usage Statement

Parts of this change (code scaffolding, unit tests, and this PR
description) were drafted with the assistance of an AI coding agent
(Anthropic Claude, claude-4.7-opus). All changes were reviewed, tested,
and verified by the author against a real Tencent Cloud COS bucket before
submission.

- Add 'cosn://' scheme alias alongside 'cos://' for Tencent COS

- Add 'security_token' config field for STS temporary credentials

- Precedence: explicit config > env (TENCENTCLOUD_TOKEN / TENCENTCLOUD_SECURITY_TOKEN / QCLOUD_SECRET_TOKEN) when config load is enabled

- Redact security_token in Debug output

- Add unit tests for from_uri parsing (cosn scheme, bucket, root, security_token) and debug redaction
@WangXiaoBao1222 WangXiaoBao1222 requested a review from Xuanwo as a code owner April 20, 2026 09:26
@dosubot dosubot Bot added size:L This PR changes 100-499 lines, ignoring generated files. releases-note/feat The PR implements a new feature or has a title that begins with "feat" labels Apr 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

releases-note/feat The PR implements a new feature or has a title that begins with "feat" size:L This PR changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

new feature: support cosn scheme with temporary credentials for Tencent COS

1 participant