Add an option to reset the buffer before sending.

[mbarnach]

Allow to reset the buffer before sending the response.

Description

When sending a response using .send, the body content is inaccessible.
But sometimes, it makes sense to reset the buffer before sending,
eg. an error handler that remove internal details,
sending a JSON payload, not kowing if there is already something inside, etc.

Motivation and Context

When capturing internal error and making them more explicit, eg. RFC 7807,
we need to reset the buffer to avoid appending internal content
or sending an invalid (JSON) payload.

How Has This Been Tested?

Add tests to check the resetted content for String, String? and Data
which is used by all underlying methods.

Checklist:

• [-] If applicable, I have updated the documentation accordingly.
• If applicable, I have added tests to cover my changes.

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities
0 Security Hotspots
7 Code Smells

No Coverage information
0.0% Duplication

[dannys42]

Thanks for the motivation and context! As an alternative, what do you think about adding a separate function call, like this:

\@discardableResult
public func removeBody() -> RouterResponse {
...
}

I think this would allow you to have syntax like:

removeBody()
send(...)

Or:

removeBody().send(...)

I'm not necessarily pushing for this, just exploring. From an API perspective, I guess it's largely a question fo whether these are separate actions. i.e. is there ever any use-case to "reset" without having to send? Or are the two functions really coupled?

If the latter, then the parameter approach that you have makes sense. But I'm not sure the "reset" name fully/effectively conveys the intent of the flag. An alternative name might be "overwrite". Or perhaps even an inverted flag called "append" (defaulting to false). (i.e. noting that the "default" behavior is to append to the body, but that you can make calls to explicitly overwrite it).

[mbarnach]

It looks like a good idea indeed.
I like the initial syntax until I had to change so many functions... I will give it a try and get back here, either with an update of the PR or my comments if I come across some un-expected changes.

[dannys42]

@mbarnach Oops, you're too fast... I had more thoughts. (see edit) :-)

[mbarnach]

@dannys42 I'm working with the following ideas:

• use a dedicated function, like mentioned above;
• call it reset to be more generic.
  Then, I'm wondering if this function should also reset:
• the state;
• the lifecycle;
• the cookies;
• the error;
• the statusCode (to .unknown);
• the userInfo
• and even the headers.

It seems to be quite a lot, but that would make sense in the case of error reporting.
A solution would then be that we use the parameters for the reset function, in the form of an OptionSet where we can define all of these parameters, and expose to the user the ability to reset any of them.

What are your thoughts on that approach?

[mbarnach]

@dannys42 A idea of it could be find in #1552