libcouchbase 1.0.4 → 1.1.0

data/lib/libcouchbase.rb

@@ -8,6 +8,9 @@ module Libcouchbase
     require 'libcouchbase/callbacks'
     require 'libcouchbase/connection'
 
+    DefaultOpts = Struct.new(:host, :bucket, :username, :password)
+    Defaults = DefaultOpts.new('127.0.0.1', 'default')
+
     class Results
         include Enumerable
 
@@ -33,4 +36,5 @@ module Libcouchbase
     autoload :ResultsEM,     'libcouchbase/results_fiber'
     autoload :ResultsLibuv,  'libcouchbase/results_fiber'
     autoload :ResultsNative, 'libcouchbase/results_native'
+    autoload :SubdocRequest, 'libcouchbase/subdoc_request'
 end

data/lib/libcouchbase/bucket.rb

@@ -164,6 +164,15 @@ module Libcouchbase
             get(key, quiet: true)
         end
 
+        # A helper method for returning a default value if one doesn't exist for the key
+        def fetch(key, value = nil, async: false, **opts)
+            cached_obj = get(key, quiet: true, async: false, extended: false)
+            return cached_obj if cached_obj
+            value = value || yield
+            set(key, value, opts.merge(async: false, extended: false))
+            value
+        end
+
         # Add the item to the database, but fail if the object exists already
         #
         # @param key [String, Symbol] Key used to reference the value.
@@ -534,6 +543,48 @@ module Libcouchbase
             result @connection.touch(**opts), async
         end
 
+        # Perform subdocument operations on a key.
+        #
+        # Yields a request builder to a block and applies the operations performed
+        #
+        # @param [String, Symbol] key
+        #
+        # @yieldparam [Libcouchbase::SubdocRequest] the subdocument request object used to define the request
+        #
+        # @example Perform a subdocument operation using a block
+        #     c.subdoc(:foo) { |subdoc|
+        #       subdoc.get('sub.key')
+        #       subdoc.exists?('other.key')
+        #       subdoc.get_count('some.array')
+        #     } # => ["sub key val", true, 23]
+        #
+        # @example perform a subdocument operation using execute!
+        #     c.subdoc(:foo).get(:bob).execute! # => { age: 13, working: false }
+        #
+        # @example perform multiple subdocument operations using execute!
+        #     c.subdoc(:foo)
+        #      .get(:bob).get(:jane).execute! # => [{ age: 13, working: false }, { age: 47, working: true }]
+        #
+        # @example perform a subdocument mutation operation
+        #     c.subdoc(:foo).counter('bob.age', 1).execute! # => 14
+        def subdoc(key, quiet: @quiet, **opts)
+            if block_given?
+                sd = SubdocRequest.new(key, quiet)
+                yield sd
+                subdoc_execute!(sd, opts)
+            else
+                SubdocRequest.new(key, quiet, bucket: self, exec_opts: opts)
+            end
+        end
+
+        def subdoc_execute!(sd, extended: false, async: false, **opts)
+            promise = @connection.subdoc(sd, opts).then { |resp|
+                raise resp.value if resp.value.is_a?(::Exception)
+                extended ? resp : resp.value
+            }
+            result promise, async
+        end
+
         # Fetch design docs stored in current bucket
         #
         # @return [Libcouchbase::DesignDocs]

data/lib/libcouchbase/connection.rb

@@ -40,6 +40,8 @@ module Libcouchbase
         define_callback function: :callback_remove
         define_callback function: :callback_cbflush
         define_callback function: :callback_http
+        define_callback function: :callback_sdlookup # subdoc lookup
+        define_callback function: :callback_sdmutate
 
         # These are passed with the request
         define_callback function: :viewquery_callback
@@ -58,7 +60,7 @@ module Libcouchbase
         end
 
 
