// Copyright 2025 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_BIGTABLE_CLIENT_H
#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_CLIENT_H

#include "google/cloud/bigtable/bound_query.h"
#include "google/cloud/bigtable/data_connection.h"
#include "google/cloud/bigtable/instance_resource.h"
#include "google/cloud/bigtable/prepared_query.h"
#include "google/cloud/bigtable/sql_statement.h"
#include "google/cloud/bigtable/version.h"
#include "google/cloud/future.h"
#include "google/cloud/options.h"
#include "google/cloud/status_or.h"
#include <memory>

namespace google {
namespace cloud {
namespace bigtable {
GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN

/**
 * Connects to Cloud Bigtable's query preparation and execution APIs.
 *
 * A Bigtable query's lifecycle consists of two phases:
 * 1. Preparing a query: The service creates and caches a query execution plan.
 * 2. Executing a query: The client sends the plan ID and concrete parameters
 *    to the service, which then executes the query.
 *
 * This class provides methods for both preparing and executing SQL queries.
 *
 * @par Cost
 * Creating a `Client` object is a relatively low-cost operation. It does not
 * require connecting to the Bigtable servers. However, each `Client` object
 * holds a `std::shared_ptr<DataConnection>`, and the first RPC made on this
 * connection may incur a higher latency as the connection is established.
 * For this reason, it is recommended to reuse `Client` objects when possible.
 *
 * @par Example
 * @snippet data_snippets.cc prepare-and-execute-query
 */
class Client {
 public:
  /**
   * Creates a new Client object.
   *
   * @param conn The connection object to use for all RPCs. This is typically
   *     created by `MakeDataConnection()`.
   * @param opts Unused for now
   */
  explicit Client(std::shared_ptr<DataConnection> conn, Options opts = {})
      : conn_(std::move(conn)),
        opts_(google::cloud::internal::MergeOptions(std::move(opts),
                                                    conn_->options())) {}

  /**
   * Prepares a query for future execution.
   *
   * This sends the SQL statement to the service, which validates it and
   * creates an execution plan, returning a handle to this plan.
   *
   * @param instance The instance to prepare the query against.
   * @param statement The SQL statement to prepare.
   * @param opts Unused for now
   * @return A `StatusOr` containing the prepared query on success. On
   *     failure, the `Status` contains error details.
   */
  StatusOr<PreparedQuery> PrepareQuery(InstanceResource const& instance,
                                       SqlStatement const& statement,
                                       Options opts = {});

  /**
   * Asynchronously prepares a query for future execution.
   *
   * This sends the SQL statement to the service, which validates it and
   * creates an execution plan, returning a handle to this plan.
   *
   * @param instance The instance to prepare the query against.
   * @param statement The SQL statement to prepare.
   * @param opts Unused for now
   * @return A `future` that will be satisfied with a `StatusOr` containing
   *     the prepared query on success. On failure, the `Status` will contain
   *     error details.
   */
  future<StatusOr<PreparedQuery>> AsyncPrepareQuery(
      InstanceResource const& instance, SqlStatement const& statement,
      Options opts = {});

  /**
   * Executes a bound query with concrete parameters.
   *
   * This returns a `RowStream`, which is a range of `StatusOr<QueryRow>`.
   * The `BoundQuery` is passed by rvalue-reference to promote thread safety,
   * as it is not safe to use a `BoundQuery` concurrently.
   *
   * @param bound_query The bound query to execute.
   * @param opts Overrides the client-level options for this call.
   * @return A `RowStream` that can be used to iterate over the result rows.
   */
  RowStream ExecuteQuery(BoundQuery&& bound_query, Options opts = {});

 private:
  std::shared_ptr<DataConnection> conn_;
  Options opts_;
};

GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
}  // namespace bigtable
}  // namespace cloud
}  // namespace google

#endif  // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_CLIENT_H