chore: document some private methods and add multiplex plumbing

Author: viacheslav-rostovtsev

google-cloud-spanner/Gemfile

@@ -19,5 +19,6 @@ gem "minitest-rg", "~> 5.3"
 gem "rake"
 gem "redcarpet", "~> 3.0"
 gem "simplecov", "~> 0.22"
+gem "solargraph", group: :development
 gem "yard", "~> 0.9"
-gem "yard-doctest", "~> 0.1.17"
+gem "yard-doctest", "~> 0.1.17", group: :development

google-cloud-spanner/lib/google/cloud/spanner/batch_client.rb

@@ -63,8 +63,18 @@ module Spanner
       #     new_partition
       #
       class BatchClient
-        ##
-        # @private Creates a new Spanner BatchClient instance.
+        # Creates a new Spanner BatchClient instance.
+        # @param project [::Google::Cloud::Spanner::Project] A `Spanner::Project` ref.
+        # @param instance_id [::String] Instance id, e.g. `"my-instance"`.
+        # @param database_id [::String] Database id, e.g. `"my-database"`.
+        # @param session_labels [::Hash, nil] Optional. The labels to be applied to all sessions
+        #   created by the client. Example: `"team" => "billing-service"`.
+        # @param query_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   query options for executing SQL query. Example parameter `:optimizer_version`.
+        # @param directed_read_options [::Hash, nil] Optional. Client options used to set
+        #   the `directed_read_options` for all ReadRequests and ExecuteSqlRequests.
+        #   Converts to `V1::DirectedReadOptions`. Example option: `:exclude_replicas`.
+        # @private
         def initialize project, instance_id, database_id, session_labels: nil,
                        query_options: nil, directed_read_options: nil
           @project = project
@@ -413,6 +423,7 @@ def ensure_service!
 
         ##
         # New session for each use.
+        # @return [::Google::Cloud::Spanner::Session]
         def session
           ensure_service!
           grpc = @project.service.create_session \

google-cloud-spanner/lib/google/cloud/spanner/client.rb

@@ -51,12 +51,26 @@ module Spanner
       #   end
       #
       class Client
-        ##
+        # A semi-arbitrary constant for thread-wide global parameter name
         # @private
         IS_TRANSACTION_RUNNING_KEY = "ruby_spanner_is_transaction_running".freeze
 
-        ##
-        # @private Creates a new Spanner Client instance.
+        # Creates a new Spanner Client instance.
+        # @param project [::Google::Cloud::Spanner::Project] A `Spanner::Project` ref.
+        # @param instance_id [::String] Instance id, e.g. `"my-instance"`.
+        # @param database_id [::String] Database id, e.g. `"my-database"`.
+        # @param session_labels [::Hash, nil] Optional. The labels to be applied to all sessions
+        #   created by the client. Example: `"team" => "billing-service"`.
+        # @param pool_opts [::Hash] Optional. `Spanner::Pool` creation options.
+        #   Example parameter: `:keepalive`.
+        # @param query_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   query options for executing SQL query. Example parameter `:optimizer_version`.
+        # @param database_role [::String, nil] Optional. The Spanner session creator role.
+        #   Example: `analyst`
+        # @param directed_read_options [Hash] Optional. Client options used to set
+        #   the `directed_read_options` for all ReadRequests and ExecuteSqlRequests.
+        #   Converts to `V1::DirectedReadOptions`. Example option: `:exclude_replicas`.
+        # @private
         def initialize project, instance_id, database_id, session_labels: nil,
                        pool_opts: {}, query_options: nil, database_role: nil,
                        directed_read_options: nil
@@ -89,7 +103,7 @@ def database_id
         end
 
         # The Spanner project connected to.
-        # @return [Project]
+        # @return [::Google::Cloud::Spanner::Project]
         def project
           @project
         end
@@ -2419,17 +2433,21 @@ def reset
           @pool.reset
         end
 
-        ##
+        # Creates a new Session objece.
+        # @param multiplexed [::Boolean] Optional. Default to `false`.
+        #   If `true`, specifies a multiplexed session.
+        # @return [::Google::Cloud::Spanner::Session]
         # @private
-        # Creates a new session object every time.
-        def create_new_session
+        def create_new_session multiplexed: false
           ensure_service!
           grpc = @project.service.create_session \
             Admin::Database::V1::DatabaseAdmin::Paths.database_path(
               project: project_id, instance: instance_id, database: database_id
             ),
             labels: @session_labels,
