// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and

/*
Package pubsublite provides an easy way to publish and receive messages using
Google Cloud Pub/Sub Lite.

Google Cloud Pub/Sub is designed to provide reliable, many-to-many, asynchronous
messaging between applications. Publisher applications can send messages to a
topic and other applications can subscribe to that topic to receive the
messages. By decoupling senders and receivers, Google Cloud Pub/Sub allows
developers to communicate between independently written applications.

Compared to Google Cloud Pub/Sub, Pub/Sub Lite provides partitioned zonal data
storage with predefined throughput and storage capacity. Guidance on how to
choose between Google Cloud Pub/Sub and Pub/Sub Lite is available at
https://cloud.google.com/pubsub/docs/choosing-pubsub-or-lite.

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

See https://godoc.org/cloud.google.com/go for authentication, timeouts,
connection pooling and similar aspects of this package.

Note: This library is in ALPHA. Backwards-incompatible changes may be made
before stable v1.0.0 is released.


Creating Topics

Messages are published to topics. Cloud Pub/Sub Lite topics may be created like
so (error handling omitted for brevity):

  topicPath := pubsublite.TopicPath{
    Project: "project-id",
    Zone:    "zone",
    TopicID: "topic-id",
  }
  topicConfig := pubsublite.TopicConfig{
    Name:                       topicPath,
    PartitionCount:             1,
    PublishCapacityMiBPerSec:   4,
    SubscribeCapacityMiBPerSec: 4,
    PerPartitionBytes:          30 * 1024 * 1024 * 1024,  // 30 GiB
    RetentionDuration:          pubsublite.InfiniteRetention,
  }

  region, err := pubsublite.ZoneToRegion(topicPath.Zone)
  adminClient, err := pubsublite.NewAdminClient(ctx, region)
  _, err = adminClient.CreateTopic(ctx, topicConfig)

See https://cloud.google.com/pubsub/lite/docs/topics for more information about
how Cloud Pub/Sub Lite topics are configured.


Publishing

The pubsublite/ps subpackage contains clients for publishing and receiving
messages, which have similar interfaces to their Topic and Subscription
counterparts in the pubsub package. Cloud Pub/Sub Lite uses gRPC streams
extensively for high throughput. For more differences, see
https://godoc.org/cloud.google.com/go/pubsublite/ps.

To publish messages to a topic, first create a PublisherClient:

  publisher, err := ps.NewPublisherClient(ctx, ps.DefaultPublishSettings, topicPath)

Then call Publish:

  // Note: result is a pubsub.PublishResult
  result := publisher.Publish(ctx, &pubsub.Message{Data: []byte("payload")})

Publish queues the message for publishing and returns immediately. When enough
messages have accumulated, or enough time has elapsed, the batch of messages is
sent to the Cloud Pub/Sub Lite service. Thresholds for batching can be
configured in PublishSettings.

Publish returns a PublishResult, which behaves like a future: its Get method
blocks until the message has been sent (or has failed to be sent) to the
service. Once you've finishing publishing, call Stop to flush all messages to
the service and close gRPC streams:

  publisher.Stop()

See https://cloud.google.com/pubsub/lite/docs/publishing for more information
about publishing.


Creating Subscriptions

To receive messages published to a topic, clients create subscriptions to the
topic. There may be more than one subscription per topic; each message that is
published to the topic will be delivered to all of its subscriptions.

Cloud Pub/Sub Lite subscriptions may be created like so:

  subscriptionPath := pubsublite.SubscriptionPath{
    Project:        "project-id",
    Zone:           "zone",
    SubscriptionID: "subscription-id",
  }
  subscriptionConfig := pubsublite.SubscriptionConfig{
    Name:                subscriptionPath,
    Topic:               topicPath,
    DeliveryRequirement: pubsublite.DeliverImmediately,
  }
  _, err = admin.CreateSubscription(ctx, subscriptionConfig)

See https://cloud.google.com/pubsub/lite/docs/subscriptions for more information
about how subscriptions are configured.


Receiving

To receive messages for a subscription, first create a SubscriberClient:

  subscriber, err := ps.NewSubscriberClient(ctx, ps.DefaultReceiveSettings, subscriptionPath)

Messages are then consumed from a subscription via callback.

  cctx, cancel := context.WithCancel(ctx)
  err = subscriber.Receive(cctx, func(ctx context.Context, m *pubsub.Message) {
    log.Printf("Got message: %s", m.Data)
    m.Ack()
  })
  if err != nil {
    // Handle error.
  }

The callback may be invoked concurrently by multiple goroutines (one per
partition that the subscriber client is connected to). To terminate a call to
Receive, cancel its context:

  cancel()

Clients must call pubsub.Message.Ack() or pubsub.Message.Nack() for every
message received. Cloud Pub/Sub Lite does not have ACK deadlines. Cloud Pub/Sub
Lite also does not actually have the concept of NACK. The default behavior
terminates the SubscriberClient. In Cloud 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.

See https://cloud.google.com/pubsub/lite/docs/subscribing for more information
about receiving messages.
*/
package pubsublite // import "cloud.google.com/go/pubsublite"