Open david-perez opened 1 year ago
Asking Smithy for guidance: https://github.com/smithy-lang/smithy/issues/2123
As we start adding support for new protocols (https://github.com/smithy-lang/smithy-rs/issues/3573), this task gains importance: existing services will want to make use of more modern protocols.
Smithy
service
shapes can be annotated with multiple protocol traits.In theory this indicates that clients invoking operations of
MyService
can use any of the tworestJson1
,@awsJson1_1
protocols, andMyService
should accept incoming requests in any of the two protocols.Currently server SDKs are generated such that they only support the first protocol the
service
shape is annotated with; the rest of the protocols are ignored.Multi-protcol support is important for services that want to begin supporting a better protocol and migrate their existing clients to it. Without a period during which the service understands both protocols, the migration becomes challenging or even impossible.
Implementation-wise, one possiblity is that when receiving a request, the server SDK iterates over a priority-ordered list of supported protocols and attempt to "claim" it: if claiming succeeds, the request is handed over to that protocol's router. If routing or any other step thereafter fails, the request is rejected: we do not attempt to process the request with the next protocol.
When tackling this issue I'd like the algorithm to be detailedly documented, and I'd like as much of it to be contributed to the Smithy specification so that other Smithy-based server SDK generators abide by the same rules. In particular, we should answer these questions:
awsJson1_1
protocol, checking first the HTTP version against thehttp
andeventStreamHttp
properties and then checking forContent-Type
equallingapplication/x-amz-json-1.1
should suffice to unambiguously detect that the request is indeed meant to be processed by said protocol (one could additionally and inexpensively check for the URI being/
, method beingPOST
, and the presence ofX-Amz-Target
, so it's important that a decision is made and the concrete steps be documented, ideally in the spec). For other protocols, likerestJson1
, the checks to perform are less apparent.UnknownOperationException
, but serializing said exception is kinda unsolvable when you haven't agreed on a protocol.