awssnssqs

package
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 29, 2019 License: Apache-2.0 Imports: 22 Imported by: 55

Documentation

Overview

Package awssnssqs provides two implementations of pubsub.Topic, one that sends messages to AWS SNS (Simple Notification Service), and one that sends messages to SQS (Simple Queuing Service). It also provides an implementation of pubsub.Subscription that receives messages from SQS.

URLs

For pubsub.OpenTopic, awssnssqs registers for the scheme "awssns" for an SNS topic, and "awssqs" for an SQS topic. For pubsub.OpenSubscription, it registers for the scheme "awssqs".

The default URL opener will use an AWS session with the default credentials and configuration; see https://docs.aws.amazon.com/sdk-for-go/api/aws/session/ for more details. To customize the URL opener, or for more details on the URL format, see URLOpener. See https://gocloud.dev/concepts/urls/ for background information.

Message Delivery Semantics

AWS SQS supports at-least-once semantics; applications must call Message.Ack after processing a message, or it will be redelivered. See https://godoc.org/gocloud.dev/pubsub#hdr-At_most_once_and_At_least_once_Delivery for more background.

Escaping

Go CDK supports all UTF-8 strings; to make this work with providers lacking full UTF-8 support, strings must be escaped (during writes) and unescaped (during reads). The following escapes are required for awssnssqs:

  • Metadata keys: Characters other than "a-zA-z0-9_-.", and additionally "." when it's at the start of the key or the previous character was ".", are escaped using "__0x<hex>__". These characters were determined by experimentation.
  • Metadata values: Escaped using URL encoding.
  • Message body: AWS SNS/SQS only supports UTF-8 strings. See the BodyBase64Encoding enum in TopicOptions for strategies on how to send non-UTF-8 message bodies. By default, non-UTF-8 message bodies are base64 encoded.

As

awssnssqs exposes the following types for As:

  • Topic: *sns.SNS (for OpenSNSTopic) or *sqs.SQS (for OpenSQSTopic)
  • Subscription: *sqs.SQS
  • Message: *sqs.Message
  • Message.BeforeSend: *sns.PublishInput (for OpenSNSTopic) or *sqs.SendMessageInput (for OpenSQSTopic)
  • Error: awserror.Error
Example (OpenSNSTopicFromURL) 
package main

import (
	"context"
	"log"

	"gocloud.dev/pubsub"
)

func main() {
	// This example is used in https://gocloud.dev/howto/pubsub/publish/#sns

	// import _ "gocloud.dev/pubsub/awssnssqs"

	// Variables set up elsewhere:
	ctx := context.Background()

	const topicARN = "arn:aws:sns:us-east-2:123456789012:mytopic"
	topic, err := pubsub.OpenTopic(ctx, "awssns://"+topicARN+"?region=us-east-2")
	if err != nil {
		log.Fatal(err)
	}
	defer topic.Shutdown(ctx)
}

Output:
Example (OpenSQSTopicFromURL) 
package main

import (
	"context"
	"log"

	"gocloud.dev/pubsub"
)

func main() {
	// This example is used in https://gocloud.dev/howto/pubsub/publish/#sqs

	// import _ "gocloud.dev/pubsub/awssnssqs"

	// Variables set up elsewhere:
	ctx := context.Background()

	// https://docs.aws.amazon.com/sdk-for-net/v2/developer-guide/QueueURL.html
	const queueURL = "https://sqs.us-east-2.amazonaws.com/123456789012/myqueue"
	topic, err := pubsub.OpenTopic(ctx, "awssqs://"+queueURL+"?region=us-east-2")
	if err != nil {
		log.Fatal(err)
	}
	defer topic.Shutdown(ctx)
}

Output:
Example (OpenSubscriptionFromURL) 
package main

import (
	"context"
	"log"

	"gocloud.dev/pubsub"
)