-        def initialize(hosts: '127.0.0.1', bucket: 'default', password: nil, thread: nil, **opts)
+        def initialize(hosts: Defaults.host, bucket: Defaults.bucket, username: Defaults.username, password: Defaults.password, thread: nil, **opts)
             # build host string http://docs.couchbase.com/sdk-api/couchbase-c-client-2.5.6/group__lcb-init.html
             hosts = Array(hosts).flatten.join(',')
             connstr = "couchbase://#{hosts}/#{bucket}"
@@ -95,7 +97,7 @@ module Libcouchbase
             @connection = Ext::CreateSt.new
             @connection[:version] = 3
             @connection[:v][:v3][:connstr]  = FFI::MemoryPointer.from_string(connstr)
-            @connection[:v][:v3][:username] = FFI::MemoryPointer.from_string(bucket.to_s)
+            @connection[:v][:v3][:username] = FFI::MemoryPointer.from_string(username&.to_s || bucket.to_s)
             @connection[:v][:v3][:passwd]   = FFI::MemoryPointer.from_string(password) if password
             @connection[:v][:v3][:io]       = @io_ptr.get_pointer(0)
             @handle_ptr = FFI::MemoryPointer.new :pointer, 1
@@ -133,15 +135,17 @@ module Libcouchbase
                     # Register the callbacks we are interested in
                     Ext.set_bootstrap_callback(@handle, callback(:bootstrap_callback))
 
-                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_get],     callback(:callback_get))
-                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_unlock],  callback(:callback_unlock))
-                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_store],   callback(:callback_store))
-                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_storedur],callback(:callback_storedur))
-                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_counter], callback(:callback_counter))
-                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_touch],   callback(:callback_touch))
-                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_remove],  callback(:callback_remove))
-                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_http],    callback(:callback_http))
-                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_cbflush], callback(:callback_cbflush)) if @flush_enabled
+                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_get],      callback(:callback_get))
+                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_unlock],   callback(:callback_unlock))
+                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_store],    callback(:callback_store))
+                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_storedur], callback(:callback_storedur))
+                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_counter],  callback(:callback_counter))
+                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_touch],    callback(:callback_touch))
+                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_remove],   callback(:callback_remove))
+                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_http],     callback(:callback_http))
+                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_sdlookup], callback(:callback_sdlookup))
+                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_sdmutate], callback(:callback_sdmutate))
+                    Ext.install_callback3(@handle, Ext::CALLBACKTYPE[:callback_cbflush],  callback(:callback_cbflush)) if @flush_enabled
 
                     # Connect to the database
                     err = Ext.connect(@handle)
@@ -453,6 +457,31 @@ module Libcouchbase
             defer.promise
         end
 
+        def subdoc(request, expire_in: nil, ttl: nil, expire_at: nil, cas: nil, **opts)
+            raise 'not connected' unless @handle
+            defer ||= @reactor.defer
+
+            cmd = Ext::CMDSUBDOC.new
+            req = Request.new(cmd, defer, request.key, request)
+            key = cmd_set_key(req, cmd, request.key)
+
+            cmd[:multimode] = request.mode == :mutate ? Ext::CMDSUBDOC::SDMULTI_MODE_MUTATE : Ext::CMDSUBDOC::SDMULTI_MODE_LOOKUP
+            cmd[:specs], cmd[:nspecs] = request.to_specs_array
+
+            cmd[:cas] = cas if cas
+            expire_in ||= ttl
+            cmd[:exptime] = expire_in ? expires_in(expire_in) : expire_at.to_i
+
+            @reactor.schedule {
+                pointer = cmd.to_ptr
+                @requests[pointer.address] = req
+                check_error(key, defer, Ext.subdoc3(@handle, pointer, cmd), subdoc: true)
+                request.free_memory
+            }
+
+            defer.promise
+        end
+
         # http://docs.couchbase.com/sdk-api/couchbase-c-client-2.6.2/group__lcb-flush.html
         def flush(defer: nil)
             raise 'not connected' unless @handle
@@ -608,7 +637,7 @@ module Libcouchbase
             end
         end
 
-        def check_error(key, defer, err)
+        def check_error(key, defer, err, subdoc: false)
             if err != :success
                 error = Error.lookup(err).new("request not scheduled for #{key}")
                 backtrace = caller
