couchbase 3.0.2 → 3.0.3

data/lib/couchbase.rb

@@ -16,3 +16,5 @@ require "couchbase/version"
 require "couchbase/libcouchbase"
 require "couchbase/logger"
 require "couchbase/cluster"
+
+require "couchbase/railtie" if defined?(Rails)

data/lib/couchbase/authenticator.rb

@@ -15,12 +15,34 @@
 module Couchbase
   # Authenticator for username/password credentials
   class PasswordAuthenticator
+    DEFAULT_SASL_MECHANISMS = [:scram_sha512, :scram_sha256, :scram_sha1].freeze
+
     attr_accessor :username
     attr_accessor :password
+    attr_accessor :allowed_sasl_mechanisms
 
+    # Creates a new password authenticator with the default settings.
+    #
+    # @param [String] password the username to use for all authentication requests
+    # @param [String] username the password
     def initialize(username, password)
       @username = username
       @password = password
+      @allowed_sasl_mechanisms = DEFAULT_SASL_MECHANISMS
+    end
+
+    # Creates a LDAP compatible password authenticator which is INSECURE if not used with TLS.
+    #
+    # Please note that this is INSECURE and will leak user credentials on the wire to eavesdroppers. This should
+    # only be enabled in trusted environments.
+    #
+    # @param [String] username the username to use for all authentication.
+    # @param [String] password the password to use alongside the username.
+    # @return [PasswordAuthenticator]
+    def self.ldap_compatible(username, password)
+      new(username, password).tap do |auth|
+        auth.allowed_sasl_mechanisms = [:plain]
+      end
     end
   end
 
@@ -31,6 +53,10 @@ module Couchbase
     attr_accessor :certificate_path
     attr_accessor :key_path
 
+    # Creates a new authenticator with certificate and key paths
+    #
+    # @param [String] certificate_path path to certificate
+    # @param [String] key_path path to private key
     def initialize(certificate_path, key_path)
       @certificate_path = certificate_path
       @key_path = key_path

data/lib/couchbase/binary_collection.rb

@@ -16,6 +16,7 @@ require "couchbase/options"
 require "couchbase/binary_collection_options"
 
 module Couchbase
+  # Allows to perform certain operations on non-JSON documents.
   class BinaryCollection
     alias inspect to_s
 

data/lib/couchbase/bucket.rb

@@ -20,6 +20,7 @@ require "couchbase/view_options"
 require "couchbase/diagnostics"
 
 module Couchbase
+  # Provides access to a Couchbase bucket APIs
   class Bucket
     # @return [String] name of the bucket
     attr_reader :name

data/lib/couchbase/cluster.rb

@@ -12,15 +12,11 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
+require "couchbase/configuration"
 require "couchbase/authenticator"
 require "couchbase/bucket"
 
-require "couchbase/management/user_manager"
-require "couchbase/management/bucket_manager"
-require "couchbase/management/query_index_manager"
-require "couchbase/management/analytics_index_manager"
-require "couchbase/management/search_index_manager"
-
+require "couchbase/management"
 require "couchbase/options"
 
 require "couchbase/search_options"
@@ -29,6 +25,7 @@ require "couchbase/analytics_options"
 require "couchbase/diagnostics"
 
 module Couchbase
+  # The main entry point when connecting to a Couchbase cluster.
   class Cluster
     alias inspect to_s
 
@@ -86,6 +83,14 @@ module Couchbase
     #   cluster.query("SELECT * FROM `travel-sample` WHERE type = $type LIMIT 10",
     #                 Options::Query(named_parameters: {type: "hotel"}, metrics: true))
     #
