Azure / Azure/typespec-rust

[Storage] Support augmenting generated options bag via `client.tsp` customization

Open
#1,011 0 comments 0 reactions 0 assignees View on GitHub
feature-request Storage
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.