yax-fauna 3.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f2163449ff0b2f3f9eb5abff36ae23d33cfb53bb81f8688f4a8b3b1acec51010
+  data.tar.gz: ba7a3a18d2492d6b3b32c052327f7272b1bfdf979a018c6c9b44fc9739dd0386
+SHA512:
+  metadata.gz: 1ab8570d7756839afa10ad19411c8928d1db9ee409da600d795382b8dfd98b508f96b05ec6bf7ea54d426e97eec95a05fb999af54a2bd1be6a5c5da97d7eef3d
+  data.tar.gz: 18d9e7727723f47073eb4a957846736351c0af9af881149c5f3c573b42ef9e97f9d1938c60da79b2636b793ee68ba49bc064b5d671eea7358407c14183f026d2

data/CHANGELOG

@@ -0,0 +1,51 @@
+4.0.0.pre.1
+* Adds `ngram` function.
+* Added `is_empty` and `is_nonempty` functions.
+* Added `to_string`, `to_number`, `to_time`, and `to_date` functions.
+* Reverses the argument order of append and prepend functions.
+* Fixed serialization to correctly wrap objects that implement `to_h` or `to_hash`
+  (unsupported objects are now explictly rejected with a `Fauna::SerializationError`).
+* Add support for the X-Last-Seen-Txn header
+
+3.0.0
+* Adds support for recursive references.
+* Removed REST api support from `Client`.
+* Added `abort` function.
+* Added `normalizer` argument to `casefold` function.
+* Added `new_id` function.
+* Deprecated `next_id` function in favor of `new_id`.
+* Added `identity` and `has_identity` functions.
+* Added `singleton` and `events` functions.
+* Added `select_all` function.
+
+2.4.0
+* Handle HTTP errors 502 and 504 as `Fauna::UnavailableError`.
+* Added support for user-defined functions.
+* Added support for the `@query` type (via `Fauna::QueryV`).
+* Added `create_function`, `function`, and `call` query functions.
+
+2.3.0
+* Change default domain to `db.fauna.com`.
+* Added `key_from_secret` and `at` query functions.
+* Added support for `@bytes` type (via `Fauna::Bytes`).
+
+2.2.0
+* Added `create_class`, `create_index`, `create_database`, `create_key`, `database`, `class`,
+  and `index` query functions.
+* Removed `count` query function.
+* Raises `Fauna::UnavailableError` for all 503s and for Faraday network errors.
+* Fix documentation errors and update links.
+
+2.1.2
+* Change default domain to `cloud.faunadb.com`.
+
+2.1.1
+* Use persistent connections (via the `net-http-persistent` adapter) by default.
+
+2.1.0
+* Added paginate helper.
+* Improved exception messages (now include FaunaDB errors).
+* Added `ref` and `next_id` query functions.
+
+2.0.0
+* Complete rewrite for API 2.0. Not backwards compatible with the old client or api.

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gem 'rake'
+gem 'jruby-openssl', platform: :jruby
+
+gemspec

data/LICENSE

@@ -0,0 +1,12 @@
+Copyright 2017 Fauna, Inc.
+
+Licensed under the Mozilla Public License, Version 2.0 (the "License"); you may
+not use this software except in compliance with the License. You may obtain a 
+copy of the License at
+
+http://mozilla.org/MPL/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.

data/README.md

