libcouchbase 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f194c4e3e8555e79f283ca6871be76d79b4bb480
+  data.tar.gz: b1c06f4435765ab5d796f070e02a8f5dc9ea8942
+SHA512:
+  metadata.gz: 0e5e60d1ee7e2cd4ac7497a719a7c75896fe4204d54c40ed620073bc2b50003dc94f8479436108d875642aa4bbe5cd374629c745e8e624fbf02cb4b8493f3034
+  data.tar.gz: e92e37450112794f8d95be56bcdc2e75d18a7978bb87b042d06a42e215f2af82c61e9bb075625c2dcf5e5210abb1af2050dbcbe75a01f970a383dfdab9eb35aa

data/.gitignore

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

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,35 @@
+language: ruby
+rvm:
+  - ruby-2.3.1
+  - ruby-2.2.5
+  - ruby-head
+  - rubinius-3.62
+  - rubinius
+  - jruby-9.1.5.0
+  - jruby-head
+branches:
+  only:
+    - master
+before_install:
+  - git submodule update --init --recursive
+  - gem install ffi
+  - sudo apt-get install libev-dev
+  - sudo wget http://packages.couchbase.com/releases/4.5.1/couchbase-server-enterprise_4.5.1-ubuntu14.04_amd64.deb
+  - sudo dpkg -i couchbase-server-enterprise_4.5.1-ubuntu14.04_amd64.deb
+  - sleep 4
+  - 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 4
+  - /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 --bucket-password=password123 --enable-flush=1 --wait
+  - /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
+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) 2004-2013 Cotag Media
+
+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 uvrb (Ruby FFI bindings for libuv only)
+Libuv itself [is using Node license](https://github.com/joyent/libuv/blob/master/LICENSE)

data/README.md

@@ -0,0 +1,389 @@
+# libcouchbase FFI bindings for Ruby
+
+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
+
+
+## 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 (currently blocked due to [#3706](https://github.com/rubinius/rubinius/issues/3706))
+
+
+Tested on the following Operating Systems:
+
+* OSX / MacOS
+* Linux
+* Windows
+  * NOTE:: windows support is not complete. This message will be removed once it is fully functional
+
+
+## Usage
+
+First, you need to load the library:
+
+```ruby
+require '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 = Libcouchbase::Bucket.new
+```
+
+To connect to other buckets, other than the default
+
+```ruby
+# Same as Libcouchbase::Bucket.new
+bucket = Libcouchbase::Bucket.new(hosts: '127.0.0.1', bucket: 'default', password: nil)
+
+# To connect to other buckets, you can also specify multiple hosts:
+bucket = Libcouchbase::Bucket.new(hosts: ['cb1.org', 'cb2.org'], bucket: 'app_data', password: 'goodluck')
+```
+
+By default connections use `:quiet` mode. This mean it won't raise
+exceptions when the given key does not exist:
+
+```ruby
+bucket.get(:missing_key)            #=> nil
+```
+
+It could be useful when you are trying to make you code a bit efficient
+by avoiding exception handling. (See `#add` and `#replace` operations).
+You can turn on these exceptions by passing `:quiet => false` 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 three different formats for representing values:
+
+* `:document` (default) format supports most of ruby types which could
+  be mapped to JSON data (hashes, arrays, string, numbers).
+
+* `:plain` This format avoids any conversions to be applied to your
+  data, but your data should be passed as String. This is useful for
+  building custom algorithms or formats.
+
+* `:marshal` Use this format if you'd like to transparently serialize your
+  ruby object with standard `Marshal.dump` and `Marshal.load` methods
+
+The library supports both synchronous and asynchronous mode. In
+asynchronous mode all operations will return control to caller
+without blocking current thread. You can collect references to these
+async operations and then wait for the results on the current thread
+or the results can be processed in a callback.
+
+```ruby
+bucket.put(:some_object, my_object, format: :marshal)
+```
+
+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)
+results << bucket.get(:key2)
+bucket.wait_results(results)          #=> ['key1_val', 'key2_val']
+
+# Is equivalent to:
+bucket.get(:key1, :key2)              #=> ['key1_val', 'key2_val']
+
+# Process result without waiting / blocking the thread at all
+# This will execute on the couchbase reactor loop so it is
+# recommended not to block, 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 #=> {format: :document, 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 add command will fail if the key already exists. It accepts the same
+options as set command above.
+
+```ruby
+bucket.add("foo", "bar")
+bucket.add("foo", "bar", ttl: 30, format: :plain)
+```
+
+
+### Replace
+
+The replace command will fail if the key already exists. It accepts the same
+options as set command above.
+
+```ruby
+bucket.replace("foo", "bar")
+```
+
+
+### Prepend/Append
+
+These commands are meaningful when you are using the `:plain` value format,
+because the concatenation is performed by server which has no idea how
+to merge to JSON values or values in ruby Marshal format.
+
+```ruby
+bucket.set(:foo, "world", format: :plain)
+bucket.append(:foo, "!")
+bucket.prepend(:foo, "Hello, ")
+bucket.get(:foo)                    #=> "Hello, world!"
+```
+
+
+### 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
+```
+
+
+### 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
+n1ql = bucket.n1ql
+n1ql.select('*').from(:default).where('port == 10001')
+res = n1ql.results
+
+# Results are lazily loaded by the enumerator
+# Results are stored for re-use until `res` goes out of scope
+# Actual database query happens here
+res.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
+res.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
+res = 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
+res.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
+res.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: ['*'])
+```
+
+