// 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
//
//     http://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.

syntax = "proto3";

package google.pubsub.v1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";

option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.PubSub.V1";
option go_package = "google.golang.org/genproto/googleapis/pubsub/v1;pubsub";
option java_multiple_files = true;
option java_outer_classname = "PubsubProto";
option java_package = "com.google.pubsub.v1";
option php_namespace = "Google\\Cloud\\PubSub\\V1";
option ruby_package = "Google::Cloud::PubSub::V1";

// A message that is published by publishers and consumed by subscribers. The
// message must contain either a non-empty data field or at least one attribute.
// Note that client libraries represent this object differently
// depending on the language. See the corresponding [client library
// documentation](https://cloud.google.com/pubsub/docs/reference/libraries) for
// more information. See [quotas and limits]
// (https://cloud.google.com/pubsub/quotas) for more information about message
// limits.
message PubsubMessage {
  // The message data field. If this field is empty, the message must contain
  // at least one attribute.
  bytes data = 1;

  // Attributes for this message. If this field is empty, the message must
  // contain non-empty data. This can be used to filter messages on the
  // subscription.
  map<string, string> attributes = 2;

  // ID of this message, assigned by the server when the message is published.
  // Guaranteed to be unique within the topic. This value may be read by a
  // subscriber that receives a `PubsubMessage` via a `Pull` call or a push
  // delivery. It must not be populated by the publisher in a `Publish` call.
  string message_id = 3;

  // The time at which the message was published, populated by the server when
  // it receives the `Publish` call. It must not be populated by the
  // publisher in a `Publish` call.
  google.protobuf.Timestamp publish_time = 4;

  // If non-empty, identifies related messages for which publish order should be
  // respected. If a `Subscription` has `enable_message_ordering` set to `true`,
  // messages published with the same non-empty `ordering_key` value will be
  // delivered to subscribers in the order in which they are received by the
  // Pub/Sub system. All `PubsubMessage`s published in a given `PublishRequest`
  // must specify the same `ordering_key` value.
  string ordering_key = 5;
}

// The service that an application uses to manipulate subscriptions and to
// consume messages from a subscription via the `Pull` method or by
// establishing a bi-directional stream using the `StreamingPull` method.
service Subscriber {
  option (google.api.default_host) = "pubsub.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform,"
      "https://www.googleapis.com/auth/pubsub";

  // Establishes a stream with the server, which sends messages down to the
  // client. The client streams acknowledgements and ack deadline modifications
  // back to the server. The server will close the stream and return the status
  // on any error. The server may close the stream with status `UNAVAILABLE` to
  // reassign server-side resources, in which case, the client should
  // re-establish the stream. Flow control can be achieved by configuring the
  // underlying RPC channel.
  rpc StreamingPull(stream StreamingPullRequest)
      returns (stream StreamingPullResponse) {}
}

// A message and its corresponding acknowledgment ID.
message ReceivedMessage {
  // This ID can be used to acknowledge the received message.
  string ack_id = 1;

  // The message.
  PubsubMessage message = 2;

  // The approximate number of times that Cloud Pub/Sub has attempted to deliver
  // the associated message to a subscriber.
  //
  // More precisely, this is 1 + (number of NACKs) +
  // (number of ack_deadline exceeds) for this message.
  //
  // A NACK is any call to ModifyAckDeadline with a 0 deadline. An ack_deadline
  // exceeds event is whenever a message is not acknowledged within
  // ack_deadline. Note that ack_deadline is initially
  // Subscription.ackDeadlineSeconds, but may get extended automatically by
  // the client library.
  //
  // Upon the first delivery of a given message, `delivery_attempt` will have a
  // value of 1. The value is calculated at best effort and is approximate.
  //
  // If a DeadLetterPolicy is not set on the subscription, this will be 0.
  int32 delivery_attempt = 3;
}

