statelydb 0.1.1

data/lib/transaction/transaction.rb

@@ -0,0 +1,398 @@
+# frozen_string_literal: true
+
+module StatelyDB
+  module Transaction
+    # Transaction coordinates sending requests and waiting for responses. Consumers should not need
+    # to interact with this class directly, but instead use the methods provided by the StatelyDB::Client.
+    #
+    # The example below demonstrates using a transaction, which accepts a block. The lines in the block
+    # are executed within the context of the transaction. The transaction is committed when the block
+    # completes successfully, OR is aborted if an exception is raised.
+    #
+    # @example
+    #   result = client.transaction do |tx|
+    #     key_path = StatelyDB::KeyPath.with('movie', 'The Shining')
+    #     movie = tx.get(key_path:)
+    #     tx.put(item: movie)
+    #   end
+    #
+    class Transaction
+      # Result represents the results of a transaction
+      #
+      # @attr_reader puts [Array<StatelyDB::Item>] the items that were put
+      # @attr_reader deletes [Array<String>] the key paths that were deleted
+      class Result
+        # puts is an array of StatelyDB::Items that were put
+        # @return [Array<StatelyDB::Item>]
+        attr_reader :puts
+
+        # deletes is an array of key paths that were deleted
+        # @return [Array<String>]
+        attr_reader :deletes
+
+        # Initialize a new Result
+        #
+        # @param puts [Array<StatelyDB::Item>] the items that were put
+        # @param deletes [Array<String>] the key paths that were deleted
+        def initialize(puts:, deletes:)
+          @puts = puts
+          @deletes = deletes
+        end
+      end
+
+      # Initialize a new Transaction
+      #
+      # @param stub [Stately::Db::DatabaseService::Stub] a StatelyDB gRPC stub
+      # @param store_id [Integer] the StatelyDB Store to transact against
+      # @param schema [StatelyDB::Schema] the schema to use for marshalling and unmarshalling Items
+      def initialize(stub:, store_id:, schema:)
+        @stub = stub
+        @store_id = store_id
+        @schema = schema
+        @is_transaction_open = false
+
+        # A queue of outbound requests
+        @outgoing_requests = StatelyDB::Transaction::Queue.new
+      end
+
+      # Send a request and wait for a response
+      #
+      # @param req [Stately::Db::TransactionRequest] the request to send
+      # @return [Stately::Db::TransactionResponse] the response
+      # @api private
+      # @!visibility private
+      def request_response(req)
+        request_only(req)
+        begin
+          resp = @incoming_responses.next
+          if req.message_id != resp.message_id
+            raise "Message ID mismatch: request #{req.message_id} != response #{resp.message_id}"
+          end
+          raise "Response type mismatch" if infer_response_type_from_request(req) != infer_response_type_from_response(resp)
+
+          resp
+        rescue StopIteration
+          nil
+        end
+      end
+
+      # Send a request and don't wait for a response
+      #
+      # @param req [Stately::Db::TransactionRequest] the request to send
+      # @return [void] nil
+      # @api private
+      # @!visibility private
+      def request_only(req)
+        req.message_id = @outgoing_requests.next_message_id
+        @outgoing_requests.push(req)
+        nil
+      end
+
+      # Send a request and process all responses, until we receive a finished message. This is used for list operations.
+      # Each response is processed by the block passed to this method, and the response for this method is a token.
+      #
+      # @param req [Stately::Db::TransactionRequest] the request to send
+      # @yieldparam resp [Stately::Db::TransactionListResponse] the response
+      # @return [Stately::Db::ListToken] the token
+      # @example
+      #   request_list_responses(req) do |resp|
+      #     resp.result.items.each do |result|
+      #       puts result.item.key_path
+      #     end
+      # @api private
+      # @!visibility private
+      def request_list_responses(req)
+        request_only(req)
+        token = nil
+        loop do
+          resp = @incoming_responses.next.list_results
+          if resp.finished
+            raw_token = resp.finished.token
+            token = StatelyDB::Token.new(token_data: raw_token.token_data,
+                                         can_continue: raw_token.can_continue,
+                                         can_sync: raw_token.can_sync)
+            break
+          end
+          yield resp
+        end
+        token
+      end
+
+      # Begin a transaction. Begin is called implicitly when the block passed to transaction is called.
+      # @return [void] nil
+      # @api private
+      # @!visibility private
+      def begin
+        @is_transaction_open = true
+        req = Stately::Db::TransactionRequest.new(begin: Stately::Db::TransactionBegin.new(store_id: @store_id.to_i))
+        request_only(req)
+        @incoming_responses = @stub.transaction(@outgoing_requests)
+        nil
+      end
+
+      # Commit a transaction. Commit is called implicitly when the block passed to transaction completes.
+      # @return [StatelyDB::Transaction::Transaction::Result]
+      # @api private
+      # @!visibility private
+      def commit
+        req = Stately::Db::TransactionRequest.new(
+          commit: Google::Protobuf::Empty.new
+        )
+        resp = request_response(req).finished
+        @is_transaction_open = false
+        Result.new(
+          puts: resp.put_results.map do |result|
+            @schema.unmarshal_item(stately_item: result)
+          end,
+          deletes: resp.delete_results.map(&:key_path)
+        )
+      end
+
+      # Abort a transaction. Abort is called implicitly if an exception is raised within the block passed to transaction.
+      # @return [Stately::Db::TransactionResponse]
+      # @api private
+      # @!visibility private
+      def abort
+        req = Stately::Db::TransactionRequest.new(
+          abort: Google::Protobuf::Empty.new
+        )
+        resp = request_only(req)
+        @is_transaction_open = false
+        resp
+      end
+
+      # Check if a transaction is open. A transaction is open if begin has been called and commit or abort has not been called.
+      #
+      # @return [Boolean] true if a transaction is open
+      # @api private
+      # @!visibility private
+      def open?
+        @is_transaction_open
+      end
+
+      # Fetch Items from a StatelyDB Store at the given key_path. Note that Items need to exist before being retrieved inside a
+      # transaction.
+      #
+      # @param key_path [String] the path to the item
+      # @return [StatelyDB::Item, NilClass] the item or nil if not found
+      # @raise [StatelyDB::Error::InvalidParameters] if the parameters are invalid
+      # @raise [StatelyDB::Error::NotFound] if the item is not found
+      #
+      # @example
+      #   client.data.transaction do |txn|
+      #     item = txn.get("/ItemType-identifier")
+      #   end
+      def get(key_path)
+        resp = get_batch(key_path)
+
+        # Always return a single Item.
+        resp.first
+      end
+
+      # Fetch a batch of Items from a StatelyDB Store at the given key_paths. Note that Items need to exist before being retrieved
+      # inside a transaction.
+      #
+      # @param key_paths [String, Array<String>] the paths to the items
+      # @return [Array<StatelyDB::Item>] the items
+      # @raise [StatelyDB::Error::InvalidParameters] if the parameters are invalid
+      # @raise [StatelyDB::Error::NotFound] if the item is not found
+      #
+      # Example:
+      #   client.data.transaction do |txn|
+      #     items = txn.get_batch("/foo", "/bar")
+      #   end
+      def get_batch(*key_paths)
+        key_paths = Array(key_paths).flatten
+        req = Stately::Db::TransactionRequest.new(
+          get_items: Stately::Db::TransactionGet.new(
+            gets: key_paths.map { |key_path| Stately::Db::GetItem.new(key_path: String(key_path)) }
+          )
+        )
+        resp = request_response(req).get_results
+
+        resp.items.map do |result|
+          @schema.unmarshal_item(stately_item: result)
+        end
+      end
+
+      # Put a single Item into a StatelyDB store. Results are not returned until the transaction is
+      # committed and will be available in the Result object returned by commit. An identifier for
+      # the item will be returned while inside the transaction block.
+      #
+      # @param item [StatelyDB::Item] the item to store
+      # @return [String, Integer] the id of the item
+      #
+      # @example
+      #   results = client.data.transaction do |txn|
+      #     txn.put(my_item)
+      #   end
+      #  results.puts.each do |result|
+      #    puts result.key_path
+      #  end
+      def put(item)
+        resp = put_batch(item)
+        resp.first
+      end
+
+      # Put a batch of Items into a StatelyDB Store. Results are not returned until the transaction is
+      # committed and will be available in the Result object returned by commit. A list of identifiers
+      # for the items will be returned while inside the transaction block.
+      #
+      # @param items [StatelyDB::Item, Array<StatelyDB::Item>] the items to store
+      # @return [Array<String>] the key paths of the items
+      #
+      # @example
+      #   results = client.data.transaction do |txn|
+      #     txn.put_batch(item1, item2)
+      #   end
+      #  results.puts.each do |result|
+      #    puts result.key_path
+      #  end
+      def put_batch(*items)
+        items = Array(items).flatten
+        req = Stately::Db::TransactionRequest.new(
+          put_items: Stately::Db::TransactionPut.new(
+            puts: items.map do |item|
+              Stately::Db::PutItem.new(
+                item: item.send("marshal_stately")
+              )
+            end
+          )
+        )
+
+        resp = request_response(req).put_ack
+        resp.generated_ids.map(&:value)
+      end
+
+      # Delete one or more Items from a StatelyDB Store at the given key_paths. Results are not returned until the transaction is
+      # committed and will be available in the Result object returned by commit.
+      #
+      # @param key_paths [String, Array<String>] the paths to the items
+      # @return [void] nil
+      #
+      # Example:
+      #   client.data.transaction do |txn|
+      #     txn.delete("/ItemType-identifier", "/ItemType-identifier2")
+      #   end
+      def delete(*key_paths)
+        key_paths = Array(key_paths).flatten
+        req = Stately::Db::TransactionRequest.new(
+          delete_items: Stately::Db::TransactionDelete.new(
+            deletes: key_paths.map { |key_path| Stately::Db::DeleteItem.new(key_path: String(key_path)) }
+          )
+        )
+        request_only(req)
+        nil
+      end
+
+      # Begin listing Items from a StatelyDB Store at the given prefix.
+      #
+      # @param prefix [String] the prefix to list
+      # @param limit [Integer] the maximum number of items to return
+      # @param sort_property [String] the property to sort by
+      # @param sort_direction [Symbol] the direction to sort by (:ascending or :descending)
+      # @return [(Array<StatelyDB::Item>, Stately::Db::ListToken)] the list of Items and the token
+      #
+      # Example:
+      #   client.data.transaction do |txn|
+      #     (items, token) = txn.begin_list("/ItemType-identifier")
+      #     (items, token) = txn.continue_list(token)
+      #   end
+      def begin_list(prefix,
+                     limit: 100,
+                     sort_property: nil,
+                     sort_direction: :ascending)
+        sort_direction = case sort_direction
+                         when :ascending
+                           0
+                         else
+                           1
+                         end
+        req = Stately::Db::TransactionRequest.new(
+          begin_list: Stately::Db::TransactionBeginList.new(
+            key_path_prefix: String(prefix),
+            limit:,
+            sort_property:,
+            sort_direction:
+          )
+        )
+        do_list_request_response(req)
+      end
+
+      # Continue listing Items from a StatelyDB Store using a token.
+      #
+      # @param token [Stately::Db::ListToken] the token to continue from
+      # @param continue_direction [Symbol] the direction to continue by (:forward or :backward)
+      # @return [(Array<StatelyDB::Item>, Stately::Db::ListToken)] the list of Items and the token
+      #
+      # Example:
+      #   client.data.transaction do |txn|
+      #     (items, token) = txn.begin_list("/foo")
+      #     (items, token) = txn.continue_list(token)
+      #   end
+      def continue_list(token, continue_direction: :forward)
+        continue_direction = continue_direction == :forward ? 0 : 1
+
+        req = Stately::Db::TransactionRequest.new(
+          continue_list: Stately::Db::TransactionContinueList.new(
+            token_data: token.token_data,
+            direction: continue_direction
+          )
+        )
+        do_list_request_response(req)
+      end
+
+      private
+
+      # Processes a list response from begin_list or continue_list
+      #
+      # @param req [Stately::Db::TransactionRequest] the request to send
+      # @return [(Array<StatelyDB::Item>, Stately::Db::ListToken)] the list of Items and the token
+      # @api private
+      # @!visibility private
+      def do_list_request_response(req)
+        items = []
+        token = request_list_responses(req) do |resp|
+          resp.result.items.each do |list_items_result|
+            items << @schema.unmarshal_item(stately_item: list_items_result)
+          end
+        end
+        [items, token]
+      end
+
+      # We are using a oneof inside the TransactionRequest to determine the type of request. The ruby
+      # generated code does not have a helper for the internal request type so we need to infer it.
+      #
+      # @param req [Stately::Db::TransactionRequest] the request
+      # @return [Class] the response type
+      # @api private
+      # @!visibility private
+      def infer_response_type_from_request(req)
+        if req.respond_to?(:get_items)
+          Stately::Db::TransactionGetResponse
+        elsif req.respond_to?(:list_items)
+          Stately::Db::TransactionListResponse
+        else
+          raise "Unknown request type or request type does not have a corresponding response type"
+        end
+      end
+
+      # We are using a oneof inside the TransactionResponse to determine the type of response. The ruby
+      # generated code does not have a helper for the internal response type so we need to infer it.
+      #
+      # @param resp [Stately::Db::TransactionResponse] the response
+      # @return [Class] the response type
+      # @api private
+      # @!visibility private
+      def infer_response_type_from_response(resp)
+        if resp.respond_to?(:get_results)
+          Stately::Db::TransactionGetResponse
+        elsif resp.respond_to?(:list_results)
+          Stately::Db::TransactionListResponse
+        else
+          raise "Unknown response type"
+        end
+      end
+    end
+  end
+end

