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.

pubsublite/README.md

@@ -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)
 }

pubsublite/doc.go

@@ -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.
 

pubsublite/ps/doc.go → pubsublite/pscompat/doc.go

@@ -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"

pubsublite/ps/example_test.go → pubsublite/pscompat/example_test.go

@@ -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.
 	}

pubsublite/ps/integration_test.go → pubsublite/pscompat/integration_test.go

@@ -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"

pubsublite/ps/message.go → pubsublite/pscompat/message.go

@@ -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"

pubsublite/ps/message_test.go → pubsublite/pscompat/message_test.go

@@ -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"

pubsublite/ps/publisher.go → pubsublite/pscompat/publisher.go

@@ -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"

pubsublite/ps/publisher_test.go → pubsublite/pscompat/publisher_test.go

@@ -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"

pubsublite/ps/settings.go → pubsublite/pscompat/settings.go

@@ -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

pubsublite/ps/settings_test.go → pubsublite/pscompat/settings_test.go

@@ -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"

pubsublite/ps/subscriber.go → pubsublite/pscompat/subscriber.go

@@ -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"

pubsublite/ps/subscriber_test.go → pubsublite/pscompat/subscriber_test.go

@@ -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"