couchbase 3.0.0.alpha.2 → 3.0.0

data/Rakefile

@@ -24,7 +24,7 @@ end
 task :compile do
   require 'tempfile'
   Dir.chdir(Dir.tmpdir) do
-    sh "ruby #{File.join(__dir__, "ext", "extconf.rb")}"
+    sh "ruby #{File.join(__dir__, 'ext', 'extconf.rb')}"
   end
 end
 
@@ -33,12 +33,16 @@ task :doc do
   input_dir = File.join(__dir__, "lib")
   output_dir = File.join(__dir__, "doc", "couchbase-ruby-client-#{Couchbase::VERSION[:sdk]}")
   rm_rf output_dir
-  sh "yard doc --output-dir #{output_dir} #{input_dir}"
+  sh "yard doc --hide-api private --output-dir #{output_dir} #{input_dir} --main README.md"
   puts "#{File.realpath(output_dir)}/index.html"
 end
 
 task :docs => :doc
 
+task :undocumented => :doc do
+  sh "yard stats --list-undoc --compact"
+end
+
 task :render_git_revision do
   build_version_path = File.join(__dir__, 'ext', 'build_version.hxx.in')
   File.write(build_version_path, File.read(build_version_path).gsub('@BACKEND_GIT_REVISION@', `git rev-parse HEAD`.strip))

data/couchbase.gemspec

@@ -12,7 +12,7 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
-lib = File.expand_path("../lib", __FILE__)
+lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "couchbase/version"
 
@@ -25,22 +25,55 @@ Gem::Specification.new do |spec|
   spec.description = "Modern SDK for Couchbase Server"
   spec.homepage = "https://www.couchbase.com"
   spec.license = "Apache-2.0"
+  spec.required_ruby_version = "~> 2.5"
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/couchbase/couchbase-ruby-client"
-  spec.metadata["changelog_uri"] = "#{spec.metadata["source_code_uri"]}/releases"
+  spec.metadata = {
+    "homepage_uri" => "https://docs.couchbase.com/ruby-sdk/3.0/hello-world/start-using-sdk.html",
+    "bug_tracker_uri" => "https://couchbase.com/issues/browse/RCBC",
+    "mailing_list_uri" => "https://forums.couchbase.com/c/ruby-sdk",
+    "source_code_uri" => "https://github.com/couchbase/couchbase-ruby-client/tree/#{spec.version}",
+    "changelog_uri" => "https://github.com/couchbase/couchbase-ruby-client/releases/tag/#{spec.version}",
+    "documentation_uri" => "https://docs.couchbase.com/sdk-api/couchbase-ruby-client-#{spec.version}/index.html",
+    "github_repo" => "ssh://github.com/couchbase/couchbase-ruby-client",
+  }
 