data/lib/uuid.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module StatelyDB
+  # UUID is a helper class for working with UUIDs in StatelyDB. The ruby version of a StatelyDB is a binary string,
+  # and this class provides convenience methods for converting to the base16 representation specified in RFC 9562.
+  # Internally this class uses the byte_string attribute to store the UUID as a string with the Encoding::ASCII_8BIT
+  # encoding.
+  class UUID
+    attr_accessor :byte_string
+
+    # @param [String] byte_string A binary-encoded string (eg: Encoding::ASCII_8BIT encoding)
+    def initialize(byte_string)
+      @byte_string = byte_string
+    end
+
+    # to_s returns the UUID as a base16 string (eg: "f4a8a24a-129d-411f-91d2-6d19d0eaa096")
+    # @return [String]
+    def to_s
+      to_str
+    end
+
+    # to_str returns the UUID as a base16 string (eg: "f4a8a24a-129d-411f-91d2-6d19d0eaa096")
+    #
+    # Note: to_str is a type coercion method that is called by Ruby when an object is coerced to a string.
+    # @return [String]
+    def to_str
+      @byte_string.unpack("H8H4H4H4H12").join("-")
+    end
+
+    # Encodes the byte string as a url-safe base64 string with padding removed.
+    # @return [String]
+    def to_base64
+      [@byte_string].pack("m0").tr("=", "").tr("+/", "-_")
+    end
+
+    # UUIDs are equal if their byte_strings are equal.
+    # @param [StatelyDB::UUID] other
+    # @return [Boolean]
+    def ==(other)
+      self.class == other.class &&
+        @byte_string == other.byte_string
+    end
+
+    # UUIDs are sorted lexigraphically by their base16 representation.
+    # @param [StatelyDB::UUID] other
+    # @return [Integer]
+    def <=>(other)
+      to_s <=> other.to_s
+    end
+
+    # Parses a base16 string (eg: "f4a8a24a-129d-411f-91d2-6d19d0eaa096") into a UUID object.
+    # The string can be the following:
+    # 1. Encoded as Encoding::ASCII_8BIT (also aliased as Encoding::BINARY) and be 16 bytes long.
+    # 2. A string of the form "f4a8a24a-129d-411f-91d2-6d19d0eaa096"
+    # @param [String] byte_string A binary-encoded string (eg: Encoding::ASCII_8BIT encoding) that is 16 bytes in length, or a
+    #                             base16-formatted UUID string.
+    # @return [StatelyDB::UUID]
+    def self.parse(byte_string)
+      if byte_string.encoding == Encoding::BINARY && byte_string.bytesize == 16
+        return new(byte_string)
+      elsif byte_string.match(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i)
+        return new([byte_string.delete("-")].pack("H*"))
+      end
+
+      raise "Invalid UUID"
+    end
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: statelydb
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Stately Cloud, Inc.
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-08-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.10.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.10.1
+- !ruby/object:Gem::Dependency
+  name: async-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.64.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.64.0
+- !ruby/object:Gem::Dependency
+  name: grpc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.63.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.63.0
+description: ''
+email: ruby@stately.cloud
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/api/db/continue_list_pb.rb
+- lib/api/db/delete_pb.rb
+- lib/api/db/get_pb.rb
+- lib/api/db/item_pb.rb
+- lib/api/db/item_property_pb.rb
+- lib/api/db/list_pb.rb
+- lib/api/db/list_token_pb.rb
+- lib/api/db/put_pb.rb
+- lib/api/db/scan_root_paths_pb.rb
+- lib/api/db/service_pb.rb
+- lib/api/db/service_services_pb.rb
+- lib/api/db/sync_list_pb.rb
+- lib/api/db/transaction_pb.rb
+- lib/api/errors/error_details_pb.rb
+- lib/common/auth/auth0_token_provider.rb
+- lib/common/auth/interceptor.rb
+- lib/common/auth/token_provider.rb
+- lib/common/error_interceptor.rb
+- lib/common/net/conn.rb
+- lib/error.rb
+- lib/key_path.rb
+- lib/statelydb.rb
+- lib/token.rb
+- lib/transaction/queue.rb
+- lib/transaction/transaction.rb
+- lib/uuid.rb
+homepage: https://stately.cloud/sdk
+licenses:
+- Apache-2.0
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: A library for interacting with StatelyDB
+test_files: []