mt-libcouchbase 1.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 10f4f1b98604be3e46e36b461ad511a8f58022631c3aef4daa56f663aed7013c
+  data.tar.gz: 2ab6d76bcc195ab6fcf39cc00990b1aca1560898ef06731f301e82100b58110b
+SHA512:
+  metadata.gz: 01e568b51b54718c8e27b091ab048927d3ff1ac5d5067ce84d7744c3a2151c15f3ca818c03dce4c984e3f970f12236c65fc405ec00e7ee7a7acf50d8580fa575
+  data.tar.gz: 3620b0685c28b7f2beaf9b132dff4220c0837861385d20dbae2025317fd3a0c1416ef3582a9a7e5ac029c584a2b2a1e425ea455eebd937bed20850322f0bb340

data/.gitignore

@@ -0,0 +1,22 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+html
+pkg
+doc
+tmp
+rerun.txt
+Gemfile.lock
+.bundle
+.idea
+*.rbc
+.yardoc
+bin
+Gemfile-custom
+vendor
+*.gem
+
+*.dll
+
+vendor/*

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "ext/libcouchbase"]
+	path = ext/libcouchbase
+	url = https://github.com/couchbase/libcouchbase.git

data/.rspec

@@ -0,0 +1 @@
+--format progress

data/.travis.yml

@@ -0,0 +1,38 @@
+language: ruby
+rvm:
+  - ruby-2.4.2
+  - ruby-2.3.5
+  - ruby-head
+  - jruby-9.1.13.0
+  - jruby-head
+  - rubinius
+  - rubinius-3.86
+branches:
+  only:
+    - master
+before_install:
+  - git submodule update --init --recursive
+  - gem install ffi
+  - sudo apt-get install libev-dev python-httplib2
+  - sudo wget https://packages.couchbase.com/releases/5.1.0/couchbase-server-enterprise_5.1.0-ubuntu14.04_amd64.deb
+  - sudo dpkg -i couchbase-server-enterprise_5.1.0-ubuntu14.04_amd64.deb
+  - sleep 8
+  - sudo service couchbase-server status
+  - /opt/couchbase/bin/couchbase-cli cluster-init -c 127.0.0.1:8091 --cluster-username=admin --cluster-password=password --cluster-ramsize=320 --cluster-index-ramsize=256 --cluster-fts-ramsize=256 --services=data,index,query,fts
+  - sleep 5
+  - /opt/couchbase/bin/couchbase-cli server-info   -c 127.0.0.1:8091 -u admin -p password
+  - /opt/couchbase/bin/couchbase-cli bucket-create -c 127.0.0.1:8091 -u admin -p password --bucket=default --bucket-type=couchbase --bucket-ramsize=160 --bucket-replica=0 --wait
+  - /opt/couchbase/bin/couchbase-cli bucket-create -c 127.0.0.1:8091 -u admin -p password --bucket=test    --bucket-type=couchbase --bucket-ramsize=160 --bucket-replica=0 --enable-flush=1 --wait
+  - sleep 1
+  - /opt/couchbase/bin/couchbase-cli user-manage   -c 127.0.0.1:8091 -u admin -p password --set --rbac-username tester --rbac-password password123 --rbac-name "Auto Tester" --roles admin --auth-domain local
+  - /opt/couchbase/bin/cbrestore -x rehash=1 -b default -B default -u admin -p password ./spec/seed http://127.0.0.1:8091
+before_script:
+  - rake compile
+matrix:
+  allow_failures:
+    - rvm: jruby-head
+    - rvm: ruby-head
+    - rvm: rubinius
+    - rvm: rubinius-3.86
+sudo: required
+dist: trusty

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+gemspec
+
+gem "rubysl", :platform => :rbx

data/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2016 ACAProjects
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+===
+
+This license applies to all parts of the libcouchbase gem (Ruby FFI bindings for libcouchbase only)
+Libcouchbase itself [is using the Couchbase license](https://github.com/couchbase/libcouchbase/blob/master/LICENSE)

data/README.md

@@ -0,0 +1,445 @@
+# libcouchbase FFI bindings for Ruby
+
+[![Build Status](https://secure.travis-ci.org/cotag/libcouchbase.svg)](http://travis-ci.org/cotag/libcouchbase)
+
+An alternative to the official [couchbase-client](https://github.com/couchbase/couchbase-ruby-client)
+
+* This client is non-blocking where possible using Fibers, which makes it simple to write performant code in Frameworks like [Rails](http://rubyonrails.org/).
+* Client is threadsafe and reentrant
+
+This is a low level wrapper around libcouchbase. For a more friendly ActiveModel interface see [couchbase-orm](https://github.com/acaprojects/couchbase-orm)
+
+## Couchbase 5 Changes
+
+The Couchbase 5 Admin Console blows away flags on documents if you edit them in the interface.
+Flags were being used to store document formats, however these were mainly implemented for compatibility with the defunct official client.
+
+
+To prevent this being an issue we've made the following changes from version 1.2 of this library:
+
+1. All writes will result in valid JSON being saved to the database
+   * No more `raw strings` they will be saved as `"raw strings"`
+   * Existing raw strings will still be read correctly
+2. Since there are no more raw strings, append / prepend are no longer needed (not that we ever used them)
+
+
+## Runtime Support:
+
+* Native Ruby
+  * Blocks the current thread while performing operations
+  * Multiple operations can occur simultaneously on different threads
+  * For [Rails](http://rubyonrails.org/) and similar, this has optimal performance when running on [Puma](http://puma.io/)
+* [EventMachine](https://github.com/eventmachine/eventmachine)
+  * Requires the use of [em-synchrony](https://github.com/igrigorik/em-synchrony) or for the EM run block to be [wrapped by a fiber](https://github.com/igrigorik/em-http-request/blob/master/examples/fibered-http.rb#L27)
+  * When running [Rails](http://rubyonrails.org/) you'll have best results with [Thin](https://github.com/macournoyer/thin) and [Rack Fiber Pool](https://github.com/alebsack/rack-fiber_pool)
+  * Requests block the current Fiber, yielding so the reactor loop is not blocked
+* [Libuv](https://github.com/cotag/libuv)
+  * When running [Rails](http://rubyonrails.org/) you'll have best results with [SpiderGazelle](https://github.com/cotag/spider-gazelle)
+  * Requests block the current Fiber, yielding so the reactor loop is not blocked
+
+Syntax is the same across all runtimes and you can perform multiple operations simultaneously then wait for the results of those operations.
+
+Operations are also aware of the context they are being executed in.
+For instance if you perform a request in an EventMachine thread pool, it will execute as Native Ruby and on the event loop it'll be non-blocking.
+
+
+## Installation
+
+This GEM includes the [libcouchbase c-library](https://github.com/couchbase/libcouchbase) with requires [cmake](https://cmake.org/) for the build process.
+The library is built on installation.
+
+* Ensure [cmake](https://cmake.org/install/) is installed
+* Run `gem install libcouchbase`
+
+
+The library is designed to run anywhere [Rails](http://rubyonrails.org/) runs:
+
+* Ruby 2.2+
+* JRuby 9.1+
+* Rubinius 3.76+
+
+
+Tested on the following Operating Systems:
+
+* OSX / MacOS
+* Linux
+* Windows
+  * Ruby x64 2.4+ with MSYS2 DevKit
+
+
+## Usage
+
+First, you need to load the library:
+
+```ruby
+require 'mt-libcouchbase'
+```
+
+The client will automatically adjust configuration when the cluster rebalances its nodes when nodes are added or deleted therefore this client is "smart".
+By default the client will connect to the default bucket on localhost.
+
+```ruby
+bucket = MTLibcouchbase::Bucket.new
+```
+
+To connect to other buckets, other than the default
+
+```ruby
+# Same as Libcouchbase::Bucket.new
+bucket = MTLibcouchbase::Bucket.new(hosts: '127.0.0.1', bucket: 'default', password: nil)
+
+# To connect to other buckets, you can also specify multiple hosts:
+bucket = MTLibcouchbase::Bucket.new(hosts: ['cb1.org', 'cb2.org'], bucket: 'app_data', password: 'goodluck')
+```
+
+Connections can be configured to use `:quiet` mode. This mean it won't raise
+exceptions when the given key does not exist:
+
+```ruby
+bucket.quiet = true
+bucket.get(:missing_key)            #=> nil
+```
+
+It could be useful avoiding exception handling. (See `#add` and `#replace` operations).
+You can turn off these exceptions by passing `:quiet => true` when you
+are instantiating the connection or change corresponding attribute:
+
+```ruby
+bucket.quiet = false
+bucket.get("missing-key")                    #=> raise Libcouchbase::Error::KeyNotFound
+bucket.get("missing-key", :quiet => true)    #=> nil
+```
+
+
+The library supports both synchronous and asynchronous operations.
+In asynchronous mode all operations will return control to caller
+without blocking current thread. By default all operations are
+synchronous, using Fibers on event loops to prevent blocking the
+reactor. Use asynchronous operations if you want mulitple operations
+to execute in parallel.
+
+
+```ruby
+# Perform operations in Async and then wait for the results
+results = []
+results << bucket.get(:key1, async: true)
+results << bucket.get(:key2, async: true)
+bucket.wait_results(results)          #=> ['key1_val', 'key2_val']
+
+# Is equivalent to:
+bucket.get(:key1, :key2)              #=> ['key1_val', 'key2_val']
+
+# Process result without waiting or blocking the thread at all
+# This will execute on the couchbase reactor loop so it is
+# recommended not to block in the callback - spin up a new thread
+# or schedule the work to occur next_tick etc
+promise = bucket.get(:key1, async: true)
+promise.then  { |result| puts result }
+promise.catch { |error|  puts error  }
+promise.finally { puts 'operation complete' }
+```
+
+
+### Get
+
+```ruby
+val = bucket.get("foo")
+
+# Get extended details
+result = bucket.get("foo", extended: true)
+result.key      #=> "foo"
+result.value    #=> {some: "value"}
+result.cas      #=> 123445
+result.metadata #=> {flags: 0}
+```
+
+
+Get multiple values. In quiet mode will put `nil` values on missing
+positions:
+
+```ruby
+vals = bucket.get(:foo, :bar, "baz")
+```
+
+Hash-like syntax
+
+```ruby
+val = bucket[:foo]
+```
+
+Return a key-value hash
+
+```ruby
+val = bucket.get(:foo, :bar, "baz", assemble_hash: true)
+val #=> {:foo => val1, :bar => val2, "baz" => val3}
+```
+
+
+### Touch
+
+```ruby
+# Expire in 30 seconds
+bucket.touch(:foo, expire_in: 30
+bucket.touch(:foo, ttl: 30)
+bucket.touch(:foo, expire_at: (Time.now + 30))
+```
+
+
+### Set
+
+The set command will unconditionally store an object in couchbase.
+
+```ruby
+bucket.add("foo", "bar")
+bucket.add("foo", "bar", ttl: 30)
+```
+
+
+### Add
+
+The add command will fail if the key already exists.
+
+```ruby
+bucket.add("foo", "bar")
+bucket.add("foo", "bar", ttl: 30)
+```
+
+
+### Replace
+
+The replace command will fail if the key doesn't already exist.
+
+```ruby
+bucket.replace("foo", "bar")
+```
+
+
+### Increment/Decrement
+
+These commands increment the value assigned to the key.
+A Couchbase increment is atomic on a distributed system.
+
+```ruby
+bucket.set(:foo, 1)
+bucket.incr(:foo)           #=> 2
+bucket.incr(:foo, delta: 2) #=> 4
+bucket.incr(:foo, 2)        #=> 6
+bucket.incr(:foo, -1)       #=> 5
+
+bucket.decr(:foo)           #=> 4
+bucket.decr(:foo, 2)        #=> 2
+
+bucket.incr(:missing1, initial: 10)      #=> 10
+bucket.incr(:missing1, initial: 10)      #=> 11
+bucket.incr(:missing2, create: true)     #=> 0
+bucket.incr(:missing2, create: true)     #=> 1
+```
+
+
+### Delete
+
+```ruby
+bucket.delete(:foo)
+bucket.delete(:foo, cas: 8835713818674332672)
+```
+
+
+### Flush
+
+Delete all items in the bucket. This must be enabled on the cluster to work
+
+```ruby
+bucket.flush
+```
+
+### Subdocument queries
+
+These allow you to modify keys within documents. There is a block form.
+
+```ruby
+c.subdoc(:foo) { |subdoc|
+    subdoc.get('sub.key')
+    subdoc.exists?('other.key')
+    subdoc.get_count('some.array')
+} # => ["sub key val", true, 23]
+```
+
+There is an inline form
+
+```ruby
+c.subdoc(:foo).get(:bob).execute! # => { age: 13, working: false }
+c.subdoc(:foo)
+    .get(:bob)
+    .get(:jane)
+    .execute! # => [{ age: 13, working: false }, { age: 47, working: true }]
+```
+
+You can't perform lookups and mutations in the same request.
+
+```ruby
+# multi-mutation example
+c.subdoc(:foo)
+    .counter('bob.age', 1)
+    .dict_upsert('bob.address', {
+        number: 23
+        street: 'Daily Ave'
+        suburb: 'Some Town'
+    }).execute! # => 14 (the new counter value)
+```
+
+By default, subkeys are created if they don't exist
+
+```ruby
+c.put(:some_key, {name: 'bob'})
+c.subdoc(:some_key).dict_add('non.existant.key', {
+  random: 123,
+  hash: 'values'
+}).execute! 
+```
+
+Possible lookup operations are:
+
+* `get`
+* `exists?`
+* `get_count`
+
+Possible mutation operations
+
+* `counter` increments the subkey by integer value passed
+* `dict_upsert` replaces the subkey with value passed
+* `dict_add`
+* `array_add_first`
+* `array_add_last`
+* `array_add_unique`
+* `array_insert`
+* `replace`
+
+You can see additional docs here: https://developer.couchbase.com/documentation/server/current/sdk/subdocument-operations.html
+
+
+### Views (Map/Reduce queries)
+
+If you store structured data, they will be treated as documents and you
+can handle them in map/reduce function from Couchbase Views. For example,
+store a couple of posts using memcached API:
+
+```ruby
+    c['biking'] = {:title => 'Biking',
+                   :body => 'My biggest hobby is mountainbiking. The other day...',
+                   :date => '2009/01/30 18:04:11'}
+    c['bought-a-cat'] = {:title => 'Bought a Cat',
+                         :body => 'I went to the the pet store earlier and brought home a little kitty...',
+                         :date => '2009/01/30 20:04:11'}
+    c['hello-world'] = {:title => 'Hello World',
+                        :body => 'Well hello and welcome to my new blog...',
+                        :date => '2009/01/15 15:52:20'}
+```
+
+Now let's create design doc with sample view and save it in file
+'blog.json':
+
+```JSON
+    {
+      "_id": "_design/blog",
+      "language": "javascript",
+      "views": {
+        "recent_posts": {
+          "map": "function(doc){if(doc.date && doc.title){emit(doc.date, doc.title);}}"
+        }
+      }
+    }
+```
+
+This design document could be loaded into the database like this (also you can
+pass the ruby Hash or String with JSON encoded document):
+
+```ruby
+    c.save_design_doc(File.open('blog.json'))
+```
+
+To execute view you need to fetch it from design document `_design/blog`:
+
+```ruby
+    blog = c.design_docs['blog']
+    blog.views                       #=> ["recent_posts"]
+
+    # Returns an Enumerator
+    res = blog.view('recent_posts')  #=> #<Libcouchbase::Results:0x007fbaed12c988>
+
+    # Results are lazily loaded by the enumerator
+    # Results are stored for re-use until `res` goes out of scope
+    # Actual database query happens here, by default documents are included
+    res.each do |row|
+        # Returns extended results by default
+        row.key
+        row.value
+        row.cas
+        row.metadata #=> {emitted: val, geometry: spatial_val, format: :document, flags: 0}
+    end
+
+    # You can however stream results to save memory and the results are not saved
+    res.stream do |row|
+        # Row is cleaned up as soon as possible
+    end
+
+    # For IDs only:
+    res = blog.view(:recent_posts, include_docs: false)
+```
+
+
+### N1QL Queries
+
+If N1QL indexes have been created, then you can query them
+
+```ruby
+results = bucket.n1ql
+  .select('*')
+  .from(:default)
+  .where('port == 10001')
+  .results
+
+# Results are lazily loaded by the enumerator
+# Results are stored for re-use until `results` goes out of scope
+# Actual database query happens here
+results.each do |row|
+    # Each row is a Hash of the data requested
+end
+
+# You can however stream results to save memory and the results are not saved
+results.stream do |row|
+    # Row is cleaned up as soon as possible
+end
+```
+
+
+### Full Text Search
+
+If Full Text Search indexes have been created, then you can query them
+
+```ruby
+results = bucket.full_text_search(:index_name, 'query')
+
+# Results are lazily loaded by the enumerator
+# Results are stored for re-use until `res` goes out of scope
+# Actual database query happens here
+results.each do |row|
+    # Each row is a Hash of the data requested
+end
+
+# You can however stream results to save memory and the results are not saved
+results.stream do |row|
+    # Row is cleaned up as soon as possible
+end
+```
+
+Full text search supports more complex queries, you can pass in a Hash as the query
+and provide any other options supported by FTS: http://developer.couchbase.com/documentation/server/current/fts/fts-queries.html
+
+```ruby
+bucket.full_text_search(:index_name, {
+    boost: 1,
+    query: "geo.accuracy:rooftop"
+}, size: 10, from: 0, explain: true, fields: ['*'])
+```
+
+

data/Rakefile

@@ -0,0 +1,76 @@
+require 'rubygems'
+require 'rspec/core/rake_task'  # testing framework
+require 'yard'                  # yard documentation
+require 'ffi'                   # loads the extension
+require 'rake/clean'            # for the :clobber rake task
+require File.expand_path('../lib/mt-libcouchbase/ext/tasks', __FILE__)    # platform specific rake tasks used by compile
+
+
+
+# By default we don't run network tests
+task :default => :limited_spec
+RSpec::Core::RakeTask.new(:limited_spec) do |t|
+    # Exclude full text search tests until we can automate index creation
+    t.rspec_opts = "--tag ~full_text_search --tag ~n1ql_query --fail-fast"
+end
+RSpec::Core::RakeTask.new(:spec)
+
+
+desc 'Run all tests'
+task :test => [:spec]
+
+
+YARD::Rake::YardocTask.new do |t|
+    t.files   = ['lib/**/*.rb', '-', 'ext/README.md', 'README.md']
+end
+
+
+desc 'Compile mt-libcouchbase from submodule'
+if FFI::Platform.windows?
+    task :compile do
+        puts "See windows_build.md for build instructions"
+    end
+else
+    task :compile => ["ext/libcouchbase/build/lib/libcouchbase_libuv.#{FFI::Platform::LIBSUFFIX}"]
+    CLOBBER.include("ext/libcouchbase/build/lib/libcouchbase_libuv.#{FFI::Platform::LIBSUFFIX}")
+end
+
+
+# NOTE:: Generated on OSX
+desc 'Generate the FFI bindings'
+task :generate_bindings do
+    require "ffi/gen"
+
+    # NOTE:: you must export the include dir:
+    # export CPATH=./ext/libcouchbase/include/
+    #
+    # Once generated we need to:
+    # * adjust the ffi_lib path:
+    #   ffi_lib ::File.expand_path("../../../../ext/libcouchbase/build/lib/libcouchbase_libuv.#{FFI::Platform::LIBSUFFIX}", __FILE__)
+    # * Rename some structs strings to pointers
+    #   create_st3.rb -> connstr, username, passwd
+    #   cmdhttp.rb -> body, reqhandle, content_type, username, password, host
+    #   cmdfts.rb -> query
+    #   respfts.rb -> row
+    #   respviewquery.rb -> value, geometry, docid
+    #   respn1ql.rb -> row
+
+    FFI::Gen.generate(
+        module_name: "MTLibcouchbase::Ext",
+        ffi_lib:     "mt-libcouchbase",
+        require_path: "mt-libcouchbase/ext/mt-libcouchbase",
+        headers:     [
+            "./ext/libcouchbase/include/libcouchbase/couchbase.h",
+            "./ext/libcouchbase/include/libcouchbase/error.h",
+            "./ext/libcouchbase/include/libcouchbase/views.h",
+            "./ext/libcouchbase/include/libcouchbase/subdoc.h",
+            "./ext/libcouchbase/include/libcouchbase/n1ql.h",
+            "./ext/libcouchbase/include/libcouchbase/cbft.h",
+            "./ext/libcouchbase/include/libcouchbase/kvbuf.h"
+        ],
+        # Searching for stdarg.h
+        cflags:      ["-I/System/Library/Frameworks/Kernel.framework/Versions/A/Headers"],
+        prefixes:    ["LCB_", "lcb_"],
+        output:      "libcouchbase.rb"
+    )
+end

data/ext/README.md

@@ -0,0 +1,6 @@
+To compile a libcouchbase.(so|dll|dylib) go to root directory of libuv project and run:
+
+```shell
+git submodule update --init
+rake compile
+```

data/ext/Rakefile

@@ -0,0 +1,19 @@
+
+require 'rubygems'
+require 'ffi'
+require 'rake/clean'
+require File.expand_path('../../lib/mt-libcouchbase/ext/tasks', __FILE__)
+
+
+Dir.chdir File.expand_path("../../", __FILE__)
+
+
+task :default => :libcouchbase
+
+desc "Compile libcouchbase from submodule"
+if FFI::Platform.windows?
+    task :libcouchbase do; end
+else
+    task :libcouchbase => ["ext/libcouchbase/build/lib/libcouchbase_libuv.#{FFI::Platform::LIBSUFFIX}"]
+    CLOBBER.include("ext/libcouchbase/build/lib/libcouchbase_libuv.#{FFI::Platform::LIBSUFFIX}")
+end