func main() {
	// This example is used in https://gocloud.dev/howto/pubsub/subscribe/#sns

	// import _ "gocloud.dev/pubsub/awssnssqs"

	// Variables set up elsewhere:
	ctx := context.Background()

	// pubsub.OpenSubscription creates a *pubsub.Subscription from a URL.
	// This URL will open the subscription with the URL
	// "https://sqs.us-east-2.amazonaws.com/123456789012/myqueue".
	subscription, err := pubsub.OpenSubscription(ctx,
		"awssqs://sqs.us-east-2.amazonaws.com/123456789012/"+
			"myqueue?region=us-east-2")
	if err != nil {
		log.Fatal(err)
	}
	defer subscription.Shutdown(ctx)
}

Output:

Index

Examples

Constants

View Source 
const SNSScheme = "awssns"

SNSScheme is the URL scheme for pubsub.OpenTopic (for an SNS topic) that awssnssqs registers its URLOpeners under on pubsub.DefaultMux.

View Source 
const SQSScheme = "awssqs"

SQSScheme is the URL scheme for pubsub.OpenTopic (for an SQS topic) and for pubsub.OpenSubscription that awssnssqs registers its URLOpeners under on pubsub.DefaultMux.

Variables

View Source 
var Set = wire.NewSet(
	SubscriptionOptions{},
	TopicOptions{},
	URLOpener{},
)

Set holds Wire providers for this package.

Functions

func OpenSNSTopic added in v0.14.0 

func OpenSNSTopic(ctx context.Context, sess client.ConfigProvider, topicARN string, opts *TopicOptions) *pubsub.Topic

OpenSNSTopic opens a topic that sends to the SNS topic with the given Amazon Resource Name (ARN).

Example 
package main

import (
	"context"
	"log"

	"github.com/aws/aws-sdk-go/aws"
	"github.com/aws/aws-sdk-go/aws/session"
	"gocloud.dev/pubsub/awssnssqs"
)

func main() {
	// This example is used in https://gocloud.dev/howto/pubsub/publish/#sns-ctor

	// Variables set up elsewhere:
	ctx := context.Background()

	// Establish an AWS session.
	// See https://docs.aws.amazon.com/sdk-for-go/api/aws/session/ for more info.
	// The region must match the region for the SNS topic "mytopic".
	sess, err := session.NewSession(&aws.Config{
		Region: aws.String("us-east-2"),
	})
	if err != nil {
		log.Fatal(err)
	}

	// Create a *pubsub.Topic.
	const topicARN = "arn:aws:sns:us-east-2:123456789012:mytopic"
	topic := awssnssqs.OpenSNSTopic(ctx, sess, topicARN, nil)
	defer topic.Shutdown(ctx)
}

Output:

func OpenSQSTopic added in v0.14.0 

func OpenSQSTopic(ctx context.Context, sess client.ConfigProvider, qURL string, opts *TopicOptions) *pubsub.Topic

OpenSQSTopic opens a topic that sends to the SQS topic with the given SQS queue URL.

Example 
package main

import (
	"context"
	"log"

	"github.com/aws/aws-sdk-go/aws"
	"github.com/aws/aws-sdk-go/aws/session"
	"gocloud.dev/pubsub/awssnssqs"
)

func main() {
	// This example is used in https://gocloud.dev/howto/pubsub/publish/#sqs-ctor

	// Variables set up elsewhere:
	ctx := context.Background()

	// Establish an AWS session.
	// See https://docs.aws.amazon.com/sdk-for-go/api/aws/session/ for more info.
	// The region must match the region for the SQS queue "myqueue".
	sess, err := session.NewSession(&aws.Config{
		Region: aws.String("us-east-2"),
	})
	if err != nil {
		log.Fatal(err)
	}

	// Create a *pubsub.Topic.
	const queueURL = "https://sqs.us-east-2.amazonaws.com/123456789012/myqueue"
	topic := awssnssqs.OpenSQSTopic(ctx, sess, queueURL, nil)
	defer topic.Shutdown(ctx)
}

Output:

func OpenSubscription 

func OpenSubscription(ctx context.Context, sess client.ConfigProvider, qURL string, opts *SubscriptionOptions) *pubsub.Subscription

OpenSubscription opens a subscription based on AWS SQS for the given SQS queue URL. The queue is assumed to be subscribed to some SNS topic, though there is no check for this.

