pubsublite

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Oct 29, 2020 License: Apache-2.0 Imports: 23 Imported by: 4

README

Cloud Pub/Sub Lite GoDoc

This library is under development and will not provide a delightful user experience until v1.0.0 has been released.

Documentation

Overview

Package pubsublite provides an interface for publishing and receiving messages using Google Pub/Sub Lite.

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

This library is under development and will not provdie a delightful user experience until v1.0.0 has been released.

Index

Constants

View Source 
const (
	// UnspecifiedDeliveryRequirement represents and unset delivery requirement.
	UnspecifiedDeliveryRequirement = DeliveryRequirement(pb.Subscription_DeliveryConfig_DELIVERY_REQUIREMENT_UNSPECIFIED)

	// DeliverImmediately means the server will not not wait for a published
	// message to be successfully written to storage before delivering it to
	// subscribers.
	DeliverImmediately = DeliveryRequirement(pb.Subscription_DeliveryConfig_DELIVER_IMMEDIATELY)

	// DeliverAfterStored means the server will not deliver a published message to
	// subscribers until the message has been successfully written to storage.
	// This will result in higher end-to-end latency, but consistent delivery.
	DeliverAfterStored = DeliveryRequirement(pb.Subscription_DeliveryConfig_DELIVER_AFTER_STORED)
)
View Source 
const (
	// MaxPublishRequestCount is the maximum number of messages that can be
	// batched in a single publish request.
	MaxPublishRequestCount = 1000

	// MaxPublishMessageBytes is the maximum allowed serialized size of a single
	// Pub/Sub message in bytes.
	MaxPublishMessageBytes = 1000000

	// MaxPublishRequestBytes is the maximum allowed serialized size of a single
	// publish request (containing a batch of messages) in bytes.
	MaxPublishRequestBytes = 3500000
)
View Source 
const InfiniteRetention = time.Duration(-1)

InfiniteRetention is a sentinel used in topic configs to denote an infinite retention duration (i.e. retain messages as long as there is available storage).

Variables

View Source 
var DefaultPublishSettings = PublishSettings{
	DelayThreshold: 10 * time.Millisecond,
	CountThreshold: 100,
	ByteThreshold:  1e6,
	Timeout:        60 * time.Second,

	BufferedByteLimit: 1 << 30,
}

DefaultPublishSettings holds the default values for PublishSettings.

View Source 
var (
	// ErrOverflow indicates that the publish buffers have overflowed. See
	// comments for PublishSettings.BufferedByteLimit.
	ErrOverflow = errors.New("pubsublite: client-side publish buffers have overflowed")
)

Functions

func ZoneToRegion 

func ZoneToRegion(zone string) (string, error)

ZoneToRegion returns the region that the given zone is in.

Types

type AdminClient 

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

AdminClient provides admin operations for Google Pub/Sub Lite resources within a Google Cloud region. An AdminClient may be shared by multiple goroutines.

func NewAdminClient 

func NewAdminClient(ctx context.Context, region string, opts ...option.ClientOption) (*AdminClient, error)

NewAdminClient creates a new Cloud Pub/Sub Lite client to perform admin operations for resources within a given region. See https://cloud.google.com/pubsub/lite/docs/locations for the list of regions and zones where Google Pub/Sub Lite is available.

func (*AdminClient) Close 

func (ac *AdminClient) Close() error

Close releases any resources held by the client when it is no longer required. If the client is available for the lifetime of the program, then Close need not be called at exit.

func (*AdminClient) CreateSubscription 

func (ac *AdminClient) CreateSubscription(ctx context.Context, config SubscriptionConfig) (*SubscriptionConfig, error)

CreateSubscription creates a new subscription from the given config.

func (*AdminClient) CreateTopic 

func (ac *AdminClient) CreateTopic(ctx context.Context, config TopicConfig) (*TopicConfig, error)

CreateTopic creates a new topic from the given config.

func (*AdminClient) DeleteSubscription 

func (ac *AdminClient) DeleteSubscription(ctx context.Context, subscription SubscriptionPath) error

DeleteSubscription deletes a subscription.

func (*AdminClient) DeleteTopic 

func (ac *AdminClient) DeleteTopic(ctx context.Context, topic TopicPath) error

DeleteTopic deletes a topic.

func (*AdminClient) Subscription 

func (ac *AdminClient) Subscription(ctx context.Context, subscription SubscriptionPath) (*SubscriptionConfig, error)

Subscription retrieves the configuration of a subscription.

func (*AdminClient) Subscriptions 

func (ac *AdminClient) Subscriptions(ctx context.Context, location LocationPath) *SubscriptionIterator

Subscriptions retrieves the list of subscription configs for a given project and zone.

func (*AdminClient) Topic 

func (ac *AdminClient) Topic(ctx context.Context, topic TopicPath) (*TopicConfig, error)

