options.h

// Copyright 2021 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
// limitations under the License.

#ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_OPTIONS_H
#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_OPTIONS_H

/**
 * @file
 *
 * This file defines options to be used with instances of
 * `google::cloud::Options`. By convention options are named with an "Option"
 * suffix. As the name would imply, all options are optional, and leaving them
 * unset will result in a reasonable default being chosen.
 *
 * Not all options are meaningful to all functions that accept a
 * `google::cloud::Options` instance. Each function that accepts a
 * `google::cloud::Options` should document which options it expects. This is
 * typically done by indicating lists of options using "OptionList" aliases.
 * For example, a function may indicate that users may set any option in
 * `PublisherOptionList`.
 *
 * @note Unrecognized options are allowed and will be ignored. To debug issues
 *     with options set `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` in the environment
 *     and unexpected options will be logged.
 *
 * @see `google::cloud::CommonOptionList`
 * @see `google::cloud::GrpcOptionList`
 */

#include "google/cloud/pubsub/backoff_policy.h"
#include "google/cloud/pubsub/retry_policy.h"
#include "google/cloud/pubsub/subscription.h"
#include "google/cloud/pubsub/version.h"
#include "google/cloud/options.h"
#include <chrono>

namespace google {
namespace cloud {
namespace pubsub {
GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN

/**
 * The retry policy
 *
 * @ingroup google-cloud-pubsub-options
 */
struct RetryPolicyOption {
  using Type = std::shared_ptr<pubsub::RetryPolicy>;
};

/**
 * The backoff policy
 *
 * @ingroup google-cloud-pubsub-options
 */
struct BackoffPolicyOption {
  using Type = std::shared_ptr<pubsub::BackoffPolicy>;
};

/// The list of all "policy" options.
using PolicyOptionList = OptionList<RetryPolicyOption, BackoffPolicyOption>;

/**
 * The maximum hold time for the messages.
 *
 * @note The implementation depends on the granularity of your OS timers. It is
 *     possible that messages are held for slightly longer times than the value
 *     set here.
 *
 * @note The first message in a batch starts the hold time counter. New
 *     messages do not extend the life of the batch. For example, if you have
 *     set the holding time to 10 milliseconds, start a batch with message 1,
 *     and publish a second message 5 milliseconds later, the second message
 *     will be flushed approximately 5 milliseconds after it is published.
 *
 * @ingroup google-cloud-pubsub-options
 */
struct MaxHoldTimeOption {
  using Type = std::chrono::microseconds;
};

/**
 * The maximum number of messages in a batch.
 *
 * @note Application developers should keep in mind that Cloud Pub/Sub
 *    sets [limits][pubsub-quota-link] on the size of a batch (1,000 messages)
 *    The library makes no attempt to validate the value provided in this
 *    option.
 *
 * [pubsub-quota-link]: https://cloud.google.com/pubsub/quotas#resource_limits
 *
 * @ingroup google-cloud-pubsub-options
 */
struct MaxBatchMessagesOption {
  using Type = std::size_t;
};

/**
 * The maximum size for the messages in a batch.
 *
 * @note Application developers should keep in mind that Cloud Pub/Sub
 *    sets [limits][pubsub-quota-link] on the size of a batch (10MB). The
 *    library makes no attempt to validate the value provided in this
 *    option.
 *
 * [pubsub-quota-link]: https://cloud.google.com/pubsub/quotas#resource_limits
 *
 * @ingroup google-cloud-pubsub-options
 */
struct MaxBatchBytesOption {
  using Type = std::size_t;
};

/**
 * The maximum number of pending messages.
 *
 * After a publisher flushes a batch of messages the batch is (obviously) not
 * received immediately by the service. While the batch remains pending it
 * potentially consumes memory resources in the client (and/or the service).
 *
 * Some applications may have constraints on the number of bytes and/or
 * messages they can tolerate in this pending state, and may prefer to block
 * or reject messages.
 *
 * @ingroup google-cloud-pubsub-options
 */
struct MaxPendingMessagesOption {
  using Type = std::size_t;
};

/**
 * The maximum size for pending messages.
 *
 * After a publisher flushes a batch of messages the batch is (obviously) not
 * received immediately by the service. While the batch remains pending it
 * potentially consumes memory resources in the client (and/or the service).
 *
 * Some applications may have constraints on the number of bytes and/or
 * messages they can tolerate in this pending state, and may prefer to block
 * or reject messages.
 *
 * @ingroup google-cloud-pubsub-options
 */
struct MaxPendingBytesOption {
  using Type = std::size_t;
};

/**
 * Publisher message ordering.
 *
 * To guarantee messages are received by the service in the same order that
 * the application gives them to a publisher, the client library needs to wait
 * until a batch of messages is successfully delivered before sending the next
 * batch, otherwise batches may arrive out of order as there is no guarantee
 * the same channel or network path is used for each batch.
 *
 * For applications that do not care about message ordering, this can limit
 * the throughput. Therefore, the behavior is disabled by default.
 *
 * @see the documentation for the `Publisher` class for details.
 *
 * @ingroup google-cloud-pubsub-options
 */
struct MessageOrderingOption {
  using Type = bool;
};

/// Actions taken by a full publisher.
enum class FullPublisherAction {
  /// Ignore full publishers, continue as usual.
  kIgnored,
  /// Configure the publisher to reject new messages when full.
  kRejects,
  /// Configure the publisher to block the caller when full.
  kBlocks
};
/**
 * The action taken by a full publisher.
 *
 * @ingroup google-cloud-pubsub-options
 */
struct FullPublisherActionOption {
  using Type = FullPublisherAction;
};

/**
 * Compression threshold.
 *
 * If set, the client library turns on gRPC compression for batches larger (in
 * bytes) than the give threshold.
 *
 * @ingroup google-cloud-pubsub-options
 */
struct CompressionThresholdOption {
  using Type = std::size_t;
};

/**
 * Compression algorithm.
 *
 * Select the gRPC compression algorithm when compression is enabled. As of this
 * writing, gRPC supports `GRPC_COMPRESS_DEFLATE` and `GRPC_COMPRESS_GZIP`.
 * Other values may be added in the future and should be settable via this
 * feature.
 *
 * @ingroup google-cloud-pubsub-options
 */
struct CompressionAlgorithmOption {
  using Type = int;
};

/**
 * The maximum number of Open Telemetry span links.
 *
 * This option controls the number of links contained in a single publish span.
 *
 * @note Application developers should keep in mind that Cloud Trace
 *    sets [limits][cloud-trace-quota-link] on the number of links per span
 *    (128). Additionally, Open Telemetry sets the default
 *    [limit][otel-quota-link] to 128.
 *
 * @ingroup google-cloud-pubsub-options
 *
 * @par Environment variable
 *    This option is controlled by the `OTEL_SPAN_LINK_COUNT_LIMIT`
 *    environment variable. If the environment variable is unset or unparsable,
 *    it uses the user provided value, and then the default of 128.
 *
 * [otel-quota-link]:
 * https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#span-limits
 * [cloud-trace-quota-link]:
 * https://github.com/googleapis/googleapis/blob/52180f8ba240022dd8ce756ee69fe5a3c429ad4d/google/devtools/cloudtrace/v2/trace.proto#L266
 */
struct MaxOtelLinkCountOption {
  using Type = std::size_t;
};

/// The list of options specific to publishers.
using PublisherOptionList =
    OptionList<MaxHoldTimeOption, MaxBatchMessagesOption, MaxBatchBytesOption,
               MaxPendingMessagesOption, MaxPendingBytesOption,
               MessageOrderingOption, FullPublisherActionOption,
               CompressionThresholdOption, MaxOtelLinkCountOption>;

/**
 * The maximum deadline for each incoming message.
 *
 * Configure how long the application has to respond (ACK or NACK) to an
 * incoming message. Note that this might be longer, or shorter, than the
 * deadline configured in the server-side subscription.
 *
 * The value `0` is reserved to leave the deadline unmodified and just use the
 * server-side configuration.
 *
 * @note The deadline applies to each message as it is delivered to the
 *     application, thus, if the library receives a batch of N messages their
 *     deadline for all the messages is extended repeatedly. Only once the
 *     message is delivered to a callback does the deadline become immutable.
 *
 * @ingroup google-cloud-pubsub-options
 */
struct MaxDeadlineTimeOption {
  using Type = std::chrono::seconds;
};

/**
 * The maximum time by which the deadline for each incoming message is extended.
 *
 * While waiting for an ack or nack, The Cloud Pub/Sub C++ client library will
 * extend the deadline by at most this amount. The default extension time is 10
 * minutes. An application may wish to reduce this extension time so the Pub/Sub
 * service will resend a message sooner when it does not hear back from a
 * Subscriber. With at-least-once semantics, making the time too short may
 * increase the number of duplicate messages delivered by the service.
 *
 * The value is clamped between 10 seconds and 10 minutes. Note that this option
 * also affects the effective range for `MinDeadlineExtensionOption`.
 *
 * @ingroup google-cloud-pubsub-options
 */
struct MaxDeadlineExtensionOption {
  using Type = std::chrono::seconds;
};

/**
 * The minimum time by which the deadline for each incoming message is extended.
 *
 * While waiting for an ack or nack from the application the Cloud Pub/Sub C++
 * client library will extend the deadline by at least this amount. The default
 * minimum extension is 1 minute. An application may wish to reduce this
 * extension so that the Pub/Sub service will resend a message sooner when it
 * does not hear back from a Subscriber. An application may wish to increase
 * this extension time to avoid duplicate message delivery.
 *
 * The value is clamped between 10 seconds and 10 minutes.  Furthermore, if the
 * application configures `MaxDeadlineExtensionOption`, then
 * `MinDeadlineExtensionOption` is clamped between 10 seconds and the value of
 * `MaxDeadlineExtensionOption`.
 *
 * @ingroup google-cloud-pubsub-options
 */
struct MinDeadlineExtensionOption {
  using Type = std::chrono::seconds;
};

/**
 * The maximum number of outstanding messages per streaming pull.
 *
 * The Cloud Pub/Sub C++ client library uses streaming pull requests to receive
 * messages from the service. The service will stop delivering messages if this
 * many messages or more have neither been acknowledged nor rejected.
 *
 * If a negative or 0 value is supplied, the number of messages will be
 * unlimited.
 *
 * @par Example
 * @snippet samples.cc subscriber-flow-control
 *
 * @ingroup google-cloud-pubsub-options
 */
struct MaxOutstandingMessagesOption {
  using Type = std::int64_t;
};

/**
 * The maximum number of outstanding bytes per streaming pull.
 *
 * The Cloud Pub/Sub C++ client library uses streaming pull requests to receive
 * messages from the service. The service will stop delivering messages if this
 * many bytes or more worth of messages have not been acknowledged nor rejected.
 *
 * If a negative or 0 value is supplied, the number of bytes will be unlimited.
 *
 * @par Example
 * @snippet samples.cc subscriber-flow-control
 *
 * @ingroup google-cloud-pubsub-options
 */
struct MaxOutstandingBytesOption {
  using Type = std::int64_t;
};

/**
 * The maximum callback concurrency.
 *
 * The Cloud Pub/Sub C++ client library will schedule parallel callbacks as long
 * as the number of outstanding callbacks is less than this maximum.
 *
 * Note that this controls the number of callbacks *scheduled*, not the number
 * of callbacks actually executing at a time. The application needs to create
 * (or configure) the background threads pool with enough parallelism to execute
 * more than one callback at a time.
 *
 * Some applications may want to share a thread pool across many subscriptions.
 * The additional level of control (scheduled vs. running callbacks) allows
 * applications, for example, to ensure that at most `K` threads in the pool are
 * used by any given subscription.
 *
 * @par Example
 * @snippet samples.cc subscriber-concurrency
 *
 * @ingroup google-cloud-pubsub-options
 */
struct MaxConcurrencyOption {
  using Type = std::size_t;
};

/**
 * How often the session polls for automatic shutdowns.
 *
 * Applications can shutdown a session by calling `.cancel()` on the returned
 * `future<Status>`.  In addition, applications can fire & forget a session,
 * which is only shutdown once the completion queue servicing the session shuts
 * down. In this latter case the session polls periodically to detect if the CQ
 * has shutdown. This controls how often this polling happens.
 *
 * @ingroup google-cloud-pubsub-options
 */
struct ShutdownPollingPeriodOption {
  using Type = std::chrono::milliseconds;
};

/**
 * Override the default subscription for a request.
 *
 * Some applications need to receive messages from multiple subscriptions. In
 * this case they can use this option to override the default subscription
 * in a `Subscriber::Pull()` or `Subscriber::Subscribe()` call.
 *
 * @ingroup google-cloud-pubsub-options
 */
struct SubscriptionOption {
  using Type = Subscription;
};

/// The list of options specific to subscribers.
/// @ingroup google-cloud-pubsub-options
using SubscriberOptionList =
    OptionList<MaxDeadlineTimeOption, MaxDeadlineExtensionOption,
               MinDeadlineExtensionOption, MaxOutstandingMessagesOption,
               MaxOutstandingBytesOption, MaxConcurrencyOption,
               ShutdownPollingPeriodOption, SubscriptionOption>;

/**
 * Convenience function to initialize a
 * `google::cloud::iam::IAMPolicyConnection`.
 *
 * To manage the IAM policies of Pub/Sub resources you need to configure the
 * `google::cloud::IAMPolicyClient` to use `pubsub.googleapis.com` as the
 * `google::cloud::EndpointOption` and `google::cloud::AuthorityOption`.
 *
 * This function returns an object that is initialized with these values, you
 * can provide additional configuration, or override some of the values before
 * passing the object to `google::cloud::iam::MakeIAMPolicyConnection`.
 *
 * @ingroup google-cloud-pubsub-options
 */
Options IAMPolicyOptions(Options opts = {});

GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
}  // namespace pubsub
}  // namespace cloud
}  // namespace google

#endif  // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_PUBSUB_OPTIONS_H