✨ Make MultipartFile recoverable to enable retrying FormData requests

[gabrielaraujoz]

• Add restoration capability to MultipartFile
• Add tests to ensure MultipartFile is not changed during cloning, it just gets a new instance that can be consumed by FormData

Possible next steps: Create method in FormData to make it recoverable/clonable as well.

New Pull Request Checklist

• I have read the Documentation
• I have searched for a similar pull request in the project and found none
• I have updated this branch with the latest main branch to avoid conflicts (via merge from master or rebase)
• I have added the required tests to prove the fix/feature I'm adding
• I have updated the documentation (if necessary)
• I have run the tests without failures
• I have updated the CHANGELOG.md in the corresponding package

Additional context and info (if any)

Hello there!

We at Revelo use Dio for all of our http requests. We also use MultiPart a lot and have gotten a significant amount of errors when retrying to send a MultiPart File because the stream has already been listened to/finalized.

exception: Bad state: The FormData has already been finalized. This typically means you are using the same FormData in repeated requests.. Error thrown .

This is a common use case for ourselves (and we think for others as well) due to access token's short duration. As it expires, we automatically renew it with the refresh token, and finally do the original request again, that's why we fall into this problem.

I thought of a possible way to make retrying these requests possible and it involves, as a first step, making MultipartFile store the original source path/value and be able to "clone" itself with a new stream generated from the same source path.

Even with this change, to retry the request we will still need to recreate FormData. But this small change already makes it possible to recreate it without the need of a secondary interface that would just be used to store the original source path. This proposed change avoids a lot of boilerplate code and extra state management, since we can "reset" the MultipartFile to it's initial state by simply calling restoreMultipartFile().

With this, we could retrieve add a new restored FormData in the RequestOptions object, and would not need to have a secondary solution just to get the file paths for each MultipartFile and each request.

WDYT? Would this ideia be a good addition to Dio? I plan to make another PR with a FormData.clone() convenience method to avoid even more boilerplate code once I have a little more spare time, but this second PR would require us to first apply the proposed change in this one.

Thanks a lot, best regards!

[AlexV525]

I'm not sure restore is a good word here because it represents manipulating the original object but here we produce a new one. Any other ideas? Other words like copy or duplicate might fit more in this case.

[gabrielaraujoz]

humm, how about reset?

[gabrielaraujoz]

I renamed it as duplicateMultipartFile, but let me know if you think reset would fit better :)

[AlexV525]

Please update codes to follow the 80-word length format or semantic line breaks.

Suggested change

	/// Restore MultipartFile, returning a new instance of the same object. This is useful if your request failed and you wish
	/// to sistematically retry it, for example a 401 error that can be solved by refreshing the token.
	/// Restore MultipartFile, returning a new instance of the same object.
	/// This is useful if your request failed and you wish to retry it,
	/// such as an unauthorized exception can be solved by refreshing the token.

[gabrielaraujoz]

I applied the line length rules to all the changes I made, thanks

[AlexV525]

The new method seems not tested though.

[gabrielaraujoz]

I changed the tests to comply to this, could you please check it out? a22208d

[gabrielaraujoz]

Hey @AlexV525, hope you're doing well. Could you please take a look and let me know if the changes are ok? We're currently dealing with this bug in production and would love to fix it with this PR.

Thanks a lot!

[kuhnroyal]

Can we not just call the method clone()?

[gabrielaraujoz]

@kuhnroyal awesome, done! @AlexV525 fyi

[gabrielaraujoz]

@kuhnroyal Thanks a lot for the approval! @AlexV525 do we have any perspective on when we could release this change?

[AlexV525]

Thanks for the contribution.

[dipu0]

@AlexV525
why MultipartFile.clone() will Deprecated? i faced this when i use fromStrem or fromFile in the time of retry. Unhandled Exception: Bad state: The MultipartFile has already been finalized. This typically means you are using the same MultipartFile in repeated requests.

but MultipartFile.fromFileSync(value.path).clone(); works great!

[AlexV525]

@AlexV525 why MultipartFile.clone() will Deprecated? i faced this when i use fromStrem or fromFile in the time of retry. Unhandled Exception: Bad state: The MultipartFile has already been finalized. This typically means you are using the same MultipartFile in repeated requests.

I don't see we've deprecated the MultipartFile.clone(), only we deprecated the unnamed constructor, and its deprecated message means: MultipartFile() is not cloneable when the stream is consumed, use the MultipartFile.fromStream instead.

[dipu0]

Then your deprecated message is not clear to me at least!
But thanks for the quick reply, that clone method is a life saver for me.

But use clones is a nice addition, but dio should not throw this error message in the first place.

Thanks again for clearing my confusion!