Topic retrieves the configuration of a topic.

func (*AdminClient) TopicPartitions 

func (ac *AdminClient) TopicPartitions(ctx context.Context, topic TopicPath) (int, error)

TopicPartitions returns the number of partitions for a topic.

func (*AdminClient) TopicSubscriptions 

func (ac *AdminClient) TopicSubscriptions(ctx context.Context, topic TopicPath) (*SubscriptionPathIterator, error)

TopicSubscriptions retrieves the list of subscription paths for a topic.

func (*AdminClient) Topics 

func (ac *AdminClient) Topics(ctx context.Context, location LocationPath) *TopicIterator

Topics retrieves the list of topic configs for a given project and zone.

func (*AdminClient) UpdateSubscription 

func (ac *AdminClient) UpdateSubscription(ctx context.Context, config SubscriptionConfigToUpdate) (*SubscriptionConfig, error)

UpdateSubscription updates an existing subscription from the given config and returns the new subscription config.

func (*AdminClient) UpdateTopic 

func (ac *AdminClient) UpdateTopic(ctx context.Context, config TopicConfigToUpdate) (*TopicConfig, error)

UpdateTopic updates an existing topic from the given config and returns the new topic config.

type AttributeValues 

type AttributeValues [][]byte

AttributeValues is a slice of strings.

type DeliveryRequirement 

type DeliveryRequirement int32

DeliveryRequirement specifies when a subscription should send messages to subscribers relative to persistence in storage.

type LocationPath 

type LocationPath struct {
	// A Google Cloud project. The project ID (e.g. "my-project") or the project
	// number (e.g. "987654321") can be provided.
	Project string

	// A Google Cloud zone, for example "us-central1-a".
	// See https://cloud.google.com/pubsub/lite/docs/locations for the list of
	// zones where Google Pub/Sub Lite is available.
	Zone string
}

LocationPath stores a path consisting of a project and zone.

func (LocationPath) String 

func (l LocationPath) String() string

type Message 

type Message struct {
	// Data is the actual data in the message.
	Data []byte

	// Attributes can be used to label the message. A key may have multiple
	// values.
	Attributes map[string]AttributeValues

	// EventTime is an optional, user-specified event time for this message.
	EventTime time.Time

	// OrderingKey identifies related messages for which publish order should
	// be respected. Messages with the same ordering key are published to the
	// same topic partition and subscribers will receive the messages in order.
	// If the ordering key is empty, the message will be sent to an arbitrary
	// partition.
	OrderingKey []byte
}

Message represents a Pub/Sub message.

type PublishSettings 

type PublishSettings struct {
	// Publish a non-empty batch after this delay has passed. Must be > 0.
	DelayThreshold time.Duration

	// Publish a batch when it has this many messages. Must be > 0. The maximum is
	// MaxPublishRequestCount.
	CountThreshold int

	// Publish a batch when its size in bytes reaches this value. Must be > 0. The
	// maximum is MaxPublishRequestBytes.
	ByteThreshold int

	// The maximum time that the client will attempt to establish a publish stream
	// connection to the server. Must be > 0.
	//
	// The timeout is exceeded, the publisher will terminate with the last error
	// that occurred while trying to reconnect. Note that if the timeout duration
	// is long, ErrOverflow may occur first.
	Timeout time.Duration

	// The maximum number of bytes that the publisher will keep in memory before
	// returning ErrOverflow. Must be > 0.
	//
	// Note that Pub/Sub Lite topics are provisioned a publishing throughput
	// capacity, per partition, shared by all publisher clients. Setting a large
	// buffer size can mitigate transient publish spikes. However, consistently
	// attempting to publish messages at a much higher rate than the publishing
	// throughput capacity can cause the buffers to overflow. For more
	// information, see https://cloud.google.com/pubsub/lite/docs/topics.
	BufferedByteLimit int
}

PublishSettings control the batching of published messages.

type SubscriptionConfig 

type SubscriptionConfig struct {
	// The full path of a subscription.
	Name SubscriptionPath

	// The name of the topic this subscription is attached to. This cannot be
	// changed after creation.
	Topic TopicPath

	// Whether a message should be delivered to subscribers immediately after it
	// has been published or after it has been successfully written to storage.
	DeliveryRequirement DeliveryRequirement
}

SubscriptionConfig describes the properties of a Google Pub/Sub Lite subscription, which is attached to a topic. See https://cloud.google.com/pubsub/lite/docs/subscriptions for more information about how subscriptions are configured.

type SubscriptionConfigToUpdate 

type SubscriptionConfigToUpdate struct {
	// The full path of the subscription to update. Required.
	Name SubscriptionPath

	// If non-zero, updates the message delivery requirement.
	DeliveryRequirement DeliveryRequirement
}

