Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
docs(pubsublite): update comments for regional topics (#5202)
Update comments to indicate that topics may belong to a region or zone.

Release-As: 1.2.2
  • Loading branch information
tmdiep committed Feb 3, 2022
1 parent 95d3609 commit 7805468
Show file tree
Hide file tree
Showing 9 changed files with 86 additions and 72 deletions.
36 changes: 19 additions & 17 deletions pubsublite/admin.go
Expand Up @@ -31,9 +31,10 @@ var (
)

// AdminClient provides admin operations for Pub/Sub Lite resources within a
// Google Cloud region. The zone component of resource paths must be within this
// region. See https://cloud.google.com/pubsub/lite/docs/locations for the list
// of zones where Pub/Sub Lite is available.
// Google Cloud region. The location (region or zone) component of resource
// paths must be within this region.
// See https://cloud.google.com/pubsub/lite/docs/locations for the list of
// regions and zones where Pub/Sub Lite is available.
//
// An AdminClient may be shared by multiple goroutines.
type AdminClient struct {
Expand Down Expand Up @@ -90,7 +91,7 @@ func (ac *AdminClient) UpdateTopic(ctx context.Context, config TopicConfigToUpda
}

// DeleteTopic deletes a topic. A valid topic path has the format:
// "projects/PROJECT_ID/locations/ZONE/topics/TOPIC_ID".
// "projects/PROJECT_ID/locations/LOCATION/topics/TOPIC_ID".
func (ac *AdminClient) DeleteTopic(ctx context.Context, topic string) error {
if _, err := wire.ParseTopicPath(topic); err != nil {
return err
Expand All @@ -99,7 +100,7 @@ func (ac *AdminClient) DeleteTopic(ctx context.Context, topic string) error {
}

// Topic retrieves the configuration of a topic. A valid topic path has the
// format: "projects/PROJECT_ID/locations/ZONE/topics/TOPIC_ID".
// format: "projects/PROJECT_ID/locations/LOCATION/topics/TOPIC_ID".
func (ac *AdminClient) Topic(ctx context.Context, topic string) (*TopicConfig, error) {
if _, err := wire.ParseTopicPath(topic); err != nil {
return nil, err
Expand All @@ -113,7 +114,7 @@ func (ac *AdminClient) Topic(ctx context.Context, topic string) (*TopicConfig, e

// TopicPartitionCount returns the number of partitions for a topic. A valid
// topic path has the format:
// "projects/PROJECT_ID/locations/ZONE/topics/TOPIC_ID".
// "projects/PROJECT_ID/locations/LOCATION/topics/TOPIC_ID".
func (ac *AdminClient) TopicPartitionCount(ctx context.Context, topic string) (int, error) {
if _, err := wire.ParseTopicPath(topic); err != nil {
return 0, err
Expand All @@ -127,7 +128,7 @@ func (ac *AdminClient) TopicPartitionCount(ctx context.Context, topic string) (i

// TopicSubscriptions retrieves the list of subscription paths for a topic.
// A valid topic path has the format:
// "projects/PROJECT_ID/locations/ZONE/topics/TOPIC_ID".
// "projects/PROJECT_ID/locations/LOCATION/topics/TOPIC_ID".
func (ac *AdminClient) TopicSubscriptions(ctx context.Context, topic string) *SubscriptionPathIterator {
if _, err := wire.ParseTopicPath(topic); err != nil {
return &SubscriptionPathIterator{err: err}
Expand All @@ -137,8 +138,9 @@ func (ac *AdminClient) TopicSubscriptions(ctx context.Context, topic string) *Su
}
}

// Topics retrieves the list of topic configs for a given project and zone.
// A valid parent path has the format: "projects/PROJECT_ID/locations/ZONE".
// Topics retrieves the list of topic configs for a given project and location
// (region or zone). A valid parent path has the format:
// "projects/PROJECT_ID/locations/LOCATION".
func (ac *AdminClient) Topics(ctx context.Context, parent string) *TopicIterator {
if _, err := wire.ParseLocationPath(parent); err != nil {
return &TopicIterator{err: err}
Expand Down Expand Up @@ -223,7 +225,7 @@ func (ac *AdminClient) UpdateSubscription(ctx context.Context, config Subscripti
// SeekSubscription initiates an out-of-band seek for a subscription to a
// specified target, which may be timestamps or named positions within the
// message backlog. A valid subscription path has the format:
// "projects/PROJECT_ID/locations/ZONE/subscriptions/SUBSCRIPTION_ID".
// "projects/PROJECT_ID/locations/LOCATION/subscriptions/SUBSCRIPTION_ID".
//
// See https://cloud.google.com/pubsub/lite/docs/seek for more information.
func (ac *AdminClient) SeekSubscription(ctx context.Context, subscription string, target SeekTarget, opts ...SeekSubscriptionOption) (*SeekSubscriptionOperation, error) {
Expand All @@ -240,7 +242,7 @@ func (ac *AdminClient) SeekSubscription(ctx context.Context, subscription string
}

// DeleteSubscription deletes a subscription. A valid subscription path has the
// format: "projects/PROJECT_ID/locations/ZONE/subscriptions/SUBSCRIPTION_ID".
// format: "projects/PROJECT_ID/locations/LOCATION/subscriptions/SUBSCRIPTION_ID".
func (ac *AdminClient) DeleteSubscription(ctx context.Context, subscription string) error {
if _, err := wire.ParseSubscriptionPath(subscription); err != nil {
return err
Expand All @@ -250,7 +252,7 @@ func (ac *AdminClient) DeleteSubscription(ctx context.Context, subscription stri

// Subscription retrieves the configuration of a subscription. A valid
// subscription name has the format:
// "projects/PROJECT_ID/locations/ZONE/subscriptions/SUBSCRIPTION_ID".
// "projects/PROJECT_ID/locations/LOCATION/subscriptions/SUBSCRIPTION_ID".
func (ac *AdminClient) Subscription(ctx context.Context, subscription string) (*SubscriptionConfig, error) {
if _, err := wire.ParseSubscriptionPath(subscription); err != nil {
return nil, err
Expand All @@ -263,8 +265,8 @@ func (ac *AdminClient) Subscription(ctx context.Context, subscription string) (*
}

// Subscriptions retrieves the list of subscription configs for a given project
// and zone. A valid parent path has the format:
// "projects/PROJECT_ID/locations/ZONE".
// and location (region or zone). A valid parent path has the format:
// "projects/PROJECT_ID/locations/LOCATION".
func (ac *AdminClient) Subscriptions(ctx context.Context, parent string) *SubscriptionIterator {
if _, err := wire.ParseLocationPath(parent); err != nil {
return &SubscriptionIterator{err: err}
Expand Down Expand Up @@ -411,8 +413,8 @@ type TopicPathIterator struct {
}

// Next returns the next topic path, which has format:
// "projects/PROJECT_ID/locations/ZONE/topics/TOPIC_ID". The
// second return value will be iterator.Done if there are no more topic paths.
// "projects/PROJECT_ID/locations/LOCATION/topics/TOPIC_ID". The second return
// value will be iterator.Done if there are no more topic paths.
func (sp *TopicPathIterator) Next() (string, error) {
if sp.err != nil {
return "", sp.err
Expand All @@ -432,7 +434,7 @@ type SubscriptionPathIterator struct {
}

// Next returns the next subscription path, which has format:
// "projects/PROJECT_ID/locations/ZONE/subscriptions/SUBSCRIPTION_ID". The
// "projects/PROJECT_ID/locations/LOCATION/subscriptions/SUBSCRIPTION_ID". The
// second return value will be iterator.Done if there are no more subscription
// paths.
func (sp *SubscriptionPathIterator) Next() (string, error) {
Expand Down
21 changes: 11 additions & 10 deletions pubsublite/config.go
Expand Up @@ -34,13 +34,14 @@ const InfiniteRetention = time.Duration(-1)
// about how topics are configured.
type TopicConfig struct {
// The full path of the topic, in the format:
// "projects/PROJECT_ID/locations/ZONE/topics/TOPIC_ID".
// "projects/PROJECT_ID/locations/LOCATION/topics/TOPIC_ID".
//
// - PROJECT_ID: The project ID (e.g. "my-project") or the project number
// (e.g. "987654321") can be provided.
// - ZONE: The Google Cloud zone (e.g. "us-central1-a") where the topic is
// located. See https://cloud.google.com/pubsub/lite/docs/locations for the
// list of zones where Pub/Sub Lite is available.
// - LOCATION: The Google Cloud region (e.g. "us-central1") or zone
// (e.g. "us-central1-a") where the topic is located.
// See https://cloud.google.com/pubsub/lite/docs/locations for the list of
// regions and zones where Pub/Sub Lite is available.
// - TOPIC_ID: The ID of the topic (e.g. "my-topic"). See
// https://cloud.google.com/pubsub/docs/admin#resource_names for information
// about valid topic IDs.
Expand Down Expand Up @@ -128,7 +129,7 @@ func protoToTopicConfig(t *pb.Topic) (*TopicConfig, error) {
// TopicConfigToUpdate specifies the properties to update for a topic.
type TopicConfigToUpdate struct {
// The full path of the topic to update, in the format:
// "projects/PROJECT_ID/locations/ZONE/topics/TOPIC_ID". Required.
// "projects/PROJECT_ID/locations/LOCATION/topics/TOPIC_ID". Required.
Name string

// If non-zero, will update the number of partitions in the topic.
Expand Down Expand Up @@ -234,19 +235,19 @@ const (
// information about how subscriptions are configured.
type SubscriptionConfig struct {
// The full path of the subscription, in the format:
// "projects/PROJECT_ID/locations/ZONE/subscriptions/SUBSCRIPTION_ID".
// "projects/PROJECT_ID/locations/LOCATION/subscriptions/SUBSCRIPTION_ID".
//
// - PROJECT_ID: The project ID (e.g. "my-project") or the project number
// (e.g. "987654321") can be provided.
// - ZONE: The Google Cloud zone (e.g. "us-central1-a") of the corresponding
// topic.
// - LOCATION: The Google Cloud region (e.g. "us-central1") or zone
// (e.g. "us-central1-a") of the corresponding topic.
// - SUBSCRIPTION_ID: The ID of the subscription (e.g. "my-subscription"). See
// https://cloud.google.com/pubsub/docs/admin#resource_names for information
// about valid subscription IDs.
Name string

// The path of the topic that this subscription is attached to, in the format:
// "projects/PROJECT_ID/locations/ZONE/topics/TOPIC_ID". This cannot be
// "projects/PROJECT_ID/locations/LOCATION/topics/TOPIC_ID". This cannot be
// changed after creation.
Topic string

Expand Down Expand Up @@ -282,7 +283,7 @@ func protoToSubscriptionConfig(s *pb.Subscription) *SubscriptionConfig {
// subscription.
type SubscriptionConfigToUpdate struct {
// The full path of the subscription to update, in the format:
// "projects/PROJECT_ID/locations/ZONE/subscriptions/SUBSCRIPTION_ID".
// "projects/PROJECT_ID/locations/LOCATION/subscriptions/SUBSCRIPTION_ID".
// Required.
Name string

Expand Down
11 changes: 11 additions & 0 deletions pubsublite/doc.go
Expand Up @@ -184,5 +184,16 @@ client that may be able to handle messages.
See https://cloud.google.com/pubsub/lite/docs/subscribing for more information
about receiving messages.
gRPC Connection Pools
Pub/Sub Lite utilizes gRPC streams extensively. gRPC allows a maximum of 100
streams per connection. Internally, the library uses a default connection pool
size of 8, which supports up to 800 topic partitions. To alter the connection
pool size, pass a ClientOption to pscompat.NewPublisherClient and
pscompat.NewSubscriberClient:
pub, err := pscompat.NewPublisherClient(ctx, topicPath, option.WithGRPCConnectionPool(10))
*/
package pubsublite // import "cloud.google.com/go/pubsublite"
56 changes: 28 additions & 28 deletions pubsublite/example_test.go
Expand Up @@ -22,22 +22,22 @@ import (
"google.golang.org/api/iterator"
)

// This example demonstrates how to create a new topic.
// See https://cloud.google.com/pubsub/lite/docs/topics for more information
// about how Pub/Sub Lite topics are configured.
// See https://cloud.google.com/pubsub/lite/docs/locations for the list of zones
// where Pub/Sub Lite is available.
// This example demonstrates how to create a new topic. Topics may be regional
// or zonal. See https://cloud.google.com/pubsub/lite/docs/topics for more
// information about how Pub/Sub Lite topics are configured.
// See https://cloud.google.com/pubsub/lite/docs/locations for the list of
// regions and zones where Pub/Sub Lite is available.
func ExampleAdminClient_CreateTopic() {
ctx := context.Background()
// NOTE: region must correspond to the zone of the topic.
// NOTE: resources must be located within this region.
admin, err := pubsublite.NewAdminClient(ctx, "region")
if err != nil {
// TODO: Handle error.
}

const gib = 1 << 30
topicConfig := pubsublite.TopicConfig{
Name: "projects/my-project/locations/zone/topics/my-topic",
Name: "projects/my-project/locations/region-or-zone/topics/my-topic",
PartitionCount: 2, // Must be at least 1.
PublishCapacityMiBPerSec: 4, // Must be 4-16 MiB/s.
SubscribeCapacityMiBPerSec: 8, // Must be 4-32 MiB/s.
Expand All @@ -53,14 +53,14 @@ func ExampleAdminClient_CreateTopic() {

func ExampleAdminClient_UpdateTopic() {
ctx := context.Background()
// NOTE: region must correspond to the zone of the topic.
// NOTE: resources must be located within this region.
admin, err := pubsublite.NewAdminClient(ctx, "region")
if err != nil {
// TODO: Handle error.
}

updateConfig := pubsublite.TopicConfigToUpdate{
Name: "projects/my-project/locations/zone/topics/my-topic",
Name: "projects/my-project/locations/region-or-zone/topics/my-topic",
PartitionCount: 3, // Only increases currently supported.
PublishCapacityMiBPerSec: 8,
SubscribeCapacityMiBPerSec: 16,
Expand All @@ -74,28 +74,28 @@ func ExampleAdminClient_UpdateTopic() {

func ExampleAdminClient_DeleteTopic() {
ctx := context.Background()
// NOTE: region must correspond to the zone of the topic.
// NOTE: resources must be located within this region.
admin, err := pubsublite.NewAdminClient(ctx, "region")
if err != nil {
// TODO: Handle error.
}

const topic = "projects/my-project/locations/zone/topics/my-topic"
const topic = "projects/my-project/locations/region-or-zone/topics/my-topic"
if err := admin.DeleteTopic(ctx, topic); err != nil {
// TODO: Handle error.
}
}

func ExampleAdminClient_Topics() {
ctx := context.Background()
// NOTE: region must correspond to the zone below.
// NOTE: resources must be located within this region.
admin, err := pubsublite.NewAdminClient(ctx, "region")
if err != nil {
// TODO: Handle error.
}

// List the configs of all topics in the given zone for the project.
it := admin.Topics(ctx, "projects/my-project/locations/zone")
// List the configs of all topics in the given region or zone for the project.
it := admin.Topics(ctx, "projects/my-project/locations/region-or-zone")
for {
topicConfig, err := it.Next()
if err == iterator.Done {
Expand All @@ -110,14 +110,14 @@ func ExampleAdminClient_Topics() {

func ExampleAdminClient_TopicSubscriptions() {
ctx := context.Background()
// NOTE: region must correspond to the zone of the topic.
// NOTE: resources must be located within this region.
admin, err := pubsublite.NewAdminClient(ctx, "region")
if err != nil {
// TODO: Handle error.
}

// List the paths of all subscriptions of a topic.
const topic = "projects/my-project/locations/zone/topics/my-topic"
const topic = "projects/my-project/locations/region-or-zone/topics/my-topic"
it := admin.TopicSubscriptions(ctx, topic)
for {
subscriptionPath, err := it.Next()
Expand All @@ -136,15 +136,15 @@ func ExampleAdminClient_TopicSubscriptions() {
// information about how subscriptions are configured.
func ExampleAdminClient_CreateSubscription() {
ctx := context.Background()
// NOTE: region must correspond to the zone of the topic and subscription.
// NOTE: resources must be located within this region.
admin, err := pubsublite.NewAdminClient(ctx, "region")
if err != nil {
// TODO: Handle error.
}

subscriptionConfig := pubsublite.SubscriptionConfig{
Name: "projects/my-project/locations/zone/subscriptions/my-subscription",
Topic: "projects/my-project/locations/zone/topics/my-topic",
Name: "projects/my-project/locations/region-or-zone/subscriptions/my-subscription",
Topic: "projects/my-project/locations/region-or-zone/topics/my-topic",
// Do not wait for a published message to be successfully written to storage
// before delivering it to subscribers.
DeliveryRequirement: pubsublite.DeliverImmediately,
Expand All @@ -157,14 +157,14 @@ func ExampleAdminClient_CreateSubscription() {

func ExampleAdminClient_UpdateSubscription() {
ctx := context.Background()
// NOTE: region must correspond to the zone of the subscription.
// NOTE: resources must be located within this region.
admin, err := pubsublite.NewAdminClient(ctx, "region")
if err != nil {
// TODO: Handle error.
}

updateConfig := pubsublite.SubscriptionConfigToUpdate{
Name: "projects/my-project/locations/zone/subscriptions/my-subscription",
Name: "projects/my-project/locations/region-or-zone/subscriptions/my-subscription",
// Deliver a published message to subscribers after it has been successfully
// written to storage.
DeliveryRequirement: pubsublite.DeliverAfterStored,
Expand All @@ -177,13 +177,13 @@ func ExampleAdminClient_UpdateSubscription() {

func ExampleAdminClient_SeekSubscription() {
ctx := context.Background()
// NOTE: region must correspond to the zone of the subscription.
// NOTE: resources must be located within this region.
admin, err := pubsublite.NewAdminClient(ctx, "region")
if err != nil {
// TODO: Handle error.
}

const subscription = "projects/my-project/locations/zone/subscriptions/my-subscription"
const subscription = "projects/my-project/locations/region-or-zone/subscriptions/my-subscription"
seekOp, err := admin.SeekSubscription(ctx, subscription, pubsublite.Beginning)
if err != nil {
// TODO: Handle error.
Expand All @@ -204,28 +204,28 @@ func ExampleAdminClient_SeekSubscription() {

func ExampleAdminClient_DeleteSubscription() {
ctx := context.Background()
// NOTE: region must correspond to the zone of the subscription.
// NOTE: resources must be located within this region.
admin, err := pubsublite.NewAdminClient(ctx, "region")
if err != nil {
// TODO: Handle error.
}

const subscription = "projects/my-project/locations/zone/subscriptions/my-subscription"
const subscription = "projects/my-project/locations/region-or-zone/subscriptions/my-subscription"
if err := admin.DeleteSubscription(ctx, subscription); err != nil {
// TODO: Handle error.
}
}

func ExampleAdminClient_Subscriptions() {
ctx := context.Background()
// NOTE: region must correspond to the zone below.
// NOTE: resources must be located within this region.
admin, err := pubsublite.NewAdminClient(ctx, "region")
if err != nil {
// TODO: Handle error.
}

// List the configs of all subscriptions in the given zone for the project.
it := admin.Subscriptions(ctx, "projects/my-project/locations/zone")
// List the configs of all subscriptions in the given region or zone for the project.
it := admin.Subscriptions(ctx, "projects/my-project/locations/region-or-zone")
for {
subscriptionConfig, err := it.Next()
if err == iterator.Done {
Expand Down
2 changes: 1 addition & 1 deletion pubsublite/internal/wire/resources.go
Expand Up @@ -63,7 +63,7 @@ func ParseLocationPath(input string) (LocationPath, error) {
parts := locPathRE.FindStringSubmatch(input)
if len(parts) < 3 {
return LocationPath{}, fmt.Errorf("pubsublite: invalid location path %q. valid format is %q",
input, "projects/PROJECT_ID/locations/ZONE")
input, "projects/PROJECT_ID/locations/LOCATION")
}
return LocationPath{Project: parts[1], Location: parts[2]}, nil
}
Expand Down
2 changes: 1 addition & 1 deletion pubsublite/operations.go
Expand Up @@ -86,7 +86,7 @@ type SeekSubscriptionResult struct{}
type OperationMetadata struct {
// The target of the operation. For example, targets of seeks are
// subscriptions, structured like:
// "projects/PROJECT_ID/locations/ZONE/subscriptions/SUBSCRIPTION_ID"
// "projects/PROJECT_ID/locations/LOCATION/subscriptions/SUBSCRIPTION_ID"
Target string

// The verb describing the kind of operation.
Expand Down

0 comments on commit 7805468

Please sign in to comment.