yax-fauna 3.0.1

data/lib/fauna/client_logger.rb

@@ -0,0 +1,52 @@
+module Fauna
+  # Example observer that can be used for debugging
+  module ClientLogger
+    ##
+    # Lambda that can be the +observer+ for a Client.
+    # Will call the passed block on a string representation of each RequestResult.
+    #
+    # Example:
+    #
+    #   logger = ClientLogger.logger do |str|
+    #     puts str
+    #   end
+    #   Client.new observer: logger, ...
+    def self.logger
+      lambda do |request_result|
+        yield show_request_result(request_result)
+      end
+    end
+
+    # Translates a RequestResult to a string suitable for logging.
+    def self.show_request_result(request_result)
+      rr = request_result
+      logged = ''
+
+      logged << "Fauna #{rr.method.to_s.upcase} /#{rr.path}#{query_string_for_logging(rr.query)}\n"
+      logged << "  Credentials: #{rr.auth}\n"
+      if rr.request_content
+        logged << "  Request JSON: #{indent(FaunaJson.to_json_pretty(rr.request_content))}\n"
+      end
+      logged << "  Response headers: #{indent(FaunaJson.to_json_pretty(rr.response_headers))}\n"
+      logged << "  Response JSON: #{indent(FaunaJson.to_json_pretty(rr.response_content))}\n"
+      logged << "  Response (#{rr.status_code}): Network latency #{(rr.time_taken * 1000).to_i}ms"
+
+      logged
+    end
+
+    def self.indent(str) # :nodoc:
+      indent_str = '  '
+      str.split("\n").join("\n" + indent_str)
+    end
+
+    def self.query_string_for_logging(query) # :nodoc:
+      return unless query && !query.empty?
+
+      '?' + query.collect do |k, v|
+        "#{k}=#{v}"
+      end.join('&')
+    end
+
+    private_class_method :indent, :query_string_for_logging
+  end
+end

data/lib/fauna/context.rb

@@ -0,0 +1,81 @@
+module Fauna
+  ##
+  # Error raised when the context is used without a client being set.
+  class NoContextError < RuntimeError; end
+
+  ##
+  # The client context wrapper.
+  #
+  # Used for accessing the client without directly passing around the client instance.
+  # Context is scoped to the current thread.
+  class Context
+    ##
+    # Returns a context block with the given client.
+    #
+    # +client+:: Client to use for the context block.
+    def self.block(client)
+      push(client)
+      yield
+    ensure
+      pop
+    end
+
+    ##
+    # Adds a client to the current context.
+    #
+    # +client+:: Client to add to the current context.
+    def self.push(client)
+      stack.push(client)
+    end
+
+    ##
+    # Removes the last client context from the stack and returns it.
+    def self.pop
+      stack.pop
+    end
+
+    ##
+    # Resets the current client context, removing all the clients from the stack.
+    def self.reset
+      stack.clear
+    end
+
+    ##
+    # Issues a query to FaunaDB with the current client context.
+    #
+    # Queries are built via the Query helpers. See {FaunaDB Query API}[https://fauna.com/documentation/queries]
+    # for information on constructing queries.
+    #
+    # +expression+:: A query expression
+    #
+    # :category: Client Methods
+    def self.query(expression = nil, &expr_block)
+      client.query(expression, &expr_block)
+    end
+
+    ##
+    # Creates a Fauna::Page for paging/iterating over a set with the current client context.
+    #
+    # +set+:: A set query to paginate over.
+    # +params+:: A list of parameters to pass to {paginate}[https://fauna.com/documentation/queries#read_functions-paginate_set].
+    # +fauna_map+:: Optional block to wrap the generated paginate query with. The block will be run in a query context.
+    #               The paginate query will be passed into the block as an argument.
+    def self.paginate(set, params = {}, &fauna_map)
+      client.paginate(set, params, &fauna_map)
+    end
+
+    ##
+    # Returns the current context's client, or if there is none, raises NoContextError.
+    def self.client
+      stack.last || fail(NoContextError, 'You must be within a Fauna::Context.block to perform operations.')
+    end
+
+    class << self
+    private
+
+      def stack
+        Thread.current[:fauna_context_stack] ||= []
+      end
+    end
+  end
+end