Example 
package main

import (
	"context"
	"log"

	"github.com/aws/aws-sdk-go/aws"
	"github.com/aws/aws-sdk-go/aws/session"
	"gocloud.dev/pubsub/awssnssqs"
)

func main() {
	// This example is used in https://gocloud.dev/howto/pubsub/subscribe/#sns-ctor

	// Variables set up elsewhere:
	ctx := context.Background()

	// Establish an AWS session.
	// See https://docs.aws.amazon.com/sdk-for-go/api/aws/session/ for more info.
	// The region must match the region for "MyQueue".
	sess, err := session.NewSession(&aws.Config{
		Region: aws.String("us-east-2"),
	})
	if err != nil {
		log.Fatal(err)
	}

	// Construct a *pubsub.Subscription.
	// https://docs.aws.amazon.com/sdk-for-net/v2/developer-guide/QueueURL.html
	const queueURL = "https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue"
	subscription := awssnssqs.OpenSubscription(ctx, sess, queueURL, nil)
	defer subscription.Shutdown(ctx)
}

Output:

func OpenTopic 

func OpenTopic(ctx context.Context, sess client.ConfigProvider, topicARN string, opts *TopicOptions) *pubsub.Topic

OpenTopic is a shortcut for OpenSNSTopic, provided for backwards compatibility.

Types

type BodyBase64Encoding 

type BodyBase64Encoding int

BodyBase64Encoding is an enum of strategies for when to base64 message bodies. 

const (
	// NonUTF8Only means that message bodies that are valid UTF-8 encodings are
	// sent as-is. Invalid UTF-8 message bodies are base64 encoded, and a
	// MessageAttribute with key "base64encoded" is added to the message.
	// When receiving messages, the "base64encoded" attribute is used to determine
	// whether to base64 decode, and is then filtered out.
	NonUTF8Only BodyBase64Encoding = 0
	// Always means that all message bodies are base64 encoded.
	// A MessageAttribute with key "base64encoded" is added to the message.
	// When receiving messages, the "base64encoded" attribute is used to determine
	// whether to base64 decode, and is then filtered out.
	Always BodyBase64Encoding = 1
	// Never means that message bodies are never base64 encoded. Non-UTF-8
	// bytes in message bodies may be modified by SNS/SQS.
	Never BodyBase64Encoding = 2
)

type SubscriptionOptions 

type SubscriptionOptions struct{}

SubscriptionOptions will contain configuration for subscriptions.

type TopicOptions 

type TopicOptions struct {
	// BodyBase64Encoding determines when message bodies are base64 encoded.
	// The default is NonUTF8Only.
	BodyBase64Encoding BodyBase64Encoding
}

TopicOptions contains configuration options for topics.

type URLOpener 

type URLOpener struct {
	// ConfigProvider configures the connection to AWS.
	ConfigProvider client.ConfigProvider

	// TopicOptions specifies the options to pass to OpenTopic.
	TopicOptions TopicOptions
	// SubscriptionOptions specifies the options to pass to OpenSubscription.
	SubscriptionOptions SubscriptionOptions
}

URLOpener opens AWS SNS/SQS URLs like "awssns://sns-topic-arn" for SNS topics or "awssqs://sqs-queue-url" for SQS topics and subscriptions.

For SNS topics, the URL's host+path is used as the topic Amazon Resource Name (ARN).

For SQS topics and subscriptions, the URL's host+path is prefixed with "https://" to create the queue URL.

See gocloud.dev/aws/ConfigFromURLParams for supported query parameters that affect the default AWS session.

func (*URLOpener) OpenSubscriptionURL 

func (o *URLOpener) OpenSubscriptionURL(ctx context.Context, u *url.URL) (*pubsub.Subscription, error)

OpenSubscriptionURL opens a pubsub.Subscription based on u.

func (*URLOpener) OpenTopicURL 

func (o *URLOpener) OpenTopicURL(ctx context.Context, u *url.URL) (*pubsub.Topic, error)

OpenTopicURL opens a pubsub.Topic based on u.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.