-  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
-    `git ls-files --recurse-submodules -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    exclude_paths = %w[
+      .idea
+      .github
+      .gitignore
+      .gitmodules
+      bin
+      test
+      spec
+      features
+      test_data
+      ext/third_party/asio/asio/src/examples
+      ext/third_party/asio/asio/src/tests
+      ext/third_party/asio/asio/src/tools
+      ext/third_party/gsl/tests
+      ext/third_party/http_parser/contrib
+      ext/third_party/http_parser/fuzzers
+      ext/third_party/json/contrib
+      ext/third_party/json/doc
+      ext/third_party/json/src/example
+      ext/third_party/json/src/perf
+      ext/third_party/json/src/test
+      ext/third_party/json/tests
+      ext/third_party/snappy/testdata
+      ext/third_party/spdlog/bench
+      ext/third_party/spdlog/example
+      ext/third_party/spdlog/logos
+      ext/third_party/spdlog/scripts
+      ext/third_party/spdlog/tests
+    ]
+    `git ls-files --recurse-submodules -z`
+      .split("\x0")
+      .reject { |f| f.match?(/^(#{Regexp.union(exclude_paths)})/) }
   end
   spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.executables = spec.files.grep(/^exe\//) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
   spec.extensions = ["ext/extconf.rb"]
-  spec.rdoc_options.append('--exclude', 'ext/')
-
-  spec.add_development_dependency "bundler", "~> 2.1"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "minitest", "~> 5.14"
-  spec.add_development_dependency "minitest-reporters", "~> 1.4"
+  spec.rdoc_options << "--exclude" << "ext/"
 end

data/examples/analytics.rb

@@ -0,0 +1,236 @@
+#    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 "couchbase"
+
+include Couchbase # rubocop:disable Style/MixinUsage for brevity
+
+options = Cluster::ClusterOptions.new
+options.authenticate("Administrator", "password")
+cluster = Cluster.connect("couchbase://localhost", options)
+
+bucket_name = "tiny_social"
+dataverse_name = "TinySocial"
+
+# Prepare dataset
+begin
+  cluster.buckets.drop_bucket(bucket_name)
+rescue Error::BucketNotFound
+  # ignore
+end
+
+settings = Management::BucketSettings.new
+settings.name = bucket_name
+settings.bucket_type = :couchbase
+settings.ram_quota_mb = 100
+cluster.buckets.create_bucket(settings)
+loop do
+  sleep 1
+  break if cluster.buckets.get_all_buckets.find { |b| b.name == bucket_name }.healthy?
+end
+
+collection = cluster.bucket(bucket_name).default_collection
+
+# Documents for GleambookUsers dataset
+[
+  {
+    "id" => 1,
+    "alias" => "Margarita",
+    "name" => "MargaritaStoddard",
+    "nickname" => "Mags",
+    "userSince" => "2012-08-20T10:10:00",
+    "friendIds" => [2, 3, 6, 10],
+    "employment" => [
+      {
+        "organizationName" => "Codetechno",
+        "start-date" => "2006-08-06",
+      },
+      {
+        "organizationName" => "geomedia",
+        "start-date" => "2010-06-17",
+        "end-date" => "2010-01-26",
+      },
+    ],
+    "gender" => "F",
+  },
+  {
+    "id" => 2,
+    "alias" => "Isbel",
+    "name" => "IsbelDull",
+    "nickname" => "Izzy",
+    "userSince" => "2011-01-22T10:10:00",
+    "friendIds" => [1, 4],
+    "employment" => [
+      {
+        "organizationName" => "Hexviafind",
+        "startDate" => "2010-04-27",
+      },
+    ],
+  },
+  {
+    "id" => 3,
+    "alias" => "Emory",
+    "name" => "EmoryUnk",
+    "userSince" => "2012-07-10T10:10:00",
+    "friendIds" => [1, 5, 8, 9],
+    "employment" => [
+      {
+        "organizationName" => "geomedia",
+        "startDate" => "2010-06-17",
+        "endDate" => "2010-01-26",
+      },
+    ],
+  },
+].each do |document|
+  collection.upsert("user:#{document['id']}",
+                    document.merge({"type" => "user"}))
+end
+
+# Documents for GleambookMessages dataset
+[
+  {
+    "messageId" => 2,
+    "authorId" => 1,
+    "inResponseTo" => 4,
+    "senderLocation" => [41.66, 80.87],
+    "message" => " dislike x-phone its touch-screen is horrible",
+  },
+  {
+    "messageId" => 3,
+    "authorId" => 2,
+    "inResponseTo" => 4,
+    "senderLocation" => [48.09, 81.01],
+    "message" => " like product-y the plan is amazing",
+  },
+  {
+    "messageId" => 4,
+    "authorId" => 1,
+    "inResponseTo" => 2,
+    "senderLocation" => [37.73, 97.04],
+    "message" => " can't stand acast the network is horrible:(",
+  },
+  {
+    "messageId" => 6,
+    "authorId" => 2,
+    "inResponseTo" => 1,
+    "senderLocation" => [31.5, 75.56],
+    "message" => " like product-z its platform is mind-blowing",
+  },
+  {
+    "messageId" => 8,
+    "authorId" => 1,
+    "inResponseTo" => 11,
+    "senderLocation" => [40.33, 80.87],
+    "message" => " like ccast the 3G is awesome:)",
+  },
+  {
+    "messageId" => 10,
+    "authorId" => 1,
+    "inResponseTo" => 12,
+    "senderLocation" => [42.5, 70.01],
+    "message" => " can't stand product-w the touch-screen is terrible",
+  },
+  {
+    "messageId" => 11,
+    "authorId" => 1,
+    "inResponseTo" => 1,
+    "senderLocation" => [38.97, 77.49],
+    "message" => " can't stand acast its plan is terrible",
+  },
+].each do |document|
+  collection.upsert("message:#{document['messageId']}",
+                    document.merge({"type" => "message"}))
+end
+
+if cluster.analytics_indexes.get_all_datasets.any? { |ds| ds.dataverse_name == dataverse_name }
+  # there are datasets on our dataverse, drop everything and re-create
+  options = Management::AnalyticsIndexManager::DisconnectLinkOptions.new
+  options.dataverse_name = dataverse_name
+  cluster.analytics_indexes.disconnect_link(options)
+  cluster.analytics_indexes.drop_dataverse(dataverse_name)
+end
+
+cluster.analytics_indexes.create_dataverse(dataverse_name)
+
+options = Management::AnalyticsIndexManager::CreateDatasetOptions.new
+options.dataverse_name = dataverse_name
+
+options.condition = '`type` = "user"'
+cluster.analytics_indexes.create_dataset("GleambookUsers", bucket_name, options)
+
+options.condition = '`type` = "message"'
+cluster.analytics_indexes.create_dataset("GleambookMessages", bucket_name, options)
+
+options = Management::AnalyticsIndexManager::ConnectLinkOptions.new
+options.dataverse_name = dataverse_name
+cluster.analytics_indexes.connect_link(options)
+
+sleep(1)
+
+puts "---- inner join"
+res = cluster.analytics_query(
+  "SELECT * FROM #{dataverse_name}.GleambookUsers u, #{dataverse_name}.GleambookMessages m WHERE m.authorId = u.id"
+)
+res.rows.each do |row|
+  puts "#{row['u']['name']}: #{row['m']['message'].inspect}"
+end
+
+# The query language supports SQL's notion of left outer join.
+puts "---- left outer join"
+res = cluster.analytics_query("
+  USE #{dataverse_name};
+  SELECT u.name AS uname, m.message AS message
+  FROM GleambookUsers u
+  LEFT OUTER JOIN GleambookMessages m ON m.authorId = u.id
+")
+res.rows.each do |row|
+  puts "#{row['uname']}: #{row['message'].inspect}"
+end
+
+# Named parameters
+puts "---- named parameters"
+options = Cluster::AnalyticsOptions.new
+options.named_parameters({user_id: 2})
+res = cluster.analytics_query("
+USE #{dataverse_name};
+
+SELECT u.name AS uname
+FROM GleambookUsers u
+WHERE u.id = $user_id
+
+UNION ALL
+
+SELECT VALUE m.message
+FROM GleambookMessages m
+WHERE authorId = $user_id
+", options)
+res.rows.each do |row|
+  p row
+end
+
+# Positional parameters
+puts "---- positional parameters"
+options = Cluster::AnalyticsOptions.new
+options.positional_parameters([2])
+res = cluster.analytics_query("
+USE #{dataverse_name};
+SELECT VALUE user
+FROM GleambookUsers AS user
+WHERE len(user.friendIds) > $1
+", options)
+res.rows.each do |row|
+  puts "#{row['name']}: #{row['friendIds'].size}"
+end
+
+# More query examples at https://docs.couchbase.com/server/current/analytics/3_query.html

data/examples/auth.rb

@@ -0,0 +1,33 @@
+#    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 "couchbase"
+include Couchbase # rubocop:disable Style/MixinUsage for brevity
+
+options = Cluster::ClusterOptions.new
+# initializes {PasswordAuthenticator} internally
+options.authenticate("Administrator", "password")
+Cluster.connect("couchbase://localhost", options)
+
+# the same as above, but more explicit
+options.authenticator = PasswordAuthenticator.new("Administrator", "password")
+Cluster.connect("couchbase://localhost", options)
+
+# shorter version, more useful for interactive sessions
+Cluster.connect("couchbase://localhost", "Administrator", "password")
+
+# authentication with TLS client certificate
+# @see https://docs.couchbase.com/server/current/manage/manage-security/configure-client-certificates.html
+options.authenticator = CertificateAuthenticator.new("/tmp/certificate.pem", "/tmp/private.key")
+Cluster.connect("couchbases://localhost?trust_certificate=/tmp/ca.pem", options)

data/examples/crud.rb

@@ -1,5 +1,19 @@
-require 'couchbase'
-include Couchbase
+#    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 "couchbase"
+include Couchbase # rubocop:disable Style/MixinUsage for brevity
 
 options = Cluster::ClusterOptions.new
 options.authenticate("Administrator", "password")

data/examples/managing_analytics_indexes.rb

@@ -0,0 +1,86 @@
+#    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 "couchbase"
+include Couchbase # rubocop:disable Style/MixinUsage for brevity
+
+def measure(msg)
+  start = Time.now
+  yield
+  printf "%<msg>s in %<elapsed>.2f seconds\n", msg: msg, elapsed: Time.now - start
+end
+
+options = Cluster::ClusterOptions.new
+options.authenticate("Administrator", "password")
+cluster = Cluster.connect("couchbase://localhost", options)
+
+manager = cluster.analytics_indexes
+
+options = Management::AnalyticsIndexManager::DropDatasetOptions.new
+options.ignore_if_does_not_exist = true
+options.dataverse_name = "beer-data"
+manager.drop_dataset("beers", options)
+manager.drop_dataset("breweries", options)
+
+options = Management::AnalyticsIndexManager::DropDataverseOptions.new
+options.ignore_if_does_not_exist = true
+manager.drop_dataverse("beer-data", options)
+
+# Creates a dataverse with the name beer-data to be used to manage other metadata entities.
+manager.create_dataverse("beer-data")
+
+# Creates 2 datasets beers and breweries on the beer-sample bucket and filters the content for each dataset by the value
+# of the type field of the record.
+options = Management::AnalyticsIndexManager::CreateDatasetOptions.new
+options.dataverse_name = "beer-data"
+options.condition = '`type` = "beer"'
+manager.create_dataset("beers", "beer-sample", options)
+
+options = Management::AnalyticsIndexManager::CreateDatasetOptions.new
+options.dataverse_name = "beer-data"
+options.condition = '`type` = "brewery"'
+manager.create_dataset("breweries", "beer-sample", options)
+
+# Creates indexes on the identified fields for the specified types.
+options = Management::AnalyticsIndexManager::CreateIndexOptions.new
+options.dataverse_name = "beer-data"
+manager.create_index("beers_name_idx", "beers", {"name" => "string"}, options)
+manager.create_index("breweries_name_idx", "beers", {"name" => "string"}, options)
+manager.create_index("breweries_loc_idx", "beers", {"geo.lon" => "double", "geo.lat" => "double"}, options)
+
+puts "---- Indexes currently defined on the cluster:"
+manager.get_all_indexes.each_with_index do |index, i|
+  puts "#{i}. #{index.dataverse_name}.#{index.dataset_name}.#{index.name} #{'(primary)' if index.primary?}"
+end
+
+# Drops one of the indexes
+options = Management::AnalyticsIndexManager::DropIndexOptions.new
+options.dataverse_name = "beer-data"
+manager.drop_index("breweries_name_idx", "beers", options)
+
+puts "---- Datasets currently defined on the cluster:"
+manager.get_all_datasets.each_with_index do |dataset, i|
+  puts "#{i}. #{dataset.dataverse_name}.#{dataset.name} (link: #{dataset.link_name}, bucket: #{dataset.bucket_name})"
+end
+
+# Connects all datasets to their Data Service buckets and starts shadowing
+options = Management::AnalyticsIndexManager::ConnectLinkOptions.new
+options.dataverse_name = "beer-data"
+manager.connect_link(options)
+
+puts "---- Pending mutations: #{manager.get_pending_mutations.inspect}"
+
+options = Management::AnalyticsIndexManager::DisconnectLinkOptions.new
+options.dataverse_name = "beer-data"
+manager.disconnect_link(options)