pubsub

package
v0.0.0-...-246a77c Latest Latest
Warning

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

 Go to latest Published: Mar 24, 2016 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package pubsub contains a Google Cloud Pub/Sub client.

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

Example (Auth) 
// Initialize an authorized context with Google Developers Console
// JSON key. Read the google package examples to learn more about
// different authorization flows you can use.
// http://godoc.org/github.com/tetrafolium/oauth2/google
jsonKey, err := ioutil.ReadFile("/path/to/json/keyfile.json")
if err != nil {
	log.Fatal(err)
}
conf, err := google.JWTConfigFromJSON(
	jsonKey,
	pubsub.ScopeCloudPlatform,
	pubsub.ScopePubSub,
)
if err != nil {
	log.Fatal(err)
}
ctx := cloud.NewContext("project-id", conf.Client(oauth2.NoContext))
// See the other samples to learn how to use the context.
return ctx

Output:

Index

Examples

Constants

View Source 
const (
	// ScopePubSub grants permissions to view and manage Pub/Sub
	// topics and subscriptions.
	ScopePubSub = "https://www.googleapis.com/auth/pubsub"

	// ScopeCloudPlatform grants permissions to view and manage your data
	// across Google Cloud Platform services.
	ScopeCloudPlatform = "https://www.googleapis.com/auth/cloud-platform"
)
View Source 
const DefaultMaxExtension = 10 * time.Minute

The default period for which to automatically extend Message acknowledgement deadlines.

View Source 
const DefaultMaxPrefetch = 100

The default maximum number of messages that are prefetched from the server.

View Source 
const MaxPublishBatchSize = 1000

Variables

This section is empty.

Functions

func Ack deprecated 

func Ack(ctx context.Context, sub string, id ...string) error

Ack acknowledges one or more Pub/Sub messages on the specified subscription.

Deprecated: Call Message.Done on a Message returned by Iterator.Next instead.

func CreateSub deprecated 

func CreateSub(ctx context.Context, name string, topic string, deadline time.Duration, endpoint string) error

CreateSub creates a Pub/Sub subscription on the backend.

Deprecated: Use TopicHandle.Subscribe instead.

A subscription should subscribe to an existing topic.

The messages that haven't acknowledged will be pushed back to the subscription again when the default acknowledgement deadline is reached. You can override the default deadline by providing a non-zero deadline. Deadline must not be specified to precision greater than one second.

As new messages are being queued on the subscription, you may recieve push notifications regarding to the new arrivals. To receive notifications of new messages in the queue, specify an endpoint callback URL. If endpoint is an empty string the backend will not notify the client of new messages.

If the subscription already exists an error will be returned.

func CreateTopic deprecated 

func CreateTopic(ctx context.Context, name string) error

CreateTopic creates a new topic with the specified name on the backend.

Deprecated: Use Client.NewTopic instead.

It will return an error if topic already exists.

func DeleteSub deprecated 

func DeleteSub(ctx context.Context, name string) error

DeleteSub deletes the subscription.

Deprecated: Use SubscriptionHandle.Delete instead.

func DeleteTopic deprecated 

func DeleteTopic(ctx context.Context, name string) error

DeleteTopic deletes the specified topic.

Deprecated: Use TopicHandle.Delete instead.

func ModifyAckDeadline deprecated 

func ModifyAckDeadline(ctx context.Context, sub string, id string, deadline time.Duration) error

ModifyAckDeadline modifies the acknowledgement deadline for the messages retrieved from the specified subscription. Deadline must not be specified to precision greater than one second.

Deprecated: Use Subscription.Pull instead, which automatically extends ack deadlines.

func ModifyPushEndpoint deprecated 

func ModifyPushEndpoint(ctx context.Context, sub, endpoint string) error

ModifyPushEndpoint modifies the URL endpoint to modify the resource to handle push notifications coming from the Pub/Sub backend for the specified subscription.

Deprecated: Use SubscriptionHandle.ModifyPushConfig instead.

func Publish deprecated 

func Publish(ctx context.Context, topic string, msgs ...*Message) ([]string, error)

Publish publishes messages to the topic's subscribers. It returns message IDs upon success.

Deprecated: Use TopicHandle.Publish instead.

Example 
ctx := Example_auth()

msgIDs, err := pubsub.Publish(ctx, "topic1", &pubsub.Message{
	Data: []byte("hello world"),
})
if err != nil {
	log.Fatal(err)
}
log.Printf("Published a message with a message id: %s\n", msgIDs[0])

Output:

func SubExists deprecated 

func SubExists(ctx context.Context, name string) (bool, error)

SubExists returns true if subscription exists.

Deprecated: Use SubscriptionHandle.Exists instead.

func TopicExists deprecated 

func TopicExists(ctx context.Context, name string) (bool, error)

TopicExists returns true if a topic exists with the specified name.

Deprecated: Use TopicHandle.Exists instead.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a Google Pub/Sub client, which may be used to perform Pub/Sub operations with a project. It must be constructed via NewClient.

func NewClient 

func NewClient(ctx context.Context, projectID string, opts ...cloud.ClientOption) (*Client, error)

NewClient creates a new PubSub client.

func (*Client) NewTopic 

func (c *Client) NewTopic(ctx context.Context, name string) (*TopicHandle, error)

NewTopic creates a new topic. The specified topic name must start with a letter, and contain only letters ([A-Za-z]), numbers ([0-9]), dashes (-), underscores (_), periods (.), tildes (~), plus (+) or percent signs (%). It must be between 3 and 255 characters in length, and must not start with "goog". If the topic already exists an error will be returned.

func (*Client) Subscription 

func (c *Client) Subscription(name string) *SubscriptionHandle

Subscription creates a reference to a subscription.

func (*Client) Subscriptions 

func (c *Client) Subscriptions(ctx context.Context) ([]*SubscriptionHandle, error)

Subscriptions lists all of the subscriptions for the client's project.

func (*Client) Topic 

func (c *Client) Topic(name string) *TopicHandle

Topic creates a reference to a topic.

func (*Client) Topics 

func (c *Client) Topics(ctx context.Context) ([]*TopicHandle, error)

Topics lists all of the topics for the client's project.

type Iterator 

type Iterator struct {
	// contains filtered or unexported fields
}

func (*Iterator) Next 

func (it *Iterator) Next() (*Message, error)

Next returns the next Message to be processed. The caller must call Done on the returned Message when finished with it. Once Stop has been called, subsequent calls to Next will return io.EOF.

func (*Iterator) Stop 

func (it *Iterator) Stop()

Client code must call Stop on an Iterator when finished with it. Stop will block until Done has been called on all Messages that have been returned by Next, or until the context with which the Iterator was created is cancelled or exceeds its deadline. Stop need only be called once, but may be called multiple times from multiple goroutines.

type Message 

type Message struct {
	// ID identifies this message.
	// This ID is assigned by the server and is populated for Messages obtained from a subscription.
	// It is otherwise ignored.
	ID string

	// Data is the actual data in the message.
	Data []byte

	// Attributes represents the key-value pairs the current message
	// is labelled with.
	Attributes map[string]string

	// AckID is the identifier to acknowledge this message.
	AckID string
	// contains filtered or unexported fields
}

Message represents a Pub/Sub message.

func Pull deprecated 

func Pull(ctx context.Context, sub string, n int) ([]*Message, error)

Pull pulls up to n messages from the subscription. n must not be larger than 100.

Deprecated: Use Subscription.Pull instead

Example 
ctx := Example_auth()

// E.g. c.CreateSub("sub1", "topic1", time.Duration(0), "")
msgs, err := pubsub.Pull(ctx, "sub1", 1)
if err != nil {
	log.Fatal(err)
}
log.Printf("New message arrived: %v\n", msgs[0])
if err := pubsub.Ack(ctx, "sub1", msgs[0].AckID); err != nil {
	log.Fatal(err)
}
log.Println("Acknowledged message")

Output:

func PullWait deprecated 

func PullWait(ctx context.Context, sub string, n int) ([]*Message, error)

PullWait pulls up to n messages from the subscription. If there are no messages in the queue, it will wait until at least one message is available or a timeout occurs. n must not be larger than 100.

Deprecated: Use Subscription.Pull instead

func (*Message) Done 

func (m *Message) Done(ack bool)

Done completes the processing of a Message that was returned from an Iterator. ack indicates whether the message should be acknowledged. Client code must call Done when finished for each Message returned by an iterator. Done may only be called on Messages returned by an iterator. If message acknowledgement fails, the Message will be redelivered. Calls to Done have no effect after the first call.

type PullOption 

type PullOption interface {
	// contains filtered or unexported methods
}

A PullOption is an optional argument to SubscriptionHandle.Pull.

func MaxExtension 

func MaxExtension(duration time.Duration) PullOption

MaxExtension returns a PullOption that limits how long acks deadlines are extended for.

An Iterator will automatically extend the ack deadline of all fetched Messages for the duration specified. Automatic deadline extension may be disabled by specifying a duration of 0.

func MaxPrefetch 

func MaxPrefetch(num int) PullOption

MaxPrefetch returns a PullOption that limits Message prefetching.

