graphd 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88eb11e1213f9fec8d7a0878d7843fe27c964d1bf58411723a786d05336030dd
-  data.tar.gz: 615be59bdd018561230ef2a94d03b1621944ff8795c35d24b22fa622104097d5
+  metadata.gz: 98359f417fb784ec316e80de7298c05e7b69ba5910de8f85ae168bdfc9aefc4d
+  data.tar.gz: 06374bfbcfb72a0b2d57003d465a2e7d6a87f7337acd51da84d50370bdf1ccc8
 SHA512:
-  metadata.gz: f11e994643bb475fcc61edd2cac76d8e93fbe34cf654e27652e16beb9222af284ae2923d9ae35c80c7c3d1c647bedfcb30ddd00a37f6c4c771b133df45e5f1c2
-  data.tar.gz: eeb3ed744e29ec79eb081a8c323d90ce066fc754800f8afa894daf31397580454826a883fa74850def50df7885fa325765f9e89189e3acc1951bfa05bafc9cd5
+  metadata.gz: a0025a478e2c14db90355a0b644d1424af1c124c35a4bf0db76f8b0b3e3259aab0a3903c4336f69b3716d2eb30764e26c41acb36f4a395b5d023705927ec9a7d
+  data.tar.gz: 57e4df0e40891cbdea1e3afe151bebfc83a3eae70efb61a44808d1b914c82aa3f8de336ca76995c4e9db60614790b4e6d0653d2437fde674784d6951f9f303c9

data/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "bundler" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "daily"

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    graphd (0.4.0)
+    graphd (0.5.0)
+      grpc (~> 1.34.0)
 
 GEM
   remote: https://rubygems.org/

data/examples/timeout_example.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'grpc'
+require_relative '../lib/graphd'
+
+def client_stub
+  # if timeout is exceeded will throw `GRPC::DeadlineExceeded`
+  @client_stub ||= Graphd::ClientStub.new('localhost:9080', timeout: 1)
+end
+
+def client(client_stub)
+  @client ||= Graphd::Client.new(client_stub)
+end
+
+def run
+  dgraph_client = client(client_stub)
+  version = dgraph_client.check_version
+  p version
+end
+
+run

data/graphd.gemspec

@@ -18,6 +18,7 @@ Gem::Specification.new do |spec|
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/thegeorgeous/graphd'
   spec.metadata['changelog_uri'] = 'https://github.com/thegeorgeous/graphd'
+  spec.metadata['documentation_uri'] = 'https://rubydoc.info/gems/graphd/'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

data/lib/graphd/client.rb

@@ -10,6 +10,10 @@ module Graphd
   # client_stub = Graphd::ClientStub.new('localhost:9080')
   # client = Graphd::Cilent.new(client_stub)
   class Client
+    # Create a new instance of Graphd::Client
+    #
+    # @param clients [Array<Graphd::ClientStub>] The stubs that can be used
+    #     to communicate with a DGraph server
     def initialize(*clients)
       raise ClientError unless clients
 
@@ -17,6 +21,9 @@ module Graphd
       @jwt = Api::Jwt.new
     end
 
+    # Get the version of the DGraph server
+    #
+    # @return [String] the version of the DGraph server
     def check_version
       request = Api::Check.new
       response = client.check_version(request)
@@ -27,6 +34,12 @@ module Graphd
       client.alter(operation)
     end
 
+    # Create a new transaction
+    #
+    # @param read_only [true, false] whether the transaction should be read only
+    # @param best_effort [true, false] Enable best-effort queries for the transaction
+    #
+    # @return [Transaction]
     def txn(read_only: false, best_effort: false)
       Transaction.new(self, read_only: read_only, best_effort: best_effort)
     end

data/lib/graphd/client_stub.rb

@@ -5,29 +5,67 @@ require_relative 'api_services_pb'
 
 module Graphd
   # gRPC Client stub for DGraph
+  # This stub is a very thin wrapper over `GRPC::ClientStub`. It exists purely
+  # to provide sensible defaults relevant to DGraph like host and credentials
   class ClientStub
     attr_reader :stub
 
+    # Creates a new Graphd::ClientStub
+    #
+    # @param host [String] the host the stub connects to
+    # @param creds [GRPC::Core::ChannelCredentials|Symbol] the channel credentials, or
+    #     :this_channel_is_insecure, which explicitly indicates that the client
+    #     should be created with an insecure connection. Note: this argument is
+    #     ignored if the channel_override argument is provided.
+    # @param channel_override [GRPC::Core::Channel] a pre-created channel
+    # @param timeout [Number] the default timeout in milliseconds to use in requests
+    #     This will be used to set the deadline for every call made using this stub
+    # @param channel_args [Hash] the channel arguments. Note: this argument is
+    #     ignored if the channel_override argument is provided.
     def initialize(
       host = 'localhost:9080',
       credentials = :this_channel_is_insecure,
-      channel_args = {}
+      channel_override: nil,
+      timeout: nil,
+      channel_args: {}
     )
-      @stub = Api::Dgraph::Stub.new(host, credentials, channel_args)
+      @stub = Api::Dgraph::Stub.new(
+        host,
+        credentials,
+        channel_override: channel_override,
+        timeout: timeout,
+        channel_args: channel_args
+      )
     end
 
