Skip to content
Permalink
Browse files
fix(pubsublite)!: rename package ps to pscompat (api review) (#3569)
pscompat is more descriptive and indicates that this package is a compatibility API, designed to emulate the Cloud Pub/Sub API.
  • Loading branch information
tmdiep committed Jan 19, 2021
1 parent 93d0ebc commit 9d8fd2b5e6999657bcf324878732da801b805591
@@ -14,7 +14,7 @@
```go
import (
"cloud.google.com/go/pubsub"
"cloud.google.com/go/pubsublite/ps"
"cloud.google.com/go/pubsublite/pscompat"
)
```

@@ -25,7 +25,7 @@ To publish messages to a topic:
// Create a PublisherClient for topic1 in zone us-central1-b.
// See https://cloud.google.com/pubsub/lite/docs/locations for available zones.
const topic = "projects/project-id/locations/us-central1-b/topics/topic1",
publisher, err := ps.NewPublisherClient(ctx, ps.DefaultPublishSettings, topic)
publisher, err := pscompat.NewPublisherClient(ctx, pscompat.DefaultPublishSettings, topic)
if err != nil {
log.Fatal(err)
}
@@ -49,7 +49,7 @@ To receive messages for a subscription:
```go
// Create a SubscriberClient for subscription1 in zone us-central1-b.
const subscription = "projects/project-id/locations/us-central1-b/subscriptions/subscription1"
subscriber, err := ps.NewSubscriberClient(ctx, ps.DefaultReceiveSettings, subscription)
subscriber, err := pscompat.NewSubscriberClient(ctx, pscompat.DefaultReceiveSettings, subscription)
if err != nil {
log.Fatal(err)
}
@@ -67,17 +67,17 @@ and zones where Pub/Sub Lite is available.
Publishing
The pubsublite/ps subpackage contains clients for publishing and receiving
messages, which have similar interfaces to their Topic and Subscription
counterparts in the Cloud Pub/Sub library:
The pubsublite/pscompat subpackage contains clients for publishing and receiving
messages, which have similar interfaces to their pubsub.Topic and
pubsub.Subscription counterparts in the Cloud Pub/Sub library:
https://pkg.go.dev/cloud.google.com/go/pubsub.
Pub/Sub Lite uses gRPC streams extensively for high throughput. For more
differences, see https://pkg.go.dev/cloud.google.com/go/pubsublite/ps.
differences, see https://pkg.go.dev/cloud.google.com/go/pubsublite/pscompat.
To publish messages to a topic, first create a PublisherClient:
publisher, err := ps.NewPublisherClient(ctx, ps.DefaultPublishSettings, topicPath)
publisher, err := pscompat.NewPublisherClient(ctx, pscompat.DefaultPublishSettings, topicPath)
if err != nil {
// TODO: Handle error.
}
@@ -136,7 +136,7 @@ Receiving
To receive messages for a subscription, first create a SubscriberClient:
subscriber, err := ps.NewSubscriberClient(ctx, ps.DefaultReceiveSettings, subscriptionPath)
subscriber, err := pscompat.NewSubscriberClient(ctx, pscompat.DefaultReceiveSettings, subscriptionPath)
Messages are then consumed from a subscription via callback.
@@ -12,35 +12,37 @@
// See the License for the specific language governing permissions and

/*
Package ps contains clients for publishing and subscribing using the Google
Cloud Pub/Sub Lite service.
Package pscompat contains clients for publishing and subscribing using the
Pub/Sub Lite service.
If interfaces are defined, PublisherClient and SubscriberClient can be used as
The clients in this package are designed to compatible with the Cloud Pub/Sub
library: https://pkg.go.dev/cloud.google.com/go/pubsub. If interfaces are
defined by the client, PublisherClient and SubscriberClient can be used as
substitutions for pubsub.Topic.Publish() and pubsub.Subscription.Receive(),
respectively, from the pubsub package.
As noted in comments, the two services have some differences:
The Cloud Pub/Sub and Pub/Sub Lite services have some differences:
- Pub/Sub Lite does not support NACK for messages. By default, this will
terminate the SubscriberClient. A custom function can be provided for
ReceiveSettings.NackHandler to handle NACKed messages.
- Pub/Sub Lite has no concept of ack deadlines. Subscribers must ACK or NACK
- Pub/Sub Lite has no concept of ACK deadlines. Subscribers must ACK or NACK
every message received and can take as much time as they need to process the
message.
- Pub/Sub Lite PublisherClients and SubscriberClients can terminate when an
unretryable error occurs.
- Pub/Sub Lite PublisherClients and SubscriberClients can fail permanently
when an unretryable error occurs.
- Publishers and subscribers will be throttled if Pub/Sub Lite publish or
subscribe throughput limits are exceeded. Thus publishing can be more
sensitive to buffer overflow than Cloud Pub/Sub.
- Pub/Sub Lite utilizes bidirectional gRPC streams extensively to maximize
publish and subscribe throughput.
More information about Google Cloud Pub/Sub Lite is available at
More information about Pub/Sub Lite is available at
https://cloud.google.com/pubsub/lite.
Information about choosing between Google Cloud Pub/Sub vs Pub/Sub Lite is
available at https://cloud.google.com/pubsub/docs/choosing-pubsub-or-lite.
Information about choosing between Cloud Pub/Sub vs Pub/Sub Lite is available at
https://cloud.google.com/pubsub/docs/choosing-pubsub-or-lite.
See https://godoc.org/cloud.google.com/go for authentication, timeouts,
See https://pkg.go.dev/cloud.google.com/go for authentication, timeouts,
connection pooling and similar aspects of this package.
*/
package ps // import "cloud.google.com/go/pubsublite/ps"
package pscompat // import "cloud.google.com/go/pubsublite/pscompat"
@@ -11,21 +11,21 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and

package ps_test
package pscompat_test

import (
"context"
"fmt"

"cloud.google.com/go/pubsub"
"cloud.google.com/go/pubsublite/ps"
"cloud.google.com/go/pubsublite/pscompat"
)

func ExamplePublisherClient_Publish() {
ctx := context.Background()
const topic = "projects/my-project/locations/zone/topics/my-topic"
// NOTE: DefaultPublishSettings and empty PublishSettings{} are equivalent.
publisher, err := ps.NewPublisherClient(ctx, ps.DefaultPublishSettings, topic)
publisher, err := pscompat.NewPublisherClient(ctx, pscompat.DefaultPublishSettings, topic)
if err != nil {
// TODO: Handle error.
}
@@ -49,7 +49,7 @@ func ExamplePublisherClient_Publish() {
func ExamplePublisherClient_Error() {
ctx := context.Background()
const topic = "projects/my-project/locations/zone/topics/my-topic"
publisher, err := ps.NewPublisherClient(ctx, ps.DefaultPublishSettings, topic)
publisher, err := pscompat.NewPublisherClient(ctx, pscompat.DefaultPublishSettings, topic)
if err != nil {
// TODO: Handle error.
}
@@ -65,7 +65,7 @@ func ExamplePublisherClient_Error() {
id, err := r.Get(ctx)
if err != nil {
// TODO: Handle error.
if err == ps.ErrPublisherStopped {
if err == pscompat.ErrPublisherStopped {
fmt.Printf("Publisher client stopped due to error: %v\n", publisher.Error())
}
}
@@ -77,7 +77,7 @@ func ExampleSubscriberClient_Receive() {
ctx := context.Background()
const subscription = "projects/my-project/locations/zone/subscriptions/my-subscription"
// NOTE: DefaultReceiveSettings and empty ReceiveSettings{} are equivalent.
subscriber, err := ps.NewSubscriberClient(ctx, ps.DefaultReceiveSettings, subscription)
subscriber, err := pscompat.NewSubscriberClient(ctx, pscompat.DefaultReceiveSettings, subscription)
if err != nil {
// TODO: Handle error.
}
@@ -103,10 +103,10 @@ func ExampleSubscriberClient_Receive() {
func ExampleSubscriberClient_Receive_maxOutstanding() {
ctx := context.Background()
const subscription = "projects/my-project/locations/zone/subscriptions/my-subscription"
settings := ps.DefaultReceiveSettings
settings := pscompat.DefaultReceiveSettings
settings.MaxOutstandingMessages = 5
settings.MaxOutstandingBytes = 10e6
subscriber, err := ps.NewSubscriberClient(ctx, settings, subscription)
subscriber, err := pscompat.NewSubscriberClient(ctx, settings, subscription)
if err != nil {
// TODO: Handle error.
}
@@ -11,7 +11,7 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and

package ps
package pscompat

import (
"context"
@@ -11,7 +11,7 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and

package ps
package pscompat

import (
"encoding/base64"
@@ -11,7 +11,7 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and

package ps
package pscompat

import (
"log"
@@ -11,7 +11,7 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and

package ps
package pscompat

import (
"context"
@@ -11,7 +11,7 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and

package ps
package pscompat

import (
"context"
@@ -11,7 +11,7 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and

package ps
package pscompat

import (
"time"
@@ -135,12 +135,12 @@ func (s *PublishSettings) toWireSettings() wire.PublishSettings {
return wireSettings
}

// NackHandler is invoked when pubsub.Message.Nack() is called. Cloud Pub/Sub
// Lite does not have a concept of 'nack'. If the nack handler implementation
// returns nil, the message is acknowledged. If an error is returned, the
// NackHandler is invoked when pubsub.Message.Nack() is called. Pub/Sub Lite
// does not have a concept of 'nack'. If the nack handler implementation returns
// nil, the message is acknowledged. If an error is returned, the
// SubscriberClient will consider this a fatal error and terminate.
//
// In Cloud Pub/Sub Lite, only a single subscriber for a given subscription is
// In Pub/Sub Lite, only a single subscriber for a given subscription is
// connected to any partition at a time, and there is no other client that may
// be able to handle messages.
type NackHandler func(*pubsub.Message) error
@@ -11,7 +11,7 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and

package ps
package pscompat

import (
"testing"
@@ -11,7 +11,7 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and

package ps
package pscompat

import (
"context"
@@ -11,7 +11,7 @@
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and

package ps
package pscompat

import (
"context"

0 comments on commit 9d8fd2b

Please sign in to comment.