@@ -717,6 +746,63 @@ module Libcouchbase
             end
         end
 
+        def callback_sdlookup(handle, type, response)
+            resp = Ext::RESPSUBDOC.new response
+            resp_callback_common(resp, :callback_sdlookup) do |req, cb|
+                subdoc_common(resp, req, cb)
+            end
+        end
+
+        # Only counter returns a result
+        def callback_sdmutate(handle, type, response)
+            resp = Ext::RESPSUBDOC.new response
+            resp_callback_common(resp, :callback_sdmutate) do |req, cb|
+                subdoc_common(resp, req, cb)
+            end
+        end
+
+        def subdoc_common(resp, req, cb)
+            iterval = FFI::MemoryPointer.new(:ulong, 1)
+            cur_res = Ext::SDENTRY.new
+            values = []
+            index = 0
+
+            ignore = req.value.ignore
+            mutation = req.value.mode == :mutate
+
+            loop do
+                check = Ext.sdresult_next(resp, cur_res, iterval)
+                break if check == 0
+
+                if cur_res[:status] == :success
+                    count = cur_res[:nvalue]
+                    if count > 0
+                        result = cur_res[:value].read_string(count)
+                    else
+                        result = true # success response
+                    end
+                    result = "[#{result}]"
+                    values << JSON.parse(result, DECODE_OPTIONS)[0]
+                elsif cur_res[:status] == :subdoc_path_enoent && ignore[mutation ? cur_res[:index] : index]
+                    values << nil
+                else
+                    values << Error.lookup(cur_res[:status]).new("Subdoc #{cb} failed for #{req.key} index #{mutation ? cur_res[:index] : index}")
+                end
+
+                index += 1
+            end
+
+            # Return the single result instead of an array if single
+            is_single = resp[:rflags] & Ext::RESPFLAGS[:resp_f_sdsingle] > 0
+            if is_single
+                values = values.first
+            elsif values.empty? # multiple mutate arrays should return true (same as a single mutate)
+                values = true
+            end
+
+            Response.new(cb, req.key, resp[:cas], values)
+        end
+
         def callback_cbflush(handle, type, response)
             resp = Ext::RESPBASE.new response
             resp_callback_common(resp, :callback_cbflush) do |req, cb|
@@ -756,7 +842,8 @@ module Libcouchbase
             req = @requests.delete(resp[:cookie].address)
             if req
                 begin
-                    if resp[:rc] == :success
+                    # Errors will be provided in the response
+                    if resp[:rc] == :success || resp[:rc] == :subdoc_multi_failure
                         req.defer.resolve(yield(req, callback))
                     else
                         req.defer.reject(Error.lookup(resp[:rc]).new("#{callback} failed for #{req.key}"))

data/lib/libcouchbase/ext/libcouchbase.rb

@@ -1016,6 +1016,46 @@ module Libcouchbase::Ext
   #
   attach_function :n1p_posparam, :lcb_n1p_posparam, [N1QLPARAMS.by_ref, :string, :ulong], ErrorT
 
+  # (Not documented)
+  #
+  # @method n1p_readonly(params, readonly)
+  # @param [N1QLPARAMS] params
+  # @param [Integer] readonly if non-zero, the query will be read-only
+  # @return [ErrorT]
+  # @scope class
+  #
+  attach_function :n1p_readonly, :lcb_n1p_readonly, [N1QLPARAMS.by_ref, :int], ErrorT
+
+  # (Not documented)
+  #
+  # @method n1p_readonly(params, readonly)
+  # @param [N1QLPARAMS] params
+  # @param [Integer] Sets maximum buffered channel size. Use 0 or a negative number to disable.
+  # @return [ErrorT]
+  # @scope class
+  #
+  attach_function :n1p_scancap, :lcb_n1p_scancap, [N1QLPARAMS.by_ref, :int], ErrorT
+
+  # (Not documented)
+  #
+  # @method n1p_readonly(params, readonly)
+  # @param [N1QLPARAMS] params
+  # @param [Integer] maximum number of items each execution operator can buffer between operators.
+  # @return [ErrorT]
+  # @scope class
+  #
+  attach_function :n1p_pipelinecap, :lcb_n1p_pipelinecap, [N1QLPARAMS.by_ref, :int], ErrorT
+
+  # (Not documented)
+  #
+  # @method n1p_readonly(params, readonly)
+  # @param [N1QLPARAMS] params
+  # @param [Integer] number of items execution operators can batch for fetch from the KV
+  # @return [ErrorT]
+  # @scope class
+  #
+  attach_function :n1p_pipelinebatch, :lcb_n1p_pipelinebatch, [N1QLPARAMS.by_ref, :int], ErrorT
+
   # (Not documented)
   #
   # @method n1p_setopt(params, name, n_name, value, n_value)