// Request for the `StreamingPull` streaming RPC method. This request is used to
// establish the initial stream as well as to stream acknowledgements and ack
// deadline modifications from the client to the server.
message StreamingPullRequest {
  // Required. The subscription for which to initialize the new stream. This
  // must be provided in the first request on the stream, and must not be set in
  // subsequent requests from client to server.
  // Format is `projects/{project}/subscriptions/{sub}`.
  string subscription = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "pubsub.googleapis.com/Subscription"
    }
  ];

  // List of acknowledgement IDs for acknowledging previously received messages
  // (received on this stream or a different stream). If an ack ID has expired,
  // the corresponding message may be redelivered later. Acknowledging a message
  // more than once will not result in an error. If the acknowledgement ID is
  // malformed, the stream will be aborted with status `INVALID_ARGUMENT`.
  repeated string ack_ids = 2;

  // The list of new ack deadlines for the IDs listed in
  // `modify_deadline_ack_ids`. The size of this list must be the same as the
  // size of `modify_deadline_ack_ids`. If it differs the stream will be aborted
  // with `INVALID_ARGUMENT`. Each element in this list is applied to the
  // element in the same position in `modify_deadline_ack_ids`. The new ack
  // deadline is with respect to the time this request was sent to the Pub/Sub
  // system. Must be >= 0. For example, if the value is 10, the new ack deadline
  // will expire 10 seconds after this request is received. If the value is 0,
  // the message is immediately made available for another streaming or
  // non-streaming pull request. If the value is < 0 (an error), the stream will
  // be aborted with status `INVALID_ARGUMENT`.
  repeated int32 modify_deadline_seconds = 3;

  // List of acknowledgement IDs whose deadline will be modified based on the
  // corresponding element in `modify_deadline_seconds`. This field can be used
  // to indicate that more time is needed to process a message by the
  // subscriber, or to make the message available for redelivery if the
  // processing was interrupted.
  repeated string modify_deadline_ack_ids = 4;

  // Required. The ack deadline to use for the stream. This must be provided in
  // the first request on the stream, but it can also be updated on subsequent
  // requests from client to server. The minimum deadline you can specify is 10
  // seconds. The maximum deadline you can specify is 600 seconds (10 minutes).
  int32 stream_ack_deadline_seconds = 5
      [(google.api.field_behavior) = REQUIRED];

  // A unique identifier that is used to distinguish client instances from each
  // other. Only needs to be provided on the initial request. When a stream
  // disconnects and reconnects for the same stream, the client_id should be set
  // to the same value so that state associated with the old stream can be
  // transferred to the new stream. The same client_id should not be used for
  // different client instances.
  string client_id = 6;

  // Flow control settings for the maximum number of outstanding messages. When
  // there are `max_outstanding_messages` or more currently sent to the
  // streaming pull client that have not yet been acked or nacked, the server
  // stops sending more messages. The sending of messages resumes once the
  // number of outstanding messages is less than this value. If the value is
  // <= 0, there is no limit to the number of outstanding messages. This
  // property can only be set on the initial StreamingPullRequest. If it is set
  // on a subsequent request, the stream will be aborted with status
  // `INVALID_ARGUMENT`.
  int64 max_outstanding_messages = 7;

  // Flow control settings for the maximum number of outstanding bytes. When
  // there are `max_outstanding_bytes` or more worth of messages currently sent
  // to the streaming pull client that have not yet been acked or nacked, the
  // server will stop sending more messages. The sending of messages resumes
  // once the number of outstanding bytes is less than this value. If the value
  // is <= 0, there is no limit to the number of outstanding bytes. This
  // property can only be set on the initial StreamingPullRequest. If it is set
  // on a subsequent request, the stream will be aborted with status
  // `INVALID_ARGUMENT`.
  int64 max_outstanding_bytes = 8;
}

// Response for the `StreamingPull` method. This response is used to stream
// messages from the server to the client.
message StreamingPullResponse {
  // Acknowledgement IDs sent in one or more previous requests to acknowledge a
  // previously received message.
  message AcknowledgeConfirmation {
    // Successfully processed acknowledgement IDs.
    repeated string ack_ids = 1 [ctype = CORD];

    // List of acknowledgement IDs that were malformed or whose acknowledgement
    // deadline has expired.
    repeated string invalid_ack_ids = 2 [ctype = CORD];

    // List of acknowledgement IDs that were out of order.
    repeated string unordered_ack_ids = 3 [ctype = CORD];
  }

  // Acknowledgement IDs sent in one or more previous requests to modify the
  // deadline for a specific message.
  message ModifyAckDeadlineConfirmation {
    // Successfully processed acknowledgement IDs.
    repeated string ack_ids = 1 [ctype = CORD];

    // List of acknowledgement IDs that were malformed or whose acknowledgement
    // deadline has expired.
    repeated string invalid_ack_ids = 2 [ctype = CORD];
  }

  // Subscription properties sent as part of the response.
  message SubscriptionProperties {
    // True iff exactly once delivery is enabled for this subscription.
    bool exactly_once_delivery_enabled = 1;
    // True iff message ordering is enabled for this subscription.
    bool message_ordering_enabled = 2;
  }

  // Received Pub/Sub messages. This will not be empty.
  repeated ReceivedMessage received_messages = 1;

  reserved 2;

  // This field will only be set if `enable_exactly_once_delivery` is set to
  // `true`.
  AcknowledgeConfirmation acknowledge_confirmation = 5;

  // This field will only be set if `enable_exactly_once_delivery` is set to
  // `true`.
  ModifyAckDeadlineConfirmation modify_ack_deadline_confirmation = 3;

  // Properties associated with this subscription.
  SubscriptionProperties subscription_properties = 4;
}