SubscriptionConfigToUpdate specifies the properties to update for a subscription.

type SubscriptionIterator 

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

SubscriptionIterator is an iterator that returns a list of subscription configs.

func (*SubscriptionIterator) Next 

func (s *SubscriptionIterator) Next() (*SubscriptionConfig, error)

Next returns the next subscription config. The second return value will be iterator.Done if there are no more subscription configs.

type SubscriptionPath 

type SubscriptionPath struct {
	// A Google Cloud project. The project ID (e.g. "my-project") or the project
	// number (e.g. "987654321") can be provided.
	Project string

	// A Google Cloud zone. An example zone is "us-central1-a".
	// See https://cloud.google.com/pubsub/lite/docs/locations for the list of
	// zones where Google Pub/Sub Lite is available.
	Zone string

	// The ID of the Google Pub/Sub Lite subscription, for example
	// "my-subscription-name".
	// See https://cloud.google.com/pubsub/docs/admin#resource_names for more
	// information.
	SubscriptionID string
}

SubscriptionPath stores the full path of a Google Pub/Sub Lite subscription. See https://cloud.google.com/pubsub/lite/docs/subscriptions for more information.

func (SubscriptionPath) String 

func (s SubscriptionPath) String() string

type SubscriptionPathIterator 

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

SubscriptionPathIterator is an iterator that returns a list of subscription paths.

func (*SubscriptionPathIterator) Next 

func (sp *SubscriptionPathIterator) Next() (SubscriptionPath, error)

Next returns the next subscription path. The second return value will be iterator.Done if there are no more subscription paths.

type TopicConfig 

type TopicConfig struct {
	// The full path of a topic.
	Name TopicPath

	// The number of partitions in the topic. Must be at least 1. Cannot be
	// changed after creation.
	PartitionCount int

	// Publish throughput capacity per partition in MiB/s.
	// Must be >= 4 and <= 16.
	PublishCapacityMiBPerSec int

	// Subscribe throughput capacity per partition in MiB/s.
	// Must be >= 4 and <= 32.
	SubscribeCapacityMiBPerSec int

	// The provisioned storage, in bytes, per partition. If the number of bytes
	// stored in any of the topic's partitions grows beyond this value, older
	// messages will be dropped to make room for newer ones, regardless of the
	// value of `RetentionDuration`. Must be > 0.
	PerPartitionBytes int64

	// How long a published message is retained. If set to `InfiniteRetention`,
	// messages will be retained as long as the bytes retained for each partition
	// is below `PerPartitionBytes`. Otherwise, must be > 0.
	RetentionDuration time.Duration
}

TopicConfig describes the properties of a Google Pub/Sub Lite topic. See https://cloud.google.com/pubsub/lite/docs/topics for more information about how topics are configured.

type TopicConfigToUpdate 

type TopicConfigToUpdate struct {
	// The full path of the topic to update. Required.
	Name TopicPath

	// If non-zero, will update the publish throughput capacity per partition.
	PublishCapacityMiBPerSec int

	// If non-zero, will update the subscribe throughput capacity per partition.
	SubscribeCapacityMiBPerSec int

	// If non-zero, will update the provisioned storage per partition.
	PerPartitionBytes int64

	// If specified, will update how long a published message is retained. To
	// clear a retention duration (i.e. retain messages as long as there is
	// available storage), set this to `InfiniteRetention`.
	RetentionDuration optional.Duration
}

TopicConfigToUpdate specifies the properties to update for a topic.

type TopicIterator 

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

TopicIterator is an iterator that returns a list of topic configs.

func (*TopicIterator) Next 

func (t *TopicIterator) Next() (*TopicConfig, error)

Next returns the next topic config. The second return value will be iterator.Done if there are no more topic configs.

type TopicPath 

type TopicPath struct {
	// A Google Cloud project. The project ID (e.g. "my-project") or the project
	// number (e.g. "987654321") can be provided.
	Project string

	// A Google Cloud zone, for example "us-central1-a".
	// See https://cloud.google.com/pubsub/lite/docs/locations for the list of
	// zones where Google Pub/Sub Lite is available.
	Zone string

	// The ID of the Google Pub/Sub Lite topic, for example "my-topic-name".
	// See https://cloud.google.com/pubsub/docs/admin#resource_names for more
	// information.
	TopicID string
}

TopicPath stores the full path of a Google Pub/Sub Lite topic. See https://cloud.google.com/pubsub/lite/docs/topics for more information.

func (TopicPath) String 

func (t TopicPath) String() string

Source Files

View all Source files

Directories

Path Synopsis
Use of Context The ctx passed to NewClient is used for authentication requests and for creating the underlying connection, but is not used for subsequent calls.
 Use of Context The ctx passed to NewClient is used for authentication requests and for creating the underlying connection, but is not used for subsequent calls.

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.