sqlite_web_vfs 1.0.1

data/lib/sqlite_web_vfs/loader.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+
+module SQLiteWebVFS
+  module Loader
+    module_function
+
+    # Absolute path to the built native extension (.bundle/.so)
+    def built_extension_path
+      # The compiled extension is installed under this logical name by extconf.rb
+      require_path = File.join('sqlite_web_vfs', 'sqlite_web_vfs')
+      # Find the actual full path Ruby would use for this require
+      $LOAD_PATH.each do |lp|
+        Dir[File.join(lp, "#{require_path}.{so,bundle,dll}")].each do |p|
+          return p if File.file?(p)
+        end
+        # Ruby might place it in a versioned directory under lp/sqlite_web_vfs
+        Dir[File.join(lp, 'sqlite_web_vfs', 'sqlite_web_vfs.{so,bundle,dll}')].each do |p|
+          return p if File.file?(p)
+        end
+      end
+      nil
+    end
+
+    # Load the HTTP VFS into the process (auto-applied to connections).
+    # This only requires the compiled extension; it registers itself via sqlite3_auto_extension.
+    # Security note: Loading extensions can execute native code. Only load trusted code.
+    def load(db = nil)
+      begin
+        require 'sqlite_web_vfs/sqlite_web_vfs'
+      rescue LoadError
+        raise_load_error(<<~MSG)
+          Could not locate the sqlite_web_vfs native extension. Ensure the gem built correctly.
+          - macOS:   brew install sqlite curl
+          - Amazon Linux 2023: sudo dnf install sqlite-devel libcurl-devel
+          If SQLite is installed but detection failed, rebuild with:
+            gem uninstall sqlite_web_vfs && gem install sqlite_web_vfs -- --with-sqlite3-dir=/path/to/prefix
+          To force building with a bundled SQLite amalgamation (advanced):
+            WEBVFS_FORCE_BUNDLED=1 gem install sqlite_web_vfs
+        MSG
+      end
+
+      # Determine loaded extension path, if any
+      dlex = %w[so bundle dll]
+      so = $LOADED_FEATURES.find do |f|
+        dlex.any? { |ext| f.end_with?("/sqlite_web_vfs/sqlite_web_vfs.#{ext}") }
+      end
+
+      # Ensure the current connection loads the extension too (auto-extension affects future opens)
+      if db
+        db.enable_load_extension(true) if db.respond_to?(:enable_load_extension)
+        if db.respond_to?(:load_extension)
+          db.load_extension(so) if so
+        elsif db.respond_to?(:api) && db.api.respond_to?(:load_extension)
+          if so
+            rc = db.api.load_extension(db.handle, so, nil, nil)
+            raise_load_error("sqlite3-ffi load_extension failed with code #{rc}") unless rc.zero?
+          end
+        end
+      end
+      so
+    end
+
+    def raise_load_error(msg)
+      raise LoadError, "SQLiteWebVFS::Loader: #{msg}"
+    end
+  end
+end

data/lib/sqlite_web_vfs.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'sqlite_web_vfs/loader'
+
+module SQLiteWebVFS
+  # Requiring the compiled extension ensures the VFS registers via sqlite3_auto_extension.
+  begin
+    require 'sqlite_web_vfs/sqlite_web_vfs'
+  rescue LoadError
+    # The loader will surface clearer installation instructions when used.
+  end
+end

data/spec/integration/sq_lite_web_vfs_integration_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'uri'
+require_relative '../spec_helper'
+require 'sqlite_web_vfs'
+
+RSpec.describe SQLiteWebVFS do
+  let(:chinook_url) { 'https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite' }
+  let(:encoded_url) { URI.encode_www_form_component(chinook_url) }
+  let(:web_uri)     { "file:/__web__?vfs=web&mode=ro&immutable=1&web_url=#{encoded_url}" }
+
+  it 'loads and queries remote DB via sqlite3 gem' do
+    begin
+      require 'sqlite3'
+    rescue LoadError
+      skip 'sqlite3 gem not available'
+    end
+    db = SQLite3::Database.new(':memory:')
+    SQLiteWebVFS::Loader.load(db)
+    db.execute('ATTACH DATABASE ? AS remote', [web_uri])
+    count = db.get_first_value('SELECT COUNT(*) FROM remote.Album')
+    expect(count).to be_a(Integer)
+  ensure
+    db&.close
+  end
+
+  it 'loads and queries remote DB via sqlite3-ffi gem' do
+    begin
+      begin
+        require 'sqlite3-ffi'
+      rescue LoadError
+        require 'sqlite3/ffi'
+      end
+    rescue LoadError
+      skip 'sqlite3-ffi gem not available'
+    end
+    db = SQLite3::Database.new(':memory:')
+    SQLiteWebVFS::Loader.load(db)
+    db.execute('ATTACH DATABASE ? AS remote', [web_uri])
+    count = db.execute('SELECT COUNT(*) FROM remote.Album').first.first
+    expect(count).to be_a(Integer)
+  ensure
+    db&.close
+  end
+end