@@ -0,0 +1,148 @@
+# FaunaDB
+
+[![Coverage Status](https://img.shields.io/codecov/c/github/fauna/faunadb-ruby/master.svg?maxAge=21600)](https://codecov.io/gh/fauna/faunadb-ruby/branch/master)
+[![Gem Version](https://img.shields.io/gem/v/fauna.svg?maxAge=21600)](https://rubygems.org/gems/fauna)
+[![License](https://img.shields.io/badge/license-MPL_2.0-blue.svg?maxAge=2592000)](https://raw.githubusercontent.com/fauna/faunadb-ruby/master/LICENSE)
+
+Ruby driver for [FaunaDB](https://fauna.com).
+
+## Installation
+
+The FaunaDB ruby driver is distributed as a gem. Install it via:
+
+    $ gem install fauna
+
+Or if you use Bundler, add it to your application's `Gemfile`:
+
+    gem 'fauna'
+
+And then execute:
+
+    $ bundle
+
+## Documentation
+
+The driver documentation is [hosted on GitHub Pages](https://fauna.github.io/faunadb-ruby/).
+
+Please see the [FaunaDB Documentation](https://fauna.com/documentation) for
+a complete API reference, or look in
+[`/test`](https://github.com/fauna/faunadb-ruby/tree/master/test) for more
+examples.
+
+## Compatibility
+
+Tested and compatible with the following ruby versions:
+
+* MRI 1.9.3
+* MRI 2.2.3
+* Jruby 1.7.19
+
+## Basic Usage
+
+First, require the gem:
+
+```ruby
+require 'fauna'
+```
+
+### Creating a Client
+
+All API requests pass through a `Fauna::Client`. Creating a client
+requires either an admin key, server key, client key, or a token.
+
+```ruby
+server_key = 'ls8AkXLdakAAAALPAJFy3LvQAAGwDRAS_Prjy6O8VQBfQAlZzwAA'
+```
+
+Now we can make a database-level client:
+
+```ruby
+$fauna = Fauna::Client.new(secret: server_key)
+```
+
+You can optionally configure an `observer` on the client. To ease
+debugging, we provide a simple logging observer at
+`Fauna::ClientLogger.logger`, which you can configure as such:
+
+```ruby
+require 'logger'
+logger = Logger.new(STDERR)
+observer = Fauna::ClientLogger.logger { |log| logger.debug(log) }
+
+$fauna = Fauna::Client.new(
+  secret: server_key,
+  observer: observer)
+```
+
+### Using the Client
+
+Now that we have a client, we can start performing queries:
+
+```ruby
+# Create a class
+$fauna.query { create ref('classes'), name: 'users' }
+
+# Create an instance of the class
+taran = $fauna.query do
+  create ref('classes/users'), data: { email: 'taran@example.com' }
+end
+
+# Update the instance
+taran = $fauna.query do
+  update taran[:ref], data: {
+    name: 'Taran',
+    profession: 'Pigkeeper'
+  }
+end
+
+# Page through a set
+pigkeepers = Fauna::Query.expr { match(ref('indexes/users_by_profession'), 'Pigkeeper') }
+oracles = Fauna::Query.expr { match(ref('indexes/users_by_profession'), 'Oracle') }
+
+$fauna.query { paginate(union(pigkeepers, oracles)) }
+
+# Delete the user
+$fauna.query { delete taran[:ref] }
+```
+
+## Running Tests
+
+You can run tests against FaunaDB Cloud yourself.
+[Create an admin key](https://fauna.com/account/keys) and set
+`FAUNA_ROOT_KEY` environment variable to it's secret. Then run `rake spec`:
+
+```bash
+export FAUNA_ROOT_KEY='kqnPAbijGhkgAAC03-36hjCvcTnWf4Pl8w97UE1HeWo'
+rake spec
+```
+
+To run a single test, use e.g. `ruby test/client_test.rb`.
+
+Coverage is automatically run as part of the tests. After running tests, check
+`coverage/index.html` for the coverage report. If using jruby, use
+`JRUBY_OPTS="--debug" bundle exec rake spec` to ensure coverage is generated
+correctly.
+
+Tests can also be run via a Docker container with
+`FAUNA_ROOT_KEY="your-cloud-secret" make docker-test` (an alternate
+Alpine-based Ruby image can be provided via `RUNTIME_IMAGE`).
+
+## Contributing
+
+GitHub pull requests are very welcome.
+
+## LICENSE
+
+Copyright 2017 [Fauna, Inc.](https://fauna.com/)
+
+Licensed under the Mozilla Public License, Version 2.0 (the
+"License"); you may not use this software except in compliance with
+the License. You may obtain a copy of the License at
+
+[http://mozilla.org/MPL/2.0/](http://mozilla.org/MPL/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.

data/Rakefile

@@ -0,0 +1,13 @@
+require 'rspec/core/rake_task'
+require 'rdoc/task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+RDoc::Task.new do |rdoc|
+  rdoc.main = 'README.md'
+  rdoc.rdoc_dir = 'doc'
+  rdoc.rdoc_files.include('README.md', 'lib/fauna.rb', 'lib/fauna/*.rb')
+end
+
+task prerelease: [:spec, :install]
+task default: :spec

data/fauna.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+require './lib/fauna/version'
+
+Gem::Specification.new do |s|
+  s.name = 'yax-fauna'
+  s.version = Fauna::VERSION.dup
+  s.author = 'Forked from Fauna, Inc.'
+  s.email = 'daniel@danielkehoe.com'
+  s.summary = 'FaunaDB Ruby driver'
+  s.description = 'Ruby driver for FaunaDB.'
+  s.homepage = 'https://github.com/yaxdotcom/yax-faunadb-ruby'
+  s.license = 'MPL-2.0'
+
+  s.files = %w(CHANGELOG Gemfile LICENSE README.md Rakefile fauna.gemspec lib/fauna.rb) + Dir.glob('lib/fauna/**') + Dir.glob('spec/**')
+  s.extra_rdoc_files = %w(CHANGELOG LICENSE README.md)
+  s.rdoc_options = %w(--line-numbers --title Fauna --main README.md)
+  s.test_files = Dir.glob('spec/**')
+  s.require_paths = ['lib']
+
+  s.add_runtime_dependency 'faraday', '~> 1.0'
+  s.add_runtime_dependency 'net-http-persistent', '~> 2.9'
+  s.add_runtime_dependency 'json', '~> 2.3'
+  s.add_development_dependency 'rspec', '~> 3.4'
+  s.add_development_dependency 'simplecov-json', '~> 0.2.0'
+  s.add_development_dependency 'rspec_junit_formatter', '~> 0.3.0'
+end

data/lib/fauna.rb

@@ -0,0 +1,25 @@
+require 'json'
+require 'logger'
+require 'uri'
+require 'faraday'
+require 'cgi'
+require 'zlib'
+require 'time'
+require 'base64'
+
+##
+# Main namespace for the FaunaDB driver.
+module Fauna; end
+
+require 'fauna/deprecate'
+require 'fauna/version'
+require 'fauna/util'
+require 'fauna/errors'
+require 'fauna/client'
+require 'fauna/client_logger'
+require 'fauna/context'
+require 'fauna/objects'
+require 'fauna/query'
+require 'fauna/json'
+require 'fauna/page'
+require 'fauna/request_result'

data/lib/fauna/client.rb

@@ -0,0 +1,253 @@
+require 'thread'
+
+module Fauna
+  ##
+  # The Ruby client for FaunaDB.
+  #
+  # All methods return a converted JSON response.
+  # This is a Hash containing Arrays, ints, floats, strings, and other Hashes.
+  # Hash keys are always Symbols.
+  #
+  # Any Ref, SetRef, Time or Date values in it will also be parsed.
+  # (So instead of <code>{ "@ref": { "id": "123", "class": { "@ref": { "id": "frogs", "class": { "@ref": { "id": "classes" } } } } } }</code>,
+  # you will get <code>Fauna::Ref.new("123", Fauna::Ref.new("frogs", Fauna::Native.classes))</code>).
+  class Client
+    # The domain requests will be sent to.
+    attr_reader :domain
+    # Scheme used when sending requests (either +http+ or +https+).
+    attr_reader :scheme
+    # Port used when sending requests.
+    attr_reader :port
+    # An array of the user and pass used for authentication when sending requests.
+    attr_reader :credentials
+    # Read timeout in seconds.
+    attr_reader :read_timeout
+    # Open timeout in seconds.
+    attr_reader :connection_timeout
+    # Callback that will be passed a +RequestResult+ after every completed request.
+    attr_reader :observer
+    # Faraday[https://github.com/lostisland/faraday] adapter in use.
+    attr_reader :adapter
+
+    # Maintains a thread-safe last seen transaction time. Clients
+    # copied using #with_secret will share the same LastSeen object.
+    class LastSeen
+      def initialize()
+        @mutex = Mutex.new
+        @time = nil
+      end
+
+      def time
+        @mutex.synchronize do
+          @time
+        end
+      end
+
+      def update(time)
+        @mutex.synchronize do
+          if @time.nil?
+            @time = time
+          elsif @time < time
+            @time = time
+          end
+        end
+      end
+
+    end
+
+    ##
+    # Create a new Client.
+    #
+    # +params+:: A list of parameters to configure the connection with.
+    #            +:domain+:: The domain to send requests to.
+    #            +:scheme+:: Scheme to use when sending requests (either +http+ or +https+).
+    #            +:port+:: Port to use when sending requests.
+    #            +:secret+:: Credentials to use when sending requests. User and pass must be separated by a colon.
+    #            +:read_timeout+:: Read timeout in seconds.
+    #            +:connection_timeout+:: Open timeout in seconds.
+    #            +:observer+:: Callback that will be passed a RequestResult after every completed request.
+    #            +:adapter+:: Faraday[https://github.com/lostisland/faraday] adapter to use. Either can be a symbol for the adapter, or an array of arguments.
+    def initialize(params = {})
+      @domain = params[:domain] || 'db.fauna.com'
+      @scheme = params[:scheme] || 'https'
+      @port = params[:port] || (scheme == 'https' ? 443 : 80)
+      @read_timeout = params[:read_timeout] || 60
+      @connection_timeout = params[:connection_timeout] || 60
+      @observer = params[:observer]
+      @adapter = params[:adapter] || :net_http_persistent
+      @last_seen = LastSeen.new
+      init_credentials(params[:secret])
+
+      init_connection
+    end
+
+    ##
+    # Create a new client from the existing config with a given secret.
+    #
+    # +:secret+:: Credentials to use when sending requests. User and pass must be separated by a colon.
+    def with_secret(secret)
+      with_dup do |client|
+        client.send(:init_credentials, secret)
+      end
+    end
+
+    ##
+    # Issues a query to FaunaDB.
+    #
+    # 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
+    # +expr_block+:: May be provided instead of expression. Block is used to build an expression with Fauna.query.
+    #
+    # Example using expression:
+    #
+    # <code>client.query(Fauna::Query.add(1, 2, Fauna::Query.subtract(3, 2)))</code>
+    #
+    # Example using block:
+    #
+    # <code>client.query { add(1, 2, subtract(3, 2)) }</code>
+    #
+    # Reference: {Executing FaunaDB Queries}[https://fauna.com/documentation#queries]
+    #
+    # :category: Query Methods
+    def query(expression = nil, &expr_block)
+      if expr_block.nil?
+        execute(:post, :'', nil, Fauna::Query::Expr.wrap(expression))
+      else
+        execute(:post, :'', nil, Fauna::Query.expr(&expr_block))
+      end
+    end
+
+    ##
+    # Creates a Fauna::Page for paging/iterating over a set.
+    #
+    # +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 paginate(set, params = {}, &fauna_map)
+      Fauna::Page.new(self, set, params, &fauna_map)
+    end
+
+    ##
+    # Ping FaunaDB.
+    #
+    # Reference: {FaunaDB Rest API}[https://fauna.com/documentation#rest-other].
+    #
+    # :category: REST Methods
+    def ping(params = {})
+      execute(:get, :ping, params)
+    end
+
+  private
+
+    def with_dup
+      new_client = self.dup
+      yield new_client
+      new_client.send(:init_connection)
+      new_client
+    end
+
+    def init_credentials(secret)
+      @credentials = secret.to_s.split(':', 2)
+    end
+
+    def init_connection
+      @connection = Faraday.new(
+        url: "#{scheme}://#{domain}:#{port}/",
+        headers: {
+          'Accept-Encoding' => 'gzip,deflate',
+          'Content-Type' => 'application/json;charset=utf-8',
+          'User-Agent' => "FaunaDB-Ruby/#{Fauna::VERSION}",
+          'X-FaunaDB-API-Version' => '2.1'
+        },
+        request: { timeout: read_timeout, open_timeout: connection_timeout },
+      ) do |conn|
+        # Let us specify arguments so we can set stubs for test adapter
+        conn.adapter(*Array(adapter))
+        conn.basic_auth(credentials[0].to_s, credentials[1].to_s)
+        conn.response :fauna_decode
+      end
+    end
+
+    def execute(action, path, query = nil, data = nil)
+      path = path.to_s
+
+      start_time = Time.now
+      begin
+        response = perform_request action, path, query, data
+      rescue Faraday::ClientError => e
+        end_time = Time.now
+
+        message = e.class.name
+        message += ": #{e.message}" unless e.message.nil?
+
+        request_result = RequestResult.new(self,
+            action, path, query, data,
+            nil, nil, nil, nil,
+            start_time, end_time)
+        raise UnexpectedError.new(message, request_result)
+      end
+      end_time = Time.now
+
+      response_raw = response.body
+      response_json = FaunaJson.json_load_or_nil response_raw
+      response_content = FaunaJson.deserialize response_json unless response_json.nil?
+
+      request_result = RequestResult.new(self,
+          action, path, query, data,
+          response_raw, response_content, response.status, response.headers,
+          start_time, end_time)
+
+
+      if response.headers.key?('X-Txn-Time')
+        time = response.headers['X-Txn-Time'].to_i
+
+        @last_seen.update(time)
+      end
+
+      @observer.call(request_result) unless @observer.nil?
+
+      FaunaError.raise_for_status_code(request_result)
+      UnexpectedError.get_or_raise request_result, response_content, :resource
+    end
+
+    def perform_request(action, path, query, data)
+      @connection.send(action) do |req|
+        req.params = query.delete_if { |_, v| v.nil? } unless query.nil?
+        req.body = FaunaJson.to_json(data) unless data.nil?
+
+        last_txn = @last_seen.time
+        unless last_txn.nil?
+          req.headers['X-Last-Seen-Txn'] = last_txn.to_s
+        end
+
+        req.url(path || '')
+      end
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError, Faraday::SSLError => e
+      raise UnavailableError.new(e)
+    end
+  end
+
+  # Middleware for decompressing responses
+  class FaunaDecode < Faraday::Middleware # :nodoc:
+    def call(env)
+      @app.call(env).on_complete do |response_env|
+        raw_body = response_env[:body]
+        response_env[:body] =
+          case response_env[:response_headers]['Content-Encoding']
+          when 'gzip'
+            io = StringIO.new raw_body
+            Zlib::GzipReader.new(io, external_encoding: Encoding::UTF_8).read
+          when 'deflate'
+            Zlib::Inflate.inflate raw_body
+          else
+            raw_body
+          end
+      end
+    end
+  end
+
+  Faraday::Response.register_middleware fauna_decode: lambda { FaunaDecode }
+end