Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add blurb on disabling endpoint prefix #2784

Merged
merged 1 commit into from
Sep 11, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 79 additions & 0 deletions content/en/docs/configuring-sdk/endpoints.md
Original file line number Diff line number Diff line change
Expand Up @@ -334,6 +334,8 @@ When migrating from v1 to v2 of endpoint resolution, the following general princ
* Returning an Endpoint with HostnameImmutable set to `true` is roughly
equivalent to implementing an `EndpointResolverV2` which returns the
originally returned URL from v1.
* The primary exception is for operations with modeled endpoint prefixes. A
note on this is given further down.

Examples for these cases are provided below.

Expand All @@ -344,6 +346,16 @@ still be set for immutable endpoints returned via v1 code, but the same will
not be done for v2.
{{% /pageinfo %}}

### Note on host prefixes

Some operations are modeled with host prefixes to be prepended to the resolved
endpoint. This behavior must work in tandem with the output of
ResolveEndpointV2 and therefore the host prefix will still be applied to that
result.

You can manually disable endpoint host prefixing by applying a middleware, see
the examples section.

### Examples

#### Mutable endpoint
Expand Down Expand Up @@ -400,3 +412,70 @@ client := svc.NewFromConfig(cfg, func (o *svc.Options) {
})
```

#### Disable host prefix

```go
import (
"context"
"fmt"
"net/url"

"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/<service>"
smithyendpoints "github.com/aws/smithy-go/endpoints"
"github.com/aws/smithy-go/middleware"
smithyhttp "github.com/aws/smithy-go/transport/http"
)

// disableEndpointPrefix applies the flag that will prevent any
// operation-specific host prefix from being applied
type disableEndpointPrefix struct{}

func (disableEndpointPrefix) ID() string { return "disableEndpointPrefix" }

func (disableEndpointPrefix) HandleInitialize(
ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler,
) (middleware.InitializeOutput, middleware.Metadata, error) {
ctx = smithyhttp.SetHostnameImmutable(ctx, true)
return next.HandleInitialize(ctx, in)
}

func addDisableEndpointPrefix(o *<service>.Options) {
o.APIOptions = append(o.APIOptions, (func(stack *middleware.Stack) error {
return stack.Initialize.Add(disableEndpointPrefix{}, middleware.After)
}))
}

type staticResolver struct{}

func (staticResolver) ResolveEndpoint(ctx context.Context, params <service>.EndpointParameters) (
smithyendpoints.Endpoint, error,
) {
u, err := url.Parse("https://custom.endpoint.api/")
if err != nil {
return smithyendpoints.Endpoint{}, err
}

return smithyendpoints.Endpoint{URI: *u}, nil
}


