Refactor XetSession commit / group CAS endpoint and auth configuration (#771)

There's no publicly documented Xet CAS endpoint. To interact with Xet
CAS, all public clients need to obtain a CAS endpoint from the same
route to obtain a CAS token.

Currently users need to
1. first construct a CAS token URL with respect to a certain operation
("read" or "write", targeted repo type, targeted repo, targeted
revision),
2. send a request to this URL to get a CAS token and CAS endpoint,
3. use the CAS endpoint to build a `XetSession`,
4. use the `XetSession` instance and the CAS token and CAS token URL to
build an upload or download group.

This is a rather completed setup. This PR address this blocker by
eagerly "refresh"-ing the CAS token if no CAS endpoint is provided, thus
users can
1. build a `XetSession`,
2. construct a CAS token URL with respect to a certain operation ("read"
or "write", targeted repo type, targeted repo, targeted revision),
3. use the `XetSession` instance and the CAS token URL to build an
upload or download group.

So effectively, there will be two common patterns:
Pattern A: endpoint known ahead of time — no eager refresh, token_info
is used as-is
```
let session = XetSessionBuilder::new().build()?;
let commit = session
    .new_upload_commit()?
    .with_endpoint(cas_url)
    .with_token_info(token, expiry)
    .with_token_refresh_url(refresh_url, /*Auth headers*/)
    .build_blocking()?;
```

Pattern B: endpoint unknown — build call fetches it; token_info seeded
from response
```
let session = XetSessionBuilder::new().build()?;
let commit = session
        .new_upload_commit()?
        .with_token_refresh_url(token_refresh_url, /*Auth headers*/)
        .build_blocking()?;
```

Other changes:
1. `with_endpoint()` and `with_custom_headers()` configuration is moved
from the `XetSession` level down to the operation level, because we can
actually have multiple operations with different CAS endpoints co-exist
in the same session instance.
2. Builder for different operations `XetUploadCommit`,
`XetFileDownloadGroup`, `XetDownloadStreamGroup` are refactored to share
common code under `struct AuthGroupBuilder<G>`.
This commit is contained in:
Di Xiao
2026-04-02 11:07:07 -07:00
committed by GitHub
parent 20198a9081
commit 1f0918c33e
14 changed files with 1567 additions and 828 deletions

1
Cargo.lock generated
View File

@@ -1963,6 +1963,7 @@ dependencies = [
"tracing",
"tracing-subscriber",
"ulid",
"wiremock",
"xet-client",
"xet-core-structures",
"xet-data",