+    # @example Execute query with consistency requirement. Make sure that the index is in sync with selected mutation
+    #   res = collection.upsert("user:42", {
+    #     "name" => "Brass Doorknob",
+    #     "email" => "brass.doorknob@example.com",
+    #   })
+    #   cluster.query("SELECT name, email FROM `mybucket`",
+    #                 Options::Query(consistent_with: MutationState.new(res.mutation_token)))
+    #
     # @return [QueryResult]
     def query(statement, options = Options::Query.new)
       resp = @backend.document_query(statement, options.to_backend)
@@ -354,42 +359,61 @@ module Couchbase
     #   @param [String] username name of the user
     #   @param [String] password password of the user
     #   @param [Options::Cluster, nil] options custom options when creating the cluster connection
+    #
+    # @overload new(configuration)
+    #   @param [Configuration] configuration configuration object
     def initialize(connection_string, *args)
       credentials = {}
+      open_options = {}
 
-      options = args.shift
-      case options
-      when String
-        credentials[:username] = options
-        credentials[:password] = args.shift
+      if connection_string.is_a?(Configuration)
+        options = connection_string
+        connection_string = options.connection_string
+        credentials[:username] = options.username
+        credentials[:password] = options.password
+        raise ArgumentError, "missing connection_string" unless connection_string
         raise ArgumentError, "missing username" unless credentials[:username]
         raise ArgumentError, "missing password" unless credentials[:password]
-      when Options::Cluster
-        authenticator = options&.authenticator
-        case authenticator
-        when PasswordAuthenticator
-          credentials[:username] = authenticator&.username
-          raise ArgumentError, "missing username" unless credentials[:username]
 
-          credentials[:password] = authenticator&.password
+        open_options[:allowed_sasl_mechanisms] = PasswordAuthenticator::DEFAULT_SASL_MECHANISMS
+      else
+        options = args.shift
+        case options
+        when String
+          credentials[:username] = options
+          credentials[:password] = args.shift
+          raise ArgumentError, "missing username" unless credentials[:username]
           raise ArgumentError, "missing password" unless credentials[:password]
 
-        when CertificateAuthenticator
-          credentials[:certificate_path] = authenticator&.certificate_path
-          raise ArgumentError, "missing certificate path" unless credentials[:certificate_path]
+          open_options[:allowed_sasl_mechanisms] = PasswordAuthenticator::DEFAULT_SASL_MECHANISMS
+        when Options::Cluster
+          authenticator = options&.authenticator
+          case authenticator
+          when PasswordAuthenticator
+            credentials[:username] = authenticator&.username
+            raise ArgumentError, "missing username" unless credentials[:username]
+
+            credentials[:password] = authenticator&.password
+            raise ArgumentError, "missing password" unless credentials[:password]
+
+            open_options[:allowed_sasl_mechanisms] = authenticator&.allowed_sasl_mechanisms
+          when CertificateAuthenticator
+            credentials[:certificate_path] = authenticator&.certificate_path
+            raise ArgumentError, "missing certificate path" unless credentials[:certificate_path]
 
-          credentials[:key_path] = authenticator&.key_path
-          raise ArgumentError, "missing key path" unless credentials[:key_path]
+            credentials[:key_path] = authenticator&.key_path
+            raise ArgumentError, "missing key path" unless credentials[:key_path]
 
+          else
+            raise ArgumentError, "options must have authenticator configured"
+          end
         else
-          raise ArgumentError, "options must have authenticator configured"
+          raise ArgumentError, "unexpected second argument, have to be String or ClusterOptions"
         end
-      else
-        raise ArgumentError, "unexpected second argument, have to be String or ClusterOptions"
       end
 
       @backend = Backend.new
-      @backend.open(connection_string, credentials, {})
+      @backend.open(connection_string, credentials, open_options)
     end
 
     # @api private

data/lib/couchbase/collection.rb

@@ -17,6 +17,7 @@ require "couchbase/collection_options"
 require "couchbase/binary_collection"
 
 module Couchbase
+  # Provides access to all collection APIs
   class Collection
     attr_reader :bucket_name
     attr_reader :scope_name