-            database_role: @database_role
+            database_role: @database_role,
+            multiplexed: multiplexed
+
           Session.from_grpc grpc, @project.service, query_options: @query_options
         end
 

google-cloud-spanner/lib/google/cloud/spanner/pool.rb

@@ -36,6 +36,16 @@ class Pool
         # and `Session` objects as values.
         attr_accessor :sessions_in_use
 
+        # Creates a new Session pool that manages non-multiplexed sessions.
+        # @param client [::Google::Cloud::Spanner::Client] A `Spanner::Client` reference
+        # @param min [Integer] Min number of sessions to keep
+        # @param max [Integer] Max number of sessions to keep
+        # @param keepalive [Numeric] How long after their last usage the sessions can be reclaimed
+        # @param fail [Boolean] If `true` the pool will raise `SessionLimitError` if number of new sessions
+        #   needed is more that can be created due to the `max` parameter. If `false` it will wait instead.
+        # @param threads [Integer, nil] Number of threads in the thread pool that is used for keepalive and
+        #   release session actions. If `nil` the Pool will choose a reasonable default.
+        # @private
         def initialize client, min: 10, max: 100, keepalive: 1800,
                        fail: true, threads: nil
           @client = client
@@ -52,6 +62,10 @@ def initialize client, min: 10, max: 100, keepalive: 1800,
           init
         end
 
+        # Provides a session for running an operation
+        # @yield session Session a client can use to run an operation
+        # @yieldparam [::Google::Cloud::Spanner::Session]
+        # @return [nil]
         def with_session
           session = checkout_session
           begin

google-cloud-spanner/lib/google/cloud/spanner/project.rb

@@ -66,12 +66,22 @@ module Spanner
       #   end
       #
       class Project
-        ##
-        # @private The Service object.
-        attr_accessor :service, :query_options
+        # The `Spanner::Service` ref.
+        # @return [::Google::Cloud::Spanner::Service]
+        # @private
+        attr_accessor :service
 
-        ##
-        # @private Creates a new Spanner Project instance.
+        # A hash of values to specify the custom query options for executing SQL query.
+        # Example option: `:optimizer_version`.
+        # @return [::Hash, nil]
+        # @private
+        attr_accessor :query_options
+
+        # Creates a new Spanner Project instance.
+        # @param [::Google::Cloud::Spanner::Service] The `Spanner::Service` ref.
+        # @param query_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   query options for executing SQL query. Example option: `:optimizer_version`.
+        # @private
         def initialize service, query_options: nil
           @service = service
           @query_options = query_options
@@ -80,6 +90,8 @@ def initialize service, query_options: nil
         ##
         # The identifier for the Cloud Spanner project.
         #
+        # @return [::String]
+        #
         # @example
         #   require "google/cloud"
         #

google-cloud-spanner/lib/google/cloud/spanner/service.rb

@@ -43,8 +43,18 @@ class Service
         RST_STREAM_INTERNAL_ERROR = "Received RST_STREAM".freeze
         EOS_INTERNAL_ERROR = "Received unexpected EOS on DATA frame from server".freeze
 
-        ##
-        # Creates a new Service instance.
+        # Creates a new `Spanner::Service` instance.
+        # @param project [::String] The project id to use
+        # @param credentials [::Symbol, ::Google::Auth::Credentials] Credentials
+        # @param quota_project_id [::String, nil] Optional. The quota project id to use
+        # @param host [::String, nil] Optional. The endpoint override.
+        # @param timeout [::Numeric, nil] Optional. Timeout for Gapic client.
+        # @param lib_name [::String, nil] Optional. Library name for headers.
+        # @param lib_version [::String, nil] Optional. Library version for headers.
+        # @param enable_leader_aware_routing [::Boolean, nil] Optional. Whether Leader
+        #   Aware Routing should be enabled.
+        # @param universe_domain [::String, nil] Optional. The domain of the universe to connect to.
+        # @private
         def initialize project, credentials, quota_project: nil,
                        host: nil, timeout: nil, lib_name: nil, lib_version: nil,
                        enable_leader_aware_routing: nil, universe_domain: nil
@@ -82,6 +92,8 @@ def chan_creds
             GRPC::Core::CallCredentials.new credentials.client.updater_proc
         end
 
