Implement endpoint bdd resolution by arandito · Pull Request #885 · smithy-lang/smithy-python

arandito · 2026-11-03T07:43:51Z

Description

This PR replaces the regional endpoint resolver that generated AWS clients us today with endpoint resolution from each service's endpoint rules. See designs/endpoints.md for the full design.

Code generation lowers the smithy.rules#endpointBdd trait into a BDD constant of plain data in the _private/endpoints.py, and configs now default endpoint_resolver to AsyncBddEndpointResolver for async clients.
smithy-core adds one rules engine and standard library that evaluate this data for every Smithy-based service. Endpoint parameters are bound from the config, the operation input, and the contextParam, staticContextParams, and operationContextParams traits.
smithy-aws-core adds AWS_RULES_EXTENSION with the aws.* rules functions, the AWS built-ins, and partition data, and removes AsyncStandardRegionalEndpointsResolver.
Generated configs get use_fips_endpoint, use_dualstack_endpoint, account_id_endpoint_mode, and a field for each clientContextParams entry, when the service's rules declare them.
The request pipeline now resolves the auth scheme and identity before the endpoint, so the rules engine can read the account ID.
Code generation turns each model's endpointTests cases into tests/test_endpoints.py in the client package. Every case is resolved with its parameters through the client's resolver and cases with operation inputs run through the client as well. This ensures parameter binding works correctly.

Sync/Async Split

BddEndpointResolver defines the resolution logic as sync code and AsyncBddEndpointResolver wraps it for async clients. The async endpoint resolver protocol follows the SRA's recommendation that endpoint resolution be async, so it doesn't assume how an endpoint is resolved and keeps our interfaces flexible. For example, users may need to define a custom endpoint resolver that makes network calls. There are also AWS services (Timestream) that define a DescribeEndpoints API for the endpoint discovery feature.

Note

Follow-up PRs will stack on top of this one for:

Applying the endpoint's auth schemes when signing.
Host prefixes and host labels from the endpoint trait.
Resolving the endpoint built-in config fields from environment variables and profile keys.

Testing

Added unit tests for the BDD lowering, the rules engine and standard library, parameter binding, the resolver, the AWS rules functions, and the endpoint test checks.
Ran make test-unit - 3376 passed, 7 skipped.
Generated the 25 existing aws-sdk-python clients plus S3 and EC2 and ran their endpoint tests: 2,257 passed, 38 skipped, 5 xfailed. The skipped client cases set AWS::S3::UseGlobalEndpoint or AWS::STS::UseGlobalEndpoint, which have no config field (legacy config options we will not support). The expected failures are S3 WriteGetObjectResponse cases that need host labels.
Broke the engine, the AWS rules functions, parameter binding, and the request pipeline on purpose and confirmed the generated tests fail on both the resolver and client paths.

Performance

An uncached resolution is 4-13x faster than boto3 and a cache hit takes about 1 µs. Mean time per uncached call in µs, on m7i.xlarge with CPython 3.14:

Case	smithy-python	boto3
S3 virtual addressing	10.3	131
S3 access point ARN	18.1	130
S3 Outposts	22.6	121
Lambda, us-east-1	4.6	18.4

Full standardized benchmark results are in the appendix in designs/endpoints.md.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

stobrien89 · 2026-11-03T15:28:16Z