@@ -142,7 +143,7 @@ module Couchbase
     # Fetches a full document and resets its expiration time to the duration provided
     #
     # @param [String] id the document id which is used to uniquely identify it.
-    # @param [Integer, #in_seconds] expiry the new expiration time for the document
+    # @param [Integer, #in_seconds, Time] expiry the new expiration time for the document
     # @param [Options::GetAndTouch] options request customization
     #
     # @example Retrieve document and prolong its expiration for another 10 seconds
@@ -151,7 +152,7 @@ module Couchbase
     # @return [GetResult]
     def get_and_touch(id, expiry, options = Options::GetAndTouch.new)
       resp = @backend.document_get_and_touch(bucket_name, "#{@scope_name}.#{@name}", id,
-                                             expiry.respond_to?(:in_seconds) ? expiry.public_send(:in_seconds) : expiry,
+                                             Utils::Time.extract_expiry_time(expiry),
                                              options.to_backend)
       GetResult.new do |res|
         res.transcoder = options.transcoder
@@ -258,6 +259,7 @@ module Couchbase
         MutationResult.new do |res|
           res.cas = entry[:cas]
           res.mutation_token = extract_mutation_token(entry)
+          res.error = entry[:error]
         end
       end
     end
@@ -338,6 +340,7 @@ module Couchbase
         MutationResult.new do |res|
           res.cas = entry[:cas]
           res.mutation_token = extract_mutation_token(entry)
+          res.error = entry[:error]
         end
       end
     end
@@ -366,7 +369,7 @@ module Couchbase
     # Update the expiration of the document with the given id
     #
     # @param [String] id the document id which is used to uniquely identify it.
-    # @param [Integer, #in_seconds] expiry new expiration time for the document
+    # @param [Integer, #in_seconds, Time] expiry new expiration time for the document
     # @param [Options::Touch] options request customization
     #
     # @example Reset expiration timer for document to 30 seconds
@@ -375,7 +378,7 @@ module Couchbase
     # @return [MutationResult]
     def touch(id, expiry, options = Options::Touch.new)
       resp = @backend.document_touch(bucket_name, "#{@scope_name}.#{@name}", id,
-                                     expiry.respond_to?(:in_seconds) ? expiry.public_send(:in_seconds) : expiry,
+                                     Utils::Time.extract_expiry_time(expiry),
                                      options.to_backend)
       MutationResult.new do |res|
         res.cas = resp[:cas]
@@ -411,6 +414,11 @@ module Couchbase
     #   ]
     #   collection.lookup_in("customer123", lookup_specs)
     #