+        # `V1::Spanner::Client` or mock.
+        # @return [::Google::Cloud::Spanner::V1::Spanner::Client]
         def service
           return mocked_service if mocked_service
           @service ||=
@@ -329,13 +341,41 @@ def get_session session_name, call_options: nil
           service.get_session({ name: session_name }, opts)
         end
 
+        # Creates a new Spanner session.
+        # This creates a `V1::Session` protobuf object not wrapped in `Spanner::Session`.
+        #
+        # @param database_name [::String] The full name of the database.
+        # @param labels [::Hash, nil] Optional. The labels to be applied to all sessions
+        #   created by the client. Example: `"team" => "billing-service"`.
+        # @param call_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   call options. Example option `:timeout`.
+        # @param database_role [::String, nil] Optional. The Spanner session creator role.
+        #   Example: `analyst`.
+        # @param multiplexed [::Boolean] Optional. Default to `false`.
+        #   If `true`, specifies a multiplexed session.
+        # @return [::Google::Cloud::Spanner::V1::Session]
+        # @private
         def create_session database_name, labels: nil,
-                           call_options: nil, database_role: nil
+                           call_options: nil, database_role: nil,
+                           multiplexed: false
           route_to_leader = LARHeaders.create_session
-          opts = default_options session_name: database_name,
-                                 call_options: call_options,
-                                 route_to_leader: route_to_leader
-          session = V1::Session.new labels: labels, creator_role: database_role if labels || database_role
+          opts = default_options(
+            session_name: database_name,
+            call_options: call_options,
+            route_to_leader: route_to_leader
+          )
+
+          # check if we need a session object in request or server defaults would work.
+          params_diff_from_default = !(labels.nil? && database_role.nil? && !multiplexed)
+
+          if params_diff_from_default
+            session = V1::Session.new(
+              labels: labels,
+              creator_role: database_role,
+              multiplexed: multiplexed
+            )
+          end
+
           service.create_session(
             { database: database_name, session: session }, opts
           )
@@ -464,6 +504,29 @@ def partition_query session_name, sql, transaction, params: nil,
           service.partition_query request, opts
         end
 
+        # Commits a transaction. Can be a predefined (`transaction_id`) transaction
+        # or a single-use created for this request. The request includes the mutations to be
+        # applied to rows in the database.
+        #
+        # @param session_name [::String]
+        #   Required. The session in which the transaction to be committed is running.
+        # @param mutations [::Array<::Google::Cloud::Spanner::V1::Mutation>] Optional.
+        #   The mutations to be executed when this transaction commits. All
+        #   mutations are applied atomically, in the order they appear in
+        #   this list. Defaults to an empty array.
+        # @param transaction_id [::String, nil] Optional.
+        #   Commit a previously-started transaction. If nil, a new single-use transation will be used.
+        # @param exclude_txn_from_change_streams [::Boolean] Optional. Defaults to `false`.
+        #   When `exclude_txn_from_change_streams` is set to `true`, it prevents read
+        #   or write transactions from being tracked in change streams.
+        # @param commit_options [::Hash, nil]  Optional. A hash of commit options.
+        #   Example option: `:return_commit_stats`.
+        # @param request_options [::Hash, nil] Optional. Common request options.
+        #   Example option: `:priority`.
+        # @param call_options [::Hash, nil] Optional. A hash of values to specify the custom
+        #   call options. Example option `:timeout`.
+        # @return [::Google::Cloud::Spanner::V1::CommitResponse]
+        # @private
         def commit session_name, mutations = [],
                    transaction_id: nil, exclude_txn_from_change_streams: false,
                    commit_options: nil, request_options: nil, call_options: nil
@@ -485,10 +548,16 @@ def commit session_name, mutations = [],
           }
 
           request = add_commit_options request, commit_options
-
+          # request is a hash equivalent of `::Google::Cloud::Spanner::V1::CommitRequest`
           service.commit request, opts
         end
 
+        # Merges commit options hash to a hash representing a `V1::CommitRequest`.
+        # @param request [::Hash] A `::Google::Cloud::Spanner::V1::CommitRequest` in a hash form.
+        # @param commit_options [::Hash, nil]  Optional. A hash of commit options.
+        #   Example option: `:return_commit_stats`.
+        # @return [Hash] An enriched `::Google::Cloud::Spanner::V1::CommitRequest` in a hash form.
+        # @private
         def add_commit_options request, commit_options
           if commit_options
             if commit_options.key? :return_commit_stats