data/lib/fauna/deprecate.rb

@@ -0,0 +1,29 @@
+module Fauna
+  module Deprecate
+    ##
+    # Deprecates a method
+    #
+    # class AClass
+    #   extend Fauna::Deprecate
+    #
+    #   def method
+    #   end
+    #
+    #   deprecate :method, :new_method
+    #
+    #   def new_method
+    #   end
+    # end
+    #
+    # +name+:: The method name to be deprecated
+    # +replacement+:: The new method that should be used instead
+    def deprecate(name, replacement)
+      old_name = "deprecated_#{name}"
+      alias_method old_name, name
+      define_method name do |*args, &block|
+        warn "Method #{name} called from #{Gem.location_of_caller.join(':')} is deprecated. Use #{replacement} instead"
+        self.__send__ old_name, *args, &block
+      end
+    end
+  end
+end

data/lib/fauna/errors.rb

@@ -0,0 +1,235 @@
+module Fauna
+  ##
+  # Error for when an object passed into a query cannot be serialized.
+  # Objects that are not native to the query language should implement +to_h+/+to_hash+.
+  class SerializationError < RuntimeError
+    def initialize(obj) # :nodoc:
+      super("Object #{obj.inspect} is not serializable")
+      @object = obj
+    end
+
+    # The object that could not be serialized.
+    attr_reader :object
+  end
+
+  ##
+  # Error for when the server returns an unexpected kind of response.
+  class UnexpectedError < RuntimeError
+    # RequestResult for the request that caused this error.
+    attr_reader :request_result
+
+    def initialize(description, request_result) # :nodoc:
+      super(description)
+      @request_result = request_result
+    end
+
+    def self.get_or_raise(request_result, hash, key) # :nodoc:
+      unless hash.is_a? Hash and hash.key? key
+        fail UnexpectedError.new("Response JSON does not contain expected key #{key}", request_result)
+      end
+      hash[key]
+    end
+  end
+
+  ##
+  # Error returned by the FaunaDB server.
+  # For documentation of error types, see the docs[https://fauna.com/documentation#errors].
+  class FaunaError < RuntimeError
+    # List of ErrorData objects returned by the server.
+    attr_reader :errors
+
+    # RequestResult for the request that caused this error.
+    attr_reader :request_result
+
+    ##
+    # Raises the associated error from a RequestResult based on the status code.
+    #
+    # Returns +nil+ for 2xx status codes
+    def self.raise_for_status_code(request_result)
+      case request_result.status_code
+      when 200..299
+
+      when 400
+        fail BadRequest.new(request_result)
+      when 401
+        fail Unauthorized.new(request_result)
+      when 403
+        fail PermissionDenied.new(request_result)
+      when 404
+        fail NotFound.new(request_result)
+      when 405
+        fail MethodNotAllowed.new(request_result)
+      when 500
+        fail InternalError.new(request_result)
+      when 502
+        fail UnavailableError.new(request_result)
+      when 503
+        fail UnavailableError.new(request_result)
+      when 504
+        fail UnavailableError.new(request_result)
+      else
+        fail UnexpectedError.new('Unexpected status code.', request_result)
+      end
+    end
+
+    # Creates a new error from a given RequestResult or Exception.
+    def initialize(request_result)
+      message = nil
+
+      if request_result.is_a? RequestResult
+        @request_result = request_result
+
+        begin
+          if request_result.response_content.nil?
+            fail UnexpectedError.new('Invalid JSON.', request_result)
+          end
+
+          errors_raw = UnexpectedError.get_or_raise request_result, request_result.response_content, :errors
+          @errors = catch :invalid_response do
+            throw :invalid_response unless errors_raw.is_a? Array
+            errors_raw.map { |error| ErrorData.from_hash(error) }
+          end
+
+          if @errors.nil?
+            fail UnexpectedError.new('Error data has an unexpected format.', request_result)
+          elsif @errors.empty?
+            fail UnexpectedError.new('Error data returned was blank.', request_result)
+          end
+
+          message = @errors.map do |error|
+            msg = 'Error'
+            msg += " at #{error.position}" unless error.position.nil?
+            msg += ": #{error.code} - #{error.description}"
+
+            unless error.failures.nil?
+              msg += ' (' + error.failures.map do |failure|
+                "Failure at #{failure.field}: #{failure.code} - #{failure.description}"
+              end.join(' ') + ')'
+            end
+
+            msg
+          end.join(' ')
+        rescue UnexpectedError => e
+          unless self.is_a?(UnavailableError) && [502, 503, 504].include?(request_result.status_code)
+            raise e
+          end
+
+          message = request_result.response_raw
+        end
+      elsif request_result.is_a? Exception
+        message = request_result.class.name
+        unless request_result.message.nil?
+          message += ": #{request_result.message}"
+        end
+      end
+
+      super(message)
+    end
+  end
+
+  # An exception thrown if FaunaDB cannot evaluate a query.
+  class BadRequest < FaunaError; end
+
+  # An exception thrown if FaunaDB responds with an HTTP 401.
+  class Unauthorized < FaunaError; end
+
+  # An exception thrown if FaunaDB responds with an HTTP 403.
+  class PermissionDenied < FaunaError; end
+
+  # An exception thrown if FaunaDB responds with an HTTP 404 for non-query endpoints.
+  class NotFound < FaunaError; end
+
+  # An exception thrown if FaunaDB responds with an HTTP 405.
+  class MethodNotAllowed < FaunaError; end
+
+  ##
+  # An exception thrown if FaunaDB responds with an HTTP 500. Such errors represent an internal
+  # failure within the database.
+  class InternalError < FaunaError; end
+
+  # An exception thrown if FaunaDB responds with an HTTP 502, 503, or 504.
+  class UnavailableError < FaunaError; end
+
+  # Data for one error returned by the server.
+  class ErrorData
+    ##
+    # Error code.
+    #
+    # Reference: {FaunaDB Error codes}[https://fauna.com/documentation#errors]
+    attr_reader :code
+    # Error description.
+    attr_reader :description
+    # Position of the error in a query. May be +nil+.
+    attr_reader :position
+    # List of Failure objects returned by the server. +nil+ except for <code>validation failed</code> errors.
+    attr_reader :failures
+
+    def self.from_hash(hash) # :nodoc:
+      code = ErrorHelpers.get_or_throw hash, :code
+      description = ErrorHelpers.get_or_throw hash, :description
+      position = ErrorHelpers.map_position hash[:position]
+      failures = hash[:failures].map(&Failure.method(:from_hash)) unless hash[:failures].nil?
+      ErrorData.new code, description, position, failures
+    end
+
+    def initialize(code, description, position, failures) # :nodoc:
+      @code = code
+      @description = description
+      @position = position
+      @failures = failures
+    end
+
+    def inspect # :nodoc:
+      "ErrorData(#{code.inspect}, #{description.inspect}, #{position.inspect}, #{failures.inspect})"
+    end
+  end
+
+  ##
+  # Part of ErrorData.
+  # For more information, see the {docs}[https://fauna.com/documentation#errors-invalid_data].
+  class Failure
+    # Failure code.
+    attr_reader :code
+    # Failure description.
+    attr_reader :description
+    # Field of the failure in the instance.
+    attr_reader :field
+
+    def self.from_hash(hash) # :nodoc:
+      Failure.new(
+        ErrorHelpers.get_or_throw(hash, :code),
+        ErrorHelpers.get_or_throw(hash, :description),
+        ErrorHelpers.map_position(hash[:field]),
+      )
+    end
+
+    def initialize(code, description, field) # :nodoc:
+      @code = code
+      @description = description
+      @field = field
+    end
+
+    def inspect # :nodoc:
+      "Failure(#{code.inspect}, #{description.inspect}, #{field.inspect})"
+    end
+  end
+
+  module ErrorHelpers # :nodoc:
+    def self.map_position(position)
+      unless position.nil?
+        position.map do |part|
+          if part.is_a? String
+            part.to_sym
+          else
+            part
+          end
+        end
+      end
+    end
+
+    def self.get_or_throw(hash, key)
+      throw :invalid_response unless hash.is_a? Hash and hash.key? key
+      hash[key]
+    end
+  end
+end

