<NME> options.rb <BEF> # Copyright 2020-2021 Couchbase, Inc. # # 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. require "couchbase/utils/time" require "couchbase/config_profiles" module Couchbase # Definition of the Option classes for data APIs module Options # rubocop:disable Metrics/ModuleLength # Base class for most of the options class Base attr_accessor :timeout # @return [Integer, #in_milliseconds, nil] attr_accessor :retry_strategy # @return [Proc, nil] attr_accessor :client_context # @return [Hash, nil] attr_accessor :parent_span # @return [Span, nil] # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [Base] def initialize(timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) @timeout = timeout @retry_strategy = retry_strategy @client_context = client_context @parent_span = parent_span yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), } end end # Options for {Collection#get} class Get < Base attr_accessor :with_expiry # @return [Boolean] attr_accessor :transcoder # @return [JsonTranscoder, #decode(String, Integer)] # Creates an instance of options for {Collection#get} # # @param [Array<String>] projections a list of paths that should be loaded if present. # @param [Boolean] with_expiry if +true+ the expiration will be also fetched with {Collection#get} # @param [JsonTranscoder, #decode(String, Integer)] transcoder used for decoding # # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [Get] self def initialize(projections: [], with_expiry: false, transcoder: JsonTranscoder.new, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @projections = projections @with_expiry = with_expiry @transcoder = transcoder @preserve_array_indexes = false yield self if block_given? end # Allows to specify a custom list paths to fetch from the document instead of the whole. # # Note that a maximum of 16 individual paths can be projected at a time due to a server limitation. If you need # more than that, think about fetching less-generic paths or the full document straight away. # # @param [String, Array<String>] paths a path that should be loaded if present. def project(*paths) @projections ||= [] @projections |= paths.flatten # union with current projections end # @api private # @return [Boolean] whether to use sparse arrays (default +false+) attr_accessor :preserve_array_indexes # @api private # @return [Array<String>] list of paths to project attr_accessor :projections # @api private # @return [Boolean] def need_projected_get? @with_expiry || !@projections&.empty? end # @api private def to_backend options = { timeout: Utils::Time.extract_duration(@timeout), } options.update(with_expiry: true) if @with_expiry unless @projections&.empty? options.update({ projections: @projections, preserve_array_indexes: @preserve_array_indexes, }) end options end end # Options for {Collection#get_multi} class GetMulti < Base # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [Get] self def initialize(transcoder: JsonTranscoder.new, timeout: nil, retry_strategy: nil, # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [GetMulti] self def initialize(transcoder: JsonTranscoder.new, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @transcoder = transcoder yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), } end end # Options for {Collection#get_and_lock} class GetAndLock < Base attr_accessor :transcoder # @return [JsonTranscoder, #decode(String, Integer)] # Creates an instance of options for {Collection#get_and_lock} # # @param [JsonTranscoder, #decode(String, Integer)] transcoder used for decoding # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [GetAndLock] self def initialize(transcoder: JsonTranscoder.new, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @transcoder = transcoder yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), } end end # Options for {Collection#get_and_touch} class GetAndTouch < Base attr_accessor :transcoder # @return [JsonTranscoder, #decode(String, Integer)] # Creates an instance of options for {Collection#get_and_touch} # # @param [JsonTranscoder, #decode(String, Integer)] transcoder used for decoding # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [GetAndTouch] self def initialize(transcoder: JsonTranscoder.new, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @transcoder = transcoder yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), } end end # Options for {Collection#get_all_replicas} class GetAllReplicas < Base attr_accessor :transcoder # @return [JsonTranscoder, #decode(String, Integer)] # Creates an instance of options for {Collection#get_all_replicas} # # @param [JsonTranscoder, #decode(String, Integer)] transcoder used for decoding # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [GetAllReplicas] self def initialize(transcoder: JsonTranscoder.new, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @transcoder = transcoder yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), } end end # Options for {Collection#get_any_replica} class GetAnyReplica < Base attr_accessor :transcoder # @return [JsonTranscoder, #decode(String, Integer)] # Creates an instance of options for {Collection#get_any_replica} # # @param [JsonTranscoder, #decode(String, Integer)] transcoder used for decoding # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [GetAnyReplica] self def initialize(transcoder: JsonTranscoder.new, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @transcoder = transcoder yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), } end end # Options for {Collection#exists} class Exists < Base # Creates an instance of options for {Collection#exists} # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [Exists self def initialize(timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), } end end # Options for {Collection#touch} class Touch < Base # Creates an instance of options for {Collection#touch} # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [TouchOptions] self def initialize(timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), } end end # Options for {Collection#unlock} class Unlock < Base # Creates an instance of options for {Collection#unlock} # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [Unlock] self def initialize(timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), } end end # Options for {Collection#remove} class Remove < Base attr_accessor :cas # @return [Integer, nil] attr_accessor :durability_level # @return [Symbol] # Creates an instance of options for {Collection#remove} # # @param [Integer, nil] cas CAS value for optimistic locking # @param [Symbol] durability_level level of durability # +:none+:: # no enhanced durability required for the mutation # +:majority+:: # the mutation must be replicated to a majority of the Data Service nodes # (that is, held in the memory allocated to the bucket) # +:majority_and_persist_to_active+:: # The mutation must be replicated to a majority of the Data Service nodes. # Additionally, it must be persisted (that is, written and synchronised to disk) on the # node hosting the active partition (vBucket) for the data. # +:persist_to_majority+:: # The mutation must be persisted to a majority of the Data Service nodes. # Accordingly, it will be written to disk on those nodes. # @param [Symbol] replicate_to number of nodes to replicate # +:none+:: do not apply any replication requirements. # +:one+:: wait for replication to at least one node. # +:two+:: wait for replication to at least two nodes. # +:three+:: wait for replication to at least three nodes. # @param [Symbol] persist_to number of nodes to persist # +:none+:: do not apply any persistence requirements. # +:active+:: wait for persistence to active node # +:one+:: wait for persistence to at least one node. # +:two+:: wait for persistence to at least two nodes. # +:three+:: wait for persistence to at least three nodes. # +:four+:: wait for persistence to four nodes (active and replicas). # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [Remove] def initialize(cas: nil, durability_level: :none, replicate_to: :none, persist_to: :none, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @cas = cas if durability_level != :none && (replicate_to != :none || persist_to != :none) raise ArgumentError, "durability_level conflicts with replicate_to and persist_to options" end @persist_to = replicate_to @replicate_to = replicate_to @durability_level = durability_level yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), durability_level: @durability_level, persist_to: @persist_to, replicate_to: @replicate_to, cas: @cas, } end end # Options for {Collection#remove_multi} class RemoveMulti < Base attr_accessor :durability_level # @return [Symbol] # Creates an instance of options for {Collection#remove} # # @param [Symbol] durability_level level of durability # +:none+:: # no enhanced durability required for the mutation # +:majority+:: # the mutation must be replicated to a majority of the Data Service nodes # (that is, held in the memory allocated to the bucket) # +:majority_and_persist_to_active+:: # The mutation must be replicated to a majority of the Data Service nodes. # Additionally, it must be persisted (that is, written and synchronised to disk) on the # node hosting the active partition (vBucket) for the data. # +:persist_to_majority+:: # The mutation must be persisted to a majority of the Data Service nodes. # Accordingly, it will be written to disk on those nodes. # @param [Symbol] replicate_to number of nodes to replicate # +:none+:: do not apply any replication requirements. # +:one+:: wait for replication to at least one node. # +:two+:: wait for replication to at least two nodes. # +:three+:: wait for replication to at least three nodes. # @param [Symbol] persist_to number of nodes to persist # +:none+:: do not apply any persistence requirements. # +:active+:: wait for persistence to active node # +:one+:: wait for persistence to at least one node. # +:two+:: wait for persistence to at least two nodes. # +:three+:: wait for persistence to at least three nodes. # +:four+:: wait for persistence to four nodes (active and replicas). # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [Remove] def initialize(durability_level: :none, replicate_to: :none, persist_to: :none, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) if durability_level != :none && (replicate_to != :none || persist_to != :none) raise ArgumentError, "durability_level conflicts with replicate_to and persist_to options" end @persist_to = replicate_to @replicate_to = replicate_to @durability_level = durability_level yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), durability_level: @durability_level, persist_to: @persist_to, replicate_to: @replicate_to, } end end # Options for {Collection#insert} class Insert < Base attr_accessor :expiry # @return [Integer, #in_seconds, nil] attr_accessor :transcoder # @return [JsonTranscoder, #encode(Object)] attr_accessor :durability_level # @return [Symbol] # Creates an instance of options for {Collection#insert} # # @param [Integer, #in_seconds, Time, nil] expiry expiration time to associate with the document # @param [JsonTranscoder, #encode(Object)] transcoder used for encoding # @param [Symbol] durability_level level of durability # +:none+:: # no enhanced durability required for the mutation # +:majority+:: # the mutation must be replicated to a majority of the Data Service nodes # (that is, held in the memory allocated to the bucket) # +:majority_and_persist_to_active+:: # The mutation must be replicated to a majority of the Data Service nodes. # Additionally, it must be persisted (that is, written and synchronised to disk) on the # node hosting the active partition (vBucket) for the data. # +:persist_to_majority+:: # The mutation must be persisted to a majority of the Data Service nodes. # Accordingly, it will be written to disk on those nodes. # @param [Symbol] replicate_to number of nodes to replicate # +:none+:: do not apply any replication requirements. # +:one+:: wait for replication to at least one node. # +:two+:: wait for replication to at least two nodes. # +:three+:: wait for replication to at least three nodes. # @param [Symbol] persist_to number of nodes to persist # +:none+:: do not apply any persistence requirements. # +:active+:: wait for persistence to active node # +:one+:: wait for persistence to at least one node. # +:two+:: wait for persistence to at least two nodes. # +:three+:: wait for persistence to at least three nodes. # +:four+:: wait for persistence to four nodes (active and replicas). # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [Insert] def initialize(expiry: nil, transcoder: JsonTranscoder.new, durability_level: :none, replicate_to: :none, persist_to: :none, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @expiry = Utils::Time.extract_expiry_time(expiry) @transcoder = transcoder if durability_level != :none && (replicate_to != :none || persist_to != :none) raise ArgumentError, "durability_level conflicts with replicate_to and persist_to options" end @persist_to = replicate_to @replicate_to = replicate_to @durability_level = durability_level yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), expiry: @expiry, durability_level: @durability_level, persist_to: @persist_to, replicate_to: @replicate_to, } end end # Options for {Collection#upsert} class Upsert < Base attr_accessor :expiry # @return [Integer, #in_seconds, nil] attr_accessor :transcoder # @return [JsonTranscoder, #encode(Object)] attr_accessor :durability_level # @return [Symbol] attr_accessor :preserve_expiry # @return [Boolean] # Creates an instance of options for {Collection#upsert} # # @param [Integer, #in_seconds, Time, nil] expiry expiration time to associate with the document # @param [Boolean] preserve_expiry if true and the document exists, the server will preserve current expiration # for the document, otherwise will use {expiry} from the operation. # @param [JsonTranscoder, #encode(Object)] transcoder used for encoding # @param [Symbol] durability_level level of durability # +:none+:: # no enhanced durability required for the mutation # +:majority+:: # the mutation must be replicated to a majority of the Data Service nodes # (that is, held in the memory allocated to the bucket) # +:majority_and_persist_to_active+:: # The mutation must be replicated to a majority of the Data Service nodes. # Additionally, it must be persisted (that is, written and synchronised to disk) on the # node hosting the active partition (vBucket) for the data. # +:persist_to_majority+:: # The mutation must be persisted to a majority of the Data Service nodes. # Accordingly, it will be written to disk on those nodes. # @param [Symbol] replicate_to number of nodes to replicate # +:none+:: do not apply any replication requirements. # +:one+:: wait for replication to at least one node. # +:two+:: wait for replication to at least two nodes. # +:three+:: wait for replication to at least three nodes. # @param [Symbol] persist_to number of nodes to persist # +:none+:: do not apply any persistence requirements. # +:active+:: wait for persistence to active node # +:one+:: wait for persistence to at least one node. # +:two+:: wait for persistence to at least two nodes. # +:three+:: wait for persistence to at least three nodes. # +:four+:: wait for persistence to four nodes (active and replicas). # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [Upsert] def initialize(expiry: nil, preserve_expiry: false, transcoder: JsonTranscoder.new, durability_level: :none, replicate_to: :none, persist_to: :none, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @expiry = Utils::Time.extract_expiry_time(expiry) @preserve_expiry = preserve_expiry @transcoder = transcoder if durability_level != :none && (replicate_to != :none || persist_to != :none) raise ArgumentError, "durability_level conflicts with replicate_to and persist_to options" end @persist_to = replicate_to @replicate_to = replicate_to @durability_level = durability_level yield self if block_given? end def to_backend { timeout: Utils::Time.extract_duration(@timeout), expiry: @expiry, preserve_expiry: @preserve_expiry, durability_level: @durability_level, persist_to: @persist_to, replicate_to: @replicate_to, } end end # Options for {Collection#upsert_multi} class UpsertMulti < Base attr_accessor :expiry # @return [Integer, #in_seconds, nil] attr_accessor :transcoder # @return [JsonTranscoder, #encode(Object)] attr_accessor :durability_level # @return [Symbol] attr_accessor :preserve_expiry # @return [Boolean] # Creates an instance of options for {Collection#upsert} # # @param [Integer, #in_seconds, Time, nil] expiry expiration time to associate with the document # @param [Boolean] preserve_expiry if true and the document exists, the server will preserve current expiration # for the document, otherwise will use {expiry} from the operation. # @param [JsonTranscoder, #encode(Object)] transcoder used for encoding # @param [Symbol] durability_level level of durability # +:none+:: # no enhanced durability required for the mutation # +:majority+:: # the mutation must be replicated to a majority of the Data Service nodes # (that is, held in the memory allocated to the bucket) # +:majority_and_persist_to_active+:: # The mutation must be replicated to a majority of the Data Service nodes. # Additionally, it must be persisted (that is, written and synchronised to disk) on the # node hosting the active partition (vBucket) for the data. # +:persist_to_majority+:: # The mutation must be persisted to a majority of the Data Service nodes. # Accordingly, it will be written to disk on those nodes. # @param [Symbol] replicate_to number of nodes to replicate # +:none+:: do not apply any replication requirements. # +:one+:: wait for replication to at least one node. # +:two+:: wait for replication to at least two nodes. # +:three+:: wait for replication to at least three nodes. # @param [Symbol] persist_to number of nodes to persist # +:none+:: do not apply any persistence requirements. # +:active+:: wait for persistence to active node # +:one+:: wait for persistence to at least one node. # +:two+:: wait for persistence to at least two nodes. # +:three+:: wait for persistence to at least three nodes. # +:four+:: wait for persistence to four nodes (active and replicas). # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [Upsert] def initialize(expiry: nil, preserve_expiry: false, transcoder: JsonTranscoder.new, durability_level: :none, replicate_to: :none, persist_to: :none, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @expiry = Utils::Time.extract_expiry_time(expiry) @preserve_expiry = preserve_expiry @transcoder = transcoder if durability_level != :none && (replicate_to != :none || persist_to != :none) raise ArgumentError, "durability_level conflicts with replicate_to and persist_to options" end @persist_to = replicate_to @replicate_to = replicate_to @durability_level = durability_level yield self if block_given? end def to_backend { timeout: Utils::Time.extract_duration(@timeout), expiry: @expiry, preserve_expiry: @preserve_expiry, durability_level: @durability_level, persist_to: @persist_to, replicate_to: @replicate_to, } end end # Options for {Collection#replace} class Replace < Base attr_accessor :expiry # @return [Integer, #in_seconds, nil] attr_accessor :transcoder # @return [JsonTranscoder, #encode(Object)] attr_accessor :cas # @return [Integer, nil] attr_accessor :durability_level # @return [Symbol] attr_accessor :preserve_expiry # @return [Boolean] # Creates an instance of options for {Collection#replace} # # @param [Integer, #in_seconds, nil] expiry expiration time to associate with the document # @param [Boolean] preserve_expiry if true and the document exists, the server will preserve current expiration # for the document, otherwise will use {expiry} from the operation. # @param [JsonTranscoder, #encode(Object)] transcoder used for encoding # @param [Integer, nil] cas a CAS value that will be taken into account on the server side for optimistic concurrency # @param [Symbol] durability_level level of durability # +:none+:: # no enhanced durability required for the mutation # +:majority+:: # the mutation must be replicated to a majority of the Data Service nodes # (that is, held in the memory allocated to the bucket) # +:majority_and_persist_to_active+:: # The mutation must be replicated to a majority of the Data Service nodes. # Additionally, it must be persisted (that is, written and synchronised to disk) on the # node hosting the active partition (vBucket) for the data. # +:persist_to_majority+:: # The mutation must be persisted to a majority of the Data Service nodes. # Accordingly, it will be written to disk on those nodes. # @param [Symbol] replicate_to number of nodes to replicate # +:none+:: do not apply any replication requirements. # +:one+:: wait for replication to at least one node. # +:two+:: wait for replication to at least two nodes. # +:three+:: wait for replication to at least three nodes. # @param [Symbol] persist_to number of nodes to persist # +:none+:: do not apply any persistence requirements. # +:active+:: wait for persistence to active node # +:one+:: wait for persistence to at least one node. # +:two+:: wait for persistence to at least two nodes. # +:three+:: wait for persistence to at least three nodes. # +:four+:: wait for persistence to four nodes (active and replicas). # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [Replace] def initialize(expiry: nil, preserve_expiry: false, transcoder: JsonTranscoder.new, cas: nil, durability_level: :none, replicate_to: :none, persist_to: :none, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @expiry = Utils::Time.extract_expiry_time(expiry) @preserve_expiry = preserve_expiry @transcoder = transcoder @cas = cas if durability_level != :none && (replicate_to != :none || persist_to != :none) raise ArgumentError, "durability_level conflicts with replicate_to and persist_to options" end @persist_to = replicate_to @replicate_to = replicate_to @durability_level = durability_level yield self if block_given? end def to_backend { timeout: Utils::Time.extract_duration(@timeout), expiry: @expiry, preserve_expiry: @preserve_expiry, durability_level: @durability_level, persist_to: @persist_to, replicate_to: @replicate_to, cas: @cas, } end end # Options for {Collection#mutate_in} class MutateIn < Base attr_accessor :expiry # @return [Integer, #in_seconds, nil] attr_accessor :store_semantics # @return [Symbol] attr_accessor :cas # @return [Integer, nil] attr_accessor :durability_level # @return [Symbol] attr_accessor :transcoder # @return [JsonTranscoder, #encode(Object)] attr_accessor :preserve_expiry # @return [Boolean] # Creates an instance of options for {Collection#mutate_in} # # @param [Integer, #in_seconds, Time, nil] expiry expiration time to associate with the document # @param [Boolean] preserve_expiry if true and the document exists, the server will preserve current expiration # for the document, otherwise will use {expiry} from the operation. # @param [Symbol] store_semantics describes how the outer document store semantics on subdoc should act # +:replace+:: replace the document, fail if it does not exist. This is the default # +:upsert+:: replace the document or create if it does not exist # +:insert+:: create the document, fail if it exists # @param [Integer, nil] cas a CAS value that will be taken into account on the server side for optimistic concurrency # @param [Boolean] access_deleted for internal use only: allows access to deleted documents that are in "tombstone" form # @param [Boolean] create_as_deleted for internal use only: allows creating documents in "tombstone" form # @param [Symbol] durability_level level of durability # +:none+:: # no enhanced durability required for the mutation # +:majority+:: # the mutation must be replicated to a majority of the Data Service nodes # (that is, held in the memory allocated to the bucket) # +:majority_and_persist_to_active+:: # The mutation must be replicated to a majority of the Data Service nodes. # Additionally, it must be persisted (that is, written and synchronised to disk) on the # node hosting the active partition (vBucket) for the data. # +:persist_to_majority+:: # The mutation must be persisted to a majority of the Data Service nodes. # Accordingly, it will be written to disk on those nodes. # @param [Symbol] replicate_to number of nodes to replicate # +:none+:: do not apply any replication requirements. # +:one+:: wait for replication to at least one node. # +:two+:: wait for replication to at least two nodes. # +:three+:: wait for replication to at least three nodes. # @param [Symbol] persist_to number of nodes to persist # +:none+:: do not apply any persistence requirements. # +:active+:: wait for persistence to active node # +:one+:: wait for persistence to at least one node. # +:two+:: wait for persistence to at least two nodes. # +:three+:: wait for persistence to at least three nodes. # +:four+:: wait for persistence to four nodes (active and replicas). # @param [JsonTranscoder, #encode(Object)] transcoder used for encoding # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [MutateIn] def initialize(expiry: nil, preserve_expiry: false, store_semantics: :replace, cas: nil, access_deleted: false, create_as_deleted: false, durability_level: :none, replicate_to: :none, persist_to: :none, transcoder: JsonTranscoder.new, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @expiry = Utils::Time.extract_expiry_time(expiry) @preserve_expiry = preserve_expiry @store_semantics = store_semantics @cas = cas @access_deleted = access_deleted @create_as_deleted = create_as_deleted if durability_level != :none && (replicate_to != :none || persist_to != :none) raise ArgumentError, "durability_level conflicts with replicate_to and persist_to options" end @persist_to = replicate_to @replicate_to = replicate_to @durability_level = durability_level @transcoder = transcoder yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), expiry: @expiry, preserve_expiry: @preserve_expiry, durability_level: @durability_level, persist_to: @persist_to, replicate_to: @replicate_to, cas: @cas, store_semantics: @store_semantics, access_deleted: @access_deleted, create_as_deleted: @create_as_deleted, } end # @api private # @return [Boolean] attr_accessor :access_deleted # @api private # @return [Boolean] attr_accessor :create_as_deleted end # Options for {Collection#lookup_in} class LookupIn < Base attr_accessor :transcoder # @return [JsonTranscoder, #decode(String)] # Creates an instance of options for {Collection#lookup_in} # # @param [Boolean] access_deleted for internal use only: allows access to deleted documents that are in "tombstone" form # @param [JsonTranscoder, #decode(String)] transcoder used for encoding # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [LookupIn] self def initialize(access_deleted: false, transcoder: JsonTranscoder.new, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @access_deleted = access_deleted @transcoder = transcoder yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), access_deleted: @access_deleted, } end # @api private # @return [Boolean] attr_accessor :access_deleted end # Options for {BinaryCollection#append} class Append < Base attr_accessor :cas # @return [Integer] # Creates an instance of options for {BinaryCollection#append} # # @param [Integer] cas The default CAS used (0 means no CAS in this context) # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [Append] self def initialize(cas: nil, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @cas = cas yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), cas: @cas, } end end # Options for {BinaryCollection#prepend} class Prepend < Base # @return [Integer] The default CAS used (0 means no CAS in this context) attr_accessor :cas # Creates an instance of options for {BinaryCollection#prepend} # # @param [Integer] cas The default CAS used (0 means no CAS in this context) # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [Prepend] self def initialize(cas: nil, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @cas = cas yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), cas: @cas, } end end # Options for {BinaryCollection#increment} class Increment < Base attr_reader :delta # @return [Integer] attr_accessor :initial # @return [Integer] attr_accessor :expiry # @return [Integer, #in_seconds] attr_accessor :durability_level # @return [Symbol] # Creates an instance of options for {BinaryCollection#increment} # # @param [Integer] delta the delta for the operation # @param [Integer] initial if present, holds the initial value # @param [Integer, #in_seconds, Time, nil] expiry if set, holds the expiration for the operation # @param [Symbol] durability_level level of durability # +:none+:: # no enhanced durability required for the mutation # +:majority+:: # the mutation must be replicated to a majority of the Data Service nodes # (that is, held in the memory allocated to the bucket) # +:majority_and_persist_to_active+:: # The mutation must be replicated to a majority of the Data Service nodes. # Additionally, it must be persisted (that is, written and synchronised to disk) on the # node hosting the active partition (vBucket) for the data. # +:persist_to_majority+:: # The mutation must be persisted to a majority of the Data Service nodes. # Accordingly, it will be written to disk on those nodes. # @param [Symbol] replicate_to number of nodes to replicate # +:none+:: do not apply any replication requirements. # +:one+:: wait for replication to at least one node. # +:two+:: wait for replication to at least two nodes. # +:three+:: wait for replication to at least three nodes. # @param [Symbol] persist_to number of nodes to persist # +:none+:: do not apply any persistence requirements. # +:active+:: wait for persistence to active node # +:one+:: wait for persistence to at least one node. # +:two+:: wait for persistence to at least two nodes. # +:three+:: wait for persistence to at least three nodes. # +:four+:: wait for persistence to four nodes (active and replicas). # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [Increment] self def initialize(delta: 1, initial: nil, expiry: nil, durability_level: :none, replicate_to: :none, persist_to: :none, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) raise ArgumentError, "the delta cannot be less than 0" if delta.negative? super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @delta = delta @initial = initial @expiry = Utils::Time.extract_expiry_time(expiry) if durability_level != :none && (replicate_to != :none || persist_to != :none) raise ArgumentError, "durability_level conflicts with replicate_to and persist_to options" end @persist_to = replicate_to @replicate_to = replicate_to @durability_level = durability_level yield self if block_given? end # @param [Integer] value delta for the operation def delta=(value) raise ArgumentError, "the delta cannot be less than 0" if delta.negative? @delta = value end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), delta: @delta, initial_value: @initial, expiry: @expiry, durability_level: @durability_level, persist_to: @persist_to, replicate_to: @replicate_to, } end end # Options for {BinaryCollection#decrement} class Decrement < Base attr_reader :delta # @return [Integer] attr_accessor :initial # @return [Integer] attr_accessor :expiry # @return [Integer, #in_seconds] attr_accessor :durability_level # @return [Symbol] # Creates an instance of options for {BinaryCollection#decrement} # # @param [Integer] delta the delta for the operation # @param [Integer] initial if present, holds the initial value # @param [Integer, #in_seconds, Time, nil] expiry if set, holds the expiration for the operation # @param [Symbol] durability_level level of durability # +:none+:: # no enhanced durability required for the mutation # +:majority+:: # the mutation must be replicated to a majority of the Data Service nodes # (that is, held in the memory allocated to the bucket) # +:majority_and_persist_to_active+:: # The mutation must be replicated to a majority of the Data Service nodes. # Additionally, it must be persisted (that is, written and synchronised to disk) on the # node hosting the active partition (vBucket) for the data. # +:persist_to_majority+:: # The mutation must be persisted to a majority of the Data Service nodes. # Accordingly, it will be written to disk on those nodes. # @param [Symbol] replicate_to number of nodes to replicate # +:none+:: do not apply any replication requirements. # +:one+:: wait for replication to at least one node. # +:two+:: wait for replication to at least two nodes. # +:three+:: wait for replication to at least three nodes. # @param [Symbol] persist_to number of nodes to persist # +:none+:: do not apply any persistence requirements. # +:active+:: wait for persistence to active node # +:one+:: wait for persistence to at least one node. # +:two+:: wait for persistence to at least two nodes. # +:three+:: wait for persistence to at least three nodes. # +:four+:: wait for persistence to four nodes (active and replicas). # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @yieldparam [Decrement] self def initialize(delta: 1, initial: nil, expiry: nil, durability_level: :none, replicate_to: :none, persist_to: :none, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) raise ArgumentError, "the delta cannot be less than 0" if delta.negative? super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @delta = delta @initial = initial @expiry = Utils::Time.extract_expiry_time(expiry) if durability_level != :none && (replicate_to != :none || persist_to != :none) raise ArgumentError, "durability_level conflicts with replicate_to and persist_to options" end @persist_to = replicate_to @replicate_to = replicate_to @durability_level = durability_level yield self if block_given? end # @param [Integer] value delta for the operation def delta=(value) raise ArgumentError, "the delta cannot be less than 0" if delta.negative? @delta = value end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), delta: @delta, initial_value: @initial, expiry: @expiry, durability_level: @durability_level, persist_to: @persist_to, replicate_to: @replicate_to, } end end # Options for {Datastructures::CouchbaseList#initialize} class CouchbaseList attr_accessor :get_options # @return [Get] attr_accessor :remove_options # @return [Remove] attr_accessor :lookup_in_options # @return [LookupIn] attr_accessor :mutate_in_options # @return [MutateIn] # Creates an instance of options for {CouchbaseList#initialize} # # @param [Get] get_options # @param [Remove] remove_options # @param [LookupIn] lookup_in_options # @param [MutateIn] mutate_in_options # # @yieldparam [CouchbaseList] def initialize(get_options: Get.new, remove_options: Remove.new, lookup_in_options: LookupIn.new, mutate_in_options: MutateIn.new(store_semantics: :upsert)) @get_options = get_options @remove_options = remove_options @lookup_in_options = lookup_in_options @mutate_in_options = mutate_in_options yield self if block_given? end end # Options for {Datastructures::CouchbaseMap#initialize} class CouchbaseMap attr_accessor :get_options # @return [Get] attr_accessor :remove_options # @return [Remove] attr_accessor :lookup_in_options # @return [LookupIn] attr_accessor :mutate_in_options # @return [MutateIn] # Creates an instance of options for {CouchbaseMap#initialize} # # @param [Get] get_options # @param [Remove] remove_options # @param [LookupIn] lookup_in_options # @param [MutateIn] mutate_in_options # # @yieldparam [CouchbaseMap] def initialize(get_options: Get.new, remove_options: Remove.new, lookup_in_options: LookupIn.new, mutate_in_options: MutateIn.new(store_semantics: :upsert)) @get_options = get_options @remove_options = remove_options @lookup_in_options = lookup_in_options @mutate_in_options = mutate_in_options yield self if block_given? end end # Options for {Datastructures::CouchbaseQueue#initialize} class CouchbaseQueue attr_accessor :get_options # @return [Get] attr_accessor :remove_options # @return [Remove] attr_accessor :lookup_in_options # @return [LookupIn] attr_accessor :mutate_in_options # @return [MutateIn] # Creates an instance of options for {CouchbaseQueue#initialize} # # @param [Get] get_options # @param [Remove] remove_options # @param [LookupIn] lookup_in_options # @param [MutateIn] mutate_in_options # # @yieldparam [CouchbaseQueue] def initialize(get_options: Get.new, remove_options: Remove.new, lookup_in_options: LookupIn.new, mutate_in_options: MutateIn.new(store_semantics: :upsert)) @get_options = get_options @remove_options = remove_options @lookup_in_options = lookup_in_options @mutate_in_options = mutate_in_options yield self if block_given? end end # Options for {Datastructures::CouchbaseSet#initialize} class CouchbaseSet attr_accessor :get_options # @return [Get] attr_accessor :remove_options # @return [Remove] attr_accessor :lookup_in_options # @return [LookupIn] attr_accessor :mutate_in_options # @return [MutateIn] # Creates an instance of options for {CouchbaseSet#initialize} # # @param [Get] get_options # @param [Remove] remove_options # @param [LookupIn] lookup_in_options # @param [MutateIn] mutate_in_options # # @yieldparam [CouchbaseSet] def initialize(get_options: Get.new, remove_options: Remove.new, lookup_in_options: LookupIn.new, mutate_in_options: MutateIn.new(store_semantics: :upsert)) @get_options = get_options @remove_options = remove_options @lookup_in_options = lookup_in_options @mutate_in_options = mutate_in_options yield self if block_given? end end # Options for {Couchbase::Cluster.connect} # # @example Pass authenticator object to Options # Cluster.connect("couchbase://localhost", # Options::Cluster(authenticator: PasswordAuthenticator.new("Administrator", "password"))) # # @example Shorter version, more useful for interactive sessions # Cluster.connect("couchbase://localhost", "Administrator", "password") # # @example Authentication with TLS client certificate (note +couchbases://+ schema) # Cluster.connect("couchbases://localhost?trust_certificate=/tmp/ca.pem", # Options::Cluster(authenticator: CertificateAuthenticator.new("/tmp/certificate.pem", "/tmp/private.key"))) # # @see https://docs.couchbase.com/server/current/manage/manage-security/configure-client-certificates.html # # @see .Cluster # class Cluster attr_accessor :authenticator # @return [PasswordAuthenticator, CertificateAuthenticator] attr_accessor :enable_metrics # @return [Boolean] attr_accessor :metrics_emit_interval # @return [nil, Integer, #in_milliseconds] attr_accessor :enable_tracing # @return [Boolean] attr_accessor :orphaned_emit_interval # @return [nil, Integer, #in_milliseconds] attr_accessor :orphaned_sample_size # @return [nil, Integer] attr_accessor :threshold_emit_interval # @return [nil, Integer, #in_milliseconds] attr_accessor :threshold_sample_size # @return [nil, Integer] attr_accessor :key_value_threshold # @return [nil, Integer, #in_milliseconds] attr_accessor :query_threshold # @return [nil, Integer, #in_milliseconds] attr_accessor :view_threshold # @return [nil, Integer, #in_milliseconds] attr_accessor :search_threshold # @return [nil, Integer, #in_milliseconds] attr_accessor :analytics_threshold # @return [nil, Integer, #in_milliseconds] attr_accessor :management_threshold # @return [nil, Integer, #in_milliseconds] attr_accessor :bootstrap_timeout # @return [nil, Integer, #in_milliseconds] attr_accessor :resolve_timeout # @return [nil, Integer, #in_milliseconds] attr_accessor :connect_timeout # @return [nil, Integer, #in_milliseconds] attr_accessor :key_value_timeout # @return [nil, Integer, #in_milliseconds] attr_accessor :view_timeout # @return [nil, Integer, #in_milliseconds] attr_accessor :query_timeout # @return [nil, Integer, #in_milliseconds] attr_accessor :analytics_timeout # @return [nil, Integer, #in_milliseconds] attr_accessor :search_timeout # @return [nil, Integer, #in_milliseconds] attr_accessor :management_timeout # @return [nil, Integer, #in_milliseconds] attr_accessor :dns_srv_timeout # @return [nil, Integer, #in_milliseconds] attr_accessor :tcp_keep_alive_interval # @return [nil, Integer, #in_milliseconds] attr_accessor :config_poll_interval # @return [nil, Integer, #in_milliseconds] attr_accessor :config_poll_floor # @return [nil, Integer, #in_milliseconds] attr_accessor :config_idle_redial_timeout # @return [nil, Integer, #in_milliseconds] attr_accessor :idle_http_connection_timeout # @return [nil, Integer, #in_milliseconds] # Creates an instance of options for {Couchbase::Cluster.connect} # # @param [PasswordAuthenticator, CertificateAuthenticator] authenticator # @param [nil, Integer, #in_milliseconds] key_value_timeout default timeout for Key/Value operations, e.g. {Collection#get} # @param [nil, Integer, #in_milliseconds] view_timeout default timeout for View query # @param [nil, Integer, #in_milliseconds] query_timeout default timeout for N1QL query # @param [nil, Integer, #in_milliseconds] analytics_timeout default timeout for Analytics query # @param [nil, Integer, #in_milliseconds] search_timeout default timeout for Search query # @param [nil, Integer, #in_milliseconds] management_timeout default timeout for management operations # # @see .Cluster # # @yieldparam [Cluster] self def initialize(authenticator: nil, enable_metrics: nil, metrics_emit_interval: nil, enable_tracing: nil, orphaned_emit_interval: nil, orphaned_sample_size: nil, threshold_emit_interval: nil, threshold_sample_size: nil, key_value_threshold: nil, query_threshold: nil, view_threshold: nil, search_threshold: nil, analytics_threshold: nil, management_threshold: nil, bootstrap_timeout: nil, resolve_timeout: nil, connect_timeout: nil, key_value_timeout: nil, view_timeout: nil, query_timeout: nil, analytics_timeout: nil, search_timeout: nil, management_timeout: nil, dns_srv_timeout: nil, tcp_keep_alive_interval: nil, config_poll_interval: nil, config_poll_floor: nil, config_idle_redial_timeout: nil, idle_http_connection_timeout: nil) @authenticator = authenticator @enable_metrics = enable_metrics @metrics_emit_interval = metrics_emit_interval @enable_tracing = enable_tracing @orphaned_emit_interval = orphaned_emit_interval @orphaned_sample_size = orphaned_sample_size @threshold_emit_interval = threshold_emit_interval @threshold_sample_size = threshold_sample_size @key_value_threshold = key_value_threshold @query_threshold = query_threshold @view_threshold = view_threshold @search_threshold = search_threshold @analytics_threshold = analytics_threshold @management_threshold = management_threshold @bootstrap_timeout = bootstrap_timeout @resolve_timeout = resolve_timeout @connect_timeout = connect_timeout @key_value_timeout = key_value_timeout @view_timeout = view_timeout @query_timeout = query_timeout @analytics_timeout = analytics_timeout @search_timeout = search_timeout @management_timeout = management_timeout @dns_srv_timeout = dns_srv_timeout @tcp_keep_alive_interval = tcp_keep_alive_interval @config_poll_interval = config_poll_interval @config_poll_floor = config_poll_floor @config_idle_redial_timeout = config_idle_redial_timeout @idle_http_connection_timeout = idle_http_connection_timeout yield self if block_given? end # @param [String] username # @param [String] password def authenticate(username, password) @authenticator = PasswordAuthenticator.new(username, password) end # @param [String] profile_name The name of the configuration profile to apply (e.g. "wan_development") def apply_profile(profile_name) ConfigProfiles::KNOWN_PROFILES.apply(profile_name, self) end # @api private def to_backend { enable_metrics: @enable_metrics, metrics_emit_interval: Utils::Time.extract_duration(@metrics_emit_interval), enable_tracing: @enable_tracing, orphaned_emit_interval: Utils::Time.extract_duration(@orphaned_emit_interval), orphaned_sample_size: @orphaned_sample_size, threshold_emit_interval: Utils::Time.extract_duration(@threshold_emit_interval), threshold_sample_size: @threshold_sample_size, key_value_threshold: Utils::Time.extract_duration(@key_value_threshold), query_threshold: Utils::Time.extract_duration(@query_threshold), view_threshold: Utils::Time.extract_duration(@view_threshold), search_threshold: Utils::Time.extract_duration(@search_threshold), analytics_threshold: Utils::Time.extract_duration(@analytics_threshold), management_threshold: Utils::Time.extract_duration(@management_threshold), bootstrap_timeout: Utils::Time.extract_duration(@bootstrap_timeout), resolve_timeout: Utils::Time.extract_duration(@resolve_timeout), connect_timeout: Utils::Time.extract_duration(@connect_timeout), key_value_timeout: Utils::Time.extract_duration(@key_value_timeout), view_timeout: Utils::Time.extract_duration(@view_timeout), query_timeout: Utils::Time.extract_duration(@query_timeout), analytics_timeout: Utils::Time.extract_duration(@analytics_timeout), search_timeout: Utils::Time.extract_duration(@search_timeout), management_timeout: Utils::Time.extract_duration(@management_timeout), dns_srv_timeout: Utils::Time.extract_duration(@dns_srv_timeout), tcp_keep_alive_interval: Utils::Time.extract_duration(@tcp_keep_alive_interval), config_poll_interval: Utils::Time.extract_duration(@config_poll_interval), config_poll_floor: Utils::Time.extract_duration(@config_poll_floor), config_idle_redial_timeout: Utils::Time.extract_duration(@config_idle_redial_timeout), idle_http_connection_timeout: Utils::Time.extract_duration(@idle_http_connection_timeout), } end end # Options for {Couchbase::Cluster#diagnostics} class Diagnostics attr_accessor :report_id # @return [String] # Creates an instance of options for {Couchbase::Cluster#diagnostics} # # @param [String] report_id Holds custom report ID. # # @yieldparam [Diagnostics] self def initialize(report_id: nil) @report_id = report_id yield self if block_given? end end # Options for {Couchbase::Bucket#ping} class Ping attr_accessor :report_id # @return [String] attr_accessor :service_types # @return [Array<Symbol>] attr_accessor :timeout # @return [Integer, #in_milliseconds] # Creates an instance of options for {Couchbase::Bucket#ping} # # @param [String] report_id Holds custom report id. # @@param [Array<Symbol>] service_types The service types to limit this diagnostics request # @param [Integer, #in_milliseconds] timeout # # @yieldparam [Ping] self def initialize(report_id: nil, service_types: [:kv, :query, :analytics, :search, :views, :management], timeout: nil) @report_id = report_id @service_types = service_types @timeout = timeout yield self if block_given? end # @api private def to_backend { timeout: Utils::Time.extract_duration(@timeout), service_types: @service_types, report_id: @report_id, } end end # Options for {Couchbase::Cluster#analytics_query} class Analytics < Base attr_accessor :client_context_id # @return [String] attr_accessor :scan_consistency # @return [Symbol] attr_accessor :readonly # @return [Boolean] attr_accessor :priority # @return [Boolean] attr_accessor :transcoder # @return [JsonTranscoder, #decode(String)] attr_accessor :scope_qualifier # @return [String] # Creates new instance of options for {Couchbase::Cluster#analytics_query} # # @param [String] client_context_id provides a custom client context ID for this query # @param [Symbol] scan_consistency specifies level of consistency for the query # +:not_bounded+:: # The index will return whatever state it has to the analytics query engine at the time of query. # # This is the default (for single-statement requests). No timestamp vector is used in the index scan. # This is also the fastest mode, because we avoid the cost of obtaining the vector, and we also avoid # any wait for the index # +:request_plus+:: # The index will wait until all mutations have been processed at the time of request before being processed # in the analytics query engine. # # This implements strong consistency per request. Before processing the request, a current vector is obtained. # The vector is used as a lower bound for the statements in the request. # @param [Boolean] readonly allows explicitly marking a query as being readonly and not mutating any documents on # the server side. # @param [Boolean] priority allows to give certain requests higher priority than others # @param [JsonTranscoder] transcoder to decode rows # @param [Array<#to_json>, nil] positional_parameters parameters to be used as substitution for numbered macros # like +$1+, +$2+ in query string # @param [Hash<String => #to_json>, nil] named_parameters parameters to be used as substitution for named macros # like +$name+ in query string # @param [String, nil] scope_qualifier Associate scope qualifier (also known as +query_context+) with the query. # The qualifier must be in form +{bucket_name}.{scope_name}+ or +default:{bucket_name}.{scope_name}+. # # @param [Integer, #in_milliseconds, nil] timeout # @param [Proc, nil] retry_strategy the custom retry strategy, if set # @param [Hash, nil] client_context the client context data, if set # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request # # @note Either +positional_parameters+ or +named_parameters+ may be specified. # # @yieldparam [Analytics] self def initialize(client_context_id: nil, scan_consistency: nil, readonly: false, priority: nil, transcoder: JsonTranscoder.new, positional_parameters: nil, named_parameters: nil, scope_qualifier: nil, timeout: nil, retry_strategy: nil, client_context: nil, parent_span: nil) raise ArgumentError, "Cannot pass positional and named parameters at the same time" if positional_parameters && named_parameters super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span) @client_context_id = client_context_id @scan_consistency = scan_consistency @readonly = readonly @priority = priority @transcoder = transcoder @positional_parameters = positional_parameters @named_parameters = named_parameters @scope_qualifier = scope_qualifier @raw_parameters = {} yield self if block_given? end # Sets positional parameters for the query # # @param [Array] positional the list of parameters that have to be substituted in the statement def positional_parameters(positional) @positional_parameters = positional @named_parameters = nil end # Sets named parameters for the query # # @param [Hash] named the key/value map of the parameters to substitute in the statement def named_parameters(named) @named_parameters = named @positional_parameters = nil end # Allows providing custom JSON key/value pairs for advanced usage # # @param [String] key the parameter name (key of the JSON property) # @param [Object] value the parameter value (value of the JSON property) def raw(key, value) @raw_parameters[key] = JSON.generate(value) end # @api private def to_backend(scope_name: nil, bucket_name: nil) { timeout: Utils::Time.extract_duration(@timeout), client_context_id: @client_context_id, scan_consistency: @scan_consistency, readonly: @readonly, priority: @priority, positional_parameters: export_positional_parameters, named_parameters: export_named_parameters, raw_parameters: @raw_parameters, scope_qualifier: @scope_qualifier, scope_name: scope_name, bucket_name: bucket_name, } end private # @api private # @return [Array<String>, nil] def export_positional_parameters @positional_parameters&.map { |p| JSON.dump(p) } end # @api private # @return [Hash<String => String>, nil] def export_named_parameters @named_parameters&.each_with_object({}) { |(n, v), o| o[n.to_s] = JSON.dump(v) } end # @api private # @return [Hash<String => #to_json>] attr_reader :raw_parameters end # Options for {Couchbase::Cluster#query} class Query < Base attr_accessor :adhoc # @return [Boolean] attr_accessor :client_context_id # @return [String] attr_accessor :max_parallelism # @return [Integer] attr_accessor :readonly # @return [Boolean] attr_accessor :scan_wait # @return [Integer, #in_milliseconds] attr_accessor :scan_cap # @return [Integer] attr_accessor :pipeline_batch # @return [Integer] attr_accessor :pipeline_cap # @return [Integer] attr_accessor :metrics # @return [Boolean] attr_accessor :profile # @return [Symbol] attr_accessor :flex_index # @return [Boolean] attr_accessor :preserve_expiry # @return [Boolean] attr_accessor :scope_qualifier # @return [String] attr_accessor :transcoder # @return [JsonTranscoder, #decode(String)] # Creates new instance of options for {Couchbase::Cluster#query} # # @param [Boolean] adhoc allows turning this request into a prepared statement query # @param [String, nil] client_context_id provides a custom client context ID for this query # @param [Integer, nil] max_parallelism allows overriding the default maximum parallelism for the query execution # on the server side. # @param [Boolean, nil] readonly allows explicitly marking a query as being readonly and not mutating any # documents on the server side. # @param [Integer, #in_milliseconds, nil] scan_wait The maximum duration (in milliseconds) the query engine # is willing to wait before failing. Allows customizing how long (in milliseconds) the query engine is willing # to wait until the index catches up to whatever scan consistency is asked for in this query. Note that if # +:not_bounded+ consistency level is used, this method doesn't do anything at all. If no value is provided to # this method, the server default is used. # @param [Integer, nil] scan_cap customize the maximum buffered channel size between the indexer and the query # service # @param [Integer, nil] pipeline_cap customize the number of items execution operators can batch for fetch # from the Key Value layer on the server. # @param [Integer, nil] pipeline_batch customize the maximum number of items each execution operator can buffer # between various operators on the server. # @param [Boolean, nil] metrics enables per-request metrics in the trailing section of the query # @param [Symbol] profile customize server profile level for this query # +:off+:: # No profiling information is added to the query response # +:phases+:: # The query response includes a profile section with stats and details about various phases of the query plan # and execution. Three phase times will be included in the +system:active_requests+ and # +system:completed_requests+ monitoring keyspaces. # +:timings+:: # Besides the phase times, the profile section of the query response document will include a full
{'addition_count': 1, 'commit_subject': 'RCBC-227: refactor options for analytics manager', 'deletion_count': 1, 'file_extension': '.rb', 'lang': 'rb', 'license': 'apache-2.0', 'repo_name': 'couchbase/couchbase-ruby-client'}