gocloud.dev: gocloud.dev/pubsub/gcppubsub Index | Examples | Files

package gcppubsub

import "gocloud.dev/pubsub/gcppubsub"

Package gcppubsub provides a pubsub implementation that uses GCP PubSub. Use OpenTopic to construct a *pubsub.Topic, and/or OpenSubscription to construct a *pubsub.Subscription.

URLs

For pubsub.OpenTopic and pubsub.OpenSubscription, gcppubsub registers for the scheme "gcppubsub". The default URL opener will creating a connection using use default credentials from the environment, as described in https://cloud.google.com/docs/authentication/production. 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

GCP Pub/Sub 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.

As

gcppubsub exposes the following types for As:

- Topic: *raw.PublisherClient
- Subscription: *raw.SubscriberClient
- Message.BeforeSend: *pb.PubsubMessage
- Message: *pb.PubsubMessage
- Error: *google.golang.org/grpc/status.Status

Code:

// This example is used in https://gocloud.dev/howto/pubsub/subscribe/#gcp

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

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

subscription, err := pubsub.OpenSubscription(ctx,
    "gcppubsub://my-project/my-subscription")
if err != nil {
    log.Fatal(err)
}
defer subscription.Shutdown(ctx)

Code:

// This example is used in https://gocloud.dev/howto/pubsub/publish/#gcp

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

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

topic, err := pubsub.OpenTopic(ctx, "gcppubsub://myproject/mytopic")
if err != nil {
    log.Fatal(err)
}
defer topic.Shutdown(ctx)

Index

Examples

Package Files

gcppubsub.go

Constants

const Scheme = "gcppubsub"

Scheme is the URL scheme gcppubsub registers its URLOpeners under on pubsub.DefaultMux.

Variables

var Set = wire.NewSet(
    Dial,
    PublisherClient,
    SubscriberClient,
    SubscriptionOptions{},
    TopicOptions{},
    URLOpener{},
)

Set holds Wire providers for this package.

func Dial Uses

func Dial(ctx context.Context, ts gcp.TokenSource) (*grpc.ClientConn, func(), error)

Dial opens a gRPC connection to the GCP Pub Sub API.

The second return value is a function that can be called to clean up the connection opened by Dial.

func OpenSubscription Uses

func OpenSubscription(client *raw.SubscriberClient, proj gcp.ProjectID, subscriptionName string, opts *SubscriptionOptions) *pubsub.Subscription

OpenSubscription returns a *pubsub.Subscription backed by an existing GCP PubSub subscription subscriptionName in the given projectID. See the package documentation for an example.

Code:

// This example is used in https://gocloud.dev/howto/pubsub/subscribe/#gcp-ctor

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

// Your GCP credentials.
// See https://cloud.google.com/docs/authentication/production
// for more info on alternatives.
creds, err := gcp.DefaultCredentials(ctx)
if err != nil {
    log.Fatal(err)
}
// Get the project ID from the credentials (required by OpenSubscription).
projectID, err := gcp.DefaultProjectID(creds)
if err != nil {
    log.Fatal(err)
}

// Open a gRPC connection to the GCP Pub/Sub API.
conn, cleanup, err := gcppubsub.Dial(ctx, creds.TokenSource)
if err != nil {
    log.Fatal(err)
}
defer cleanup()

// Construct a SubscriberClient using the connection.
subClient, err := gcppubsub.SubscriberClient(ctx, conn)
if err != nil {
    log.Fatal(err)
}
defer subClient.Close()

// Construct a *pubsub.Subscription.
subscription := gcppubsub.OpenSubscription(
    subClient, projectID, "example-subscription", nil)
defer subscription.Shutdown(ctx)

func OpenTopic Uses

func OpenTopic(client *raw.PublisherClient, proj gcp.ProjectID, topicName string, opts *TopicOptions) *pubsub.Topic

OpenTopic returns a *pubsub.Topic backed by an existing GCP PubSub topic topicName in the given projectID. See the package documentation for an example.

Code:

// This example is used in https://gocloud.dev/howto/pubsub/publish/#gcp-ctor

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

// Your GCP credentials.
// See https://cloud.google.com/docs/authentication/production
// for more info on alternatives.
creds, err := gcp.DefaultCredentials(ctx)
if err != nil {
    log.Fatal(err)
}
// Get the project ID from the credentials (required by OpenTopic).
projectID, err := gcp.DefaultProjectID(creds)
if err != nil {
    log.Fatal(err)
}
// Open a gRPC connection to the GCP Pub/Sub API.
conn, cleanup, err := gcppubsub.Dial(ctx, creds.TokenSource)
if err != nil {
    log.Fatal(err)
}
defer cleanup()

// Construct a PublisherClient using the connection.
pubClient, err := gcppubsub.PublisherClient(ctx, conn)
if err != nil {
    log.Fatal(err)
}
defer pubClient.Close()

// Construct a *pubsub.Topic.
topic := gcppubsub.OpenTopic(pubClient, projectID, "example-topic", nil)
defer topic.Shutdown(ctx)

func PublisherClient Uses

func PublisherClient(ctx context.Context, conn *grpc.ClientConn) (*raw.PublisherClient, error)

PublisherClient returns a *raw.PublisherClient that can be used in OpenTopic.

func SubscriberClient Uses

func SubscriberClient(ctx context.Context, conn *grpc.ClientConn) (*raw.SubscriberClient, error)

SubscriberClient returns a *raw.SubscriberClient that can be used in OpenSubscription.

type SubscriptionOptions Uses

type SubscriptionOptions struct{}

SubscriptionOptions will contain configuration for subscriptions.

type TopicOptions Uses

type TopicOptions struct{}

TopicOptions will contain configuration for topics.

type URLOpener Uses

type URLOpener struct {
    // Conn must be set to a non-nil ClientConn authenticated with
    // Cloud Pub/Sub scope or equivalent.
    Conn *grpc.ClientConn

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

URLOpener opens GCP Pub/Sub URLs like "gcppubsub://myproject/mytopic" for topics or "gcppubsub://myproject/mysub" for subscriptions.

The URL's host is used as the projectID, and the URL's path (with the leading "/" trimmed) is used as the topic or subscription name.

No URL parameters are supported.

func (*URLOpener) OpenSubscriptionURL Uses

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

OpenSubscriptionURL opens a pubsub.Subscription based on u.

func (*URLOpener) OpenTopicURL Uses

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

OpenTopicURL opens a pubsub.Topic based on u.

Package gcppubsub imports 21 packages (graph) and is imported by 10 packages. Updated 2019-05-16. Refresh now. Tools for package owners.