+    # @example Retrieve country name and check if pending purchases array is empty
+    #   collection.lookup_in "customer123", [
+    #     LookupInSpec.get("addresses.delivery.country"),
+    #     LookupInSpec.exists("purchases.pending[-1]"),
+    #   ]
     # @return [LookupInResult]
     def lookup_in(id, specs, options = Options::LookupIn.new)
       resp = @backend.document_lookup_in(
@@ -453,6 +461,13 @@ module Couchbase
     #   ]
     #   collection.mutate_in("customer123", mutation_specs, Options::MutateIn(expiry: 10))
     #
+    # @example Write meta attribute, remove array entry and replace email field
+    #   collection.mutate_in("customer123", [
+    #     MutateInSpec.upsert("_framework.model_type", "Customer").xattr,
+    #     MutateInSpec.remove("addresses.billing[2]"),
+    #     MutateInSpec.replace("email", "dougr96@hotmail.com"),
+    #   ])
+    #
     # @return [MutateInResult]
     def mutate_in(id, specs, options = Options::MutateIn.new)
       resp = @backend.document_mutate_in(

data/lib/couchbase/collection_options.rb

@@ -32,6 +32,11 @@ module Couchbase
       # @return [Error::CouchbaseError, nil] error associated with the result, or nil (used in {Collection#get_multi})
       attr_accessor :error
 
+      # @return [Boolean] true if error was not associated with the result (useful for multi-operations)
+      def success?
+        !error
+      end
+
       # @return [String] The encoded content when loading the document
       # @api private
       attr_accessor :encoded
@@ -112,6 +117,11 @@ module Couchbase
       #   {Collection#remove_multi})
       attr_accessor :error
 
+      # @return [Boolean] true if error was not associated with the result (useful for multi-operations)
+      def success?
+        !error
+      end
+
       # @yieldparam [MutationResult] self
       def initialize
         @error = nil

data/lib/couchbase/configuration.rb

@@ -0,0 +1,57 @@
+#    Copyright 2020 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 "yaml"
+require "erb"
+
+module Couchbase
+  class Configuration
+    attr_accessor :connection_string
+    attr_accessor :username
+    attr_accessor :password
+
+    def initialize
+      @connection_string = "couchbase://localhost"
+    end
+
+    def load!(path, environment = default_environment_name)
+      settings = load_yaml(path, environment)
+      load_configuration(settings)
+    end
+
+    private
+
+    def load_configuration(settings)
+      configuration = settings.with_indifferent_access
+      @connection_string = configuration[:connection_string]
+      @username = configuration[:username]
+      @password = configuration[:password]
+    end
+
+    def load_yaml(path, environment)
+      file_content = ERB.new(File.read(path)).result
+      YAML.safe_load(file_content, aliases: :default)[environment]
+    end
+
+    def default_environment_name
+      if defined?(::Rails)
+        ::Rails.env
+      elsif defined?(::Sinatra)
+        ::Sinatra::Base.environment.to_s
+      else
+        ENV["RACK_ENV"] || ENV["COUCHBASE_ENV"] or raise ::Couchbase::Error::NoEnvironment
+      end
+    end
+  end
+end

data/lib/couchbase/datastructures.rb

@@ -12,6 +12,12 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
+module Couchbase
+  # This namespace includes easy-to-use wrappers for various concurrent data-structures.
+  module Datastructures
+  end
+end
+
 require "couchbase/datastructures/couchbase_list"
 require "couchbase/datastructures/couchbase_set"
 require "couchbase/datastructures/couchbase_queue"

data/lib/couchbase/errors.rb

@@ -12,34 +12,59 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
+require "json"
+
 module Couchbase
+  # This namespace contains all error types that the library might raise.
   module Error
     class CouchbaseError < StandardError
+      # @return [Hash] attributes associated with the error
+      attr_reader :context
+
+      def to_s
+        defined?(@context) ? "#{super}, context=#{JSON.generate(@context)}" : super
+      end
     end
 
-    # Common exceptions
+    class InvalidArgument < ArgumentError
+      # @return [Hash] attributes associated with the error
+      attr_reader :context
 
-    class RequestCanceled < CouchbaseError
+      def to_s
+        defined?(@context) ? "#{super}, context=#{JSON.generate(@context)}" : super
+      end
     end
 
-    class InvalidArgument < ArgumentError
+    # Common exceptions
+
+    class RequestCanceled < CouchbaseError
     end
 
     class ServiceNotAvailable < CouchbaseError
     end
 
+    # Indicates an operation failed because there has been an internal error in the server.
     class InternalServerFailure < CouchbaseError
     end
 
+    # Every exception that has to do with authentication problems should either instantiate or subclass from this type.
     class AuthenticationFailure < CouchbaseError
     end
 
     class TemporaryFailure < CouchbaseError
     end
 
+    # Indicates an operation failed because parsing of the input returned with an error.
     class ParsingFailure < CouchbaseError
     end
 
+    # Indicates an optimistic locking failure.
+    #
+    # The operation failed because the specified compare and swap (CAS) value differs from the document's actual CAS
+    # value. This means the document was modified since the original CAS value was acquired.
+    #
+    # The application should usually respond by fetching a fresh version of the document and repeating the failed
+    # operation.
     class CasMismatch < CouchbaseError
     end
 
@@ -58,123 +83,201 @@ module Couchbase
     class IndexExists < CouchbaseError
     end
 
+    # Raised when provided content could not be successfully encoded.
     class EncodingFailure < CouchbaseError
     end
 
+    # Raised when provided content could not be successfully decoded.
     class DecodingFailure < CouchbaseError
     end
 
     class UnsupportedOperation < CouchbaseError
     end
 
+    # The {Timeout} signals that an operation timed out before it could be completed.
+    #
+    # It is important to understand that the timeout itself is always just the effect an underlying cause, never the
+    # issue itself. The root cause might not even be on the application side, also the network and server need to be
+    # taken into account.
+    #
+    # Right now the SDK can throw two different implementations of this class:
+    #
+    # {AmbiguousTimeout}::
+    #   The operation might have caused a side effect on the server and should not be retried without
+    #   actions and checks.
+    #
+    # {UnambiguousTimeout}::
+    #   The operation has not caused a side effect on the server and is safe to retry. This is always the case for
+    #   idempotent operations. For non-idempotent operations it depends on the state the operation was in at the time of
+    #   cancellation.
     class Timeout < CouchbaseError
     end
 
+    # This is a special case of the timeout exception, signaling that the timeout happened with an ambiguous cause.
     class AmbiguousTimeout < Timeout
     end
 
+    # This is a special case of the timeout exception, signaling that the timeout happened with no ambiguous cause.
     class UnambiguousTimeout < Timeout
     end
 
+    # Exception which states that the feature is not available.
     class FeatureNotAvailable < CouchbaseError
     end
 
     # KeyValue exceptions
 
+    # Indicates an operation failed because the key does not exist.
     class DocumentNotFound < CouchbaseError
     end
 
+    # Indicates an operation completed but no successful document was retrievable.
     class DocumentIrretrievable < CouchbaseError
     end
 
+    # Thrown when the server reports a temporary failure that is very likely to be lock-related (like an already locked
+    # key or a bad cas used for unlock).
+    #
+    # See https://issues.couchbase.com/browse/MB-13087 for an explanation of why this is only _likely_ to be
+    # lock-related.
     class DocumentLocked < CouchbaseError
     end
 
+    # Thrown when the request is too big for some reason.
     class ValueTooLarge < CouchbaseError
     end
 
+    # Indicates an operation failed because the key already exists.
     class DocumentExists < CouchbaseError
     end
 
+    # This exception is raised when a durability level has been requested that is not available on the server.
     class DurabilityLevelNotAvailable < CouchbaseError
     end
 
+    # The given durability requirements are currently impossible to achieve, as not enough configured replicas are
+    # currently available.
     class DurabilityImpossible < CouchbaseError
     end
 
+    # The synchronous replication durability work can return an ambiguous error (or we timeout waiting for the response,
+    # which is effectively the same).  Here we know the change is on a majority of replicas, or it's on none.
     class DurabilityAmbiguous < CouchbaseError
     end
 
+    # Returned if an attempt is made to mutate a key which already has a durable write pending.
     class DurableWriteInProgress < CouchbaseError
     end
 
+    # The requested key has a SyncWrite which is being re-committed.
     class DurableWriteReCommitInProgress < CouchbaseError
     end
 
+    # Subdocument exception thrown when a path does not exist in the document. The exact meaning of path existence
+    # depends on the operation and inputs.
     class PathNotFound < CouchbaseError
     end
 
+    # Subdocument exception thrown when the path structure conflicts with the document structure (for example, if a
+    # path mentions foo.bar[0].baz, but foo.bar is actually a JSON object).
     class PathMismatch < CouchbaseError
     end
 
+    # Subdocument exception thrown when path has a syntax error, or path syntax is incorrect for the operation (for
+    # example, if operation requires an array index).
     class PathInvalid < CouchbaseError
     end
 
+    # Subdocument exception thrown when path is too deep to parse. Depth of a path is determined by how many components
+    # (or levels) it contains.
+    #
+    # The current limitation is there to ensure a single parse does not consume too much memory (overloading the
+    # server). This error is similar to other TooDeep errors, which all relate to various validation stages to ensure
+    # the server does not consume too much memory when parsing a single document.
     class PathTooDeep < CouchbaseError
     end
 
     class PathTooBig < CouchbaseError
     end
 
+    # Subdocument exception thrown when proposed value would make the document too deep to parse.
+    #
+    # The current limitation is there to ensure a single parse does not consume too much memory (overloading the
+    # server). This error is similar to other TooDeep errors, which all relate to various validation stages to ensure
+    # the server does not consume too much memory when parsing a single document.
     class ValueTooDeep < CouchbaseError
     end
 
+    # Subdocument exception thrown when the provided value cannot be inserted at the given path.
+    #
+    # It is actually thrown when the delta in an counter operation is valid, but applying that delta would
+    # result in an out-of-range number (server interprets numbers as 64-bit integers).
     class ValueInvalid < CouchbaseError
     end
 
+    # Subdocument exception thrown when the targeted enclosing document itself is not JSON.
     class DocumentNotJson < CouchbaseError
     end
 
+    # Subdocument exception thrown when existing number value in document is too big.
+    #
+    # The value is interpreted as 64 bit on the server side.
     class NumberTooBig < CouchbaseError
     end
 
+    # Subdocument exception thrown when the delta in an arithmetic operation (eg counter) is invalid. In this SDK, this
+    # is equivalent to saying that the delta is zero.
+    #
+    # Note that the server also returns the corresponding error code when the delta value itself is too big, or not a
+    # number, but since the SDK enforces deltas to be of type long, these cases shouldn't come up.
     class DeltaInvalid < CouchbaseError
     end
 
+    # Subdocument exception thrown when a path already exists and it shouldn't
     class PathExists < CouchbaseError
     end
 
+    # Subdocument exception thrown when a macro has been requested which is not recognised by the server.
     class XattrUnknownMacro < CouchbaseError
     end
 
+    # Subdocument exception thrown when more than one xattr key has been requested.
     class XattrInvalidKeyCombo < CouchbaseError
     end
 
+    # Subdocument exception thrown when a virtual attribute has been requested which is not recognised by the server.
     class XattrUnknownVirtualAttribute < CouchbaseError
     end
 
+    # Subdocument exception thrown when the virtual attribute cannot be modified.
     class XattrCannotModifyVirtualAttribute < CouchbaseError
     end
 
     # Query exceptions
 
+    # Indicates an operation failed because there has been an issue with the query planner.
     class PlanningFailure < CouchbaseError
     end
 
+    # Indicates an operation failed because there has been an issue with the query planner or similar.
     class IndexFailure < CouchbaseError
     end
 
+    # Indicates an operation failed because there has been an issue with query prepared statements.
     class PreparedStatementFailure < CouchbaseError
     end
 
     # Analytics exceptions
 
+    # The analytics query failed to compile.
     class CompilationFailure < CouchbaseError
     end
 
+    # Indicates the analytics server job queue is full
     class JobQueueFull < CouchbaseError
     end
 
+    # The queried dataset is not found on the server.
     class DatasetNotFound < CouchbaseError
     end
 
@@ -203,6 +306,7 @@ module Couchbase
     class DesignDocumentNotFound < CouchbaseError
     end
 
+    # The queried view is not found on the server
     class ViewNotFound < CouchbaseError
     end
 
@@ -233,5 +337,9 @@ module Couchbase
 
     class BackendError < CouchbaseError
     end
+
+    # Environment name string cannot be determined
+    class NoEnvironment < CouchbaseError
+    end
   end
 end