surrealdb-embedded 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7b75d55cc942993d3d7ea7bb41a0cb728d744d948a7483c79fb90e1db921f2a9
+  data.tar.gz: 5d5a09ad19b759d6335aeab6df38e747b1ba36967a3f5314dafbb75766510c66
+SHA512:
+  metadata.gz: 4436eead8dd1e61e2a1e3673681dc55d750b0b0d1c4a0b22bd24944ee76a0325dc815ded55b9b5de7dd6748978ebd89cba0f6e3a9180d58a6a2bfe3a6ec78b0c
+  data.tar.gz: 80da57f4362cd5c6db546585a7686bfca397ed96f23ef1eaecdc09673144d6b49df271fbe9e2617cba93d480adf63b5b59ea845feeeee4d33c7e96a8e3c46690

data/lib/surrealdb/connections/embedded.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module SurrealDB
+  module Connections
+    # 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.
+    class Embedded < Base
+      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
+
+      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
+
+      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
+
+      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
+
+      def supports_live_queries?
+        true
+      end
+
+      # @param live_query_id [String]
+      # @param handler [Proc, Queue]
+      def on_notification(live_query_id, handler)
+        @mutex.synchronize { @live_handlers[live_query_id] = handler }
+      end
+
+      # @param live_query_id [String]
+      def remove_notification_handler(live_query_id)
+        @mutex.synchronize { @live_handlers.delete(live_query_id) }
+      end
+
+      private
+
+      def read_and_free_response(res_ptr, length)
+        raw_ptr = res_ptr.read_pointer
+        begin
+          bytes = raw_ptr.read_bytes(length)
+          response = @rpc.decode_response(bytes)
+          Protocol::Response.extract_result(response)
+        ensure
+          Native.sr_free_byte_arr(raw_ptr, length)
+        end
+      end
+
+      def check_error!(ret, err_ptr)
+        return if ret >= 0
+
+        err_str_ptr = err_ptr.read_pointer
+        message = err_str_ptr.null? ? "unknown error (code #{ret})" : err_str_ptr.read_string
+        Native.sr_free_string(err_str_ptr) unless err_str_ptr.null?
+
+        if ret == Native::SR_FATAL
+          @connected = false
+          raise ConnectionError, "fatal error (connection poisoned): #{message}"
+        end
+
+        raise ServerError, message
+      end
+
+      def start_notification_stream
+        err_ptr = FFI::MemoryPointer.new(:pointer)
+        stream_ptr = FFI::MemoryPointer.new(:pointer)
+
+        ret = Native.sr_surreal_rpc_notifications(@rpc_ptr, err_ptr, stream_ptr)
+        return if ret.negative?
+
+        @stream_ptr = stream_ptr.read_pointer
+        @notification_thread = Thread.new do
+          Thread.current.report_on_exception = false
+          notification_loop
+        end
+      end
+
+      def notification_loop
+        while @connected
+          res_ptr = FFI::MemoryPointer.new(:pointer)
+          ret = Native.sr_rpc_stream_next(@stream_ptr, res_ptr)
+
+          break if ret == Native::SR_CLOSED || !@connected
+
+          next unless ret.positive?
+
+          raw_ptr = res_ptr.read_pointer
+          begin
+            bytes = raw_ptr.read_bytes(ret)
+            dispatch_notification(bytes)
+          ensure
+            Native.sr_free_byte_arr(raw_ptr, ret)
+          end
+        end
+      rescue StandardError => e
+        log(:warn, "Notification stream error: #{e.class}: #{e.message}")
+      ensure
+        Native.sr_rpc_stream_free(@stream_ptr) if @stream_ptr
+        @stream_ptr = nil
+      end
+
+      def dispatch_notification(bytes) # rubocop:disable Metrics/CyclomaticComplexity
+        raw = ::CBOR.decode(bytes)
+        resolved = CBOR::Decoder.resolve(raw)
+        result = resolved.is_a?(Hash) ? (resolved['result'] || resolved) : resolved
+        live_id = result['id'] if result.is_a?(Hash)
+        return unless live_id
+
+        handler = @mutex.synchronize { @live_handlers[live_id] }
+        return unless handler
+
+        case handler
+        when Queue then handler.push(result)
+        when Proc  then handler.call(result)
+        end
+      end
+
+      def stop_notification_stream
+        @notification_thread&.join(2)
+        @notification_thread&.kill if @notification_thread&.alive?
+        @notification_thread = nil
+      end
+
+      def log(level, message)
+        SurrealDB.configuration.logger&.send(level, message)
+      end
+    end
+  end
+end

data/lib/surrealdb/embedded.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Opt-in entrypoint for the embedded SurrealDB connection.
+# Loads the FFI bindings and the Embedded connection class.
+#
+# Usage:
+#   require "surrealdb"
+#   require "surrealdb/embedded"
+#
+#   SurrealDB.connect("mem://") do |db|
+#     db.use("test", "test")
+#     # ...
+#   end
+#
+# Requires the `ffi` gem and either:
+# - SURREALDB_LIB_PATH env var pointing to libsurrealdb_c
+# - libsurrealdb_c installed in the system library path
+
+require_relative 'native/platform'
+require_relative 'native/ffi'
+require_relative 'connections/embedded'

data/lib/surrealdb/native/ffi.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+module SurrealDB
+  module Native
+    extend FFI::Library
+
+    ffi_lib Platform.library_path
+
+    # sr_option_t is passed by value to sr_surreal_rpc_new.
+    class SrOption < FFI::Struct
+      layout :strict, :bool,
+             :query_timeout, :uint8,
+             :transaction_timeout, :uint8
+    end
+
+    # Return code constants from surrealdb.h
+    SR_NONE = 0 # success / no more items
+    SR_CLOSED = -1  # stream closed
+    SR_ERROR  = -2  # recoverable error
+    SR_FATAL  = -3  # connection poisoned, must not reuse
+
+    # Connection lifecycle
+    attach_function :sr_surreal_rpc_new,
+                    [:pointer, :pointer, :string, SrOption.by_value], :int,
+                    blocking: true
+    attach_function :sr_surreal_rpc_free,
+                    [:pointer], :void
+
+    # CBOR request/response
+    attach_function :sr_surreal_rpc_execute,
+                    %i[pointer pointer pointer pointer int], :int,
+                    blocking: true
+
+    # Live query notification stream
+    attach_function :sr_surreal_rpc_notifications,
+                    %i[pointer pointer pointer], :int,
+                    blocking: true
+    attach_function :sr_rpc_stream_next,
+                    %i[pointer pointer], :int,
+                    blocking: true
+    attach_function :sr_rpc_stream_free,
+                    [:pointer], :void
+
+    # Memory cleanup
+    attach_function :sr_free_string, [:pointer], :void
+    attach_function :sr_free_byte_arr, %i[pointer int], :void
+  end
+end

data/lib/surrealdb/native/platform.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SurrealDB
+  module Native
+    # Resolves the platform-specific path to the libsurrealdb_c shared library.
+    module Platform
+      module_function
+
+      # @return [String] absolute path or library name for FFI.ffi_lib
+      # @raise [LoadError] if the library cannot be found
+      def library_path
+        from_env || from_system
+      end
+
+      # @return [String] shared library file extension for the current OS
+      def library_extension
+        case host_os
+        when :macos   then 'dylib'
+        when :windows then 'dll'
+        else 'so'
+        end
+      end
+
+      # @return [String] expected library filename
+      def library_name
+        case host_os
+        when :windows then 'surrealdb_c.dll'
+        else "libsurrealdb_c.#{library_extension}"
+        end
+      end
+
+      # @return [Symbol] :linux, :macos, or :windows
+      def host_os
+        case RbConfig::CONFIG['host_os']
+        when /darwin/i then :macos
+        when /mingw|mswin|cygwin/i then :windows
+        else :linux
+        end
+      end
+
+      # @return [Symbol] :x86_64 or :aarch64
+      def host_cpu
+        case RbConfig::CONFIG['host_cpu']
+        when /x86_64|amd64/i then :x86_64
+        when /aarch64|arm64/i then :aarch64
+        else RbConfig::CONFIG['host_cpu'].to_sym
+        end
+      end
+
+      def from_env
+        path = ENV.fetch('SURREALDB_LIB_PATH', nil)
+        return nil if path.nil? || path.empty?
+        raise LoadError, "SURREALDB_LIB_PATH points to missing file: #{path}" unless File.exist?(path)
+
+        path
+      end
+
+      def from_system
+        library_name
+      end
+
+      private_class_method :from_env, :from_system
+    end
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: surrealdb-embedded
+version: !ruby/object:Gem::Version
+  version: 0.7.0
+platform: ruby
+authors:
+- SurrealDB
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: surrealdb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+description: Adds embedded database support (mem://, surrealkv://, file://) to the
+  SurrealDB Ruby SDK via FFI bindings to libsurrealdb_c. Requires libsurrealdb_c to
+  be installed or SURREALDB_LIB_PATH to be set.
+email:
+- stu.schwartz@surrealdb.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/surrealdb/connections/embedded.rb
+- lib/surrealdb/embedded.rb
+- lib/surrealdb/native/ffi.rb
+- lib/surrealdb/native/platform.rb
+homepage: https://github.com/surrealdb/surrealdb.rb
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/surrealdb/surrealdb.rb
+  source_code_uri: https://github.com/surrealdb/surrealdb.rb
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: Embedded SurrealDB engine for the Ruby SDK
+test_files: []