data/lib/libcouchbase/ext/libcouchbase/cmdsubdoc.rb

@@ -35,14 +35,26 @@ module Libcouchbase::Ext
   #   This field may be left empty, in which case the mode is implicitly
   #   derived from the _first_ command issued.
   class CMDSUBDOC < FFI::Struct
+    # CMD flags
+    UPSERT_DOC = (1<<16) # document is to be created if it does not exist.
+    INSERT_DOC = (1<<17) # document must be created anew. Fail if it exists
+    ACCESS_DELETED = (1<<18) # Access a potentially deleted document.
+
+    SDMULTI_MODE_INVALID = 0
+    SDMULTI_MODE_LOOKUP = 1
+    SDMULTI_MODE_MUTATE = 2
+
     layout :cmdflags, :uint,
            :exptime, :uint,
            :cas, :ulong_long,
            :key, KEYBUF.by_value,
            :hashkey, KEYBUF.by_value,
-           :specs, SDSPEC.by_ref,
+           :specs, :pointer, # ==> SDSPEC.by_ref,
            :nspecs, :ulong,
            :error_index, :pointer,
+
+           # This can either be SDMULTI_MODE_LOOKUP or SDMULTI_MODE_MUTATE
+           # This field may be left empty, in which case the mode is implicitly derived from the _first_ command issued.
            :multimode, :uint
   end
 

data/lib/libcouchbase/ext/libcouchbase/enums.rb

@@ -124,7 +124,8 @@ module Libcouchbase::Ext
     :resp_f_clientgen, 2,
     :resp_f_nmvgen, 4,
     :resp_f_extdata, 8,
-    :resp_f_sdsingle, 16
+    :resp_f_sdsingle, 16,
+    :resp_f_errinfo, 0x20
   ]
 
   # (Not documented)

data/lib/libcouchbase/ext/libcouchbase/sdspec.rb

@@ -17,6 +17,11 @@ module Libcouchbase::Ext
   #   @ref LCB_SDSPEC_SET_VALUE. The contents of the value should be valid
   #   until the operation is scheduled (i.e. lcb_subdoc3())
   class SDSPEC < FFI::Struct
+    MKINTERMEDIATES = (1<<16) # Create intermediate paths
+    XATTRPATH = (1<<18) # Access document XATTR path 
+    XATTR_MACROVALUES = (1<<19) # Access document virtual/materialized path
+    XATTR_DELETED_OK = (1<<20) # Access Xattrs of deleted documents
+
     layout :sdcmd, :uint,
            :options, :uint,
            :path, KEYBUF.by_value,

