feat: support virtual-host addressing for S3-compatible snapshot back

[davidmyriel]

What problem does this solve?

I tried to point the OSS snapshot backend at an S3-compatible provider that requires virtual-host bucket addressing and found there was no way to make it work.

The backend picks the addressing style automatically in detect_addressing_style: Alibaba OSS endpoints and endpoints that already contain the bucket name get virtual-host style (https://bucket.example.com/key), and everything else falls back to path style (https://example.com/bucket/key). That fallback is the problem — a growing set of providers only reliably support virtual-host addressing (AWS S3 buckets created after the path-style deprecation, Cloudflare R2, Tigris), and for those the auto-detection guesses wrong with no way to override it. The result is confusing request failures at runtime rather than anything that points at addressing style.

What this PR does

Adds an optional addressing_style field to [backend.oss]:

[backend.oss]
endpoint = "https://t3.storage.dev"
bucket = "agentenv-snapshots"
region = "auto"
addressing_style = "virtual"   # or "path"

The behavior is strictly opt-in:

• When set, the explicit value wins and is passed straight through to the object-store client.
• When unset, the existing detect_addressing_style auto-detection runs exactly as before — zero behavior change for current Alibaba OSS / MinIO setups.

The plumbing is small: a new OssAddressingStyle config enum, a mapping in NormalizedOssConfig, and an override-or-detect resolution in OssClient::new.

Testing

• Unit tests covering: the detection fallback for generic endpoints, the existing Aliyun/bucket-in-endpoint detection, the override taking precedence, and the config mapping.
• Verified end-to-end against a real Tigris bucket with the included tigris_smoke example, which drives the same build_object_store_operator path the backend uses: write → read-back → verify → delete round-trip succeeds with addressing_style = "virtual".
• Also confirmed at the wire level (via a local Host-header echo endpoint) that the two styles genuinely produce different requests — Host: bucket.endpoint vs /bucket/key on the path — so the override reaches the wire rather than being silently dropped.
• cargo fmt, cargo clippy -- -D warnings, and cargo test -p object-store-operator are clean.

Docs

• docs/src/configuration/reference.md: new row in the [backend.oss] table plus a short worked example.
• docs/src/getting-started/on-demand-loading.md: one-line pointer after the OSS example config, since anyone following that guide with a virtual-host-only provider would otherwise hit an opaque failure.
• Commented-out example in config/default.toml.

Happy to drop the smoke example if you'd rather keep examples/ lean

[github-actions]

✅ OpenCodeReview: No comments generated. Looks good to me.

[guozy18]

Thanks for adding this. Being able to override the addressing style is useful for S3-compatible providers that cannot use the current default.

I'm requesting changes because the setting currently only reaches the repository client, not the OverlayBD path used to read remote snapshot layers. That means uploads can succeed while restoring a sandbox still fails. There is also a missing field in an existing integration test, plus a couple of cleanup issues in the smoke example.

One more thing: could you also update the commit message to follow the Conventional Commits format? The current message, "add tigris data", does not describe the change clearly. Something like feat(oss): support configurable S3 addressing style would be more appropriate. See https://www.conventionalcommits.org/en/v1.0.0/.

[davidmyriel]

@guozy18 all the comments are addressed and verified via test. Should be good to go.

I dropped the smoke test from the PR as it was attracting Github bots comments.

Congrats on the project success. Would like to do some promotions and comarketing + more integration work.

[github-actions]

[documentation · low]
The new option also accepts "path", but the default configuration only documents the virtual override. An explicit path override is important when auto-detection selects virtual style (for example, an Alibaba/custom bucket-in-host endpoint that nevertheless expects path style). Please list both accepted values and describe "path" as the force-path override; also consider avoiding “require” for the provider examples unless that requirement is guaranteed, since some S3-compatible providers support both styles.

Suggestion:

Suggested change

	# # path style). Set "virtual" for providers that require virtual-host
	# # addressing, e.g. AWS S3 new buckets, Cloudflare R2, or Tigris
	# # (endpoint = "https://t3.storage.dev", region = "auto").
	# addressing_style = "virtual"
	# # path style). Set "virtual" to force virtual-host addressing, or "path"
	# # to force path-style addressing. For example, virtual-host style can be used
	# # with AWS S3, Cloudflare R2, or Tigris
	# # (endpoint = "https://t3.storage.dev", region = "auto").
	# addressing_style = "virtual"

[github-actions]

[test · low]
Passing None makes read_at call size() first, so the recorder's only request is a metadata HEAD; the 404 then prevents the advertised range GET from being issued. This still checks the operator host/path, but it does not provide the stated wire-level proof for remote layer reads. Supply a size hint so read_at sends the GET directly (and consider asserting the request method).

Suggestion:

Suggested change

	.open_with_size_hint("s3://127/layers/explicit-style-object", None)
	.expect("open remote layer file");
	.open_with_size_hint("s3://127/layers/explicit-style-object", Some(4))
	.expect("open remote layer file");

[guozy18]

Thanks for the kind words, and thanks for addressing the earlier feedback. The main implementation direction now looks right, while the existing auto-detection behavior remains the default.

I still have a few requests before this is ready to merge:

1. Rebase onto the latest main and fix the resulting build failure

2. Address the two remaining automated review comments

   Both look valid to me:

   • Document both supported overrides, "virtual" and "path", and avoid overstating which providers strictly require either style.
   • Change the remote-read test from None to Some(4) so it exercises the range GET path rather than stopping after a metadata HEAD request. It would also be useful to assert that the captured request method is GET.

3. Do a simplification pass over the implementation and tests

   The PR currently adds around 375 lines, with a substantial amount of overlapping test coverage. I would keep the tests that protect distinct contracts: configuration parsing, repository-client override behavior, propagation into the generated OverlayBD config, endpoint validation, and one wire-level remote-read test.

   Tests that only cover unchanged auto-detection behavior, or repeat the same override behavior at adjacent layers, can likely be consolidated. For example, the newly added repository-client auto-detection tests overlap with existing OverlayBD tests, and some of the parsing, normalization, and wire-level assertions cover the same branch more than once.

[guozy18]

This PR changes OssClient::new to take six arguments. However, the snapshot image export service recently added on main still calls it with five arguments in image_export/service.rs.

After rebasing, please pass the configured override there as well:

config.addressing_style(),