func main() {
cfg, err := config.LoadDefaultConfig(context.Background())
if err != nil {
panic(err)
}

svc := <service>.NewFromConfig(cfg, func(o *<service>.Options) {
o.EndpointResolverV2 = staticResolver{}
})

_, err = svc.<Operation>(context.Background(), &<service>.<OperationInput>{ /* ... */ },
addDisableEndpointPrefix)
if err != nil {
panic(err)
}
}
```

6 changes: 3 additions & 3 deletions docs/404.html
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<!doctype html>
<html itemscope itemtype="http://schema.org/WebPage" lang="en" class="no-js">
<head><script src="/aws-sdk-go-v2/livereload.js?mindelay=10&amp;v=2&amp;port=1313&amp;path=aws-sdk-go-v2/livereload" data-no-instant defer></script>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<meta name="generator" content="Hugo 0.115.4">
Expand All @@ -23,7 +23,7 @@
<meta property="og:title" content="404 Page not found" />
<meta property="og:description" content="The AWS SDK for Go V2 provides APIs and utilities that developers can use to build Go applications that use AWS services." />
<meta property="og:type" content="website" />
<meta property="og:url" content="http://localhost:1313/aws-sdk-go-v2/404.html" />
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lol

<meta property="og:url" content="https://aws.github.io/aws-sdk-go-v2/404.html" />
<meta itemprop="name" content="404 Page not found">
<meta itemprop="description" content="The AWS SDK for Go V2 provides APIs and utilities that developers can use to build Go applications that use AWS services."><meta name="twitter:card" content="summary"/>
<meta name="twitter:title" content="404 Page not found"/>
Expand Down Expand Up @@ -99,7 +99,7 @@
aria-label="Search this site…"
autocomplete="off"

data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.30b245754e63db1f94dcbaa3ba0f9915.json"
data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.1ed5201c9429d6d49ab1e6d6c5e5409e.json"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Were you able to confirm if this offline search works?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did actually check this and it worked for me both in the preview and on the current render of the public site. We'll see what happens when this merges and gets propagated. The search index appears to get a new filename every time, it's possible that it just went out of sync in a previous pass on re-generating.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
Expand Down
14 changes: 7 additions & 7 deletions docs/docs/cloud9-go/index.html
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<!doctype html>
<html itemscope itemtype="http://schema.org/WebPage" lang="en" class="no-js">
<head><script src="/aws-sdk-go-v2/livereload.js?mindelay=10&amp;v=2&amp;port=1313&amp;path=aws-sdk-go-v2/livereload" data-no-instant defer></script>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<meta name="generator" content="Hugo 0.115.4">
Expand All @@ -24,7 +24,7 @@
<meta property="og:title" content="Using AWS Cloud9 with the AWS SDK for Go V2" />
<meta property="og:description" content="You can use AWS Cloud9 with the AWS SDK for Go V2 to write and run your Go code using just a browser. AWS Cloud9 includes tools such as a code editor and terminal. The AWS Cloud9 IDE is cloud based, so you can work on your projects from your office, home, or anywhere using an internet-connected machine. For general information about AWS Cloud9, see the AWS Cloud9 User Guide." />
<meta property="og:type" content="article" />
<meta property="og:url" content="http://localhost:1313/aws-sdk-go-v2/docs/cloud9-go/" /><meta property="article:section" content="docs" />
<meta property="og:url" content="https://aws.github.io/aws-sdk-go-v2/docs/cloud9-go/" /><meta property="article:section" content="docs" />
<meta property="article:published_time" content="2020-11-12T00:00:00+00:00" />
<meta property="article:modified_time" content="2021-04-23T01:04:37+02:00" />
<meta itemprop="name" content="Using AWS Cloud9 with the AWS SDK for Go V2">
Expand Down Expand Up @@ -105,7 +105,7 @@
aria-label="Search this site…"
autocomplete="off"

data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.30b245754e63db1f94dcbaa3ba0f9915.json"
data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.1ed5201c9429d6d49ab1e6d6c5e5409e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
Expand All @@ -127,7 +127,7 @@
aria-label="Search this site…"
autocomplete="off"

data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.30b245754e63db1f94dcbaa3ba0f9915.json"
data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.1ed5201c9429d6d49ab1e6d6c5e5409e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
Expand Down Expand Up @@ -475,10 +475,10 @@
<nav aria-label="breadcrumb" class="td-breadcrumbs">
<ol class="breadcrumb">
<li class="breadcrumb-item">
<a href="http://localhost:1313/aws-sdk-go-v2/docs/">Developer Guide</a>
<a href="https://aws.github.io/aws-sdk-go-v2/docs/">Developer Guide</a>
</li>
<li class="breadcrumb-item active" aria-current="page">
<a href="http://localhost:1313/aws-sdk-go-v2/docs/cloud9-go/" aria-disabled="true" class="btn-link disabled">Using Cloud9 with the SDK</a>
<a href="https://aws.github.io/aws-sdk-go-v2/docs/cloud9-go/" aria-disabled="true" class="btn-link disabled">Using Cloud9 with the SDK</a>
</li>
</ol>
</nav>
Expand Down Expand Up @@ -576,7 +576,7 @@ <h2 id="InstallUpgradeGo">Installing/Upgrading AWS Cloud9 Go Version</h2>


<div class="text-muted mt-5 pt-3 border-top">
Last modified April 23, 2021: <a href="https://github.com/aws/aws-sdk-go-v2/commit/6c3cbc2a767107ac17f06d43c815f2ea3bb57484">Fixing broken links, correcting typos (#1236) (6c3cbc2)</a>
Last modified April 23, 2021: <a href="https://github.com/aws/aws-sdk-go-v2/commit/6c3cbc2a767107ac17f06d43c815f2ea3bb57484">Fixing broken links, correcting typos (#1236) (6c3cbc2a76)</a>
</div>

</div>
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<!DOCTYPE html>
<html lang="en">
<head><script src="/aws-sdk-go-v2/livereload.js?mindelay=10&amp;v=2&amp;port=1313&amp;path=aws-sdk-go-v2/livereload" data-no-instant defer></script>
<head>
<meta charset="UTF-8">
<meta name="robots" content="noindex">
<meta http-equiv="Refresh" content="0; url='https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2"/>
Expand Down
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
<title>AWS SDK for Go V2 – CreateCustomMetricv2</title>
<link>http://localhost:1313/aws-sdk-go-v2/docs/code-examples/cloudwatch/createcustommetric/</link>
<link>https://aws.github.io/aws-sdk-go-v2/docs/code-examples/cloudwatch/createcustommetric/</link>
<description>Recent content in CreateCustomMetricv2 on AWS SDK for Go V2</description>
<generator>Hugo -- gohugo.io</generator>
<language>en</language>

<atom:link href="http://localhost:1313/aws-sdk-go-v2/docs/code-examples/cloudwatch/createcustommetric/index.xml" rel="self" type="application/rss+xml" />
<atom:link href="https://aws.github.io/aws-sdk-go-v2/docs/code-examples/cloudwatch/createcustommetric/index.xml" rel="self" type="application/rss+xml" />



Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<!DOCTYPE html>
<html lang="en">
<head><script src="/aws-sdk-go-v2/livereload.js?mindelay=10&amp;v=2&amp;port=1313&amp;path=aws-sdk-go-v2/livereload" data-no-instant defer></script>
<head>
<meta charset="UTF-8">
<meta name="robots" content="noindex">
<meta http-equiv="Refresh" content="0; url='https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2"/>
Expand Down
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
<title>AWS SDK for Go V2 – CreateEnableMetricAlarmv2</title>
<link>http://localhost:1313/aws-sdk-go-v2/docs/code-examples/cloudwatch/createenablemetricalarm/</link>
<link>https://aws.github.io/aws-sdk-go-v2/docs/code-examples/cloudwatch/createenablemetricalarm/</link>
<description>Recent content in CreateEnableMetricAlarmv2 on AWS SDK for Go V2</description>
<generator>Hugo -- gohugo.io</generator>
<language>en</language>

<atom:link href="http://localhost:1313/aws-sdk-go-v2/docs/code-examples/cloudwatch/createenablemetricalarm/index.xml" rel="self" type="application/rss+xml" />
<atom:link href="https://aws.github.io/aws-sdk-go-v2/docs/code-examples/cloudwatch/createenablemetricalarm/index.xml" rel="self" type="application/rss+xml" />



Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<!DOCTYPE html>
<html lang="en">
<head><script src="/aws-sdk-go-v2/livereload.js?mindelay=10&amp;v=2&amp;port=1313&amp;path=aws-sdk-go-v2/livereload" data-no-instant defer></script>
<head>
<meta charset="UTF-8">
<meta name="robots" content="noindex">
<meta http-equiv="Refresh" content="0; url='https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2"/>
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/code-examples/cloudwatch/describealarms/index.xml
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
<title>AWS SDK for Go V2 – DescribeAlarmsv2</title>
<link>http://localhost:1313/aws-sdk-go-v2/docs/code-examples/cloudwatch/describealarms/</link>
<link>https://aws.github.io/aws-sdk-go-v2/docs/code-examples/cloudwatch/describealarms/</link>
<description>Recent content in DescribeAlarmsv2 on AWS SDK for Go V2</description>
<generator>Hugo -- gohugo.io</generator>
<language>en</language>

<atom:link href="http://localhost:1313/aws-sdk-go-v2/docs/code-examples/cloudwatch/describealarms/index.xml" rel="self" type="application/rss+xml" />
<atom:link href="https://aws.github.io/aws-sdk-go-v2/docs/code-examples/cloudwatch/describealarms/index.xml" rel="self" type="application/rss+xml" />



Expand Down
2 changes: 1 addition & 1 deletion docs/docs/code-examples/cloudwatch/disablealarm/index.html
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<!DOCTYPE html>
<html lang="en">
<head><script src="/aws-sdk-go-v2/livereload.js?mindelay=10&amp;v=2&amp;port=1313&amp;path=aws-sdk-go-v2/livereload" data-no-instant defer></script>
<head>
<meta charset="UTF-8">
<meta name="robots" content="noindex">
<meta http-equiv="Refresh" content="0; url='https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2"/>
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/code-examples/cloudwatch/disablealarm/index.xml
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
<title>AWS SDK for Go V2 – DisableAlarmv2</title>
<link>http://localhost:1313/aws-sdk-go-v2/docs/code-examples/cloudwatch/disablealarm/</link>
<link>https://aws.github.io/aws-sdk-go-v2/docs/code-examples/cloudwatch/disablealarm/</link>
<description>Recent content in DisableAlarmv2 on AWS SDK for Go V2</description>
<generator>Hugo -- gohugo.io</generator>
<language>en</language>

<atom:link href="http://localhost:1313/aws-sdk-go-v2/docs/code-examples/cloudwatch/disablealarm/index.xml" rel="self" type="application/rss+xml" />
<atom:link href="https://aws.github.io/aws-sdk-go-v2/docs/code-examples/cloudwatch/disablealarm/index.xml" rel="self" type="application/rss+xml" />



Expand Down
18 changes: 9 additions & 9 deletions docs/docs/code-examples/cloudwatch/index.html
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
<!doctype html>
<html itemscope itemtype="http://schema.org/WebPage" lang="en" class="no-js">
<head><script src="/aws-sdk-go-v2/livereload.js?mindelay=10&amp;v=2&amp;port=1313&amp;path=aws-sdk-go-v2/livereload" data-no-instant defer></script>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<meta name="generator" content="Hugo 0.115.4">
<link rel="alternate" type="application/rss&#43;xml" href="http://localhost:1313/aws-sdk-go-v2/docs/code-examples/cloudwatch/index.xml">
<link rel="alternate" type="application/rss&#43;xml" href="https://aws.github.io/aws-sdk-go-v2/docs/code-examples/cloudwatch/index.xml">
<meta name="robots" content="index, follow">


Expand All @@ -25,7 +25,7 @@
<meta property="og:title" content="Amazon CloudWatch Examples" />
<meta property="og:description" content="The AWS SDK for Go V2 provides APIs and utilities that developers can use to build Go applications that use AWS services." />
<meta property="og:type" content="website" />
<meta property="og:url" content="http://localhost:1313/aws-sdk-go-v2/docs/code-examples/cloudwatch/" />
<meta property="og:url" content="https://aws.github.io/aws-sdk-go-v2/docs/code-examples/cloudwatch/" />
<meta itemprop="name" content="Amazon CloudWatch Examples">
<meta itemprop="description" content="The AWS SDK for Go V2 provides APIs and utilities that developers can use to build Go applications that use AWS services."><meta name="twitter:card" content="summary"/>
<meta name="twitter:title" content="Amazon CloudWatch Examples"/>
Expand Down Expand Up @@ -101,7 +101,7 @@
aria-label="Search this site…"
autocomplete="off"

data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.30b245754e63db1f94dcbaa3ba0f9915.json"
data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.1ed5201c9429d6d49ab1e6d6c5e5409e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
Expand All @@ -123,7 +123,7 @@
aria-label="Search this site…"
autocomplete="off"

data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.30b245754e63db1f94dcbaa3ba0f9915.json"
data-offline-search-index-json-src="/aws-sdk-go-v2/offline-search-index.1ed5201c9429d6d49ab1e6d6c5e5409e.json"
data-offline-search-base-href="/"
data-offline-search-max-results="10"
>
Expand Down Expand Up @@ -453,13 +453,13 @@
<nav aria-label="breadcrumb" class="td-breadcrumbs">
<ol class="breadcrumb">
<li class="breadcrumb-item">
<a href="http://localhost:1313/aws-sdk-go-v2/docs/">Developer Guide</a>
<a href="https://aws.github.io/aws-sdk-go-v2/docs/">Developer Guide</a>
</li>
<li class="breadcrumb-item">
<a href="http://localhost:1313/aws-sdk-go-v2/docs/code-examples/">Code Examples</a>
<a href="https://aws.github.io/aws-sdk-go-v2/docs/code-examples/">Code Examples</a>
</li>
<li class="breadcrumb-item active" aria-current="page">
<a href="http://localhost:1313/aws-sdk-go-v2/docs/code-examples/cloudwatch/" aria-disabled="true" class="btn-link disabled">Amazon CloudWatch</a>
<a href="https://aws.github.io/aws-sdk-go-v2/docs/code-examples/cloudwatch/" aria-disabled="true" class="btn-link disabled">Amazon CloudWatch</a>
</li>
</ol>
</nav>
Expand Down Expand Up @@ -549,7 +549,7 @@ <h5>


<div class="text-muted mt-5 pt-3 border-top">
Last modified January 14, 2021: <a href="https://github.com/aws/aws-sdk-go-v2/commit/6b77d0a0af50a1fdb5a265b225530fc50386a068">Added code examples from AWS SDK docs repo (#1015) (6b77d0a)</a>
Last modified January 14, 2021: <a href="https://github.com/aws/aws-sdk-go-v2/commit/6b77d0a0af50a1fdb5a265b225530fc50386a068">Added code examples from AWS SDK docs repo (#1015) (6b77d0a0af)</a>
</div>

</div>
Expand Down
Loading
Loading