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.
Motivation / Current State
In
azure_storage_blob, BlobClientDownloadOptions (hand-written) is a near-exact copy of the generatedBlobClientDownloadInternalOptions. The two differ by only 2 fields:parallelOption<NonZero<usize>>partition_sizeOption<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:
parallelandpartition_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.tspwhich 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 withInternalin 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/BlockBlobClientUploadOptionson 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.tspway 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 asdownload_internal(private REST method used internally by our publicly exposeddownload()) while renaming its options bag to the publicBlobClientDownloadOptions.