data/spec/integration/sqlite_web_vfs_integration_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'uri'
+require_relative '../spec_helper'
+require 'sqlite_web_vfs'
+
+RSpec.describe SQLiteWebVFS do
+  let(:chinook_url) { ENV['CHINOOK_URL'] || 'https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite' }
+  let(:encoded_url) { URI.encode_www_form_component(chinook_url) }
+  let(:web_uri)     { "file:/__web__?vfs=web&mode=ro&immutable=1&web_url=#{encoded_url}" }
+
+  it 'loads and queries remote DB via sqlite3 gem' do
+    begin
+      require 'sqlite3'
+    rescue LoadError
+      skip 'sqlite3 gem not available'
+    end
+    db = SQLite3::Database.new(':memory:')
+    SQLiteWebVFS::Loader.load(db)
+    db.execute('ATTACH DATABASE ? AS remote', [web_uri])
+    count = db.get_first_value('SELECT COUNT(*) FROM remote.Album')
+    expect(count).to be_a(Integer)
+  ensure
+    db&.close
+  end
+
+  it 'loads and queries remote DB via sqlite3-ffi gem' do
+    begin
+      begin
+        require 'sqlite3-ffi'
+      rescue LoadError
+        require 'sqlite3/ffi'
+      end
+    rescue LoadError
+      skip 'sqlite3-ffi gem not available'
+    end
+    db = SQLite3::Database.new(':memory:')
+    SQLiteWebVFS::Loader.load(db)
+    db.execute('ATTACH DATABASE ? AS remote', [web_uri])
+    count = db.execute('SELECT COUNT(*) FROM remote.Album').first.first
+    expect(count).to be_a(Integer)
+  ensure
+    db&.close
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: sqlite_web_vfs
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Denis Sablic
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Builds and loads the HTTP VFS from mlin/sqlite_web_vfs for SQLite, enabling
+  remote DB access over HTTP(S) via Range requests.
+email: denis.sablic@gmail.com
+executables: []
+extensions:
+- ext/sqlite_web_vfs/extconf.rb
+extra_rdoc_files: []
+files:
+- LICENSE-3RD-PARTY.md
+- README.md
+- examples/sqlite3_example.rb
+- examples/sqlite3_ffi_example.rb
+- ext/sqlite_web_vfs/Makefile
+- ext/sqlite_web_vfs/_wrap_web_vfs.o
+- ext/sqlite_web_vfs/extconf.rb
+- ext/sqlite_web_vfs/readerwriterqueue.h
+- ext/sqlite_web_vfs/shim.c
+- ext/sqlite_web_vfs/shim.o
+- ext/sqlite_web_vfs/upstream/HTTP.h
+- ext/sqlite_web_vfs/upstream/SQLiteVFS.h
+- ext/sqlite_web_vfs/upstream/ThreadPool.h
+- ext/sqlite_web_vfs/upstream/atomicops.h
+- ext/sqlite_web_vfs/upstream/dbi.h
+- ext/sqlite_web_vfs/upstream/readerwriterqueue.h
+- ext/sqlite_web_vfs/upstream/web_vfs.cc
+- ext/sqlite_web_vfs/upstream/web_vfs.h
+- lib/sqlite_web_vfs.rb
+- lib/sqlite_web_vfs/loader.rb
+- spec/integration/sq_lite_web_vfs_integration_spec.rb
+- spec/integration/sqlite_web_vfs_integration_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/dsablic/sqlite_web_vfs
+licenses:
+- BSD-3-Clause
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/dsablic/sqlite_web_vfs
+  bug_tracker_uri: https://github.com/dsablic/sqlite_web_vfs/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Loadable SQLite HTTP VFS (Ruby loader)
+test_files: []