-
+            if signing is not None:
+                option, scheme, identity = signing
                signer_properties = scheme.signer_properties(


I think we’re missing the resolved endpoint’s auth properties here. It looks like signingRegion, signingName, and disableDoubleEncoding never get merged into the signer properties

stobrien89 · 2026-11-03T15:32:23Z

+        for (OperationShape operation : TopDownIndex.of(model).getContainedOperations(service)) {
+            var http = operation.getTrait(HttpTrait.class);
+            if (http.isPresent() && placesBucket(model, operation, http.get())) {
+                var uri = http.get().getUri().toString().substring(BUCKET_LABEL.length());


could we avoid removing /{Bucket} from the operation model unconditionally? Ideally static/custom resolvers retain the modeled path

jonathan343

Thanks @arandito! I mostly have questions for now. Still processing all these changes

jonathan343 · 2026-11-03T16:24:46Z

+    use_dualstack_endpoint: bool | None = None
+    """Whether to use dual-stack."""
+
+    use_fips_endpoint: bool | None = None
+    """Whether to use FIPS-compliant regional endpoint."""


nit - I think our descriptions can be improved a bit here to be more helpful

jonathan343 · 2026-11-03T16:26:11Z

-                ),
-                "root": 2,
-                "nodeCount": 14,
-                "nodes": "/////wAAAAH/////AAAAAAAAAA0AAAADAAAAAQAAAAQF9eEMAAAAAgAAAAUF9eEMAAAAAwAAAAgAAAAGAAAABAAAAAcF9eELAAAABQX14QkF9eEKAAAABAAAAAsAAAAJAAAABgAAAAoF9eEIAAAABwX14QYF9eEHAAAABQAAAAwF9eEFAAAABgX14QQF9eEFAAAAAwX14QEAAAAOAAAABAX14QIF9eED",


Investigating myself, but asking incase I forget

Why isn't this reflected in the endpoints.py file? Do we do some conversion into a different format?

The trait stores nodes as a base64 string (spec) and EndpointBddGenerator decodes them to plain ints in endpoints.py to avoid doing it at runtime. For example, /////wAAAAH///// decodes to -1, 1, -1.

jonathan343 · 2026-11-03T16:28:21Z

 ]

 dependencies = [
-    "smithy_aws_core~=0.12.0",


Why did this change here and not in the other places?

Edit: Oh is it because the old endpoint resolver was the only thing it was pulling in? And the others still pull in this dependency for other things like protocols?

jonathan343 · 2026-11-03T19:34:19Z

+            new BuiltInField("use_dualstack_endpoint", null),
+            // The SDKs and Tools Reference Guide default.
+            "AWS::Auth::AccountIdEndpointMode",
+            new BuiltInField("account_id_endpoint_mode", "preferred"));


Is this value validated anywhere. We should only be allowing preferred, disabled, or required. We also need to treat it as disabled when the request isn't signed.

jonathan343 · 2026-11-03T19:39:39Z

+                    ContextParamTrait.ID, // endpoint parameter plans read these at runtime
+                    StaticContextParamsTrait.ID,
+                    OperationContextParamsTrait.ID,


I don't see these being pulled in in the protocol test clients we have generated in this repo. Was this tested E2E with a service that does use them?

jonathan343 · 2026-11-03T19:41:56Z

@@ -0,0 +1,476 @@
+# Endpoint Resolution


can you format this w/ npx prettier or something? Main thing for readability is the long lines for me

jonathan343 · 2026-11-03T19:43:33Z

@@ -0,0 +1,4 @@
+{
+  "type": "breaking",
+  "description": "Removed `AsyncStandardRegionalEndpointsResolver` and its `smithy_aws_core.aio.endpoints` package, along with `smithy_aws_core.endpoints.RegionalEndpointConfig` and `REGIONAL_ENDPOINT_CONFIG`. Generated AWS clients now resolve endpoints from the service's endpoint rules with `smithy_core.aio.endpoints.AsyncBddEndpointResolver` and `smithy_aws_core.endpoints.AWS_RULES_EXTENSION`."


and its smithy_aws_core.aio.endpoints package

Do you mean module?

jonathan343 · 2026-11-03T19:47:36Z

+    auth_schemes=MappingProxyType(
+        {
+            "sigv4": SigV4Trait.id,
+            "sigv4a": ShapeID("aws.auth#sigv4a"),


What happens when we see sigv4a and don't support it?

jonathan343 · 2026-11-03T19:50:42Z

@@ -0,0 +1,4 @@
+{
+  "type": "breaking",
+  "description": "Added the required `auth_schemes` attribute to the `smithy_core.interfaces.Endpoint` protocol. Custom endpoint types that don't subclass `smithy_core.endpoints.Endpoint` must add it."


Why is this required now?

jonathan343 · 2026-11-03T19:57:41Z


 __version__ = "0.1.0"
-__all__ = ("ConformanceError", "deep_equal", "verify_models", "xml_equal")
+__all__ = (


Do you know what caused this formatting change?

Implement endpoint bdd resolution

4c6d80c

arandito force-pushed the endpoints-bdd branch from 3ebacff to 4c6d80c Compare November 3, 2026 08:05

arandito marked this pull request as ready for review November 3, 2026 15:06

arandito requested a review from a team as a code owner November 3, 2026 15:06

stobrien89 requested changes Nov 3, 2026

View reviewed changes

jonathan343 reviewed Nov 3, 2026

View reviewed changes

Conversation

arandito commented Nov 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Sync/Async Split

Testing

Performance

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jonathan343 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

arandito commented Nov 3, 2026 •

edited

Loading