For performance reasons, the pubsub library may prefetch a pool of Messages to be returned serially from Iterator.Next. MaxPrefetch is used to limit the the size of this pool.

If num is less than 1, it will be treated as if it were 1.

type PushConfig 

type PushConfig struct {
	// A URL locating the endpoint to which messages should be pushed.
	Endpoint string

	// Endpoint configuration attributes. See https://cloud.google.com/pubsub/reference/rest/v1/projects.subscriptions#PushConfig.FIELDS.attributes for more details.
	Attributes map[string]string
}

PushConfig contains configuration for subscriptions that operate in push mode.

type SubscriptionConfig 

type SubscriptionConfig struct {
	Topic      *TopicHandle
	PushConfig PushConfig

	// The default maximum time after a subscriber receives a message
	// before the subscriber should acknowledge the message.  Note:
	// messages which are obtained via an Iterator need not be acknowledged
	// within this deadline, as the deadline will be automatically
	// extended.
	AckDeadline time.Duration
}

Subscription config contains the configuration of a subscription.

type SubscriptionHandle 

type SubscriptionHandle struct {
	// contains filtered or unexported fields
}

SubscriptionHandle is a reference to a PubSub subscription.

func (*SubscriptionHandle) Config 

func (s *SubscriptionHandle) Config(ctx context.Context) (*SubscriptionConfig, error)

Config fetches the current configuration for the subscription.

func (*SubscriptionHandle) Delete 

func (s *SubscriptionHandle) Delete(ctx context.Context) error

Delete deletes the subscription.

func (*SubscriptionHandle) Exists 

func (s *SubscriptionHandle) Exists(ctx context.Context) (bool, error)

Exists reports whether the subscription exists on the server.

func (*SubscriptionHandle) ModifyPushConfig 

func (s *SubscriptionHandle) ModifyPushConfig(ctx context.Context, conf *PushConfig) error

ModifyPushConfig updates the endpoint URL and other attributes of a push subscription.

func (*SubscriptionHandle) Name 

func (s *SubscriptionHandle) Name() string

Name returns the globally unique name for the subscription.

func (*SubscriptionHandle) Pull 

func (s *SubscriptionHandle) Pull(ctx context.Context, opts ...PullOption) (*Iterator, error)

Pull returns an Iterator that can be used to fetch Messages. The Iterator will automatically extend the ack deadline of all fetched Messages, for the period specified by DefaultMaxExtension. This may be overriden by supplying a MaxExtension pull option.

If ctx is cancelled or exceeds its deadline, outstanding acks or deadline extensions will fail.

The caller must call Stop on the Iterator once finished with it.

type TopicHandle 

type TopicHandle struct {
	// contains filtered or unexported fields
}

TopicHandle is a reference to a PubSub topic.

func (*TopicHandle) Delete 

func (t *TopicHandle) Delete(ctx context.Context) error

Delete deletes the topic.

func (*TopicHandle) Exists 

func (t *TopicHandle) Exists(ctx context.Context) (bool, error)

Exists reports whether the topic exists on the server.

func (*TopicHandle) Name 

func (t *TopicHandle) Name() string

Name returns the globally unique name for the topic.

func (*TopicHandle) Publish 

func (t *TopicHandle) Publish(ctx context.Context, msgs ...*Message) ([]string, error)

Publish publishes the supplied Messages to the topic. If successful, the server-assigned message IDs are returned in the same order as the supplied Messages. At most MaxPublishBatchSize messages may be supplied.

func (*TopicHandle) Subscribe 

func (t *TopicHandle) Subscribe(ctx context.Context, name string, ackDeadline time.Duration, pushConfig *PushConfig) (*SubscriptionHandle, error)

Subscribe creates a new subscription to the topic. The specified subscription name must start with a letter, and contain only letters ([A-Za-z]), numbers ([0-9]), dashes (-), underscores (_), periods (.), tildes (~), plus (+) or percent signs (%). It must be between 3 and 255 characters in length, and must not start with "goog".

ackDeadline is the maximum time after a subscriber receives a message before the subscriber should acknowledge the message. It must be between 10 and 600 seconds (inclusive), and is rounded down to the nearest second. If the provided ackDeadline is 0, then the default value of 10 seconds is used. Note: messages which are obtained via an Iterator need not be acknowledged within this deadline, as the deadline will be automatically extended.

pushConfig may be set to configure this subscription for push delivery.

If the subscription already exists an error will be returned.

func (*TopicHandle) Subscriptions 

func (t *TopicHandle) Subscriptions(ctx context.Context) ([]*SubscriptionHandle, error)

Subscriptions lists the subscriptions for this topic.

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.