Feature-gate public use of http-body and hyper within aws-smithy-types
#3088
Conversation
|
A new generated diff is ready to view.
A new doc preview is ready to view. |
ysaito1001
added
breaking-change
|
A new generated diff is ready to view.
A new doc preview is ready to view. |
|
A new generated diff is ready to view.
A new doc preview is ready to view. |
|
A new generated diff is ready to view.
A new doc preview is ready to view. |
|
A new generated diff is ready to view.
A new doc preview is ready to view. |
There was a problem hiding this comment.
API stabilization clarifications:
When we say "going 1.x," I understand this indicates a commitment to API stabilization. I'd like to clarify what this means in practical terms:
- Does "API stabilization" imply that we will never remove a function from the API? If a removal does happen, would it necessitate the introduction of a new major version?
- Are we allowed to add more functions to a crate post stabilization?
- Is it possible to deprecate functions, or will we avoid that completely?
- Can feature flags be added or removed after stabilization?
- Could a current API be placed behind a feature flag in a subsequent minor version after going 1.x?
- Are we bound to using the same underlying libraries indefinitely, or do we have the flexibility to switch them out? For example, if we're presently utilizing
rustlsinternally, would we have the liberty to transition tonative-tlsdown the line, as long as there isn't any disruption to the API?
Specifics on this PR:
Is it accurate to say that all functionalities associated with http::Body are now under the http-body-0-4-x flag? Hence, we have renamed functions. For instance, ByteStream::from_path to ByteStream::from_path_0_4 due to the API's reliance on http::Body. Are there elements within ByteStream that function independently of http::Body?
Minor questions regarding renaming:
Am I correct in understanding that the reason for renaming ByteStream::from_body(http::Body) to ByteStream::from_body_0_4(http::Body) is due to concerns about future changes in http::Body? If the name remained unchanged, it would suggest our API can always create a ByteStream from http::Body. Is there a concern that certain features in the http::Body 1.x release might prevent us from maintaining this capability, thus making it impossible to produce a ByteStream from http::Body post 1.x?
- If
http-bodyreleases a version 0.5, will we rename the function from::from_body_0_4to::from_body_0_5? Alternatively, do we anticipate thathttp-bodywill never release a0.5? - When
http-bodyupdates to 1.x, will thehttp-body-0-4-xfeature flag remain in place?
API stabilization clarifications:
Removing a function would necessitate a new major version.
Yes.
It is possible to deprecate functions.
They can be added but not removed.
No, this would break users. Even it we made it a default feature, users with
We are only bound in cases where external types are exposed in our public API. Transitioning to new defaults is breaking but we have a proposal from Russell on how to do that in a non-breaking way. Contact him for more info. Specifics on this PR
Yes, based on the current version of
Yes. Any code that doesn't need to interact with the inner body as a v0.4 HTTP body will not be feature-gated. Minor questions regarding renaming
If we decide compatibility with a new version is important, we'll create functions for it. I don't anticipate a v0.5 version of http-body, but if one releases, we'll consider supporting it. Renaming the function would be a breaking change. We are committed indefinitely to supporting any API that exposes a 3rd-party type.
Yes, the feature flag will still exist. One last thingThe only thing that would cause us to remove the v0.4 stuff is if http-body goes 1.0 before our GA. We can't count on that so we must be prepared to support multiple versions of the API. |
|
A new generated diff is ready to view.
A new doc preview is ready to view. |
#3101) ## Motivation and Context Follow up on #3088 ## Description This PR reverts `ByteStream::read_with_body_0_4_from`, `ByteStream::from_path_body_0_4`, and `ByteStream::from_file_body_0_4` to the old names since from a customers' point of view, `FsBuilder` should not mention anything about an `http-body` version at the API level. `FsBuilder` is currently an opt-in feature (with `rt-tokio` enabled) and we make it tied to `http-body-0-4-x` by requiring `rt-tokio` including a dependency on `http-body` version 0.4.x. ## Testing Relied on the existing tests in CI ## Checklist - [x] I have updated `CHANGELOG.next.toml` if I made changes to the smithy-rs codegen or runtime crates ---- _By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice._
Motivation and Context
Implements #3033
Description
This PR hides behind cargo features the third-party types from
http-bodyandhypercrates that are used inaws-smithy-types' public API. Customers need to opt-in by enabling a cargo featurehttp-body-0-4-xinaws-smithy-typesto create anSdkBodyorByteStreamusing those third-party types. For more details, please see the upgrade guide.As can been seen from code changes, to reduce the surface area where we need to feature-gate things, we have fused the
aws_smithy_types::body::Inner::Streamingenum variant intoaws_smithy_types::body::Inner::Dynvariant, thereby removingSdkBody::from_dyn.Testing
Relied on existing tests in CI
Checklist
CHANGELOG.next.tomlif I made changes to the smithy-rs codegen or runtime cratesBy submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.