data/lib/libcouchbase/subdoc_request.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true, encoding: ASCII-8BIT
+
+module Libcouchbase; end;
+class Libcouchbase::SubdocRequest
+
+    def initialize(key, quiet, bucket: nil, exec_opts: nil)
+        @key = key.to_s
+        raise ArgumentError.new("invalid document key #{key.inspect}") unless @key.length > 0
+        @refs = []
+        @mode = nil
+        @quiet = quiet
+        @specs = []
+        @ignore = []
+
+        @bucket = bucket
+        @exec_opts = exec_opts
+    end
+
+    attr_reader :mode, :key, :ignore
+
+    # Internal use only
+    def to_specs_array
+        return @mem if @mem # effectively freezes this object
+        number = @specs.length
+        @mem = FFI::MemoryPointer.new(::Libcouchbase::Ext::SDSPEC, number, false)
+        @specs.each_with_index do |spec, index|
+            struct_bytes = spec.to_ptr.get_bytes(0, ::Libcouchbase::Ext::SDSPEC.size) # (offset, length)
+            @mem[index].put_bytes(0, struct_bytes) # (offset, byte_string)
+        end
+        @specs = nil
+        [@mem, number]
+    end
+
+    # Internal use only
+    def free_memory
+        @refs = nil
+        @mem = nil
+    end
+
+    # When not used in block form
+    def execute!(**opts)
+        opts = @exec_opts.merge(opts)
+        @exec_opts = nil
+        bucket = @bucket
+        @bucket = nil
+        bucket.subdoc_execute!(self, **opts)
+    end
+
+
+    # =========
+    #  Lookups
+    # =========
+
+    [ :get, :exists, :get_count ].each do |cmd|
+        command = :"sdcmd_#{cmd}"
+        define_method cmd do |path, quiet: nil, **opts|
+            quiet = @quiet if quiet.nil?
+            new_spec(quiet, path, command, :lookup)
+            self
+        end
+    end
+    alias_method :exists?, :exists
+
+
+    # ===========
+    #  Mutations
+    # ===========
+
+    def remove(path, quiet: nil, **opts)
+        quiet = @quiet if quiet.nil?
+        new_spec(quiet, path, :sdcmd_remove, :mutate)
+        self
+    end
+
+    [
+        :replace, :dict_add, :dict_upsert, :array_add_first, :array_add_last,
+        :array_add_unique, :array_insert, :counter
+    ].each do |cmd|
+        command = :"sdcmd_#{cmd}"
+        define_method cmd do |path, value, create_intermediates: true, **opts|
+            spec = new_spec(false, path, command, :mutate, create_intermediates)
+            set_value(spec, value)
+            self
+        end
+    end
+
+
+    protected
+
+
+    # http://docs.couchbase.com/sdk-api/couchbase-c-client-2.8.2/group__lcb-subdoc.html#ga53e89dd6b480e81b82fb305d04d92e18
+    def new_spec(quiet, path, cmd, mode, create_intermediates = false)
+        @mode ||= mode
+        raise "unable to perform #{cmd} as mode is currently #{@mode}" if @mode != mode
+
+        spec = ::Libcouchbase::Ext::SDSPEC.new
+        spec[:sdcmd] = ::Libcouchbase::Ext::SUBDOCOP[cmd]
+        spec[:options] = ::Libcouchbase::Ext::SDSPEC::MKINTERMEDIATES if create_intermediates
+
+        loc = path.to_s
+        str = ref(loc)
+        spec[:path][:type] = :kv_copy
+        spec[:path][:contig][:bytes] = str
+        spec[:path][:contig][:nbytes] = loc.bytesize
+
+        @ignore << quiet
+        @specs << spec
+        spec
+    end
+
+    # http://docs.couchbase.com/sdk-api/couchbase-c-client-2.8.2/group__lcb-subdoc.html#ga61009762f6b23ae2a9685ddb888dc406
+    def set_value(spec, value)
+        # Create a JSON version of the value.
+        #  We throw it into an array so strings and numbers etc are valid, then we remove the array.
+        val = [value].to_json[1...-1]
+        str = ref(val)
+        spec[:value][:vtype] = :kv_copy
+        spec[:value][:u_buf][:contig][:bytes] = str
+        spec[:value][:u_buf][:contig][:nbytes] = val.bytesize
+        value
+    end
+
+    # We need to hold a reference to c-strings so they are not GC'd
+    def ref(string)
+        str = ::FFI::MemoryPointer.from_string(string)
+        @refs << str
+        str
+    end
+end