top

Package pubsub provides an easy way to publish and receive Google Cloud Pub/Sub messages, hiding the the details of the underlying server RPCs. Google Cloud Pub/Sub is a many-to-many, asynchronous messaging system that decouples senders and receivers.

Note: This package is experimental and may make backwards-incompatible changes.

More information about Google Cloud Pub/Sub is available at https://cloud.google.com/pubsub/docs

Publishing

Google Cloud Pub/Sub messages are published to topics. Topics may be created using the pubsub package like so:

topic, err := pubsubClient.CreateTopic(context.Background(), "topic-name")

Messages may then be published to a topic:

 msgIDs, err := topic.Publish(ctx, &pubsub.Message{
	Data: []byte("payload"),
 })

Receiving

To receive messages published to a topic, clients create subscriptions to the topic. There may be more than one subscription per topic; each message that is published to the topic will be delivered to all of its subscriptions.

Subsciptions may be created like so:

sub, err := pubsubClient.CreateSubscription(context.Background(), "sub-name", topic, 0, nil)

Messages are then consumed from a subscription via an iterator:

 // Construct the iterator
 it, err := sub.Pull(context.Background())
 if err != nil {
	// handle err ...
 }
 defer it.Stop()

 // Consume N messages
 for i := 0; i < N; i++ {
 	msg, err := it.Next()
 	if err == iterator.Done {
 		break
 	}
 	if err != nil {
 		// handle err ...
 		break
 	}

 	log.Print("got message: ", string(msg.Data))
 	msg.Done(true)
 }

The message iterator returns messages one at a time, fetching batches of messages behind the scenes as needed. Once client code has processed the message, it must call Message.Done, otherwise the message will eventually be redelivered. For more information and configuration options, see "Deadlines" below.

Note: It is possible for Messages to be redelivered, even if Message.Done has been called. Client code must be robust to multiple deliveries of messages.

Deadlines

The default pubsub deadlines are suitable for most use cases, but may be overridden. This section describes the tradeoffs that should be considered when overriding the defaults.

Behind the scenes, each message returned by the Pub/Sub server has an associated lease, known as an "ACK deadline". Unless a message is acknowledged within the ACK deadline, or the client requests that the ACK deadline be extended, the message will become elegible for redelivery. As a convenience, the pubsub package will automatically extend deadlines until either:

* Message.Done is called, or
* the "MaxExtension" period elapses from the time the message is fetched from the server.

The initial ACK deadline given to each messages defaults to 10 seconds, but may be overridden during subscription creation. Selecting an ACK deadline is a tradeoff between message redelivery latency and RPC volume. If the pubsub package fails to acknowledge or extend a message (e.g. due to unexpected termination of the process), a shorter ACK deadline will generally result in faster message redelivery by the Pub/Sub system. However, a short ACK deadline may also increase the number of deadline extension RPCs that the pubsub package sends to the server.

The default max extension period is DefaultMaxExtension, and can be overridden by passing a MaxExtension option to Subscription.Pull. Selecting a max extension period is a tradeoff between the speed at which client code must process messages, and the redelivery delay if messages fail to be acknowledged (e.g. because client code neglects to do so). Using a large MaxExtension increases the available time for client code to process messages. However, if the client code neglects to call Message.Done, a large MaxExtension will increase the delay before the message is redelivered.

Imported by 26 package(s)

  1. chromium.googlesource.com/external/github.com/luci/luci-go.git/common/tsmon/monitor
  2. chromium.googlesource.com/infra/infra.git/go/src/infra/monitoring/proxy
  3. chromium.googlesource.com/infra/infra.git/go/src/infra/monitoring/pubsubalerts/pull
  4. cloud.google.com/go/examples/pubsub/cmdline
  5. cloud.google.com/go/examples/pubsub/consumer
  6. github.com/GoogleCloudPlatform/golang-samples/docs/managed_vms/pubsub
  7. github.com/GoogleCloudPlatform/golang-samples/getting-started/bookshelf
  8. github.com/GoogleCloudPlatform/golang-samples/getting-started/bookshelf/app
  9. github.com/GoogleCloudPlatform/golang-samples/getting-started/bookshelf/pubsub_worker
  10. github.com/GoogleCloudPlatform/golang-samples/pubsub/subscriptions
  11. github.com/GoogleCloudPlatform/golang-samples/pubsub/topics
  12. github.com/NYTimes/gizmo/pubsub/gcp
  13. github.com/Nitecon/gcloud-golang/examples/pubsub/cmdline
  14. github.com/Nitecon/gcloud-golang/examples/pubsub/consumer
  15. github.com/erans/pipeline/gcloud
  16. github.com/foxish/contrib/mungegithub/webhooks-publisher
  17. github.com/kubernetes/contrib/mungegithub/webhooks-publisher
  18. github.com/luci/luci-go/common/gcloud/pubsub
  19. github.com/luci/luci-go/common/tsmon/monitor
  20. github.com/luci/luci-go/logdog/appengine/coordinator
  21. github.com/luci/luci-go/logdog/client/butler/output/logdog
  22. github.com/luci/luci-go/logdog/client/butler/output/pubsub
  23. github.com/micro/go-plugins/broker/googlepubsub
  24. github.com/st3v/go-plugins/broker/googlepubsub
  25. github.com/tortuoise/golang-samples/getting-started/bookshelf
  26. k8s.io/contrib/mungegithub/webhooks-publisher

Imported only in test by 4 package(s)

  1. github.com/GoogleCloudPlatform/gcloud-golang/pubsub
  2. github.com/Nitecon/gcloud-golang/pubsub
  3. github.com/jba/google-cloud-go/pubsub
  4. github.com/tortuoise/gcloud-golang/pubsub

Imports 10 package(s)

  1. google.golang.org/genproto/googleapis/pubsub/v1
  2. google.golang.org/grpc
  3. cloud.google.com/go/pubsub/apiv1
  4. golang.org/x/net/context
  5. google.golang.org/api/iterator
  6. github.com/golang/protobuf/ptypes
  7. cloud.google.com/go/iam
  8. google.golang.org/api/option
  9. google.golang.org/api/support/bundler
  10. google.golang.org/grpc/codes

Test imports 1 package(s)

  1. cloud.google.com/go/internal/testutil