fauna 1.3.4 → 2.0.0

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,135 @@
+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
+
+    ##
+    # Performs a +GET+ request for a REST endpoint within the current client context.
+    #
+    # +path+:: Path to +GET+.
+    # +query+:: Query parameters to append to the path.
+    #
+    # Reference: {FaunaDB REST API}[https://faunadb.com/documentation/rest]
+    #
+    # :category: Client Methods
+    def self.get(path, query = {})
+      client.get(path, query)
+    end
+
+    ##
+    # Performs a +POST+ request for a REST endpoint within the current client context.
+    #
+    # +path+:: Path to +POST+.
+    # +data+:: Data to post as the body.
+    #
+    # Reference: {FaunaDB REST API}[https://faunadb.com/documentation/rest]
+    #
+    # :category: Client Methods
+    def self.post(path, data = {})
+      client.post(path, data)
+    end
+
+    ##
+    # Performs a +PUT+ request for a REST endpoint within the current client context.
+    #
+    # +path+:: Path to +PUT+.
+    # +data+:: Data to post as the body.
+    #
+    # Reference: {FaunaDB REST API}[https://faunadb.com/documentation/rest]
+    #
+    # :category: Client Methods
+    def self.put(path, data = {})
+      client.put(path, data)
+    end
+
+    ##
+    # Performs a +PATCH+ request for a REST endpoint within the current client context.
+    #
+    # +path+:: Path to +PATCH+.
+    # +data+:: Data to post as the body.
+    #
+    # Reference: {FaunaDB REST API}[https://faunadb.com/documentation/rest]
+    #
+    # :category: Client Methods
+    def self.patch(path, data = {})
+      client.patch(path, data)
+    end
+
+    ##
+    # Performs a +DELETE+ request for a REST endpoint within the current client context.
+    #
+    # +path+:: Path to +DELETE+.
+    # +data+:: Data to post as the body.
+    #
+    # Reference: {FaunaDB REST API}[https://faunadb.com/documentation/rest]
+    #
+    # :category: Client Methods
+    def self.delete(path)
+      client.delete(path)
+    end
+
+    ##
+    # Issues a query to FaunaDB with the current client context.
+    #
+    # Queries are built via the Query helpers. See {FaunaDB Query API}[https://faunadb.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
+
+    ##
+    # 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/errors.rb

@@ -0,0 +1,181 @@
+module Fauna
+  ##
+  # 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://faunadb.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 503
+        fail UnavailableError.new(request_result)
+      else
+        fail UnexpectedError.new('Unexpected status code.', request_result)
+      end
+    end
+
+    # Creates a new error from a given RequestResult.
+    def initialize(request_result)
+      @request_result = request_result
+      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)
+      end
+
+      super(@errors ? @errors[0].description : '(empty `errors`)')
+    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 503.
+  class UnavailableError < FaunaError; end
+
+  # Data for one error returned by the server.
+  class ErrorData
+    ##
+    # Error code.
+    #
+    # Reference: {FaunaDB Error codes}[https://faunadb.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://faunadb.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,60 @@
+module Fauna
+  module FaunaJson # :nodoc:
+    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.new obj[:@ref]
+        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]
+        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
+    end
+
+    def self.json_load_or_nil(body)
+      json_load body
+    rescue JSON::ParserError
+      nil
+    end
+
+    def self.serialize(value)
+      if value.is_a? Time
+        # 9 means: include nanoseconds in encoding
+        { :@ts => value.iso8601(9) }
+      elsif value.is_a? Date
+        { :@date => value.iso8601 }
+      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.respond_to? :to_hash
+        serialize(value.to_hash)
+      else
+        value
+      end
+    end
+  end
+end

data/lib/fauna/objects.rb

@@ -0,0 +1,96 @@
+module Fauna
+  ##
+  # A Ref.
+  #
+  # Reference: {FaunaDB Special Types}[https://faunadb.com/documentation/queries-values-special_types]
+  class Ref
+    # The raw ref string.
+    attr_accessor :value
+
+    ##
+    # Creates a Ref object.
+    #
+    # :call-seq:
+    #   Ref.new('databases/prydain')
+    #   Ref.new('databases', 'prydain')
+    #   Ref.new(Ref.new('databases'), 'prydain')
+    #
+    # +parts+: A string, or a list of strings/refs to be joined.
+    def initialize(*parts)
+      @value = parts.join '/'
+    end
+
+    ##
+    # Gets the class part out of the Ref.
+    # This is done by removing ref.id().
+    # So <code>Fauna::Ref.new('a', 'b/c').to_class</code> will be
+    # <code>Fauna::Ref.new('a/b')</code>.
+    def to_class
+      parts = value.split '/'
+      if parts.length == 1
+        self
+      else
+        Fauna::Ref.new(*parts[0...-1])
+      end
+    end
+
+    ##
+    # Removes the class part of the ref, leaving only the id.
+    # This is everything after the last /.
+    def id
+      parts = value.split '/'
+      fail ArgumentError.new 'The Ref does not have an id.' if parts.length == 1
+      parts.last
+    end
+
+    # Converts the Ref to a string
+    def to_s
+      value
+    end
+
+    # Converts the Ref in Hash form.
+    def to_hash
+      { :@ref => value }
+    end
+
+    # Returns +true+ if +other+ is a Ref and contains the same value.
+    def ==(other)
+      return false unless other.is_a? Ref
+      value == other.value
+    end
+
+    alias_method :eql?, :==
+  end
+
+  ##
+  # A SetRef.
+  #
+  # Reference: {FaunaDB Special Types}[https://faunadb.com/documentation/queries-values-special_types]
+  class SetRef
+    # The raw set hash.
+    attr_accessor :value
+
+    ##
+    # Creates a new SetRef with the given parameters.
+    #
+    # +params+:: Hash of parameters to build the SetRef with.
+    #
+    # Reference: {FaunaDB Special Types}[https://faunadb.com/documentation/queries-values-special_types]
+    def initialize(params = {})
+      self.value = params
+    end
+
+    # Converts the SetRef to Hash form.
+    def to_hash
+      { :@set => value }
+    end
+
+    # Returns +true+ if +other+ is a SetRef and contains the same value.
+    def ==(other)
+      return false unless other.is_a? SetRef
+      value == other.value
+    end
+
+    alias_method :eql?, :==
+  end
+end