+    # Request the version of the DGraph server running on host
+    #
+    # @param request [Api::Check]
+    # @return [Api::Version]
     def check_version(request)
       @stub.check_version(request)
     end
 
+    # Run operations that alter the DGraph db like set schema and drop_all
+    #
+    # @param operation [Api::Operation]
+    # @return [Api::Payload]
     def alter(operation)
       @stub.alter(operation)
     end
 
+    # Query the db
+    #
+    # @param request [Api::Request]
+    # @return [Api::Response]
     def query(request)
       @stub.query(request)
     end
 
+    # Commit a mutation or abort if it fails
+    #
+    # @param transaction_context [Api::TxnContext]
+    # @return [Api::TxnContext]
     def commit_or_abort(transaction_context:)
       @stub.commit_or_abort(transaction_context)
     end

data/lib/graphd/transaction.rb

@@ -1,9 +1,26 @@
 # frozen_string_literal: true
 
 require 'json'
+require_relative 'transaction_error'
 
 module Graphd
+  # A transaction to perform queries and mutations
+  #
+  # A transaction bounds a sequence of queries and mutations that are committed
+  # by Dgraph as a single unit: that is, on commit, either all the changes are
+  # accepted by Dgraph or none are.
   class Transaction
+    # Create a new transaction
+    #
+    # @param client [Graphd::Client] The client for which the transaction needs to be created
+    # @param read_only [true, false] whether the transaction should be read only
+    #     Read-only transactions are ideal for transactions which only involve
+    #     queries. Mutations and commits are not allowed.
+    # @param best_effort [true, false] Enable best-effort queries Best-effort
+    #     queries are faster than normal queries because they bypass the normal
+    #     consensus protocol. For this same reason, best-effort queries cannot
+    #     guarantee to return the latest data. Best-effort queries are only
+    #     supported by read-only transactions.
     def initialize(client, read_only: false, best_effort: false)
       if !read_only && best_effort
         raise TransactionError, 'Best effort transactions are only compatible with read-only transactions'
@@ -30,6 +47,17 @@ module Graphd
       do_request(request)
     end
 
+    # Create or modify an instance of Api::Mutation with the provided configuration
+    #
+    # @param mutation [Api::Mutation] (optional) A mutation to be modified
+    # @param set_obj [Hash] (optional) A Hash that represent a value to be set
+    #     This value will be set the value of `set_json` of `Api::Mutation`
+    # @param del_obj [Hash] (optional) A Hash that represents a value to be deleted
+    #     This value will be set the value of `delete_json` of `Api::Mutation`
+    # @param set_nquads [String] (optional) An N-Quad representing the value to be set for `Api::Mutation`
+    # @param del_nquads [String] (optional) An N-Quad representing the value to be deleted for `Api::Mutation`
+    #
+    # @return [Api::Mutation]
     def create_mutation(mutation: nil, set_obj: nil, del_obj: nil, set_nquads: nil, del_nquads: nil, cond: nil)
       mutation ||= ::Api::Mutation.new
 
@@ -42,6 +70,18 @@ module Graphd
       mutation
     end
 
+    # Create an instance of Api::Request
+    #
+    # @param query [String] (optional) A GraphQL query as a string
+    # @param query [Hash] (optional) A Hash of variables used in the provided query
+    #     The keys can be symbols or strings but not numbers. The values must be
+    #     strings
+    # @param mutations [Array<Api::Mutation>] A list of mutations
+    # @param commit_now [true, false] Indicate that the mutation must be
+    #     immediately committed. This can be used when the mutation needs to be
+    #     committed, without querying anything further.
+    #
+    # @return [Api::Request]
     def create_request(query: nil, variables: nil, mutations: nil, commit_now: nil)
       request = ::Api::Request.new(
         start_ts: @transaction_context.start_ts,
@@ -50,10 +90,12 @@ module Graphd
         best_effort: true
       )
       variables&.each do |key, value|
-        unless key.is_a?(String) && value.is_a?(String)
-          raise TransactionError, 'Values and keys in variable map must be strings'
+        unless key.is_a?(Symbol) || key.is_a?(String)
+          raise TransactionError, 'Keys in variable map must be symbols or strings'
         end
 
+        raise TransactionError, 'Values in variable map must be strings' unless value.is_a?(String)
+
         request.vars[key] = value
       end
 

data/lib/graphd/transaction_error.rb

@@ -1,4 +1,4 @@
-# lib/transaction_error.rb
+# frozen_string_literal: true
 
 module Graphd
   class TransactionError < StandardError

data/lib/graphd/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Graphd
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphd
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - George Thomas
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-12-27 00:00:00.000000000 Z
+date: 2020-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grpc
@@ -33,6 +33,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/dependabot.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
@@ -47,6 +48,7 @@ files:
 - bin/console
 - bin/setup
 - examples/simple_example.rb
+- examples/timeout_example.rb
 - graphd.gemspec
 - lib/graphd.rb
 - lib/graphd/aborted_error.rb
@@ -67,6 +69,7 @@ metadata:
   homepage_uri: https://github.com/thegeorgeous/graphd
   source_code_uri: https://github.com/thegeorgeous/graphd
   changelog_uri: https://github.com/thegeorgeous/graphd
+  documentation_uri: https://rubydoc.info/gems/graphd/
 post_install_message: 
 rdoc_options: []
 require_paths: