class Fauna::Client

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 { "@ref": { "id": "123", "class": { "@ref": { "id": "frogs", "class": { "@ref": { "id": "classes" } } } } } }, you will get Fauna::Ref.new("123", Fauna::Ref.new("frogs", Fauna::Native.classes))).

Attributes

adapter[R]

Faraday adapter in use.

connection_timeout[R]

Open timeout in seconds.

credentials[R]

An array of the user and pass used for authentication when sending requests.

domain[R]

The domain requests will be sent to.

observer[R]

Callback that will be passed a RequestResult after every completed request.

port[R]

Port used when sending requests.

read_timeout[R]

Read timeout in seconds.

scheme[R]

Scheme used when sending requests (either http or https).

Public Class Methods

new(params = {}) click to toggle source

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 adapter to use. Either can be a symbol for the adapter, or an array of arguments.

   # File lib/fauna/client.rb
42 def initialize(params = {})
43   @domain = params[:domain] || 'db.fauna.com'
44   @scheme = params[:scheme] || 'https'
45   @port = params[:port] || (scheme == 'https' ? 443 : 80)
46   @read_timeout = params[:read_timeout] || 60
47   @connection_timeout = params[:connection_timeout] || 60
48   @observer = params[:observer]
49   @adapter = params[:adapter] || :net_http_persistent
50   init_credentials(params[:secret])
51 
52   init_connection
53 end

Public Instance Methods

paginate(set, params = {}, &fauna_map) click to toggle source

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.

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.

    # File lib/fauna/client.rb
100 def paginate(set, params = {}, &fauna_map)
101   Fauna::Page.new(self, set, params, &fauna_map)
102 end
with_secret(secret) click to toggle source

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.

   # File lib/fauna/client.rb
59 def with_secret(secret)
60   with_dup do |client|
61     client.send(:init_credentials, secret)
62   end
63 end

Private Instance Methods

execute(action, path, query = nil, data = nil) click to toggle source
    # File lib/fauna/client.rb
145 def execute(action, path, query = nil, data = nil)
146   path = path.to_s
147 
148   start_time = Time.now
149   begin
150     response = perform_request action, path, query, data
151   rescue Faraday::ClientError => e
152     end_time = Time.now
153 
154     message = e.class.name
155     message += ": #{e.message}" unless e.message.nil?
156 
157     request_result = RequestResult.new(self,
158         action, path, query, data,
159         nil, nil, nil, nil,
160         start_time, end_time)
161     raise UnexpectedError.new(message, request_result)
162   end
163   end_time = Time.now
164 
165   response_raw = response.body
166   response_json = FaunaJson.json_load_or_nil response_raw
167   response_content = FaunaJson.deserialize response_json unless response_json.nil?
168 
169   request_result = RequestResult.new(self,
170       action, path, query, data,
171       response_raw, response_content, response.status, response.headers,
172       start_time, end_time)
173 
174   @observer.call(request_result) unless @observer.nil?
175 
176   FaunaError.raise_for_status_code(request_result)
177   UnexpectedError.get_or_raise request_result, response_content, :resource
178 end
init_connection() click to toggle source
    # File lib/fauna/client.rb
127 def init_connection
128   @connection = Faraday.new(
129     url: "#{scheme}://#{domain}:#{port}/",
130     headers: {
131       'Accept-Encoding' => 'gzip,deflate',
132       'Content-Type' => 'application/json;charset=utf-8',
133       'User-Agent' => "FaunaDB-Ruby/#{Fauna::VERSION}",
134       'X-FaunaDB-API-Version' => '2.1'
135     },
136     request: { timeout: read_timeout, open_timeout: connection_timeout },
137   ) do |conn|
138     # Let us specify arguments so we can set stubs for test adapter
139     conn.adapter(*Array(adapter))
140     conn.basic_auth(credentials[0].to_s, credentials[1].to_s)
141     conn.response :fauna_decode
142   end
143 end
init_credentials(secret) click to toggle source
    # File lib/fauna/client.rb
123 def init_credentials(secret)
124   @credentials = secret.to_s.split(':', 2)
125 end
perform_request(action, path, query, data) click to toggle source
    # File lib/fauna/client.rb
180 def perform_request(action, path, query, data)
181   @connection.send(action) do |req|
182     req.params = query.delete_if { |_, v| v.nil? } unless query.nil?
183     req.body = FaunaJson.to_json(data) unless data.nil?
184     req.url(path || '')
185   end
186 rescue Faraday::ConnectionFailed, Faraday::TimeoutError, Faraday::SSLError => e
187   raise UnavailableError.new(e)
188 end
with_dup() { |new_client| ... } click to toggle source
    # File lib/fauna/client.rb
116 def with_dup
117   new_client = self.dup
118   yield new_client
119   new_client.send(:init_connection)
120   new_client
121 end

Query Methods

↑ top

Public Instance Methods

query(expression = nil, &expr_block) click to toggle source

Issues a query to FaunaDB.

Queries are built via the Query helpers. See FaunaDB Query API 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:

client.query(Fauna::Query.add(1, 2, Fauna::Query.subtract(3, 2)))

Example using block:

client.query { add(1, 2, subtract(3, 2)) }

Reference: Executing FaunaDB Queries

   # File lib/fauna/client.rb
85 def query(expression = nil, &expr_block)
86   if expr_block.nil?
87     execute(:post, :'', nil, Fauna::Query::Expr.wrap(expression))
88   else
89     execute(:post, :'', nil, Fauna::Query.expr(&expr_block))
90   end
91 end

REST Methods

↑ top

Public Instance Methods

ping(params = {}) click to toggle source

Ping FaunaDB.

Reference: FaunaDB Rest API.

    # File lib/fauna/client.rb
110 def ping(params = {})
111   execute(:get, :ping, params)
112 end