data/lib/fauna/json.rb

@@ -0,0 +1,99 @@
+module Fauna
+  module FaunaJson # :nodoc:
+    @@serializable_types = [String, Numeric, TrueClass, FalseClass, NilClass, Hash, Array, Symbol, Time, Date, Fauna::Ref, Fauna::SetRef, Fauna::Bytes, Fauna::QueryV, Fauna::Query::Expr]
+
+    def self.serializable_types
+      @@serializable_types
+    end
+
+    def self.to_json(value)
+      serialize(value).to_json
+    end
+
+    def self.to_json_pretty(value)
+      JSON.pretty_generate serialize(value)
+    end
+
+    def self.deserialize(obj)
+      if obj.is_a?(Hash)
+        if obj.key? :@ref
+          ref = obj[:@ref]
+          id = ref[:id]
+
+          if !ref.key?(:class) && !ref.key?(:database)
+            Native.from_name(id)
+          else
+            cls = self.deserialize(ref[:class])
+            db = self.deserialize(ref[:database])
+            Ref.new(id, cls, db)
+          end
+        elsif obj.key? :@set
+          SetRef.new deserialize(obj[:@set])
+        elsif obj.key? :@obj
+          deserialize(obj[:@obj])
+        elsif obj.key? :@ts
+          Time.iso8601 obj[:@ts]
+        elsif obj.key? :@date
+          Date.iso8601 obj[:@date]
+        elsif obj.key? :@bytes
+          Bytes.from_base64 obj[:@bytes]
+        elsif obj.key? :@query
+          QueryV.new deserialize(obj[:@query])
+        else
+          Hash[obj.collect { |k, v| [k, deserialize(v)] }]
+        end
+      elsif obj.is_a?(Array)
+        obj.collect { |val| deserialize(val) }
+      else
+        obj
+      end
+    end
+
+    def self.json_load(body)
+      JSON.load body, nil, max_nesting: false, symbolize_names: true, create_additions: false
+    end
+
+    def self.json_load_or_nil(body)
+      json_load body
+    rescue JSON::ParserError
+      nil
+    end
+
+    def self.serialize(value)
+      # Handle primitives
+      if [String, Numeric, TrueClass, FalseClass, NilClass].any? { |type| value.is_a? type }
+        value
+      elsif value.is_a? Hash
+        Hash[value.collect { |k, v| [k, serialize(v)] }]
+      elsif value.is_a? Array
+        value.collect { |val| serialize(val) }
+      elsif value.is_a? Symbol
+        value.to_s
+      # Natively supported types
+      elsif value.is_a? Time
+        # 9 means: include nanoseconds in encoding
+        { :@ts => value.iso8601(9) }
+      elsif value.is_a? Date
+        { :@date => value.iso8601 }
+      # Fauna native types
+      elsif value.is_a? Ref
+        ref = { id: value.id }
+        ref[:class] = value.class_ unless value.class_.nil?
+        ref[:database] = value.database unless value.database.nil?
+        { :@ref => serialize(ref) }
+      elsif value.is_a? SetRef
+        { :@set => serialize(value.value) }
+      elsif value.is_a? Bytes
+        { :@bytes => value.to_base64 }
+      elsif value.is_a? QueryV
+        { :@query => serialize(value.value) }
+      # Query expression wrapper
+      elsif value.is_a? Query::Expr
+        serialize(value.raw)
+      # Everything else is rejected
+      else
+        fail SerializationError.new(value)
+      end
+    end
+  end
+end