Class: SurrealDB::Connections::Embedded

Inherits:
Base
  • Object
show all
Defined in:
lib/surrealdb/connections/embedded.rb

Overview

Embedded transport for SurrealDB via FFI to libsurrealdb_c.

Supports mem://, surrealkv://, and file:// URL schemes. Uses the same CBOR RPC protocol as the WebSocket/HTTP transports, but calls directly into the C library instead of going over the network.

Requires require "surrealdb/embedded" before use.

Thread Safety

The underlying C library handles its own threading via a Tokio runtime. All FFI calls use blocking: true to release the GVL. However, the Ruby-side request lifecycle is not atomic -- use one Client per thread.

Instance Attribute Summary

Attributes inherited from Base

#rpc, #url

Instance Method Summary collapse

Methods inherited from Base

#connected?

Constructor Details

#initialize(url, **options) ⇒ Embedded

Returns a new instance of Embedded.



19
20
21
22
23
24
25
26
27
 
# File 'lib/surrealdb/connections/embedded.rb', line 19

def initialize(url, **options)
  super
  @timeout = options.fetch(:timeout, SurrealDB.configuration.timeout)
  @strict = options.fetch(:strict, false)
  @rpc_ptr = nil
  @live_handlers = {}
  @mutex = Mutex.new
  @notification_thread = nil
end

Instance Method Details

#close ⇒ Object 



47
48
49
50
51
52
53
54
55
 
# File 'lib/surrealdb/connections/embedded.rb', line 47

def close
  return unless @connected

  @connected = false
  stop_notification_stream
  Native.sr_surreal_rpc_free(@rpc_ptr) if @rpc_ptr
  @rpc_ptr = nil
  log(:debug, 'Embedded connection closed')
end

#connect ⇒ Object 



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/surrealdb/connections/embedded.rb', line 29

def connect
  err_ptr = FFI::MemoryPointer.new(:pointer)
  surreal_ptr = FFI::MemoryPointer.new(:pointer)

  opts = Native::SrOption.new
  opts[:strict] = @strict
  opts[:query_timeout] = @timeout
  opts[:transaction_timeout] = @timeout

  ret = Native.sr_surreal_rpc_new(err_ptr, surreal_ptr, @url, opts)
  check_error!(ret, err_ptr)

  @rpc_ptr = surreal_ptr.read_pointer
  @connected = true
  start_notification_stream
  log(:debug, "Embedded connection opened: #{@url}")
end

#on_notification(live_query_id, handler) ⇒ Object

Parameters:

  • live_query_id (String)
  • handler (Proc, Queue) 


80
81
82
 
# File 'lib/surrealdb/connections/embedded.rb', line 80

def on_notification(live_query_id, handler)
  @mutex.synchronize { @live_handlers[live_query_id] = handler }
end

#remove_notification_handler(live_query_id) ⇒ Object

Parameters:

  • live_query_id (String) 


85
86
87
 
# File 'lib/surrealdb/connections/embedded.rb', line 85

def remove_notification_handler(live_query_id)
  @mutex.synchronize { @live_handlers.delete(live_query_id) }
end

#send_request(method, params = []) ⇒ Object

Raises:



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/surrealdb/connections/embedded.rb', line 57

def send_request(method, params = [])
  raise ConnectionError, 'not connected' unless @connected

  _id, encoded = @rpc.encode_request(method, params)

  err_ptr = FFI::MemoryPointer.new(:pointer)
  res_ptr = FFI::MemoryPointer.new(:pointer)

  ret = Native.sr_surreal_rpc_execute(
    @rpc_ptr, err_ptr, res_ptr,
    encoded, encoded.bytesize
  )
  check_error!(ret, err_ptr)

  read_and_free_response(res_ptr, ret)
end

#supports_live_queries? ⇒ Boolean

Returns:

  • (Boolean) 


74
75
76
 
# File 'lib/surrealdb/connections/embedded.rb', line 74

def supports_live_queries?
  true
end