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
Faraday adapter in use.
Open timeout in seconds.
An array of the user and pass used for authentication when sending requests.
The domain requests will be sent to.
Callback that will be passed a RequestResult
after every completed request.
Port used when sending requests.
Read timeout in seconds.
Scheme used when sending requests (either http
or https
).
Public Class Methods
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
orhttps
). :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
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
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
# 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
# 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
# File lib/fauna/client.rb 123 def init_credentials(secret) 124 @credentials = secret.to_s.split(':', 2) 125 end
# 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
# 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
↑ topPublic Instance Methods
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
↑ topPublic Instance Methods
Ping FaunaDB.
Reference: FaunaDB Rest API.
# File lib/fauna/client.rb 110 def ping(params = {}) 111 execute(:get, :ping, params) 112 end