[Storage] Support augmenting generated options bag via `client.tsp` customization
- Dominant language
- Rust
- Stars
- 7
- Forks
- 11
- Avg merge
- 2d 5h
- Merged PRs (30d)
- 5
Description
### Motivation / Current State
In `azure_storage_blob`, [BlobClientDownloadOptions](https://github.com/Azure/azure-sdk-for-rust/blob/main/sdk/storage/azure_storage_blob/src/models/method_options.rs#L17-L110) (hand-written) is a near-exact copy of the generated `BlobClientDownloadInternalOptions`. The two differ by only **2 fields**:
| Field | Type | Present in hand-written| Present in generated |
|-------|------|:-:|:-:|
| `parallel` | `Option>` | ✅ | ❌ |
| `partition_size` | `Option>` | ✅ | ❌ |
These two fields are consumed by the SDK's own download orchestration (chunked/parallel download) and are **not** part of the REST contract, so they cannot be added to `routes.tsp`, but they are valid options for the SDK to change download behavior.
The same can be seen with [BlockBlobClientUploadOptions](https://github.com/Azure/azure-sdk-for-rust/blob/main/sdk/storage/azure_storage_blob/src/models/method_options.rs#L112-L200), which again is a full redefinition just to gain the ability to add 2 fields necessary for the SDK to achieve the most performant implementation: `parallel` and `partition_size`.
Because there's no way to inject them into the generated type, we currently have to hand-copy the entire generated struct and use the handwritten one in place of the fully generated one due to these SDK-necessary options that can't be appended to the options bag which are auto-generated based on their definitions in `routes.tsp` which align with the REST contract.
#### Aside: Independently controlling the options bag name
Note: Depending on discussion for support for the above, I can break this out to a seperate issue. But this issue does not need to be solved unless we have the above.
In these cases we deliberately surface a **hand-written public API** (`download`, `upload`) that internally drives an **internal-only REST operation** (`download_internal`, `upload_internal`). Because the REST operation is named `*_internal`, its generated options bag is also named with `Internal` in it: e.g. BlobClientDownloadInternalOptions, `BlockBlobClientUploadInternalOptions`.
Today that "Internal" naming is fine because the bag is a private, generated implementation detail and we hand-write the public `BlobClientDownloadOptions` / `BlockBlobClientUploadOptions` on top. But if we instead **augment the generated bag directly** (per the proposal above), that same struct is now **the** only ubiquitous options bag.
So if we get support for the above, we will also need a `client.tsp` way to **independently control the generated options bag's name**, decoupled from the operation name it derives from. Concretely, we'd want to keep the operation as `download_internal` (private REST method used internally by our publicly exposed `download()`) while renaming its options bag to the public `BlobClientDownloadOptions`.
Contributor guide
Research direction
Start by tracing the client.tsp customization path and the generated options derived from routes.tsp. Compare the generated BlobClientDownloadInternalOptions and BlockBlobClientUploadInternalOptions with the handwritten options described in the issue. Done means SDK-specific fields can augment the generated options bag, with independent public naming support if the aside remains in scope.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100