Change default encoding of timestamps in HTTP bodies

[Baccata]

The context

AWS defines for its protocols that the default encoding of timestamps in HTTP bodies should be epoch-seconds.

Due to an early-days implementation mistake in smithy4s, the default encoding of timestamps in HTTP bodies is date-time. When we extracted the protocol definition to the alloy project, it was decided that the mistake would be "officialised" in the protocol, to avoid breaking existing users.

The problem(s)

Even though it's conceptually fine for the distinction to exist between what AWS does and what Alloy does, it creates a number of problems :

• The divergence breaks the principle of least surprise
• The divergence makes it harder to switch from alloy#simpleRestJson to the aws restJson protocol, which implies that tooling issued by AWS and tooling issued by DisneyStreaming have a smaller overlap
• The last point implies that in order for smithy4s to benefit from some protocol-tests issued by AWS, a fair amount of logic needs to be added in order to change some small semantics in the tests (as opposed to copy/pasting the test altogether). This increases the maintenance burden of a codebase that is already quite complex, conceptually speaking.

The proposal

I believe it is still reasonable to change the semantics of the protocol to align alloy on what AWS does. The benefit of increasing the compatibility of various tools in the ecosystem is high, and preventing an increase of maintenance burden due to small, context-dependant details that is appealing.

The mitigation

In order to mitigate the potential breakage in userland for any user that will not read release notes of whatever version of smithy4s performs that switch, it would be sensible to create a smithy validator that would encourage users to be specific about the timestamp formats, whenever a timestamp shape is transitively connected to a service that uses the simpleRestJson protocol. The validator would issue warnings when timestamps are found without any indication of preference for serialisation.

This is open for discussion.

Before pulling the trigger on this, I'd like the opinion of people.

[lewisjkl]

I think the change is definitely moving in the right direction, so I'm on board. The only concern I have is that people don't tend (imo) to pay much attention to smithy model warnings. I worry that it could easily go unnoticed and someone could introduce a breaking change to their API without realizing it. Making it an error does seem a bit too drastic though since then people would never be able to take advantage of the default format.. I'm not sure I have any great ideas to solve around it.

[kubukoz]

You can always go our way - turn warnings into errors on CI 😬

[daddykotex]

I'd also make it an error and advise that people suppress it that's really what they want

[Baccata]

Errors can't be suppressed. I think Danger can possibly be suppressed. I suggested warning cause I know they can be suppressed.

[Baccata]

You can always go our way - turn warnings into errors on CI

The point is that we don't oversee what other users do.

[yisraelU]

To me the question is more about the mitigation process for existing users and how we can improve
Its the right direction, for the aforementioned reasons
I do not like the idea, of providing a warning for not including a timestampFormat trait, I think that goes against the grain of the protocol, which is that a protocol trait, should inform all serialization. and the timestamp trait is meant as an override .
That said , I dont see another way , other than a Validator

[Baccata]

I do not like the idea, of providing a warning for not including a timestampFormat trait, I think that goes against the grain of the protocol, which is that a protocol trait, should inform all serialization. and the timestamp trait is meant as an override

Yeah I totally agree. We could remove the validator later on maybe ?

[yisraelU]

yeah , maybe this is the best we can get. only run it in 0.18