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

Open
#1,011 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
45/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
rust
Domain
tooling

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.

Description

feature-request Storage
Motivation / Current State

In azure_storage_blob, BlobClientDownloadOptions (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<NonZero<usize>>
partition_size Option<NonZero<usize>>

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, 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.

Dominant language
Rust
Stars
7
Forks
11
Avg merge
14h 15m
Merged PRs (30d)
6

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Azure/typespec-rust

All issues in Azure/typespec-rust

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.