Add client guidance for endpoint resolution#2941
Conversation
|
This pull request does not contain a staged changelog entry. To create one, use the Make sure that the description is appropriate for a changelog entry and that the proper feature type is used. See |
| Smithy clients need to know which server to connect to when making requests. | ||
| This server location is specified by a URI, called an **endpoint**. This guide |
There was a problem hiding this comment.
Nit: This phrasing makes it sound like URI and endpoint are synonymous but the below interface shows that endpoints are more that simplify URIs.
| #### Context | ||
|
|
||
| Endpoints may require additional context that impacts the request outside of | ||
| setting the URI. This context carries metadata that tells the client how to | ||
| modify requests for this specific endpoint. For example, some AWS use-cases | ||
| require that additional headers be added to HTTP requests for certain endpoints. | ||
|
|
||
| ```java | ||
| public static final Context.Key<Map<String, List<String>>> HEADERS = Context.key("Endpoint headers"); | ||
| ``` |
There was a problem hiding this comment.
Question: This is a departure from SRA where we recommended that HTTP headers be a first-class property of an endpoint. Why the change here?
There was a problem hiding this comment.
Because Smithy is protocol agnostic and there should therefore be no coupling to protocols, even transport protocols like http. Smithy, for example, already has traits to support mqtt.
| ## Progressive flexibility | ||
|
|
||
| For simple services using HTTP protocols, there may only be one URI to address. | ||
| When creating a Smithy client intended for such services, the obvious solution | ||
| to endpoint resolution is to expose a simple configuration option that takes the | ||
| entire URI. | ||
|
|
||
| As services scale, that simple configuration strategy may become cumbersome to | ||
| customers. Services with geographically-distributed deployment regions may wish | ||
| to have a simplified way to refer to those regions that customers can use as an | ||
| alternative. There may additionally be other factors that complicate endpoint | ||
| resolution, such as alternative endpoints dedicated to IPv6, cellular | ||
| architecture, operation-specific endpoints, and so on. To support these needs, | ||
| it is recommended that Smithy clients allow endpoint resolution to be flexible, | ||
| without sacrificing the ability to easily specify a URI. |
There was a problem hiding this comment.
Opinion: This section doesn't recommend or even mention using separate resolver/params interfaces for each service, which SRA does. I think we should maintain that recommendation and call it out in this document.
There was a problem hiding this comment.
It isn't necessary, and it makes everything more complex than it needs to be. When I was working on that for smithy-python, it was a nightmare. You can make it extensible and safe at the cost of it being fiendishly tedious to extend, or you can give up and just add a blank-check codegen hook. Perhaps tolerable for AWS SDK teams, but nobody else.
Instead this recommends providing the entire request, the schema for that request (simplified version of the model), and the request context. With all of that there's really no need to have service-specific interfaces. This is how smithy-java works, and it's perfectly capable of handling even S3's complex endpoint resolution.
| To further simplify the common case of defining a static URI, it is recommended | ||
| to provide helper methods that implement the interface for common URI or URL | ||
| types. |
There was a problem hiding this comment.
Nit: URLs are a strict subset of URIs and we don't mention the term URL anywhere else so mentioning it here feels out of place.
| ## Usage | ||
|
|
||
| It is recommended to invoke the `EndpointResolver` in every operation call, | ||
| rather than only once upon client construction. This is because the endpoint can | ||
| vary based on the operation, or the parameters in the operation. |
There was a problem hiding this comment.
Opinion: Given the interface and requirements defined above, it seems impossible to invoke an endpoint resolver only once upon client construction since there's no operation, resolver params, or context. I recommend dropping this section.
There was a problem hiding this comment.
True. Perhaps there's a better place for this, since I do think the need for per-operation resolution must be justified as it isn't the obvious path.
JordonPhillips
force-pushed
the
client-guidance-endpoints
branch
from
914ed54 to
c68801d
Compare
JordonPhillips
force-pushed
the
client-guidance-endpoints
branch
2 times, most recently
from
a20dcbe to
c8a9336
Compare
JordonPhillips
force-pushed
the
client-guidance-endpoints
branch
from
c8a9336 to
fd3a60c
Compare
4 participants
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.